diff --git a/.gitattributes b/.gitattributes
index a6344aac8c09253b3b630fb776ae94478aa0275b..26736b149f33ba71b3f2f80be0e7ceb9b0b4f6ec 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -33,3 +33,52 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+static/bg/bg_classroom.png filter=lfs diff=lfs merge=lfs -text
+static/bg/bg_hallway.png filter=lfs diff=lfs merge=lfs -text
+static/bg/bg_library.png filter=lfs diff=lfs merge=lfs -text
+static/bg/classroom_bg.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/marie/_preframe/marie_angry.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/marie/_preframe/marie_embarrassed.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/marie/_preframe/marie_laugh.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/marie/_preframe/marie_neutral.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/marie/_preframe/marie_sad.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/marie/_preframe/marie_smile.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/marie/_preframe/marie_surprised.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/marie/marie_angry.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/marie/marie_base.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/marie/marie_embarrassed.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/marie/marie_laugh.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/marie/marie_neutral.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/marie/marie_sad.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/marie/marie_smile.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/marie/marie_surprised.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/sakura/_preframe/sakura_angry.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/sakura/_preframe/sakura_embarrassed.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/sakura/_preframe/sakura_laugh.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/sakura/_preframe/sakura_neutral.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/sakura/_preframe/sakura_sad.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/sakura/_preframe/sakura_smile.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/sakura/_preframe/sakura_surprised.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/sakura/sakura_angry.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/sakura/sakura_base.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/sakura/sakura_embarrassed.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/sakura/sakura_laugh.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/sakura/sakura_neutral.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/sakura/sakura_sad.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/sakura/sakura_smile.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/sakura/sakura_surprised.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/yuki/_preframe/yuki_angry.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/yuki/_preframe/yuki_embarrassed.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/yuki/_preframe/yuki_laugh.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/yuki/_preframe/yuki_neutral.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/yuki/_preframe/yuki_sad.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/yuki/_preframe/yuki_smile.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/yuki/_preframe/yuki_surprised.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/yuki/yuki_angry.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/yuki/yuki_base.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/yuki/yuki_embarrassed.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/yuki/yuki_laugh.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/yuki/yuki_neutral.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/yuki/yuki_sad.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/yuki/yuki_smile.png filter=lfs diff=lfs merge=lfs -text
+static/sprites/curated/yuki/yuki_surprised.png filter=lfs diff=lfs merge=lfs -text
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000000000000000000000000000000000000..75d965ecfc05c633d7657924418a95c89f5ed04e
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Virtual environment
+.venv/
+
+# Testing
+.pytest_cache/
+*.coverage
+htmlcov/
+
+# IDE
+.claude/
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Runtime
+*.log
+logs/
+
+# Generated assets & runtime data (regenerable sprites/backgrounds,
+# save slots, contact-sheet report) — kept out of version control.
+static/
+saves/
+cast_report.md
+
+# Windows alternate-data-stream / scratch artifacts
+*:Zone.Identifier
+*:PG$Secure
+*:Avecto.Zone.Identifier
+*.bak
diff --git a/.pytest_cache/.gitignore b/.pytest_cache/.gitignore
new file mode 100644
index 0000000000000000000000000000000000000000..bc1a1f6167d09c909aad37280b760bb715d0f1da
--- /dev/null
+++ b/.pytest_cache/.gitignore
@@ -0,0 +1,2 @@
+# Created by pytest automatically.
+*
diff --git a/.pytest_cache/CACHEDIR.TAG b/.pytest_cache/CACHEDIR.TAG
new file mode 100644
index 0000000000000000000000000000000000000000..fce15ad7eaa74e5682b644c84efb75334c112f95
--- /dev/null
+++ b/.pytest_cache/CACHEDIR.TAG
@@ -0,0 +1,4 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by pytest.
+# For information about cache directory tags, see:
+#	https://bford.info/cachedir/spec.html
diff --git a/.pytest_cache/README.md b/.pytest_cache/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..b89018ced91c0a8af7f3f23ce8901870da89f3a0
--- /dev/null
+++ b/.pytest_cache/README.md
@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.
diff --git a/.pytest_cache/v/cache/lastfailed b/.pytest_cache/v/cache/lastfailed
new file mode 100644
index 0000000000000000000000000000000000000000..9e26dfeeb6e641a33dae4961196235bdb965b21b
--- /dev/null
+++ b/.pytest_cache/v/cache/lastfailed
@@ -0,0 +1 @@
+{}
\ No newline at end of file
diff --git a/.pytest_cache/v/cache/nodeids b/.pytest_cache/v/cache/nodeids
new file mode 100644
index 0000000000000000000000000000000000000000..6e1317900fed150f6efcdaaa2c3a6ff4c36c15e4
--- /dev/null
+++ b/.pytest_cache/v/cache/nodeids
@@ -0,0 +1,76 @@
+[
+  "tests/test_engine_mock.py::TestChoiceFlow::test_apply_choice_effects",
+  "tests/test_engine_mock.py::TestChoiceFlow::test_choice_affection_triggers",
+  "tests/test_engine_mock.py::TestChoiceFlow::test_choices_set_by_model",
+  "tests/test_engine_mock.py::TestSaveLoad::test_cast_persistence_across_saves",
+  "tests/test_engine_mock.py::TestSaveLoad::test_scene_state_roundtrip",
+  "tests/test_engine_mock.py::TestVNTurnLoop::test_cast_lock_cleanup",
+  "tests/test_engine_mock.py::TestVNTurnLoop::test_expression_changes_in_narration",
+  "tests/test_engine_mock.py::TestVNTurnLoop::test_first_turn_returns_narration",
+  "tests/test_engine_mock.py::TestVNTurnLoop::test_multi_turn_preserves_state",
+  "tests/test_engine_mock.py::TestVNTurnLoop::test_tool_calls_parsed_in_narration",
+  "tests/test_trace_log.py::test_mock_model_is_not_logged",
+  "tests/test_trace_log.py::test_real_model_turn_is_logged",
+  "tests/test_trace_log.py::test_trace_disabled_by_env",
+  "tests/test_unit.py::TestCastLock::test_check_case_insensitive",
+  "tests/test_unit.py::TestCastLock::test_check_nonexistent_character",
+  "tests/test_unit.py::TestCastLock::test_check_valid_character",
+  "tests/test_unit.py::TestCastLock::test_clean_noncast_dialogue",
+  "tests/test_unit.py::TestCastLock::test_repair_cast_violation_flags",
+  "tests/test_unit.py::TestCastMember::test_character_immutability",
+  "tests/test_unit.py::TestCastMember::test_expression_map_completeness",
+  "tests/test_unit.py::TestCastMember::test_get_sprite_fallback",
+  "tests/test_unit.py::TestCastPipeline::test_cast_character_identity",
+  "tests/test_unit.py::TestCastPipeline::test_cast_to_dict_roundtrip",
+  "tests/test_unit.py::TestCastPipeline::test_curated_cast_has_all_expressions",
+  "tests/test_unit.py::TestCastPipeline::test_curated_cast_sprite_paths_exist",
+  "tests/test_unit.py::TestCastPipeline::test_pipeline_returns_list",
+  "tests/test_unit.py::TestCastPipeline::test_standard_expressions_constant",
+  "tests/test_unit.py::TestEnterExitCharacter::test_enter_character_adds_to_present",
+  "tests/test_unit.py::TestEnterExitCharacter::test_enter_character_cast_lock_violation",
+  "tests/test_unit.py::TestEnterExitCharacter::test_enter_character_idempotent",
+  "tests/test_unit.py::TestEnterExitCharacter::test_enter_character_routed",
+  "tests/test_unit.py::TestEnterExitCharacter::test_exit_character_cast_lock_violation",
+  "tests/test_unit.py::TestEnterExitCharacter::test_exit_character_not_present_no_error",
+  "tests/test_unit.py::TestEnterExitCharacter::test_exit_character_removes_from_present",
+  "tests/test_unit.py::TestEnterExitCharacter::test_exit_character_routed",
+  "tests/test_unit.py::TestEnterExitCharacter::test_parse_enter_character",
+  "tests/test_unit.py::TestEnterExitCharacter::test_parse_exit_character",
+  "tests/test_unit.py::TestExpressionState::test_choice_expression_changes_applied",
+  "tests/test_unit.py::TestExpressionState::test_invalid_expression_leaves_state",
+  "tests/test_unit.py::TestExpressionState::test_set_expression_updates_scene_state",
+  "tests/test_unit.py::TestExpressionState::test_state_banner_shows_expressions",
+  "tests/test_unit.py::TestSaveLoadJson::test_engine_save_load_roundtrip",
+  "tests/test_unit.py::TestSaveLoadJson::test_load_missing_slot_raises",
+  "tests/test_unit.py::TestSaveLoadJson::test_savedata_dict_roundtrip",
+  "tests/test_unit.py::TestSceneState::test_affection_flags",
+  "tests/test_unit.py::TestSceneState::test_has_affection",
+  "tests/test_unit.py::TestSceneState::test_initial_state",
+  "tests/test_unit.py::TestSceneState::test_present_characters",
+  "tests/test_unit.py::TestSelectiveVoicing::test_dialogue_recorded_in_scene",
+  "tests/test_unit.py::TestSelectiveVoicing::test_no_voice_without_expression_change",
+  "tests/test_unit.py::TestSelectiveVoicing::test_voices_line_after_expression_change",
+  "tests/test_unit.py::TestSetBackgroundTool::test_parse_set_background",
+  "tests/test_unit.py::TestSetBackgroundTool::test_set_background_mutation",
+  "tests/test_unit.py::TestSetBackgroundTool::test_set_background_requires_key",
+  "tests/test_unit.py::TestSetBackgroundTool::test_set_background_routed",
+  "tests/test_unit.py::TestToolParsing::test_loads_lenient_preserves_colon_in_values",
+  "tests/test_unit.py::TestToolParsing::test_no_tools_returns_empty",
+  "tests/test_unit.py::TestToolParsing::test_offer_choices_lenient_loose_json",
+  "tests/test_unit.py::TestToolParsing::test_offer_choices_with_apostrophes_routes_ok",
+  "tests/test_unit.py::TestToolParsing::test_parse_advance_scene",
+  "tests/test_unit.py::TestToolParsing::test_parse_apostrophe_in_double_quoted_arg",
+  "tests/test_unit.py::TestToolParsing::test_parse_apostrophe_in_plain_single_quoted_arg",
+  "tests/test_unit.py::TestToolParsing::test_parse_apostrophe_in_trailing_single_quoted_arg",
+  "tests/test_unit.py::TestToolParsing::test_parse_bare_unquoted_json_value",
+  "tests/test_unit.py::TestToolParsing::test_parse_choices_with_apostrophes",
+  "tests/test_unit.py::TestToolParsing::test_parse_multiple_tools",
+  "tests/test_unit.py::TestToolParsing::test_parse_offer_choices",
+  "tests/test_unit.py::TestToolParsing::test_parse_save_checkpoint",
+  "tests/test_unit.py::TestToolParsing::test_parse_set_expression",
+  "tests/test_unit.py::TestToolRouting::test_advance_scene_mutation",
+  "tests/test_unit.py::TestToolRouting::test_apply_choice_effects",
+  "tests/test_unit.py::TestToolRouting::test_offer_choices_sets_state",
+  "tests/test_unit.py::TestToolRouting::test_set_expression_invalid_character",
+  "tests/test_unit.py::TestToolRouting::test_set_expression_valid"
+]
\ No newline at end of file
diff --git a/README.md b/README.md
index 2b9fb5ffd14cf7444885b2e48c1a350f211ec5b8..72659fca443e9708a79291d0ef6e30350fde3183 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,55 @@
 ---
-title: Ars Fabula Vn
-emoji: 📊
+title: Ars Fabula VN
+emoji: 🌸
 colorFrom: pink
-colorTo: pink
+colorTo: indigo
 sdk: gradio
-sdk_version: 6.17.3
-python_version: '3.13'
+sdk_version: 6.16.0
 app_file: app.py
 pinned: false
+license: apache-2.0
+short_description: An AI-driven visual novel — a small LLM writes every scene
+models:
+  - google/gemma-3-4b-it
+tags:
+  - build-small-hackathon
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🌸 Ars Fabula VN
+
+An AI-driven visual novel where every scene is written live by a **small
+local-class LLM**. The model narrates, voices a three-character cast,
+swaps expressions and backgrounds, and offers branching choices — through
+a plain-text tool-call protocol (`[TOOL: set_expression …]`) that any
+small instruct model can speak. No fine-tune, no function-calling API.
+
+**Track:** Thousand Token Wood · **Hackathon:** Build Small
+
+## How to play
+
+1. Press **Begin** on the title screen.
+2. Read at your own pace — click / Space / Enter advances each beat.
+3. Pick a choice button, or type any action you want in the free-text bar.
+4. Save/Load slots persist for your session.
+
+## What's running
+
+| Piece | On this Space (ZeroGPU) | At home |
+|---|---|---|
+| Scene writer | `google/gemma-3-4b-it` via transformers, `@spaces.GPU` | Gemma 4 26B-A4B MoE on a custom llama.cpp fork (MTP speculative decoding) on an 8 GB GPU |
+| Character sprites | Curated set (pre-baked with the pipeline below) | Live ComfyUI pipeline: face-gated base gen → expression warping → background removal |
+| Backgrounds | Preset library (same pipeline) | Preset + live txt2img for novel scene keys |
+
+The engine is model-independent: the same code drives a mock model (for
+tests), a llama.cpp server, or an in-process transformers model — picked
+by `ARS_FABULA_BACKEND`. On an 8 GB card the LLM and the diffusion stack
+can't co-reside, so the home setup stops/relaunches servers around image
+bakes; on ZeroGPU none of that is needed — the GPU is granted per call.
+
+## Run it locally
+
+```bash
+pip install -r requirements.txt gradio==6.16.0
+python app.py                          # in-process model: ARS_FABULA_BACKEND=transformers
+ARS_FABULA_BACKEND=mock python app.py  # no model needed
+```
diff --git a/app.py b/app.py
new file mode 100644
index 0000000000000000000000000000000000000000..501c7cae9dbd7b89e1c0b97190b6b3d486e784a7
--- /dev/null
+++ b/app.py
@@ -0,0 +1,295 @@
+"""
+Ars-Fabula Visual Novel — Gradio entrypoint.
+
+The VN UI is split across the `ui/` package:
+  ui.styles     — CSS + onload JS
+  ui.media      — data: URI image embedding
+  ui.bootstrap  — constants, initial scene, engine construction
+  ui.screens    — HTML builders for the canvas
+  ui.beats      — response → paced display beats + screen render
+  ui.callbacks  — Gradio event handlers (make_callbacks)
+
+This module only assembles the gr.Blocks layout, wires events, and launches.
+
+Run with:
+    python app.py                            # production (tries real model)
+    ARS_FABULA_BACKEND=mock python app.py    # test mode (no server)
+    ARS_FABULA_VOICE=kokoro python app.py    # voiced lines via Kokoro
+"""
+from __future__ import annotations
+import os
+
+# ── Hugging Face Spaces / ZeroGPU ──────────────────────────────────────
+# SPACE_ID is set by the Spaces runtime. There, the LLM runs in-process
+# via transformers (+ @spaces.GPU); llama-server/ComfyUI don't exist, and
+# their fallbacks (curated cast, preset backgrounds, mock voice) apply.
+ON_SPACES = bool(os.getenv("SPACE_ID"))
+if ON_SPACES:
+    os.environ.setdefault("ARS_FABULA_BACKEND", "transformers")
+    os.environ.setdefault("ARS_FABULA_MODEL", "google/gemma-3-4b-it")
+
+import gradio as gr
+
+from providers import get_background_provider
+from ui.styles import CSS, ONLOAD_JS
+from ui.bootstrap import make_initial_scene, DEFAULT_CAST, STATIC_DIR
+from ui.screens import _title_screen_html
+from ui.callbacks import make_callbacks
+
+
+def create_ui():
+    """Build and return the Gradio VN app."""
+    bg_backend = os.getenv("ARS_FABULA_BG", "preset")
+    bg_provider = get_background_provider(bg_backend)
+    (on_start, on_choice, on_save, on_load, on_reset, on_advance,
+     on_free_submit, on_casting_confirm, on_casting_redo,
+     on_menu_load) = make_callbacks(bg_provider)
+
+    initial_scene = make_initial_scene()
+
+    with gr.Blocks(title="Ars-Fabula VN") as app:
+        # ── State ──────────────────────────────────────────────
+        scene_state = gr.State(initial_scene)
+        engine_ref = gr.State(None)
+        cast_data = gr.State(DEFAULT_CAST)
+        prev_bg_state = gr.State("")
+        beats_state = gr.State([])        # ordered display beats for this turn
+        beat_idx_state = gr.State(0)      # which beat is currently shown
+        casting_state = gr.State(None)    # interactive casting review state
+
+        # ── The stage: the canvas plus the free-text bar overlaid inside its
+        #    frame. The wrapping Column is the positioned ancestor the bar
+        #    anchors to (#stage { position: relative }), so the overlay stays
+        #    docked in the canvas instead of flying across the viewport — the
+        #    failure mode of an earlier absolute version with no such ancestor.
+        with gr.Column(elem_id="stage"):
+            # Initial value is the TITLE SCREEN.
+            vn_screen = gr.HTML(_title_screen_html())
+
+            # Free-text action bar — docked inside the canvas, in the same
+            # centered column as the choices (which stack just above it) and
+            # styled to match the choice buttons, so it feels like part of the
+            # interaction cluster. Revealed only at the END of a turn (JS
+            # toggles body.vn-playing once the last beat's text is shown or
+            # choices appear), not while earlier beats are still being read.
+            with gr.Row(elem_id="free-input-row"):
+                free_input = gr.Textbox(
+                    scale=8, lines=1, max_lines=1,
+                    placeholder="Your choice…",
+                    label=None, show_label=False, container=False,
+                    elem_id="free-input",
+                )
+                free_submit = gr.Button("➤", scale=1, size="sm",
+                                        elem_id="free-submit-btn")
+
+        # ── Cast Setup — MENU ONLY (renderd as HTML inside the canvas, NOT Gradio).
+        #    Shown on the main menu after Begin → Generated; hidden once a game
+        #    starts, restored on Reset (which returns to the title).
+        #    Hidden bridge controls: the in-canvas HTML buttons set these via JS
+        #    (same pattern as preset-box / player-name-box) before clicking the
+        #    hidden generate button. ──
+        cs_n_0 = gr.Textbox(value="", visible="hidden", interactive=True, elem_id="cs-n-0")
+        cs_c_0 = gr.Textbox(value="", visible="hidden", interactive=True, elem_id="cs-c-0")
+        cs_t_0 = gr.Textbox(value="", visible="hidden", interactive=True, elem_id="cs-t-0")
+        cs_n_1 = gr.Textbox(value="", visible="hidden", interactive=True, elem_id="cs-n-1")
+        cs_c_1 = gr.Textbox(value="", visible="hidden", interactive=True, elem_id="cs-c-1")
+        cs_t_1 = gr.Textbox(value="", visible="hidden", interactive=True, elem_id="cs-t-1")
+        cs_n_2 = gr.Textbox(value="", visible="hidden", interactive=True, elem_id="cs-n-2")
+        cs_c_2 = gr.Textbox(value="", visible="hidden", interactive=True, elem_id="cs-c-2")
+        cs_t_2 = gr.Textbox(value="", visible="hidden", interactive=True, elem_id="cs-t-2")
+        cs_fast = gr.Checkbox(value=False, visible="hidden", elem_id="cs-fast")
+        generate_cast_btn = gr.Button("Generate", visible="hidden",
+                                      elem_id="generate-cast-btn")
+
+        # ── Hidden sinks (callback outputs the JS never reads) ───
+        cast_panel = gr.HTML(visible=False)
+        scene_info = gr.Markdown(visible=False)
+        narration_log = gr.Textbox(visible=False, interactive=False)
+
+        # CSS-collapsed, not visible=False — the <audio> element must mount
+        # for autoplay to fire.
+        voice_audio = gr.Audio(
+            value=None, autoplay=True, visible=True,
+            interactive=False, elem_id="voice-audio", container=False,
+        )
+
+        # ── Hidden JS bridges ─────────────────────────────────────
+        # visible="hidden" keeps these in the DOM (visible=False would remove
+        # them and break the JS bridge)
+        preset_box = gr.Textbox(value="generated", visible="hidden",
+                                interactive=True, elem_id="preset-box")
+        player_name_box = gr.Textbox(value="Player", visible="hidden",
+                                     interactive=True, elem_id="player-name-box")
+        start_btn = gr.Button("Begin", visible="hidden",
+                              elem_id="start-btn-hidden")
+        save_slot = gr.Number(value=0, minimum=0, maximum=4, step=1,
+                              precision=0, visible="hidden",
+                              elem_id="save-slot-hidden")
+        save_btn = gr.Button("Save", visible="hidden", elem_id="save-btn-hidden")
+        load_btn = gr.Button("Load", visible="hidden", elem_id="load-btn-hidden")
+        reset_btn = gr.Button("Reset", visible="hidden", elem_id="reset-btn-hidden")
+        save_status = gr.Markdown("", visible="hidden",
+                                  elem_id="save-status-hidden")
+        # Save-name bridge (the in-panel name input writes here before Save) +
+        # the slot-rows mirror JS copies into the open panel after a save.
+        save_name_box = gr.Textbox(value="", visible="hidden", interactive=True,
+                                   elem_id="save-name-box")
+        slots_meta = gr.HTML("", visible="hidden", elem_id="slots-meta-hidden")
+        # Main-menu Load: clicked by the title-screen load list via JS.
+        menu_load_btn = gr.Button("Menu Load", visible="hidden",
+                                  elem_id="menu-load-btn")
+
+        choice_input = gr.Textbox(visible="hidden", interactive=True,
+                                  elem_id="choice-id-box")
+        choice_text_input = gr.Textbox(visible="hidden", interactive=True,
+                                       elem_id="choice-text-box")
+        submit_choice_btn = gr.Button("Submit Choice", visible="hidden",
+                                      elem_id="submit-choice-btn")
+        # Hidden "next beat" trigger — clicked by the screen-click / Space-Enter
+        # JS hook when there is more text to read this turn.
+        advance_btn = gr.Button("Advance", visible="hidden",
+                                elem_id="advance-btn")
+
+        # Hidden state for free-text fallback choice id
+        free_choice_id = gr.Textbox(value="__free__", visible="hidden",
+                                    elem_id="free-choice-id")
+
+        # ── Casting review bridge widgets ──────────────────────
+        casting_prompt_box = gr.Textbox(visible="hidden", interactive=True,
+                                        elem_id="casting-prompt-box")
+        casting_confirm_btn = gr.Button("Confirm", visible="hidden",
+                                        elem_id="casting-confirm-btn")
+        casting_redo_btn = gr.Button("Redo", visible="hidden",
+                                      elem_id="casting-redo-btn")
+
+        main_outputs = [scene_state, engine_ref, vn_screen, cast_data,
+                        cast_panel, narration_log, scene_info,
+                        voice_audio, prev_bg_state]
+        # Turn callbacks also carry the beat list + index (read-at-your-own-pace).
+        turn_outputs = main_outputs + [beats_state, beat_idx_state]
+        # Start + casting confirm carry the interactive review state as well.
+        start_outputs = turn_outputs + [casting_state]
+
+        # ── Event wiring ───────────────────────────────────────
+        # Two entry points into on_start, both reading the preset:
+        #   • start_btn  — clicked by Begin for the CURATED path (no setup step).
+        #   • generate_cast_btn — clicked from the Cast Setup step (GENERATED).
+        # Cast Setup's visibility is driven entirely by JS (body.cast-setup-active
+        # + CSS), so no Gradio show/hide is needed here.
+        # show_progress="hidden" everywhere: Gradio's default queue overlay dims
+        # the whole canvas (.pending → opacity 0.2) and slides a dark .eta-bar
+        # across it via a transform — which read as the entire UI (sprites
+        # included) "dragging" diagonally while a turn was processing.
+        _start_inputs = [preset_box, casting_state, player_name_box,
+                       cs_n_0, cs_c_0, cs_t_0,
+                       cs_n_1, cs_c_1, cs_t_1,
+                       cs_n_2, cs_c_2, cs_t_2,
+                       cs_fast]
+        start_btn.click(fn=on_start, inputs=_start_inputs, outputs=start_outputs,
+                        show_progress="hidden")
+        generate_cast_btn.click(fn=on_start, inputs=_start_inputs, outputs=start_outputs,
+                                show_progress="hidden")
+
+        submit_choice_btn.click(
+            fn=on_choice,
+            inputs=[choice_input, choice_text_input, scene_state, engine_ref,
+                    prev_bg_state, narration_log],
+            outputs=turn_outputs,
+            show_progress="hidden",
+        )
+
+        # Advance one beat: re-render the screen, bump the index, chain the
+        # crossfade (prev_bg), and play that beat's voiced line if any.
+        advance_btn.click(
+            fn=on_advance,
+            inputs=[beats_state, beat_idx_state, scene_state, prev_bg_state,
+                    narration_log],
+            outputs=[vn_screen, beat_idx_state, voice_audio, scene_info, prev_bg_state],
+            show_progress="hidden",
+        )
+
+        save_btn.click(fn=on_save,
+                       inputs=[save_slot, save_name_box, narration_log,
+                               scene_state, engine_ref],
+                       outputs=[save_status, slots_meta], show_progress="hidden")
+        load_btn.click(fn=on_load,
+                       inputs=[save_slot, scene_state, engine_ref, prev_bg_state],
+                       outputs=turn_outputs + [save_status],
+                       show_progress="hidden")
+        menu_load_btn.click(fn=on_menu_load, inputs=[save_slot],
+                            outputs=turn_outputs + [save_status],
+                            show_progress="hidden")
+
+        reset_btn.click(fn=on_reset, outputs=turn_outputs, show_progress="hidden")
+
+        # ── Casting review — confirm advances to next character ──
+        casting_confirm_btn.click(
+            fn=on_casting_confirm,
+            inputs=[casting_state, casting_prompt_box, scene_state, engine_ref, prev_bg_state],
+            outputs=start_outputs,
+            show_progress="hidden",
+        )
+        # ── Casting review — redo regenerates current base ────
+        redo_outputs = [vn_screen, scene_info, casting_state, casting_prompt_box]
+        casting_redo_btn.click(
+            fn=on_casting_redo,
+            inputs=[casting_state, casting_prompt_box],
+            outputs=redo_outputs,
+            show_progress="hidden",
+        )
+
+        # ── Free-text action (fallback when no choices, or "Write your
+        #    own action…"). Clears the box server-side via the extra output. ─
+        # Both the ➤ button and Enter (via JS bridge → clicks this button)
+        # route here; clears the box server-side via the extra output.
+        free_outputs = turn_outputs + [free_input]
+        free_submit.click(
+            fn=on_free_submit,
+            inputs=[free_input, scene_state, engine_ref, prev_bg_state,
+                    narration_log],
+            outputs=free_outputs,
+            show_progress="hidden",
+        )
+
+    return app
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# Main
+# ═══════════════════════════════════════════════════════════════════════
+
+if __name__ == "__main__":
+    import sys
+
+    port = int(os.getenv("GRADIO_PORT", "7861"))
+    if len(sys.argv) > 1:
+        try:
+            port = int(sys.argv[1])
+        except ValueError:
+            pass
+
+    if ON_SPACES:
+        # ZeroGPU wants the model loaded (and placed on cuda, under its
+        # emulation layer) at startup, not lazily inside a request.
+        from model_client import preload_transformers
+        preload_transformers()
+        port = int(os.getenv("GRADIO_SERVER_PORT", "7860"))
+
+    app = create_ui()
+    print(f"\n🌸 Ars-Fabula VN starting on http://127.0.0.1:{port}")
+    print(f"   Mock mode: {os.getenv('ARS_FABULA_BACKEND', 'server') == 'mock'}")
+    print(f"   Voice: {os.getenv('ARS_FABULA_VOICE', 'mock')} · "
+          f"BG: {os.getenv('ARS_FABULA_BG', 'preset')}\n")
+    app.launch(
+        server_name="0.0.0.0" if ON_SPACES else "127.0.0.1",
+        server_port=port,
+        allowed_paths=[STATIC_DIR],   # belt-and-braces; images are data URIs anyway
+        css=CSS,                      # Gradio 6: css/js/theme live on launch()
+        js=ONLOAD_JS,
+        theme=gr.themes.Base(
+            primary_hue="amber",
+            neutral_hue="slate",
+        ),
+        quiet=False,
+        share=False,
+    )
diff --git a/cast_pipeline.py b/cast_pipeline.py
new file mode 100644
index 0000000000000000000000000000000000000000..cb2618b7e402ed1771fcc455251f5f003ff6e486
--- /dev/null
+++ b/cast_pipeline.py
@@ -0,0 +1,1382 @@
+"""
+cast_pipeline.py — Generate or load character casts for the VN.
+
+Pipeline (mirrors the VALIDATED ComfyUI workflow
+`tools/workflows/anima_expression_sheet.json` — tested by hand on this
+machine's ComfyUI install):
+    Anima base gen (UNETLoader anima-base-v1.0 + Qwen CLIP/VAE)
+      → face detect gate (face_yolov8n via Impact-Pack; retry on miss)
+      → FaceDetailer per expression — only the face region is
+        re-generated with the expression prompt (denoise 0.55; the sheet's
+        note suggests 0.4–0.7, lower = subtler), so body/clothes/background
+        stay identical and identity holds
+      → rembg isnet-anime matte → alpha sprites
+
+Two modes:
+1. GENERATE (default): requires ComfyUI at localhost:8188 with the Anima
+   model and Impact-Pack (UltralyticsDetectorProvider, FaceDetailer, SAM).
+2. CURATED: loads pre-made sprites from static/sprites/curated/<name>/.
+
+Same return type either way — list[CastMember] (frozen Wave 0.5 contract:
+generate_cast(prefs) -> list[CastMember]) — so nothing downstream changes.
+Use vn_contracts.cast_to_dict() to build SceneState's name->member dict.
+
+Usage:
+    from cast_pipeline import generate_cast, load_curated_cast
+    from vn_contracts import cast_to_dict
+
+    cast = generate_cast({"mood": "romance", "preset": "childhood_friends"})
+    scene_cast = cast_to_dict(cast)
+"""
+from __future__ import annotations
+import json
+import os
+import sys
+import time
+import urllib.request
+import urllib.error
+import shutil
+import re
+from typing import Optional
+
+from vn_contracts import Character, CastMember, STANDARD_EXPRESSIONS
+
+# ── Constants ─────────────────────────────────────────────────────────
+# Override with ARS_FABULA_COMFY if ComfyUI runs elsewhere (e.g. on the
+# Windows side of WSL: start it with `--listen 0.0.0.0` and point this at
+# the Windows host IP).
+COMFY_HOST = os.getenv("ARS_FABULA_COMFY", "http://127.0.0.1:8188").rstrip("/")
+COMFY_OUTPUT = os.path.expanduser("~/comfy/ComfyUI/output")  # legacy; results now fetched via /view
+PROJECT_DIR = os.path.dirname(__file__)
+CURATED_DIR = os.path.join(PROJECT_DIR, "static", "sprites", "curated")
+GENERATED_DIR = os.path.join(PROJECT_DIR, "static", "sprites", "generated")
+
+# Anima-tuned (per the June 2026 ADT/LDG synthesis): pony/score_ quality
+# tags DEGRADE Anima output; `absurdres` is the only quality tag that helps.
+# `safe` is the SFW content rating. (Override via env if you re-tune.)
+QUALITY = os.getenv("ARS_FABULA_QUALITY", "absurdres")
+NEGATIVE = os.getenv("ARS_FABULA_NEGATIVE",
+                     "worst quality, low quality, blurry, jpeg artifacts, "
+                     "sepia, bad anatomy, ugly, deformed")
+
+# Anima sampler/scheduler. dpm_2_ancestral won the A/B sweep on this
+# install (tools/sampler_sweep.py — best subjective quality). Env-overridable
+# to retest others without code edits, e.g.:
+#   ARS_FABULA_SAMPLER=flow_euler python app.py
+SAMPLER = os.getenv("ARS_FABULA_SAMPLER", "dpm_2_ancestral")
+SCHEDULER = os.getenv("ARS_FABULA_SCHEDULER", "simple")
+
+# Fixed generation seed — every base + expression starts here, so the whole
+# cast is reproducible run-to-run. Env-overridable. The face-gate / expression
+# retries still bump it locally (+attempt) to self-heal a bad draw.
+SEED = int(os.getenv("ARS_FABULA_SEED", "42"))
+
+# Shared style block — prepended to EVERY prompt (cast + backgrounds) so the
+# whole game shares one look. Generic style descriptors by default; add
+# `@artistname` danbooru artist tags here (or via env) to narrow further.
+STYLE_TAGS = os.getenv(
+    "ARS_FABULA_STYLE",
+    "official art, light novel illustration style, clean lineart, "
+    "soft cel shading, pastel color palette, soft lighting, "
+    "shiny detailed eyes, smooth shading",
+)
+
+# Full-body base canvas (taller than the old 512x768). We generate the whole
+# body for CONSISTENT framing, then crop the upper portion — full-body
+# composition lands the head at a consistent place/scale across characters,
+# which upper-body framing did not.
+BASE_WIDTH, BASE_HEIGHT = 512, 896
+
+# Fast generation: bake the base at a LOWER RESOLUTION (same 4:7 aspect) for a
+# much quicker cast. Also uses lighter FaceDetailer parameters (fewer steps,
+# smaller guide/max size, euler sampler) so both the base gen and expression
+# pass are faster. Toggled per run from the UI via set_fast_generation(); fast
+# dims are env-overridable.
+FAST_GENERATION = False
+FAST_BASE_WIDTH = int(os.getenv("ARS_FABULA_FAST_WIDTH", "384"))
+FAST_BASE_HEIGHT = int(os.getenv("ARS_FABULA_FAST_HEIGHT", "672"))
+
+# Expression FaceDetailer params are now UNIFIED across all modes (fast and
+# standard). The only mode difference is base canvas resolution — see
+# _base_dims(). These lighter params (euler, 15 steps, guide_size=256) come
+# from the user's validated expression sheet; the old heavier config
+# (dpm_2_ancestral, 20 steps, guide_size=384) added cost with no quality gain.
+
+
+def set_fast_generation(enabled: bool) -> None:
+    """Enable/disable the lower-resolution fast bake for subsequent runs."""
+    global FAST_GENERATION
+    FAST_GENERATION = bool(enabled)
+
+
+def _base_dims() -> tuple[int, int]:
+    """Base canvas size for the current mode (fast = lower resolution)."""
+    if FAST_GENERATION:
+        return FAST_BASE_WIDTH, FAST_BASE_HEIGHT
+    return BASE_WIDTH, BASE_HEIGHT
+
+
+def _char_dir(key: str) -> str:
+    """Per-character generated-sprite folder for the current mode. Fast (low-
+    res) bakes use a separate '<key>_fast' folder so they never collide with —
+    or get silently reused as — the full-resolution set, and vice versa."""
+    return os.path.join(GENERATED_DIR, f"{key}_fast" if FAST_GENERATION else key)
+
+
+# Fraction of the (matted) image height kept for the on-screen sprite,
+# measured DOWN from the head crown. ~0.62 = head + torso (waist-up).
+UPPER_BODY_FRAC = float(os.getenv("ARS_FABULA_SPRITE_FRAC", "0.62"))
+
+# Face-anchored ZOOMED framing — equal faces, cropped legs, real height gaps.
+# Using the face-gate mask, every sprite is scaled so the detected FACE is the
+# SAME fraction of the SCENE height (FACE_TARGET_FRAC), then composited so the
+# FEET sit FEET_DROP_FACES face-heights BELOW the canvas bottom (the lower legs
+# crop off-screen — the zoom). Equal faces + a shared feet baseline mean a
+# character drawn taller (smaller face ⇒ more face-heights of body) still has
+# their head reach higher in the frame, so implied heights survive the zoom.
+# All sprites share one pixel size, so the UI's uniform height-lock scales them
+# identically. Falls back to the crude alpha-crown crop when no mask exists.
+#
+# GEOMETRY LIMIT: the visible span is (figure-height-in-faces − FEET_DROP_FACES)
+# × FACE_TARGET_FRAC of the scene. The current cast measures 7.6–8.3 faces tall,
+# so 0.13 is the largest face fraction that keeps every crown on-screen with
+# feet at −2 faces; raising it toward 1/5 crops heads at the canvas top.
+FACE_TARGET_FRAC = float(os.getenv("ARS_FABULA_FACE_TARGET", "0.13"))  # face height ÷ SCENE height
+FEET_DROP_FACES = float(os.getenv("ARS_FABULA_FEET_DROP", "2.0"))      # feet this many face-heights below the bottom
+UI_SPRITE_FRAC = 0.86  # .vn-sprite { height: 86% } in ui/styles.py — canvas→scene factor
+SPRITE_CANVAS_MULT = float(os.getenv("ARS_FABULA_SPRITE_CANVAS", "1.4"))  # output canvas size ÷ base size (headroom for tall figures)
+
+# ── Sprite pose block (researched danbooru framing/pose tags) ─────────
+# Locked onto EVERY identity prompt — but ONLY the essentials: framing,
+# eye contact, and a mattable background. Body attitude (slight 3/4
+# angle, hand on hip, arms crossed…) is character design and belongs in
+# the appearance tags; VN sprites are rarely dead-frontal.
+#   upper body        — waist-up framing (the VN sprite standard;
+#                       cowboy_shot = mid-thigh if taller sprites wanted)
+#   standing, looking at viewer — sprite stance + player eye contact
+#                       (eye contact holds even at a slight body angle)
+#   solo              — exactly one character
+#   simple/white background — clean rembg matte
+# Hard angle failures (profile, from behind/above/below) are handled by
+# SPRITE_NEGATIVE instead of over-constraining the positive prompt.
+# NOTE: NO weighted tags — (tag:weight) emphasis is inconsistent on Anima,
+# so everything here is plain comma-separated tags.
+SPRITE_POSE_TAGS = ("solo, full body, standing, full length, "
+                    "looking at viewer, calm expression, "
+                    "simple background, white background")
+
+# Framing failure modes, negated for BASE generation only (the FaceDetailer
+# pass keeps the plain NEGATIVE — these would fight it). We now WANT full
+# body, so the old full-body/legs/cowboy negatives are gone; we still kill
+# wrong camera angles, multi-character, and Anima's "coomer bias"
+# (exaggerated proportions, ADT #106) so the school cast stays normal.
+SPRITE_NEGATIVE = (f"{NEGATIVE}, close-up, portrait, profile, from behind, "
+                   "from above, from below, dutch angle, multiple views, "
+                   "multiple girls, multiple boys, 2girls, 2boys, "
+                   "text, watermark, signature, out of frame")
+
+
+def _spaces_not_underscores(tags: str) -> str:
+    """Underscores break Anima's tag parser — normalize to spaces.
+    (The LLM designer can emit canonical danbooru tags like
+    'looking_at_viewer'; convert them.)"""
+    return tags.replace("_", " ")
+
+
+def build_identity_prompt(appearance_tags: str) -> str:
+    """Quality + style + the character's APPEARANCE tags + the locked pose.
+
+    appearance_tags should describe only the character (1girl/1boy, hair,
+    eyes, build, clothing, accessories, aura) — pose/framing/background
+    come from SPRITE_POSE_TAGS and must not be duplicated or contradicted.
+    """
+    tags = _spaces_not_underscores(appearance_tags.strip().rstrip(","))
+    return f"{QUALITY}, {STYLE_TAGS}. {tags}, {SPRITE_POSE_TAGS}"
+
+
+def _face_anchor(identity_or_tags: str) -> str:
+    """Pull the must-preserve face traits (eye + hair colour) out of a
+    character's tags, so the FaceDetailer keeps them across expressions.
+
+    Returns e.g. "red eyes, silver hair" (either part may be missing)."""
+    parts = []
+    m = re.search(r'([a-z]+(?:\s[a-z]+)?)\s+eyes', identity_or_tags.lower())
+    if m:
+        parts.append(f"{m.group(1).strip()} eyes")
+    m = re.search(r'([a-z]+(?:\s[a-z]+)?)\s+hair', identity_or_tags.lower())
+    if m:
+        parts.append(f"{m.group(1).strip()} hair")
+    return ", ".join(parts)
+
+# Face detector (Impact-Pack UltralyticsDetectorProvider model) — taken
+# verbatim from the validated expression sheet, which confirmed it detects
+# Anima-style faces on this install. If detection ever misses, try an
+# anime-specific model (e.g. yolov8x6_animeface.pt) here.
+ANIME_FACE_MODEL = "bbox/face_yolov8n.pt"
+
+# How many times to regenerate the base (seed bump) if no anime face is found
+FACE_GATE_RETRIES = 2
+
+# ── Preset character templates ────────────────────────────────────────
+
+PRESET_CHARACTERS: dict[str, dict] = {
+    "yuki": {
+        "identity_prompt": build_identity_prompt(
+            "1girl, yuki tanaka, long silver hair, straight hair, "
+            "red eyes, fair skin, flat chest, high school uniform, white shirt, "
+            "blue skirt, red ribbon, gentle expression, quiet reserved aura, "
+            "soft lighting"
+        ),
+        "personality": "Quiet and reserved but a deeply caring girl. Speaks in short sentences. "
+                       "Notices small details about others. Opens up slowly. "
+                       "Has a dry sense of humor that surprises people.",
+        "voice_id": "af_bella",
+        "role": "classmate",
+        "seed": SEED,
+    },
+    "marie": {
+        "identity_prompt": build_identity_prompt(
+            "1girl, marie, long blonde hair, drill hair, blue eyes, "
+            "fair skin, elegant, high school uniform, white shirt, "
+            "blue skirt, red ribbon, refined posture, graceful aura, "
+            "proud expression, ojou-sama"
+        ),
+        "personality": "A refined, well-bred ojou-sama from old money. Proud and "
+                       "elegant, with a signature 'ohohoho' laugh behind a raised "
+                       "hand. Competitive and a touch haughty, but genuinely caring "
+                       "underneath — she'd never admit how much she enjoys company.",
+        "voice_id": "af_sarah",
+        "role": "ojou-sama",
+        "seed": SEED,
+    },
+    "sakura": {
+        "identity_prompt": build_identity_prompt(
+            "1girl, long pink hair, side ponytail, "
+            "green eyes, fair skin, freckles, high school uniform, white shirt, "
+            "pink bow, cheerful genki energy, bubbly"
+        ),
+        "personality": "Cheerful and energetic genki girl. Always smiling. "
+                       "Best friend energy. Gives great hugs. "
+                       "Perceptive despite her bubbly exterior.",
+        "voice_id": "af_sky",
+        "role": "best friend",
+        "seed": SEED,
+    },
+    "ryo": {
+        "identity_prompt": build_identity_prompt(
+            "1boy, ryo akira, short blue hair, sharp eyes, "
+            "tall build, high school uniform, blazer, "
+            "cool aura, sharp gaze, composed"
+        ),
+        "personality": "Cool and aloof on the surface. Secretly a huge romantic. "
+                       "Gives surprisingly good advice. "
+                       "Has a hidden soft spot for cute things.",
+        "voice_id": "am_adam",      # Kokoro male voice
+        "role": "senpai",
+        "seed": SEED,
+    },
+}
+
+# Expression prompts fed to the FaceDetailer. Each is engineered to read
+# DISTINCTLY from the others along three axes — eyes, mouth, brows — plus a
+# signature effect, so the 7 don't blur together:
+#   eyes:  open / soft / >_< squint / wide+shrunk / averted
+#   mouth: closed / slight / open grin / frown / wavy
+#   extra: blush / tears / anger vein / sweatdrops
+# NOTE on closed eyes: the face detector runs on the open-eyed BASE image,
+# THEN inpaints the expression — so closed/squint eyes in the prompt do NOT
+# break detection (earlier worry was wrong). Plain tags only (no weights).
+EXPRESSION_TAGS = {
+    # "neutral" is the DEFAULT sprite (get_sprite falls back here) AND a callable
+    # emotion — deadpan/stoic characters need a true flat affect. We avoid the bare
+    # token "neutral expression" (Anima reads it as grumpy → angry/sad drift) and use
+    # "expressionless" with relaxed brows + closed mouth so it stays flat, not cross.
+    "neutral": "expressionless, calm, looking at viewer, relaxed, closed mouth, level eyebrows",
+    # SMILE = Passive Contentment (Eyes wide and calm, subtle lip curve)
+    "smile": "gentle smile, parted lips, pleasant expression, calm eyes, looking at viewer, serene",
+    # LAUGH = Dynamic Joy (Eyes naturally squinting/crinkling from a wide, open-mouthed grin)
+    "laugh": "joyful laughter, wide open mouth, laughing expression, squinting eyes, crinkling eyes, big happy grin, radiant smile, elevated cheeks",
+    "sad": "sad expression, deep frown, downturned mouth, worried eyebrows, downcast eyes, casting eyes downward, distressed",
+    "angry": "angry glare, slanting v-shaped eyebrows, furrowed brow, gritting teeth, tight jaw, intense eyes, looking at viewer",
+    "surprised": "surprised expression, wide-eyed, shocked, shrunken pupils, slightly open gasping mouth, raised elevated eyebrows",
+    "embarrassed": "embarrassed, heavy blush, (@_@), spiral eyes, averted eyes, flying sweatdrops, nervous",
+}
+
+# Per-expression NEGATIVES, appended to the plain NEGATIVE for the
+# FaceDetailer pass. Each kills that expression's observed failure mode —
+# drifting back toward the base's calm face (laugh rendering as a mild
+# closed-mouth smile, sad as neutral-pleasant, surprised as calm) — without
+# constraining the rest of the set.
+EXPRESSION_NEGATIVE_TAGS = {
+    "laugh": "closed mouth, expressionless, neutral expression, frown, slight smile",
+    "sad": "smile, grin, laughing, happy, cheerful, expressionless",
+    "surprised": "smile, expressionless, calm, half-closed eyes, closed eyes, closed mouth",
+    "angry": "smile, happy, expressionless, calm",
+}
+
+# FaceDetailer strength — the sheet's note: 0.4–0.7, lower = subtler.
+EXPRESSION_DENOISE = 0.6
+# The big-delta expressions need a stronger inpaint to actually commit
+# (at 0.6 they often kept too much of the base's calm face — the source of
+# inconsistent laugh/sad/surprised sets); 0.7 is the top of the sheet's
+# recommended range, identity still held by the anchor + face-only mask.
+EXPRESSION_DENOISE_OVERRIDES = {
+    "laugh": 0.7,
+    "sad": 0.68,
+    "surprised": 0.7,
+}
+
+# Model files (must match the names installed in ComfyUI — taken verbatim
+# from the validated workflow).
+UNET_NAME = "anima-base-v1.0-Q5_K_M.gguf"
+CLIP_NAME = "qwen_3_06b_base.safetensors"
+VAE_NAME = "qwen_image_vae.safetensors"
+SAM_NAME = "sam_vit_b_01ec64.pth"
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# Character design — concept phrase -> appearance tags (LLM or heuristic)
+# ═══════════════════════════════════════════════════════════════════════
+
+FEMALE_VOICES = ["af_bella", "af_sky", "af_nicole", "af_sarah"]
+MALE_VOICES = ["am_michael", "am_adam"]
+
+# Keyword fallbacks for when no LLM is reachable — coarse but coherent.
+_CONCEPT_DESIGNS = [
+    (("childhood friend",), "girl",
+     "1girl, brown hair, medium hair, ahoge, warm brown eyes, fair skin, "
+     "school uniform, white shirt, red ribbon, hands behind back, "
+     "cheerful aura, approachable", "childhood friend"),
+    (("genki", "energetic", "cheerful"), "girl",
+     "1girl, orange hair, short hair, bright eyes, fang, school uniform, "
+     "loose socks, hand on hip, energetic aura, sporty", "genki classmate"),
+    (("shy", "bookworm", "quiet", "library"), "girl",
+     "1girl, dark blue hair, long hair, blunt bangs, glasses, purple eyes, "
+     "cardigan, school uniform, holding book, head tilt, timid aura",
+     "shy bookworm"),
+    (("cool", "aloof", "senpai", "stoic"), "boy",
+     "1boy, black hair, short hair, sharp grey eyes, tall, school uniform, "
+     "blazer, hands in pockets, composed, cool aura", "cool senpai"),
+    (("delinquent", "rebel", "punk"), "boy",
+     "1boy, blonde hair, slicked back hair, sharp eyes, open collar, "
+     "school uniform, untucked shirt, piercing, hands in pockets, "
+     "rough aura", "delinquent"),
+    (("class rep", "president", "strict"), "girl",
+     "1girl, black hair, long hair, hime cut, serious eyes, school uniform, "
+     "armband, own hands together, neat, dignified aura",
+     "class representative"),
+    (("gyaru", "gal",), "girl",
+     "1girl, blonde hair, long wavy hair, tan skin, nail polish, "
+     "school uniform, loose ribbon, accessories, hand on hip, "
+     "confident aura", "gyaru"),
+    (("athlete", "sporty", "club"), "boy",
+     "1boy, brown hair, very short hair, tan skin, athletic build, "
+     "school uniform, sports towel, arms crossed, energetic aura",
+     "athlete"),
+]
+
+_DEFAULT_DESIGN = ("girl",
+                   "1girl, {hair} hair, expressive eyes, fair skin, "
+                   "school uniform, white shirt",
+                   "classmate")
+_HAIR_ROTATION = ["chestnut", "ash blonde", "teal", "auburn", "lavender", "black"]
+
+
+def _stable_seed(*parts: str) -> int:
+    import zlib
+    return zlib.crc32("|".join(parts).encode("utf-8")) & 0x7FFFFFFF
+
+
+def _heuristic_design(name: str, concept: str) -> dict:
+    """No-LLM fallback: map concept keywords to a coherent design."""
+    low = (concept or "").lower()
+    if any(k in low for k in ("boy", "male", "guy", "him", "prince", "butler")):
+        forced_gender = "boy"
+    elif any(k in low for k in ("girl", "female", "her", "princess", "maid")):
+        forced_gender = "girl"
+    else:
+        forced_gender = None
+
+    for keywords, gender, tags, role in _CONCEPT_DESIGNS:
+        if any(k in low for k in keywords):
+            if forced_gender and forced_gender != gender:
+                tags = tags.replace("1girl", "1boy") if forced_gender == "boy" \
+                    else tags.replace("1boy", "1girl")
+                gender = forced_gender
+            return {"gender": gender, "tags": tags, "role": role,
+                    "personality": concept or f"{name} — {role}."}
+
+    gender, tags, role = _DEFAULT_DESIGN
+    gender = forced_gender or gender
+    hair = _HAIR_ROTATION[_stable_seed(name, concept) % len(_HAIR_ROTATION)]
+    tags = tags.format(hair=hair)
+    if gender == "boy":
+        tags = tags.replace("1girl", "1boy")
+    return {"gender": gender, "tags": tags, "role": role,
+            "personality": concept or f"{name}, a {role}."}
+
+
+def design_character(name: str, concept: str) -> dict:
+    """Concept phrase -> {gender, tags, personality, role}.
+
+    Uses the story LLM when reachable (CHARACTER_DESIGNER_PROMPT,
+    strict-JSON reply); falls back to the keyword heuristics so the
+    casting beat never blocks on a missing server.
+    """
+    try:
+        from model_client import get_model, ModelConfig
+        from vn_prompt import CHARACTER_DESIGNER_PROMPT
+        cfg = ModelConfig.from_env()
+        if cfg.backend != "mock":
+            client = get_model(cfg)
+            if client.health():
+                raw = client.generate([
+                    {"role": "system", "content": CHARACTER_DESIGNER_PROMPT},
+                    {"role": "user", "content": f"Name: {name}\nConcept: {concept}"},
+                ]) or ""
+                start, end = raw.find("{"), raw.rfind("}")
+                if start != -1 and end > start:
+                    data = json.loads(raw[start:end + 1])
+                    tags = str(data.get("tags", "")).strip()
+                    if tags and ("1girl" in tags or "1boy" in tags):
+                        return {
+                            "gender": "boy" if "1boy" in tags else "girl",
+                            "tags": tags,
+                            "personality": str(data.get("personality", concept)).strip()
+                                           or concept,
+                            "role": str(data.get("role", "classmate")).strip()
+                                    or "classmate",
+                        }
+                print(f"  [cast] LLM design for '{name}' unusable — using heuristics")
+    except Exception as e:
+        print(f"  [cast] LLM design failed for '{name}' ({e}) — using heuristics")
+    return _heuristic_design(name, concept)
+
+
+def build_custom_specs(cards: list[dict]) -> list[tuple[str, dict]]:
+    """Turn UI character cards into (cache_key, preset) specs.
+
+    Card fields: name (required), concept (regular mode), tags (advanced
+    mode — overrides the designer; pose block still appended).
+    The cache key embeds a hash of the final prompt, so editing a
+    character's design automatically invalidates their sprite cache.
+    """
+    import hashlib
+    specs: list[tuple[str, dict]] = []
+    voice_idx = {"girl": 0, "boy": 0}
+
+    for i, card in enumerate(cards):
+        name = (card.get("name") or "").strip()
+        if not name:
+            continue
+        concept = (card.get("concept") or "").strip()
+        adv_tags = (card.get("tags") or "").strip()
+
+        if adv_tags:   # advanced mode: tags are authoritative
+            gender = "boy" if "1boy" in adv_tags else "girl"
+            design = {"gender": gender, "tags": adv_tags,
+                      "personality": concept or f"{name}.",
+                      "role": concept.split(",")[0][:24] if concept else "custom"}
+        else:
+            design = design_character(name, concept)
+
+        pool = MALE_VOICES if design["gender"] == "boy" else FEMALE_VOICES
+        voice = pool[voice_idx[design["gender"]] % len(pool)]
+        voice_idx[design["gender"]] += 1
+
+        identity_prompt = build_identity_prompt(design["tags"])
+        slug = "".join(ch for ch in name.lower() if ch.isalnum()) or f"char{i}"
+        key = f"{slug}_{hashlib.md5(identity_prompt.encode()).hexdigest()[:8]}"
+
+        specs.append((key, {
+            "name": name,
+            "identity_prompt": identity_prompt,
+            "personality": design["personality"],
+            "voice_id": voice,
+            "role": design["role"],
+            "seed": SEED,
+        }))
+    return specs
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# ComfyUI helpers
+# ═══════════════════════════════════════════════════════════════════════
+
+_COMFY_SESSION = None
+
+
+def _session():
+    """Shared requests session for ComfyUI.
+
+    trust_env=False is the important part: it makes requests IGNORE
+    http_proxy/https_proxy environment variables (common on corporate
+    machines), which otherwise hijack even 127.0.0.1 traffic and kill
+    POSTs with [Errno 32] Broken pipe while GETs appear to work.
+    """
+    global _COMFY_SESSION
+    if _COMFY_SESSION is None:
+        import requests
+        s = requests.Session()
+        s.trust_env = False
+        _COMFY_SESSION = s
+    return _COMFY_SESSION
+
+
+def _comfy_upload(path: str, name: str) -> dict:
+    """Upload an image to ComfyUI's input folder.
+
+    Uses `requests` with a proper multipart encoder — the previous
+    hand-rolled multipart body could make aiohttp drop the connection
+    mid-write (the "broken pipe"). `overwrite=true` matters: without it,
+    re-uploading the same filename makes ComfyUI save a renamed copy and
+    the workflow's LoadImage silently keeps reading the OLD image.
+    """
+    with open(path, "rb") as f:
+        resp = _session().post(
+            f"{COMFY_HOST}/upload/image",
+            files={"image": (name, f, "image/png")},
+            data={"overwrite": "true"},
+            timeout=60,
+        )
+    if not resp.ok:
+        raise RuntimeError(
+            f"ComfyUI upload of '{name}' failed: HTTP {resp.status_code} — {resp.text[:300]}")
+    return resp.json()
+
+
+def _comfy_submit(workflow: dict, client_id: str) -> str:
+    """Submit a workflow to ComfyUI and return the prompt_id.
+
+    On a 400, surfaces ComfyUI's validation error (bad node class, missing
+    model file, wrong input name) instead of dying with a transport error.
+    """
+    resp = _session().post(
+        f"{COMFY_HOST}/prompt",
+        json={"prompt": workflow, "client_id": client_id},
+        timeout=60,
+    )
+    if not resp.ok:
+        raise RuntimeError(
+            f"ComfyUI rejected workflow '{client_id}': HTTP {resp.status_code} — {resp.text[:1000]}")
+    return resp.json()["prompt_id"]
+
+
+def _comfy_wait(prompt_id: str, timeout: int = 180) -> Optional[dict]:
+    """Wait for a ComfyUI prompt to finish.
+
+    Returns the first output image's info dict ({filename, subfolder, type})
+    or None. Doesn't rely on the 'completed' status flag (absent in some
+    ComfyUI versions) — the presence of outputs is the ground truth — and
+    prints execution errors from the history so failures aren't silent.
+    """
+    for i in range(timeout // 2):
+        time.sleep(2)
+        try:
+            hist = _session().get(f"{COMFY_HOST}/history/{prompt_id}", timeout=15).json()
+        except Exception:
+            continue
+        if prompt_id not in hist:
+            continue
+        entry = hist[prompt_id]
+
+        # Outputs present → done, regardless of what status says
+        for nout in (entry.get("outputs") or {}).values():
+            for img in nout.get("images", []):
+                return img
+
+        # Surface execution errors instead of timing out silently
+        status = entry.get("status") or {}
+        for msg in status.get("messages", []):
+            if isinstance(msg, (list, tuple)) and msg and msg[0] == "execution_error":
+                detail = msg[1] if len(msg) > 1 else {}
+                print(f"  [cast] ComfyUI execution error in node "
+                      f"{detail.get('node_type', '?')}: "
+                      f"{detail.get('exception_message', detail)}")
+                return None
+        if status.get("status_str") == "error":
+            print(f"  [cast] ComfyUI reported an error for prompt {prompt_id}: {status}")
+            return None
+        if status.get("completed"):
+            return None   # finished with no image outputs
+    print(f"  [cast] Timed out waiting for prompt {prompt_id}")
+    return None
+
+
+def _comfy_fetch_image(img_info: dict, dest_path: str) -> Optional[str]:
+    """Download a generated image from ComfyUI via its /view endpoint.
+
+    This replaces copying from a guessed output directory on disk — which
+    breaks whenever ComfyUI lives somewhere else (or SaveImage used a
+    subfolder). Works regardless of where/how ComfyUI is installed.
+    """
+    try:
+        resp = _session().get(
+            f"{COMFY_HOST}/view",
+            params={
+                "filename": img_info.get("filename", ""),
+                "subfolder": img_info.get("subfolder", ""),
+                "type": img_info.get("type", "output"),
+            },
+            timeout=60,
+        )
+        if not resp.ok:
+            print(f"  [cast] /view fetch failed: HTTP {resp.status_code} for {img_info}")
+            return None
+        os.makedirs(os.path.dirname(dest_path), exist_ok=True)
+        with open(dest_path, "wb") as f:
+            f.write(resp.content)
+        return dest_path
+    except Exception as e:
+        print(f"  [cast] /view fetch failed for {img_info}: {e}")
+        return None
+
+
+def _comfy_health() -> bool:
+    """Check if ComfyUI is reachable (proxy-bypassing, like all other calls)."""
+    try:
+        return _session().get(f"{COMFY_HOST}/system_stats", timeout=3).ok
+    except Exception:
+        return False
+
+
+def comfy_free_vram() -> bool:
+    """Unload ComfyUI's models from VRAM via its /free endpoint.
+
+    Called after a cast bake so the scene LLM has the GPU to itself.
+    ComfyUI reloads its models lazily on the next /prompt, so this is safe
+    to call between casting beats. No-op if ComfyUI isn't reachable.
+    """
+    try:
+        r = _session().post(f"{COMFY_HOST}/free",
+                            json={"unload_models": True, "free_memory": True},
+                            timeout=20)
+        if r.ok:
+            print("[vram] ComfyUI models unloaded (/free)")
+            return True
+    except Exception as e:
+        print(f"[vram] ComfyUI /free failed (ignored): {e}")
+    return False
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# Base generation (txt2img)
+# ═══════════════════════════════════════════════════════════════════════
+
+def _generate_base(character_key: str, preset: dict, out_dir: str,
+                   seed: Optional[int] = None) -> Optional[str]:
+    """Generate base character image via ComfyUI txt2img.
+
+    Returns path to the generated base PNG, or None on failure.
+    """
+    os.makedirs(out_dir, exist_ok=True)
+    out_path = os.path.join(out_dir, f"{character_key}_base.png")
+    seed = preset["seed"] if seed is None else seed
+    base_w, base_h = _base_dims()
+
+    workflow = {
+        "1": {"inputs": {"filename_prefix": f"base_{character_key}", "images": ["8", 0]}, "class_type": "SaveImage"},
+        "8": {"inputs": {"samples": ["19", 0], "vae": ["15", 0]}, "class_type": "VAEDecode"},
+        "11": {"inputs": {"text": preset["identity_prompt"], "clip": ["45", 0]}, "class_type": "CLIPTextEncode"},
+        "12": {"inputs": {"text": SPRITE_NEGATIVE, "clip": ["45", 0]}, "class_type": "CLIPTextEncode"},
+        "15": {"inputs": {"vae_name": VAE_NAME}, "class_type": "VAELoader"},
+        "19": {"inputs": {
+            "seed": seed, "steps": 30, "cfg": 4.0,
+            "sampler_name": SAMPLER, "scheduler": SCHEDULER, "denoise": 1.0,
+            "model": ["44", 0], "positive": ["11", 0], "negative": ["12", 0],
+            "latent_image": ["28", 0],
+        }, "class_type": "KSampler"},
+        "28": {"inputs": {"width": base_w, "height": base_h, "batch_size": 1}, "class_type": "EmptyLatentImage"},
+        "44": {"inputs": {"unet_name": UNET_NAME}, "class_type": "UnetLoaderGGUF"},
+        "45": {"inputs": {"clip_name": CLIP_NAME, "type": "stable_diffusion", "device": "default"}, "class_type": "CLIPLoader"},
+    }
+
+    pid = _comfy_submit(workflow, f"base_{character_key}")
+    result = _comfy_wait(pid)
+    if result and _comfy_fetch_image(result, out_path):
+        print(f"  [cast] Generated base for {character_key} (seed={seed}): {out_path}")
+        return out_path
+    return None
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# Anime face detection gate
+# ═══════════════════════════════════════════════════════════════════════
+
+def _detect_anime_face(base_path: str, character_key: str) -> Optional[bool]:
+    """Check the base image contains a detectable anime face.
+
+    Runs an Impact-Pack detector workflow with the ANIME face model and
+    inspects the combined detection mask: non-empty mask == face found.
+
+    Returns:
+        True  — anime face detected
+        False — no face detected (caller should retry base gen)
+        None  — gate unavailable (node/model missing); caller proceeds
+    """
+    try:
+        _comfy_upload(base_path, f"{character_key}_base.png")
+    except Exception as e:
+        print(f"  [cast] Face gate upload failed ({e}); proceeding without gate")
+        return None
+
+    workflow = {
+        "10": {"inputs": {"image": f"{character_key}_base.png"}, "class_type": "LoadImage"},
+        "70": {"inputs": {"model_name": ANIME_FACE_MODEL}, "class_type": "UltralyticsDetectorProvider"},
+        "71": {"inputs": {
+            "bbox_detector": ["70", 0], "image": ["10", 0],
+            "threshold": 0.3, "dilation": 0, "crop_factor": 1.0,
+            "drop_size": 10, "labels": "all",
+        }, "class_type": "BboxDetectorSEGS"},
+        "72": {"inputs": {"segs": ["71", 0]}, "class_type": "SegsToCombinedMask"},
+        "73": {"inputs": {"mask": ["72", 0]}, "class_type": "MaskToImage"},
+        "74": {"inputs": {"filename_prefix": f"facegate_{character_key}", "images": ["73", 0]}, "class_type": "SaveImage"},
+    }
+
+    try:
+        pid = _comfy_submit(workflow, f"facegate_{character_key}")
+    except Exception as e:
+        print(f"  [cast] Face gate unavailable ({e}); proceeding without gate")
+        return None
+
+    result = _comfy_wait(pid, timeout=60)
+    if not result:
+        print(f"  [cast] Face gate produced no output; proceeding without gate")
+        return None
+
+    mask_path = os.path.join(_char_dir(character_key), "_facegate_mask.png")
+    if not _comfy_fetch_image(result, mask_path):
+        print(f"  [cast] Face gate mask fetch failed; proceeding without gate")
+        return None
+    try:
+        from PIL import Image
+        with Image.open(mask_path) as img:
+            extrema = img.convert("L").getextrema()
+        return extrema[1] > 0   # any non-black pixel => a face was detected
+    except Exception as e:
+        print(f"  [cast] Face gate mask check failed ({e}); proceeding without gate")
+        return None
+
+
+def _generate_base_with_face_gate(character_key: str, preset: dict, out_dir: str) -> Optional[str]:
+    """Base gen + anime-face-detect gate, retrying with bumped seeds."""
+    for attempt in range(FACE_GATE_RETRIES + 1):
+        seed = preset["seed"] + attempt
+        base_path = _generate_base(character_key, preset, out_dir, seed=seed)
+        if not base_path:
+            return None
+        detected = _detect_anime_face(base_path, character_key)
+        if detected is not False:   # True, or gate unavailable
+            if detected is True:
+                print(f"  [cast] Anime face confirmed for {character_key}")
+            return base_path
+        print(f"  [cast] No anime face in {character_key} base "
+              f"(attempt {attempt + 1}/{FACE_GATE_RETRIES + 1}); regenerating...")
+    print(f"  [cast] Face gate failed for {character_key} after retries; using last base")
+    return base_path
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# Expression generation via FaceDetailer (the validated expression sheet)
+# ═══════════════════════════════════════════════════════════════════════
+
+def _generate_expression(base_path: str, character_key: str, expr_name: str,
+                         expr_tags: str, seed: int, anchor: str = "") -> Optional[str]:
+    """Generate a single expression with the validated FaceDetailer sheet
+    (tools/workflows/anima_expression_sheet.json, API form).
+
+    Only the detected face region is re-generated with the expression
+    prompt — body, clothes and background stay identical, which is what
+    preserves identity across the set. `anchor` (eye/hair colour) is folded
+    into the prompt so those traits don't drift across expressions.
+
+    Returns path to the expression PNG, or None on failure.
+    """
+    out_dir = _char_dir(character_key)
+    os.makedirs(out_dir, exist_ok=True)
+    out_path = os.path.join(out_dir, f"{character_key}_{expr_name}.png")
+
+    # neutral == the base itself, just copied through (base prompts are
+    # already neutral-faced; copying beats re-generating for identity)
+    if expr_name == "neutral":
+        shutil.copy2(base_path, out_path)
+        return out_path
+
+    _comfy_upload(base_path, f"{character_key}_base.png")
+
+    anchor_part = f"{anchor}, " if anchor else ""
+    expr_prompt = f"{QUALITY}, {STYLE_TAGS}. {anchor_part}{expr_tags}"
+
+    # Per-expression strength + negatives (see EXPRESSION_DENOISE_OVERRIDES /
+    # EXPRESSION_NEGATIVE_TAGS): big-delta expressions inpaint harder and
+    # negate their drift-back-to-calm failure mode.
+    denoise = EXPRESSION_DENOISE_OVERRIDES.get(expr_name, EXPRESSION_DENOISE)
+    expr_negative = NEGATIVE
+    if expr_name in EXPRESSION_NEGATIVE_TAGS:
+        expr_negative = f"{NEGATIVE}, {EXPRESSION_NEGATIVE_TAGS[expr_name]}"
+
+    # FaceDetailer inputs — unified across all modes (see the module-level
+    # comment above; only base resolution differs per mode).
+    # Unified FaceDetailer params from the validated expression sheet.
+    # Lighter than the old heavier config (guide_size 384→256, steps 20→15,
+    # dpm_2_ancestral→euler) with no quality loss. bbox_threshold 0.5 catches
+    # expressions reliably (was 0.3 with more dilation/crop to compensate).
+    _fd_inputs = {
+        "image": ["10", 0], "model": ["44", 0], "clip": ["45", 0], "vae": ["15", 0],
+        "guide_size": 256, "guide_size_for": True, "max_size": 384,
+        "seed": seed, "steps": 15, "cfg": 4.0,
+        "sampler_name": "euler", "scheduler": SCHEDULER,
+        "positive": ["11", 0], "negative": ["12", 0],
+        "denoise": denoise, "feather": 15,
+        "noise_mask": True, "force_inpaint": True,
+        "bbox_threshold": 0.5, "bbox_dilation": 25, "bbox_crop_factor": 2.0,
+        "sam_detection_hint": "center-1", "sam_dilation": 0,
+        "sam_threshold": 0.93, "sam_bbox_expansion": 0,
+        "sam_mask_hint_threshold": 0.7, "sam_mask_hint_use_negative": "False",
+        "drop_size": 10, "wildcard": "", "cycle": 1,
+        "noise_mask_feather": 20,
+        "bbox_detector": ["70", 0], "sam_model_opt": ["73", 0],
+    }
+
+    workflow = {
+        "10": {"inputs": {"image": f"{character_key}_base.png"}, "class_type": "LoadImage"},
+        "11": {"inputs": {"text": expr_prompt, "clip": ["45", 0]}, "class_type": "CLIPTextEncode"},
+        "12": {"inputs": {"text": expr_negative, "clip": ["45", 0]}, "class_type": "CLIPTextEncode"},
+        "15": {"inputs": {"vae_name": VAE_NAME}, "class_type": "VAELoader"},
+        "44": {"inputs": {"unet_name": UNET_NAME}, "class_type": "UnetLoaderGGUF"},
+        "45": {"inputs": {"clip_name": CLIP_NAME, "type": "stable_diffusion", "device": "default"}, "class_type": "CLIPLoader"},
+        "70": {"inputs": {"model_name": ANIME_FACE_MODEL}, "class_type": "UltralyticsDetectorProvider"},
+        "73": {"inputs": {"model_name": SAM_NAME, "device_mode": "AUTO"}, "class_type": "SAMLoader"},
+        "80": {"inputs": _fd_inputs, "class_type": "FaceDetailer"},
+        "1": {"inputs": {"filename_prefix": f"{character_key}_{expr_name}", "images": ["80", 0]}, "class_type": "SaveImage"},
+    }
+
+    pid = _comfy_submit(workflow, f"{character_key}_{expr_name}_{seed}")
+    result = _comfy_wait(pid, timeout=200)
+    if result and _comfy_fetch_image(result, out_path):
+        return out_path
+    return None
+
+
+# Per-expression retry count on failure (bumped seed). 0 = no retry.
+EXPRESSION_RETRIES = 1
+
+
+def _generate_expression_retry(base_path: str, character_key: str,
+                               expr_name: str, expr_tags: str,
+                               seed: int, anchor: str = "") -> Optional[str]:
+    """Generate one expression, retrying with a bumped seed if it fails
+    (transient face-detect miss / empty output). Self-heals the occasional
+    'laugh didn't generate' without re-running the whole cast."""
+    for attempt in range(EXPRESSION_RETRIES + 1):
+        path = _generate_expression(base_path, character_key, expr_name,
+                                    expr_tags, seed + attempt * 1000, anchor=anchor)
+        if path:
+            return path
+        if attempt < EXPRESSION_RETRIES:
+            print(f"    {expr_name}: empty/failed — retrying with bumped seed")
+    return None
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# Background removal (rembg isnet-anime)
+# ═══════════════════════════════════════════════════════════════════════
+
+_REMBG_SESSION = None
+
+
+def _get_rembg_session():
+    """Lazily create (and cache) the isnet-anime rembg session."""
+    global _REMBG_SESSION
+    if _REMBG_SESSION is None:
+        from rembg import new_session
+        _REMBG_SESSION = new_session("isnet-anime")
+    return _REMBG_SESSION
+
+
+_REMBG_WARNED = False
+
+
+def _warn_rembg_missing(detail: str) -> None:
+    """One-time, prominent, actionable warning — silent failure here is why
+    sprites came out with white backgrounds."""
+    global _REMBG_WARNED
+    if _REMBG_WARNED:
+        return
+    _REMBG_WARNED = True
+    print("\n" + "!" * 64)
+    print("  [cast] BACKGROUND REMOVAL DID NOT RUN — sprites will keep their")
+    print(f"         white background. Reason: {detail}")
+    print("         Install it INTO THIS venv (rembg + an onnxruntime):")
+    print("           .venv/bin/pip install rembg onnxruntime")
+    print("         (use onnxruntime-gpu instead for CUDA). The isnet-anime")
+    print("         model at ~/.u2net/isnet-anime.pth is already present.")
+    print("!" * 64 + "\n")
+
+
+def _has_transparency(path: str) -> bool:
+    try:
+        from PIL import Image
+        with Image.open(path) as img:
+            if img.mode not in ("RGBA", "LA", "PA"):
+                return False
+            alpha = img.convert("RGBA").getchannel("A").getextrema()
+        return alpha[0] < 250   # some pixel is meaningfully transparent
+    except Exception:
+        return False
+
+
+def _remove_bg(input_path: str) -> Optional[str]:
+    """Remove background using rembg with the isnet-anime matte.
+
+    Overwrites the input in-place with an RGBA PNG. Uses the rembg 2.x
+    session API (`new_session("isnet-anime")` — the old `model_name=`
+    kwarg no longer exists and would silently skip matting). Verifies the
+    output actually became transparent; warns loudly if not.
+    """
+    out_path = input_path
+    try:
+        from rembg import remove
+    except ImportError:
+        _warn_rembg_missing("`import rembg` failed (not installed in this venv)")
+        return input_path
+
+    try:
+        with open(input_path, "rb") as f:
+            img_data = f.read()
+        try:
+            result = remove(img_data, session=_get_rembg_session())
+        except Exception as e:
+            print(f"  [cast] isnet-anime session failed ({e}); trying default rembg model")
+            result = remove(img_data)
+        with open(out_path, "wb") as f:
+            f.write(result)
+        if not _has_transparency(out_path):
+            _warn_rembg_missing("rembg ran but produced no transparency "
+                                "(onnxruntime missing/broken, or model failed to load)")
+        return out_path
+    except Exception as e:
+        _warn_rembg_missing(f"rembg error: {e}")
+        return input_path
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# Public API
+# ═══════════════════════════════════════════════════════════════════════
+
+def _frame_upper_body(char_dir: str, key: str,
+                      frac: Optional[float] = None, pad: int = 12) -> None:
+    """Crop a character's full-body renders to a consistent waist-up sprite.
+
+    Vertical: anchored on the head crown (union alpha-bbox TOP) and a FIXED
+    height (frac × image height) down from it — so the head sits at the same
+    place and the framing is identical across the whole cast.
+    Horizontal: the character's union extent + padding (trims side
+    whitespace; widths may differ per character, which is fine — the UI
+    height-locks sprites).
+    The SAME box is applied to all 7 expressions so they don't jump on swap.
+    """
+    try:
+        from PIL import Image
+    except ImportError:
+        return
+    frac = UPPER_BODY_FRAC if frac is None else frac
+
+    paths = [os.path.join(char_dir, f"{key}_{e}.png") for e in STANDARD_EXPRESSIONS]
+    paths = [p for p in paths if os.path.exists(p)]
+    if not paths:
+        return
+
+    # Union alpha bbox across the set → stable crown + horizontal extent
+    union = None
+    H = W = 0
+    for p in paths:
+        with Image.open(p) as img:
+            rgba = img.convert("RGBA")
+            W, H = rgba.size
+            bbox = rgba.getchannel("A").getbbox()
+        if bbox:
+            union = bbox if union is None else (
+                min(union[0], bbox[0]), min(union[1], bbox[1]),
+                max(union[2], bbox[2]), max(union[3], bbox[3]),
+            )
+    if union is None:
+        return
+
+    # Detected face height (base px), from the face-gate mask if present.
+    face_h = None
+    mask_path = os.path.join(char_dir, "_facegate_mask.png")
+    if os.path.exists(mask_path):
+        try:
+            with Image.open(mask_path) as m:
+                ml = m.convert("L")
+                _, mH = ml.size
+                fb = ml.getbbox()           # bbox of the white (detected-face) region
+            if fb and mH:
+                face_h = (fb[3] - fb[1]) * (H / mH)   # scale mask→sprite if res differs
+        except Exception as e:
+            print(f"  [cast] face mask unusable for {key} ({e}); crude crop")
+
+    if face_h and face_h > 1:
+        # FACE-NORMALIZED ZOOMED bake: every face = FACE_TARGET_FRAC of the
+        # SCENE height (the UI shows the canvas at UI_SPRITE_FRAC of the
+        # screen, so the canvas target is FACE_TARGET_FRAC / UI_SPRITE_FRAC),
+        # and the FEET sit FEET_DROP_FACES face-heights BELOW the canvas
+        # bottom (lower legs crop off — the zoom-in). Equal faces + shared
+        # feet baseline ⇒ taller figures' heads still reach higher.
+        H0 = int(H * SPRITE_CANVAS_MULT)
+        face_px = H0 * FACE_TARGET_FRAC / UI_SPRITE_FRAC   # target face height on canvas
+        scale = face_px / face_h
+        # Canvas WIDTH grows to fit the scaled figure (wide poses — drill hair,
+        # full skirts — must never hit the vertical edges; a hard clip line
+        # mid-screen looks broken). Heights stay uniform across the cast, which
+        # is what keeps faces equal under the UI height-lock; widths may vary.
+        fig_w = (union[2] - union[0]) * scale
+        W0 = max(int(W * SPRITE_CANVAS_MULT), int(fig_w) + 1 + 2 * pad)
+        cx = (union[0] + union[2]) / 2.0               # figure center-x (base px)
+        off_x = int(round(W0 / 2.0 - cx * scale))      # center horizontally
+        # union bottom (feet) lands FEET_DROP_FACES faces below the canvas edge
+        off_y = int(round(H0 + FEET_DROP_FACES * face_px - union[3] * scale))
+        sw, sh = max(1, int(round(W * scale))), max(1, int(round(H * scale)))
+        crown_clip = -(off_y + union[1] * scale)       # px of head above the canvas top
+        for p in paths:
+            with Image.open(p) as img:
+                resized = img.convert("RGBA").resize((sw, sh), Image.LANCZOS)
+            canvas = Image.new("RGBA", (W0, H0), (0, 0, 0, 0))
+            canvas.paste(resized, (off_x, off_y), resized)   # mask = alpha; clips overflow
+            canvas.save(p)
+        print(f"  [cast] Framed {len(paths)} sprites for {key} "
+              f"(face-normalized zoom, scale={scale:.2f}, face={face_h:.0f}px → "
+              f"{FACE_TARGET_FRAC:.0%} of scene, feet at -{FEET_DROP_FACES:g} faces, {W0}x{H0})")
+        if crown_clip > 1:
+            print(f"  [cast] WARNING: {key}'s crown overflows the canvas top by "
+                  f"{crown_clip:.0f}px — lower ARS_FABULA_FACE_TARGET or ARS_FABULA_FEET_DROP")
+        return
+
+    # ── Fallback: crude alpha-crown + fixed-fraction crop (no usable mask) ──
+    crown_y = max(0, union[1] - pad)
+    crop_h = int(H * frac)
+    bottom = min(H, crown_y + crop_h)
+    left = max(0, union[0] - pad)
+    right = min(W, union[2] + pad)
+    box = (left, crown_y, right, bottom)
+    for p in paths:
+        with Image.open(p) as img:
+            img.convert("RGBA").crop(box).save(p)
+    print(f"  [cast] Framed {len(paths)} sprites for {key} (alpha-crown crop) to {box}")
+
+
+# Back-compat alias: tools/recrop_sprites.py calls _autocrop_sprite_set.
+_autocrop_sprite_set = _frame_upper_body
+
+
+def generate_cast(preferences: Optional[dict] = None) -> list[CastMember]:
+    """Generate a full cast via ComfyUI (or fall back to curated).
+
+    This is the main entry point for the casting beat. It:
+    1. Decides which 3-4 characters to generate based on preferences
+    2. Generates base images (anime-face-gated) + warped expression sets
+    3. Removes backgrounds for alpha compositing
+    4. Returns locked CastMember objects
+
+    Args:
+        preferences: Optional dict with keys like "mood", "preferences",
+            "preset", "characters".
+
+    Returns:
+        list[CastMember] with expression_map filled (frozen contract).
+    """
+    # Decide the cast specs: custom cards take precedence over presets.
+    # VRAM choreography (LLM and diffusion can't co-reside):
+    #   custom mode needs the design LLM first, so free ComfyUI to make room
+    #   for it; preset mode designs nothing and skips that step.
+    if preferences and preferences.get("custom_cast"):
+        comfy_free_vram()                       # room for the design LLM
+        try:                                    # bring the LLM up if a prior bake killed it
+            from model_client import ensure_llm
+            ensure_llm(timeout=300)
+        except Exception as e:
+            print(f"[cast] ensure_llm before design failed ({e}); designing with heuristics")
+        specs = build_custom_specs(preferences["custom_cast"])   # LLM designs
+        if not specs:
+            specs = [(k, PRESET_CHARACTERS[k]) for k in ["yuki", "marie", "sakura"]]
+    else:
+        if preferences and "preset" in preferences:
+            char_keys = _get_preset_chars(preferences["preset"])
+        elif preferences and "characters" in preferences:
+            char_keys = preferences["characters"]
+        else:
+            char_keys = ["yuki", "marie", "sakura"]  # Default 3-character cast
+        specs = [(k, PRESET_CHARACTERS[k]) for k in char_keys
+                 if k in PRESET_CHARACTERS]
+
+    # Try ComfyUI generation
+    comfy_ok = _comfy_health()
+    if comfy_ok:
+        # Only a real bake loads diffusion models — a fully-cached reuse
+        # doesn't, so don't needlessly evict the LLM in that case.
+        will_bake = bool(os.getenv("ARS_FABULA_REGEN")) or \
+            not all(_generated_complete(k) for k, _ in specs)
+        if will_bake:
+            # Evict the LLM before ComfyUI loads its models — covers both the
+            # design LLM just used (custom mode) and one left resident from a
+            # prior scene (Reset → regenerate).
+            from model_client import release_vram
+            release_vram()
+        print("[cast] ComfyUI reachable — generating cast...")
+        return _generate_via_comfy(specs)
+
+    # ComfyUI down — previously baked sprites beat placeholders
+    if all(_generated_complete(k) for k, _ in specs):
+        print("[cast] ComfyUI not available — using previously generated sprites.")
+        return [_load_generated_member(k, p) for k, p in specs]
+
+    # Fall back to curated (presets) / placeholders (custom)
+    print("[cast] ComfyUI not available — using curated/placeholder cast.")
+    out: list[CastMember] = []
+    for k, p in specs:
+        if k in PRESET_CHARACTERS:
+            out.extend(load_curated_cast([k]))
+        else:
+            out.append(_placeholder_member(k, p))
+    return out
+
+
+def load_curated_cast(char_keys: Optional[list[str]] = None) -> list[CastMember]:
+    """Load pre-made character sprites from the curated directory.
+
+    Each character has a folder under static/sprites/curated/<name>/
+    with PNG files named <name>_<expression>.png
+
+    Args:
+        char_keys: Optional list of character keys to load. Defaults to all.
+
+    Returns:
+        list[CastMember] with loaded sprite paths (frozen contract).
+    """
+    if char_keys is None:
+        char_keys = list(PRESET_CHARACTERS.keys())
+
+    cast: list[CastMember] = []
+    for key in char_keys:
+        preset = PRESET_CHARACTERS.get(key)
+        if not preset:
+            continue
+
+        member = _build_member(key, preset)
+
+        # Check curated folder
+        curated_char_dir = os.path.join(CURATED_DIR, key)
+        if os.path.isdir(curated_char_dir):
+            for expr in STANDARD_EXPRESSIONS:
+                expr_path = os.path.join(curated_char_dir, f"{key}_{expr}.png")
+                if os.path.exists(expr_path):
+                    member.expression_map[expr] = expr_path
+
+        # If missing expressions, use generated directory
+        generated_char_dir = os.path.join(GENERATED_DIR, key)
+        if os.path.isdir(generated_char_dir):
+            for expr in STANDARD_EXPRESSIONS:
+                if expr not in member.expression_map:
+                    expr_path = os.path.join(generated_char_dir, f"{key}_{expr}.png")
+                    if os.path.exists(expr_path):
+                        member.expression_map[expr] = expr_path
+
+        # If still missing, create placeholder sprites
+        for expr in STANDARD_EXPRESSIONS:
+            if expr not in member.expression_map:
+                placeholder = _make_placeholder_sprite(key, expr, member)
+                if placeholder:
+                    member.expression_map[expr] = placeholder
+
+        cast.append(member)
+
+    return cast
+
+
+def _build_member(key: str, preset: dict) -> CastMember:
+    character = Character(
+        name=preset.get("name", key.capitalize()),
+        identity_prompt=preset["identity_prompt"],
+        seed=preset["seed"],
+        personality=preset["personality"],
+        voice_id=preset["voice_id"],
+        role=preset["role"],
+    )
+    return CastMember(character=character)
+
+
+def _placeholder_member(key: str, preset: dict) -> CastMember:
+    """A custom character with placeholder sprites (no ComfyUI, no curated art)."""
+    member = _build_member(key, preset)
+    for expr in STANDARD_EXPRESSIONS:
+        placeholder = _make_placeholder_sprite(key, expr, member)
+        if placeholder:
+            member.expression_map[expr] = placeholder
+    return member
+
+
+def _generate_via_comfy(specs: list[tuple[str, dict]]) -> list[CastMember]:
+    """Generate a cast using ComfyUI. Full pipeline per character.
+
+    Any HTTP/ComfyUI failure for one character (broken pipe, rejected
+    workflow, timeout) falls back to curated sprites (presets) or
+    placeholders (custom characters) instead of crashing the batch.
+    """
+    cast: list[CastMember] = []
+
+    for key, preset in specs:
+        try:
+            cast.append(_generate_one_via_comfy(key, preset))
+        except Exception as e:
+            print(f"  [cast] ComfyUI pipeline failed for {key}: {e}")
+            if key in PRESET_CHARACTERS:
+                print(f"  [cast] Falling back to curated sprites for {key}")
+                cast.extend(load_curated_cast([key]))
+            else:
+                print(f"  [cast] Falling back to placeholder sprites for {key}")
+                cast.append(_placeholder_member(key, preset))
+
+    return cast
+
+
+def _generated_complete(key: str) -> bool:
+    """True if a full generated sprite set already exists on disk
+    (for the current mode — fast and full are cached separately)."""
+    char_dir = _char_dir(key)
+    return all(os.path.exists(os.path.join(char_dir, f"{key}_{e}.png"))
+               for e in STANDARD_EXPRESSIONS)
+
+
+def _load_generated_member(key: str, preset: dict) -> CastMember:
+    """Build a CastMember from already-generated sprites on disk."""
+    char_dir = _char_dir(key)
+    member = _build_member(key, preset)
+    for expr in STANDARD_EXPRESSIONS:
+        member.expression_map[expr] = os.path.join(char_dir, f"{key}_{expr}.png")
+    return member
+
+
+def _generate_one_via_comfy(key: str, preset: dict, base_path: str = None) -> CastMember:
+    """Full ComfyUI pipeline for one character. Raises on hard failure.
+
+    Cached: if the character's full sprite set already exists under
+    static/sprites/generated/<key>/, it is reused — the bake happens once,
+    not on every casting beat. Force a re-bake by deleting that folder or
+    running with ARS_FABULA_REGEN=1.
+
+    When *base_path* is given, step 1 (base generation) is skipped — the
+    caller already ran the face-gated base gen and now only needs
+    expressions baked from it. The base is copied into the char dir if
+    it isn't already there.
+    """
+    if _generated_complete(key) and not os.getenv("ARS_FABULA_REGEN"):
+        print(f"  [cast] Reusing generated sprites for {key} "
+              f"(delete {_char_dir(key)}/ or set ARS_FABULA_REGEN=1 to re-bake)")
+        return _load_generated_member(key, preset)
+
+    char_dir = _char_dir(key)
+    os.makedirs(char_dir, exist_ok=True)
+
+    # Step 1: Generate base (face-gated) — skipped if base_path provided and exists
+    if base_path and os.path.exists(base_path):
+        dest = os.path.join(char_dir, f"{key}_base.png")
+        if os.path.abspath(base_path) != os.path.abspath(dest):
+            shutil.copy2(base_path, dest)
+        print(f"  [cast] Using supplied base for {key}: {base_path}")
+    else:
+        print(f"  [cast] Generating {key} (seed={preset['seed']})...")
+        base_path = _generate_base_with_face_gate(key, preset, char_dir)
+        if not base_path:
+            raise RuntimeError("base generation produced no image")
+
+    # Step 2: Generate expressions via the FaceDetailer sheet.
+    # The eye/hair anchor keeps those traits from drifting across the set.
+    anchor = _face_anchor(preset.get("identity_prompt", ""))
+    print(f"  [cast] Generating expressions for {key} (anchor: {anchor or 'none'})...")
+    for expr_name in STANDARD_EXPRESSIONS:
+        tags = EXPRESSION_TAGS[expr_name]
+        expr_path = _generate_expression_retry(base_path, key, expr_name,
+                                               tags, preset["seed"], anchor=anchor)
+        status = "OK" if expr_path else "FAILED"
+        print(f"    {expr_name}: {status}")
+
+    # Step 3: Remove backgrounds (isnet-anime matte)
+    print(f"  [cast] Removing backgrounds for {key}...")
+    for expr_name in STANDARD_EXPRESSIONS:
+        src = os.path.join(char_dir, f"{key}_{expr_name}.png")
+        if os.path.exists(src):
+            _remove_bg(src)
+
+    # Step 3.5: Crop full-body renders to a consistent waist-up sprite,
+    # anchored on the head crown so the whole cast lines up.
+    _frame_upper_body(char_dir, key)
+
+    # Step 4: Build CastMember
+    member = _build_member(key, preset)
+    for expr_name in STANDARD_EXPRESSIONS:
+        path = os.path.join(char_dir, f"{key}_{expr_name}.png")
+        if os.path.exists(path):
+            member.expression_map[expr_name] = path
+
+    # Any expression that failed gets a placeholder so the sprite-set
+    # integrity invariant (every emotion present) still holds.
+    for expr_name in STANDARD_EXPRESSIONS:
+        if expr_name not in member.expression_map:
+            placeholder = _make_placeholder_sprite(key, expr_name, member)
+            if placeholder:
+                member.expression_map[expr_name] = placeholder
+
+    return member
+
+
+def _get_preset_chars(preset_name: str) -> list[str]:
+    """Get character keys for a named cast preset."""
+    presets = {
+        "childhood_friends": ["yuki", "marie", "sakura"],
+        "love_triangle": ["yuki", "marie", "ryo"],
+        "girls_night": ["yuki", "marie", "sakura"],  # was yuki+sakura; Marie joins the girls
+        "full_cast": ["yuki", "marie", "sakura", "ryo"],
+        "default": ["yuki", "marie", "sakura"],
+    }
+    return presets.get(preset_name, presets["default"])
+
+
+def _make_placeholder_sprite(char_key: str, expr: str, member: CastMember) -> Optional[str]:
+    """Create a colored placeholder sprite for missing expressions."""
+    char_dir = _char_dir(char_key)
+    os.makedirs(char_dir, exist_ok=True)
+    path = os.path.join(char_dir, f"{char_key}_{expr}.png")
+
+    try:
+        from PIL import Image, ImageDraw
+        # Base color per character
+        colors = {
+            "yuki": (200, 210, 230),
+            "marie": (235, 225, 180),
+            "sakura": (230, 200, 210),
+            "ryo": (190, 200, 220),
+        }
+        r, g, b = colors.get(char_key, (200, 200, 200))
+
+        # Slight variation per expression
+        expr_shifts = {
+            "neutral": (0, 0, 0),
+            "smile": (10, 10, 0),
+            "laugh": (20, 15, 0),
+            "sad": (0, 0, -20),
+            "angry": (20, 0, 0),
+            "surprised": (0, 10, 20),
+            "embarrassed": (20, 0, 10),
+        }
+        dr, dg, db = expr_shifts.get(expr, (0, 0, 0))
+
+        img = Image.new("RGBA", (member.sprite_width, member.sprite_height),
+                        (min(255, r + dr), min(255, g + dg), min(255, b + db), 255))
+        draw = ImageDraw.Draw(img)
+        draw.text((member.sprite_width // 2, member.sprite_height // 2),
+                  f"{char_key}\n{expr}", fill=(255, 255, 255, 255), anchor="mm")
+        img.save(path)
+        return path
+    except ImportError:
+        return None
diff --git a/model_client.py b/model_client.py
new file mode 100644
index 0000000000000000000000000000000000000000..86165c8b96a8774623efee6b6765edcf4e4cfc5a
--- /dev/null
+++ b/model_client.py
@@ -0,0 +1,541 @@
+"""
+model_client.py — the model-independence layer.
+
+The engine depends on the `ModelClient` interface, never on a concrete model or URL.
+Swap models by changing env vars; run tests with no server via MockModel.
+
+  ARS_FABULA_BACKEND  = "server" | "transformers" | "mock"   (default: server)
+  ARS_FABULA_BASE_URL = "http://localhost:8110/v1"
+  ARS_FABULA_MODEL    = "gemma-12b"  (later: "gemma-26b-a4b", "gemma-31b")
+                        for the transformers backend: a HF repo id,
+                        e.g. "google/gemma-3-4b-it"
+  ARS_FABULA_API_KEY  = "not-needed"
+
+The "transformers" backend runs the model in-process — built for Hugging
+Face Spaces / ZeroGPU, where external servers (llama-server, ComfyUI)
+cannot hold a GPU. GPU time is only granted inside @spaces.GPU calls.
+"""
+from __future__ import annotations
+import os
+import json
+import time
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Optional, Callable
+
+import requests
+
+
+# ── Config ──────────────────────────────────────────────────────────────
+
+@dataclass
+class ModelConfig:
+    backend: str = "server"
+    base_url: str = "http://localhost:8110/v1"
+    model: str = "gemma-12b"
+    api_key: str = "not-needed"
+    temperature: float = 0.8
+    max_tokens: int = 1024
+    timeout: int = 120
+
+    @classmethod
+    def from_env(cls) -> "ModelConfig":
+        return cls(
+            backend=os.getenv("ARS_FABULA_BACKEND", "server"),
+            base_url=os.getenv("ARS_FABULA_BASE_URL", "http://localhost:8110/v1"),
+            model=os.getenv("ARS_FABULA_MODEL", "gemma-12b"),
+            api_key=os.getenv("ARS_FABULA_API_KEY", "not-needed"),
+            temperature=float(os.getenv("ARS_FABULA_TEMPERATURE", "0.8")),
+            max_tokens=int(os.getenv("ARS_FABULA_MAX_TOKENS", "1024")),
+            timeout=int(os.getenv("ARS_FABULA_TIMEOUT", "120")),
+        )
+
+
+# ── Interface ───────────────────────────────────────────────────────────
+
+class ModelClient(ABC):
+    """Minimal surface the engine needs. Any model that speaks it is swappable."""
+
+    @abstractmethod
+    def chat(self, messages: list[dict], tools: Optional[list] = None, **kw) -> dict:
+        """Return an assistant message dict: {"role","content","tool_calls"?}."""
+        ...
+
+    def generate(self, messages: list[dict], **kw) -> str:
+        """Convenience: text-only completion."""
+        return self.chat(messages, **kw).get("content") or ""
+
+    def health(self) -> bool:
+        """Check if the backend is reachable. Default False for abstract clients."""
+        return False
+
+
+# ── Real backend: any OpenAI-compatible llama-server ────────────────────
+
+class LlamaServerClient(ModelClient):
+    def __init__(self, config: Optional[ModelConfig] = None):
+        self.cfg = config or ModelConfig.from_env()
+
+    def chat(self, messages, tools=None, **kw) -> dict:
+        payload = {
+            "model": kw.get("model", self.cfg.model),
+            "messages": messages,
+            "temperature": kw.get("temperature", self.cfg.temperature),
+            "max_tokens": kw.get("max_tokens", self.cfg.max_tokens),
+        }
+        if tools:
+            payload["tools"] = tools
+            payload["tool_choice"] = kw.get("tool_choice", "auto")
+        resp = requests.post(
+            f"{self.cfg.base_url}/chat/completions",
+            headers={"Authorization": f"Bearer {self.cfg.api_key}",
+                     "Content-Type": "application/json"},
+            json=payload, timeout=self.cfg.timeout,
+        )
+        resp.raise_for_status()
+        return resp.json()["choices"][0]["message"]
+
+    def health(self) -> bool:
+        try:
+            base = self.cfg.base_url.rsplit("/v1", 1)[0]
+            return requests.get(f"{base}/health", timeout=5).status_code == 200
+        except requests.RequestException:
+            return False
+
+
+# ── Transformers backend: in-process model (HF Spaces / ZeroGPU) ────────
+#
+# On ZeroGPU the model must be loaded and placed on "cuda" at startup
+# (a CUDA emulation layer makes that legal outside @spaces.GPU); the real
+# GPU only exists inside the @spaces.GPU-decorated generate call. The
+# decorator is a no-op off-Spaces, so the same code path runs anywhere
+# torch + transformers are installed.
+
+# HF repo ids tried in order when ARS_FABULA_MODEL isn't itself a repo id.
+# Gemma is the project's model family but is license-gated — if the Space
+# token can't access it, fall through to an ungated small model rather
+# than dropping the whole demo to mock.
+_HF_MODEL_CANDIDATES = [
+    "google/gemma-3-4b-it",
+    "Qwen/Qwen3-4B-Instruct-2507",
+]
+
+_HF_STATE: dict = {"model": None, "tokenizer": None, "id": None}
+
+try:
+    import spaces as _spaces
+    _gpu_decorator = _spaces.GPU(duration=120)
+except ImportError:
+    _gpu_decorator = lambda f: f
+
+
+def _hf_load(model_id: Optional[str] = None):
+    """Load the chat model once, module-wide. Returns the loaded repo id
+    or None if nothing could be loaded (no torch, gated repo, etc.)."""
+    if _HF_STATE["model"] is not None:
+        return _HF_STATE["id"]
+    try:
+        import torch
+        from transformers import AutoModelForCausalLM, AutoTokenizer
+    except ImportError as e:
+        print(f"[hf] transformers backend unavailable ({e})")
+        return None
+
+    candidates = [model_id] if model_id and "/" in model_id else list(_HF_MODEL_CANDIDATES)
+    for mid in candidates:
+        try:
+            print(f"[hf] loading {mid}…")
+            tok = AutoTokenizer.from_pretrained(mid)
+            model = AutoModelForCausalLM.from_pretrained(mid, dtype=torch.bfloat16)
+            if torch.cuda.is_available():
+                model = model.to("cuda")
+            model.eval()
+            _HF_STATE.update(model=model, tokenizer=tok, id=mid)
+            print(f"[hf] {mid} ready on {model.device}")
+            return mid
+        except Exception as e:
+            print(f"[hf] could not load {mid}: {type(e).__name__}: {e}")
+    return None
+
+
+@_gpu_decorator
+def _hf_generate(messages: list[dict], max_new_tokens: int,
+                 temperature: float) -> str:
+    import torch
+    tok, model = _HF_STATE["tokenizer"], _HF_STATE["model"]
+    inputs = tok.apply_chat_template(
+        messages, add_generation_prompt=True,
+        return_tensors="pt", return_dict=True,
+    ).to(model.device)
+    with torch.inference_mode():
+        out = model.generate(
+            **inputs,
+            max_new_tokens=max_new_tokens,
+            do_sample=temperature > 0,
+            temperature=max(temperature, 1e-3),
+            top_p=0.95,
+        )
+    return tok.decode(out[0][inputs["input_ids"].shape[-1]:],
+                      skip_special_tokens=True)
+
+
+class TransformersClient(ModelClient):
+    """In-process HF transformers chat model (the ZeroGPU path)."""
+
+    def __init__(self, config: Optional[ModelConfig] = None):
+        self.cfg = config or ModelConfig.from_env()
+        self._loaded_id = _hf_load(self.cfg.model)
+
+    def chat(self, messages, tools=None, **kw) -> dict:
+        if not self.health():
+            raise RuntimeError("transformers backend has no loaded model")
+        text = _hf_generate(
+            messages,
+            max_new_tokens=kw.get("max_tokens", self.cfg.max_tokens),
+            temperature=kw.get("temperature", self.cfg.temperature),
+        )
+        return {"role": "assistant", "content": text}
+
+    def health(self) -> bool:
+        return _HF_STATE["model"] is not None
+
+
+def preload_transformers() -> bool:
+    """Warm the in-process model at app startup (ZeroGPU wants the CUDA
+    placement done at module/startup time, not lazily mid-request)."""
+    cfg = ModelConfig.from_env()
+    if cfg.backend != "transformers":
+        return False
+    return _hf_load(cfg.model) is not None
+
+
+# ── Mock backend: scripted, no server (for unit/CI tests) ───────────────
+
+class MockModel(ModelClient):
+    """Returns programmed responses and records what it was asked.
+
+    Program with either:
+      MockModel(responses=["text 1", {"role":"assistant","tool_calls":[...]}, ...])
+      MockModel(handler=lambda messages, tools: "...")  # dynamic
+    """
+    # Scripted output is not real model data — the engine skips trace logging
+    # for mock models so tests and mock fallbacks don't pollute the dataset.
+    is_mock = True
+
+    def __init__(self, responses: Optional[list] = None,
+                 handler: Optional[Callable[[list, Optional[list]], object]] = None):
+        self._queue = list(responses or [])
+        self._handler = handler
+        self.calls: list[dict] = []          # every chat() invocation, for assertions
+        self.default = "The scene holds its breath for a moment, waiting."
+
+    def chat(self, messages, tools=None, **kw) -> dict:
+        self.calls.append({"messages": messages, "tools": tools, "kw": kw})
+        if self._handler:
+            out = self._handler(messages, tools)
+        elif self._queue:
+            out = self._queue.pop(0)
+        else:
+            out = self.default
+        if isinstance(out, str):
+            return {"role": "assistant", "content": out}
+        return out  # already a message dict (may carry tool_calls)
+
+    # test helpers
+    def last_prompt_text(self) -> str:
+        """Concatenated content of the most recent call's messages."""
+        if not self.calls:
+            return ""
+        return "\n".join(str(m.get("content", "")) for m in self.calls[-1]["messages"])
+
+    def queue(self, *responses):
+        self._queue.extend(responses)
+
+
+# ── Factory ─────────────────────────────────────────────────────────────
+
+def get_model(config: Optional[ModelConfig] = None) -> ModelClient:
+    cfg = config or ModelConfig.from_env()
+    if cfg.backend == "mock":
+        return MockModel()
+    if cfg.backend == "transformers":
+        return TransformersClient(cfg)
+    return LlamaServerClient(cfg)
+
+
+# ── VRAM management — swap the LLM out so the image model can load ──────
+#
+# The LLM and the diffusion stack don't fit in VRAM together (e.g. Gemma
+# 12B IQ4_XS ~6GB on an 8GB card). llama.cpp's llama-server has NO unload
+# API, so we STOP the server process before a ComfyUI bake and RELAUNCH it
+# afterward, polling /health before resuming scene turns.
+#
+# Default behavior auto-detects a WSL-native atomic-fork llama-server (Gemma
+# 4 26B-A4B MoE + MTP) or falls back to a WSL→Windows llama-server.exe.
+# Everything is env-overridable:
+#   ARS_FABULA_LLM_MANAGE      = auto (default) | wsl | win | none | ollama
+#   ARS_FABULA_LLM_STOP_CMD    = "<shell cmd>"   # custom stop
+#   ARS_FABULA_LLM_START_CMD   = "<shell cmd>"   # custom start (detached)
+#   ARS_FABULA_LLM_UNLOAD_URL  = "http://.../unload"
+#   ARS_FABULA_LLAMA_EXE_WIN   = C:\\...\\llama-server.exe    # Windows mode
+#   ARS_FABULA_LLAMA_MODEL_WIN = C:\\...\\model.gguf
+#   ARS_FABULA_LLAMA_ARGS      = "<llama-server flags>"       # shared
+#   ARS_FABULA_LLAMA_BIN       = /path/to/llama-server  (WSL) # WSL mode
+#   ARS_FABULA_LLAMA_MODEL     = /path/to/model.gguf   (WSL)
+#   ARS_FABULA_LLAMA_DRAFTER   = /path/to/mtp-drafter.gguf    # MTP
+#   ARS_FABULA_LLAMA_LD_PATH   = /path/to/lib/dir             # LD_LIBRARY_PATH
+
+_DEFAULT_LLAMA_EXE_WIN = r"C:\Users\vruizes\llama-cpp-setup\llama-server.exe"
+_DEFAULT_LLAMA_MODEL_WIN = r"C:\Users\vruizes\Downloads\gemma-4-12b-it-IQ4_XS.gguf"
+# 'none' reasoning profile from the launcher .bat — fastest, cleanest tool
+# output for the VN (thinking tokens just add latency to bracket emission).
+_DEFAULT_LLAMA_ARGS = ("-ngl 99 -fa on -ctk q8_0 -ctv q8_0 -c 16384 "
+                       "--reasoning off -np 1 --cache-ram 0 "
+                       "--host 0.0.0.0 --port 8110")
+
+# ── WSL-native defaults (atomic-llama-cpp-turboquant, Gemma 4 26B-A4B) ──
+_DEFAULT_LLAMA_BIN_WSL = "/mnt/c/Users/vruizes/atomic-llama-cpp-turboquant/" \
+                         "build/bin/llama-server"
+_DEFAULT_LLAMA_MODEL_WSL = "/mnt/c/Users/vruizes/Downloads/" \
+                           "gemma-4-26B-A4B-it-UD-Q4_K_M.gguf"
+_DEFAULT_LLAMA_DRAFTER_WSL = "/mnt/c/Users/vruizes/Downloads/" \
+                              "gemma-4-26B-A4B-it-assistant.Q4_K_M.gguf"
+_DEFAULT_LLAMA_LD_PATH_WSL = "/mnt/c/Users/vruizes/" \
+                              "atomic-llama-cpp-turboquant/build/bin"
+# 32K context, CPU MoE offload (GPU can't fit 26B MoE experts), MTP drafter,
+# no reasoning tokens (they add latency to bracket emission).
+_DEFAULT_LLAMA_ARGS_WSL = ("--spec-type mtp --draft-block-size 3 "
+                           "--draft-max 8 --draft-min 0 "
+                           "-ngl 99 -ngld 99 -fa on -ctk q8_0 -ctv q8_0 "
+                           "-c 32000 --cpu-moe --reasoning off "
+                           "--host 0.0.0.0 --port 8110")
+
+
+def _is_wsl() -> bool:
+    if os.name != "posix":
+        return False
+    try:
+        with open("/proc/version") as f:
+            return "microsoft" in f.read().lower()
+    except OSError:
+        return False
+
+
+def _win_to_wsl(win_path: str) -> str:
+    """C:\\Users\\x → /mnt/c/Users/x (for existence checks from WSL)."""
+    p = win_path.replace("\\", "/")
+    if len(p) > 1 and p[1] == ":":
+        return f"/mnt/{p[0].lower()}{p[2:]}"
+    return p
+
+
+def _llm_manage_mode(cfg: ModelConfig) -> str:
+    mode = os.getenv("ARS_FABULA_LLM_MANAGE", "auto").lower()
+    if mode != "auto":
+        return mode
+    # auto: a custom stop hook wins; then try WSL-native atomic fork,
+    # then Windows .exe via interop, then ollama.
+    if os.getenv("ARS_FABULA_LLM_STOP_CMD"):
+        return "cmd"
+    # Check for WSL-native atomic-fork binary first
+    bin_path = os.getenv("ARS_FABULA_LLAMA_BIN", _DEFAULT_LLAMA_BIN_WSL)
+    if _is_wsl() and os.path.exists(bin_path):
+        return "wsl"
+    exe = os.getenv("ARS_FABULA_LLAMA_EXE_WIN", _DEFAULT_LLAMA_EXE_WIN)
+    if _is_wsl() and os.path.exists(_win_to_wsl(exe)):
+        return "win"
+    if "11434" in cfg.base_url:
+        return "ollama"
+    return "none"
+
+
+def _win_health(cfg: ModelConfig) -> bool:
+    try:
+        base = cfg.base_url.rsplit("/v1", 1)[0]
+        return requests.get(f"{base}/health", timeout=3).status_code == 200
+    except requests.RequestException:
+        return False
+
+
+def release_vram(config: Optional[ModelConfig] = None) -> bool:
+    """Stop/evict the LLM so ComfyUI can load. Returns True if it acted."""
+    cfg = config or ModelConfig.from_env()
+    # mock has nothing to stop; transformers is in-process — on ZeroGPU the
+    # GPU is granted per-call and released automatically, so the whole
+    # stop/relaunch swap dance does not apply.
+    if cfg.backend in ("mock", "transformers"):
+        return False
+    mode = _llm_manage_mode(cfg)
+    if mode == "none":
+        return False
+    import subprocess
+
+    if mode == "cmd" or os.getenv("ARS_FABULA_LLM_STOP_CMD"):
+        cmd = os.getenv("ARS_FABULA_LLM_STOP_CMD")
+        if cmd:
+            try:
+                subprocess.run(cmd, shell=True, timeout=30, check=False)
+                print(f"[vram] LLM stopped via STOP_CMD")
+                return True
+            except Exception as e:
+                print(f"[vram] STOP_CMD failed: {e}")
+
+    if mode == "win":
+        # Kill the Windows llama-server.exe from WSL via interop
+        for killer in ("taskkill.exe", "/mnt/c/Windows/System32/taskkill.exe"):
+            try:
+                subprocess.run([killer, "/IM", "llama-server.exe", "/F"],
+                               timeout=20, check=False,
+                               stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+                print("[vram] llama-server.exe stopped (taskkill)")
+                # give the driver a moment to release VRAM
+                time.sleep(2)
+                return True
+            except Exception:
+                continue
+        print("[vram] taskkill unavailable — could not stop llama-server")
+        return False
+
+    if mode == "wsl":
+        # Kill the WSL-native atomic-fork llama-server (Linux process)
+        try:
+            subprocess.run(["pkill", "-f", "build/bin/llama-server"],
+                           timeout=15, check=False,
+                           stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            print("[vram] WSL llama-server stopped (pkill build/bin/llama-server)")
+            time.sleep(2)
+            return True
+        except Exception as e:
+            print(f"[vram] pkill failed: {e}")
+            return False
+
+    url = os.getenv("ARS_FABULA_LLM_UNLOAD_URL")
+    if url:
+        try:
+            requests.post(url, json={}, timeout=15)
+            print(f"[vram] LLM unload URL hit: {url}")
+            return True
+        except Exception as e:
+            print(f"[vram] unload URL failed: {e}")
+
+    if mode == "ollama":
+        root = cfg.base_url.rsplit("/v1", 1)[0].rstrip("/")
+        try:
+            if requests.post(f"{root}/api/generate",
+                             json={"model": cfg.model, "keep_alive": 0,
+                                   "prompt": "", "stream": False}, timeout=15).ok:
+                print(f"[vram] LLM unloaded via ollama keep_alive=0")
+                return True
+        except Exception:
+            pass
+    return False
+
+
+def ensure_llm(config: Optional[ModelConfig] = None, timeout: int = 300) -> bool:
+    """Make sure the LLM server is up and answering /health, relaunching it
+    if we manage it. Returns True when healthy, False on give-up."""
+    cfg = config or ModelConfig.from_env()
+    if cfg.backend == "mock":
+        return False
+    if cfg.backend == "transformers":
+        # In-process model: there is no server to relaunch or poll.
+        return _HF_STATE["model"] is not None or preload_transformers()
+    if _win_health(cfg):
+        return True
+
+    mode = _llm_manage_mode(cfg)
+    import subprocess
+
+    started = False
+    start_cmd = os.getenv("ARS_FABULA_LLM_START_CMD")
+    if start_cmd:
+        try:
+            subprocess.Popen(start_cmd, shell=True,
+                             stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            started = True
+            print("[vram] LLM starting via START_CMD…")
+        except Exception as e:
+            print(f"[vram] START_CMD failed: {e}")
+    elif mode == "win":
+        exe = os.getenv("ARS_FABULA_LLAMA_EXE_WIN", _DEFAULT_LLAMA_EXE_WIN)
+        model = os.getenv("ARS_FABULA_LLAMA_MODEL_WIN", _DEFAULT_LLAMA_MODEL_WIN)
+        args = os.getenv("ARS_FABULA_LLAMA_ARGS", _DEFAULT_LLAMA_ARGS)
+        # Execute the Windows .exe DIRECTLY via its WSL path — no cmd.exe,
+        # no `start` (whose title arg gets mangled across the WSL boundary).
+        # The exe is a Windows program, so the model path stays a Windows
+        # path; Popen returns immediately and the process keeps running.
+        import shlex
+        exe_wsl = _win_to_wsl(exe)
+        cmd = [exe_wsl, "-m", model] + shlex.split(args)
+        try:
+            subprocess.Popen(cmd, stdout=subprocess.DEVNULL,
+                             stderr=subprocess.DEVNULL,
+                             stdin=subprocess.DEVNULL,
+                             start_new_session=True)
+            started = True
+            print(f"[vram] llama-server.exe relaunching (detached): {exe_wsl}")
+        except Exception as e:
+            print(f"[vram] direct launch failed ({e}); trying the headless .bat")
+            # Fallback: run the headless launcher .bat via cmd.exe /c
+            bat = os.getenv("ARS_FABULA_LLAMA_BAT")
+            if bat:
+                for shell in ("cmd.exe", "/mnt/c/Windows/System32/cmd.exe"):
+                    try:
+                        subprocess.Popen([shell, "/c", bat],
+                                         stdout=subprocess.DEVNULL,
+                                         stderr=subprocess.DEVNULL,
+                                         start_new_session=True)
+                        started = True
+                        print("[vram] llama-server relaunching via .bat…")
+                        break
+                    except Exception:
+                        continue
+
+    elif mode == "wsl":
+        # Launch the WSL-native atomic-fork llama-server (Gemma 4 26B-A4B
+        # MoE + MTP drafter). The binary is a Linux ELF with CUDA deps, so
+        # LD_LIBRARY_PATH must point at its build/bin for libggml*.so etc.
+        bin_path = os.getenv("ARS_FABULA_LLAMA_BIN", _DEFAULT_LLAMA_BIN_WSL)
+        model_path = os.getenv("ARS_FABULA_LLAMA_MODEL",
+                               _DEFAULT_LLAMA_MODEL_WSL)
+        drafter_path = os.getenv("ARS_FABULA_LLAMA_DRAFTER",
+                                 _DEFAULT_LLAMA_DRAFTER_WSL)
+        ld_path = os.getenv("ARS_FABULA_LLAMA_LD_PATH",
+                            _DEFAULT_LLAMA_LD_PATH_WSL)
+        args_str = os.getenv("ARS_FABULA_LLAMA_ARGS",
+                             _DEFAULT_LLAMA_ARGS_WSL)
+        import shlex
+        cmd = [bin_path, "-m", model_path,
+               "--mtp-head", drafter_path] + shlex.split(args_str)
+        launch_env = os.environ.copy()
+        launch_env["LD_LIBRARY_PATH"] = (
+            f"{ld_path}:{launch_env.get('LD_LIBRARY_PATH', '')}"
+        )
+        try:
+            subprocess.Popen(cmd, env=launch_env,
+                             stdout=subprocess.DEVNULL,
+                             stderr=subprocess.DEVNULL,
+                             stdin=subprocess.DEVNULL,
+                             start_new_session=True)
+            started = True
+            print(f"[vram] atomic-fork llama-server starting (WSL-native): "
+                  f"{bin_path}")
+        except Exception as e:
+            print(f"[vram] WSL launch failed: {e}")
+
+    if not started:
+        # Nothing we could launch — wait only a short grace period in case
+        # the user is bringing it up by hand, then give up to mock.
+        print("[vram] LLM not running and no launcher configured — "
+              "start llama-server (or set ARS_FABULA_LLM_START_CMD). "
+              "Using mock until it's up.")
+        timeout = 6
+
+    # Poll /health until the model finishes loading
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        if _win_health(cfg):
+            print("[vram] LLM is healthy.")
+            return True
+        time.sleep(2)
+    return _win_health(cfg)
diff --git a/providers.py b/providers.py
new file mode 100644
index 0000000000000000000000000000000000000000..1252ffa9b424443b66d0ea38485a4bcb9149a516
--- /dev/null
+++ b/providers.py
@@ -0,0 +1,425 @@
+"""
+providers.py — Swappable Background and Voice providers.
+
+BackgroundProvider: preset library + live gen hook.
+VoiceProvider: Chatterbox (emotion) + Kokoro (fast) selectable.
+
+Both are interfaces with concrete implementations.
+"""
+from __future__ import annotations
+import os
+import subprocess
+import json
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Optional
+
+# ── Asset paths ──────────────────────────────────────────────────────
+ASSET_DIR = os.path.join(os.path.dirname(__file__), "static")
+BG_DIR = os.path.join(ASSET_DIR, "bg")
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# Background Provider
+# ═══════════════════════════════════════════════════════════════════════
+
+# Preset background library — maps keys to image paths or generation prompts
+PRESET_BACKGROUNDS: dict[str, dict] = {
+    "classroom": {
+        "path": "bg_classroom.png",
+        "label": "High School Classroom",
+        "prompt": "sunlit Japanese high school classroom, desks in rows, blackboard, afternoon light through windows, anime style",
+    },
+    "hallway": {
+        "path": "bg_hallway.png",
+        "label": "School Hallway",
+        "prompt": "Japanese school hallway with lockers, shoe cubbies, afternoon sunlight, empty corridor, anime style",
+    },
+    "rooftop": {
+        "path": "bg_rooftop.png",
+        "label": "School Rooftop",
+        "prompt": "school rooftop at sunset, city skyline in distance, fence, water tower, sky gradient, anime style",
+    },
+    "courtyard": {
+        "path": "bg_courtyard.png",
+        "label": "Courtyard",
+        "prompt": "school courtyard with cherry blossom trees in full bloom, benches, students walking, spring, anime style",
+    },
+    "cafe": {
+        "path": "bg_cafe.png",
+        "label": "Café",
+        "prompt": "cozy cafe interior, warm lighting, wooden tables, plants, window seat, afternoon, anime style",
+    },
+    "park": {
+        "path": "bg_park.png",
+        "label": "City Park",
+        "prompt": "city park with green grass, trees, pond, benches, jogging path, blue sky, anime style",
+    },
+    "library": {
+        "path": "bg_library.png",
+        "label": "School Library",
+        "prompt": "quiet school library, tall bookshelves, reading tables, lamp light, large windows, anime style",
+    },
+    "home_room": {
+        "path": "bg_home_room.png",
+        "label": "Character's Room",
+        "prompt": "cozy Japanese bedroom, low bed, desk with laptop, posters on wall, evening light, anime style",
+    },
+    "gate": {
+        "path": "bg_gate.png",
+        "label": "School Gate",
+        "prompt": "school gate at the end of the day, cherry blossom petals falling, sunset, students leaving, anime style",
+    },
+    "sunset_hill": {
+        "path": "bg_sunset_hill.png",
+        "label": "Sunset Hill",
+        "prompt": "hill overlooking the city at sunset, grass, wind, two silhouettes, romantic atmosphere, anime style",
+    },
+}
+
+
+@dataclass
+class BackgroundInfo:
+    """Information about a background image."""
+    key: str
+    label: str
+    path: str            # absolute path to the image file
+    is_placeholder: bool = False
+
+
+class BackgroundProvider(ABC):
+    """Interface for providing background images."""
+
+    @abstractmethod
+    def get_background(self, key: str) -> BackgroundInfo:
+        """Get a background image by key. Returns info with path."""
+        ...
+
+    @abstractmethod
+    def list_available(self) -> list[str]:
+        """List all available background keys."""
+        ...
+
+    def get_prompt_for_gen(self, key: str) -> str:
+        """Get the generation prompt for a key (for live gen hook)."""
+        info = PRESET_BACKGROUNDS.get(key)
+        return info["prompt"] if info else f"anime style background, {key}"
+
+
+class PresetBackgroundProvider(BackgroundProvider):
+    """Uses pre-rendered background images from static/bg/."""
+
+    def get_background(self, key: str) -> BackgroundInfo:
+        info = PRESET_BACKGROUNDS.get(key)
+        if not info:
+            # Fallback to first available
+            key = list(PRESET_BACKGROUNDS.keys())[0]
+            info = PRESET_BACKGROUNDS[key]
+
+        path = os.path.join(BG_DIR, info["path"])
+        is_placeholder = not os.path.exists(path)
+        if is_placeholder:
+            path = os.path.join(BG_DIR, "_placeholder.png")
+            # Use a default placeholder if we have one
+            if not os.path.exists(path):
+                path = self._make_placeholder(key)
+
+        return BackgroundInfo(
+            key=key,
+            label=info["label"],
+            path=path,
+            is_placeholder=is_placeholder,
+        )
+
+    def list_available(self) -> list[str]:
+        return list(PRESET_BACKGROUNDS.keys())
+
+    def _make_placeholder(self, key: str) -> str:
+        """Create a colored placeholder background."""
+        colors = {
+            "classroom": (200, 190, 160),
+            "hallway": (180, 175, 155),
+            "rooftop": (200, 180, 140),
+            "courtyard": (160, 190, 140),
+            "cafe": (180, 150, 120),
+            "park": (140, 180, 130),
+            "library": (160, 150, 130),
+            "home_room": (170, 140, 130),
+            "gate": (180, 170, 140),
+            "sunset_hill": (200, 150, 100),
+        }
+        try:
+            from PIL import Image, ImageDraw, ImageFont
+            r, g, b = colors.get(key, (150, 150, 150))
+            img = Image.new("RGB", (1024, 768), (r, g, b))
+            draw = ImageDraw.Draw(img)
+            draw.text((512, 384), key, fill=(255, 255, 255), anchor="mm")
+            os.makedirs(BG_DIR, exist_ok=True)
+            path = os.path.join(BG_DIR, "_placeholder.png")
+            img.save(path)
+            return path
+        except ImportError:
+            # Fallback — write a minimal PNG manually
+            path = os.path.join(BG_DIR, "_placeholder.png")
+            if not os.path.exists(path):
+                self._write_minimal_png(path, r, g, b)
+            return path
+
+    def _write_minimal_png(self, path: str, r: int, g: int, b: int):
+        """Write a minimal valid 1x1 PNG as absolute last resort."""
+        import struct, zlib
+        width, height = 1024, 768
+        raw = b""
+        for y in range(height):
+            raw += b"\x00" + bytes([r, g, b]) * width
+        compressed = zlib.compress(raw)
+        def chunk(ctype, data):
+            c = ctype + data
+            return struct.pack(">I", len(data)) + c + struct.pack(">I", zlib.crc32(c) & 0xFFFFFFFF)
+        ihdr = struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0)
+        png = b"\x89PNG\r\n\x1a\n" + chunk(b"IHDR", ihdr) + chunk(b"IDAT", compressed) + chunk(b"IEND", b"")
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "wb") as f:
+            f.write(png)
+
+
+class ComfyUIBackgroundProvider(PresetBackgroundProvider):
+    """Extends PresetBackgroundProvider with live gen for novel keys.
+
+    Live gen happens ONLY for keys outside the preset library — and per the
+    plan's hard rule it should be invoked from beat boundaries (casting /
+    pre-staging), never mid-scene-turn.
+    """
+
+    def __init__(self, comfy_host: str = "http://127.0.0.1:8188"):
+        super().__init__()
+        self.comfy_host = comfy_host
+        self._generated_paths: dict[str, str] = {}
+
+    def get_background(self, key: str) -> BackgroundInfo:
+        if key in PRESET_BACKGROUNDS:
+            return super().get_background(key)
+
+        # Novel key — generate once, then serve from disk
+        if key not in self._generated_paths:
+            path = self._generate_background(key)
+            if path:
+                self._generated_paths[key] = path
+
+        if key in self._generated_paths and os.path.exists(self._generated_paths[key]):
+            return BackgroundInfo(
+                key=key,
+                label=key.replace("_", " ").title(),
+                path=self._generated_paths[key],
+                is_placeholder=False,
+            )
+
+        # Generation failed — fall back to preset/placeholder behavior
+        return super().get_background(key)
+
+    def _generate_background(self, key: str) -> Optional[str]:
+        """Generate a background via ComfyUI txt2img, WAIT for completion,
+        and copy the result into static/bg/ so it can actually be served.
+
+        Returns the local path of the generated image, or None on failure.
+        """
+        prompt_text = self.get_prompt_for_gen(key)
+        try:
+            # Reuse the cast pipeline's ComfyUI helpers and model names
+            # (UNETLoader + Qwen CLIP/VAE — same trio as the validated
+            # expression sheet; anima is a UNET-only file, so
+            # CheckpointLoaderSimple would fail to load it).
+            from cast_pipeline import (_comfy_submit, _comfy_wait,
+                                       _comfy_fetch_image,
+                                       UNET_NAME, CLIP_NAME, VAE_NAME,
+                                       SAMPLER, SCHEDULER, STYLE_TAGS)
+
+            workflow = {
+                "3": {"class_type": "KSampler", "inputs": {"seed": abs(hash(key)) % (2**31), "steps": 30, "cfg": 4.0, "sampler_name": SAMPLER, "scheduler": SCHEDULER, "denoise": 1.0, "model": ["44", 0], "positive": ["6", 0], "negative": ["7", 0], "latent_image": ["5", 0]}},
+                "44": {"class_type": "UnetLoaderGGUF", "inputs": {"unet_name": UNET_NAME}},
+                "45": {"class_type": "CLIPLoader", "inputs": {"clip_name": CLIP_NAME, "type": "stable_diffusion", "device": "default"}},
+                "15": {"class_type": "VAELoader", "inputs": {"vae_name": VAE_NAME}},
+                "5": {"class_type": "EmptyLatentImage", "inputs": {"width": 1024, "height": 768, "batch_size": 1}},
+                "6": {"class_type": "CLIPTextEncode", "inputs": {"text": f"absurdres, {STYLE_TAGS}, {prompt_text}", "clip": ["45", 0]}},
+                "7": {"class_type": "CLIPTextEncode", "inputs": {"text": "worst quality, low quality, blurry", "clip": ["45", 0]}},
+                "8": {"class_type": "VAEDecode", "inputs": {"samples": ["3", 0], "vae": ["15", 0]}},
+                "9": {"class_type": "SaveImage", "inputs": {"filename_prefix": f"bg_{key}", "images": ["8", 0]}},
+            }
+
+            pid = _comfy_submit(workflow, f"bg_{key}")
+            result = _comfy_wait(pid, timeout=120)
+            if not result:
+                print(f"[bg] Generation failed/timed out for '{key}'")
+                return None
+
+            dst = os.path.join(BG_DIR, f"bg_{key}.png")
+            if not _comfy_fetch_image(result, dst):
+                return None
+            print(f"[bg] Generated background '{key}' -> {dst}")
+            return dst
+        except Exception as e:
+            print(f"[bg] Failed to generate background '{key}': {e}")
+            return None
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# Voice Provider
+# ═══════════════════════════════════════════════════════════════════════
+
+@dataclass
+class VoiceLine:
+    """A voice line ready for playback."""
+    text: str
+    character: str
+    emotion: str           # happy, sad, angry, surprised, neutral, embarrassed
+    wav_path: Optional[str] = None
+    duration_ms: int = 0
+
+
+class VoiceProvider(ABC):
+    """Interface for generating voice lines."""
+
+    @abstractmethod
+    def speak(self, text: str, character: str, emotion: str = "neutral",
+              voice_id: Optional[str] = None) -> VoiceLine:
+        """Generate a voiced line. Returns a VoiceLine with path to WAV.
+
+        Args:
+            text: The line to voice.
+            character: Character name (for filenames/metadata).
+            emotion: Emotion tag (happy, sad, angry, surprised, neutral, embarrassed).
+            voice_id: The character's locked voice (Character.voice_id).
+                Providers that support per-voice synthesis MUST honor it.
+        """
+        ...
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        ...
+
+
+class KokoroVoiceProvider(VoiceProvider):
+    """Fast TTS via Kokoro (local model on port 11436 by default)."""
+
+    def __init__(self, base_url: str = "http://localhost:11436"):
+        self.base_url = base_url
+        self._name = "kokoro"
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    def speak(self, text: str, character: str, emotion: str = "neutral",
+              voice_id: Optional[str] = None) -> VoiceLine:
+        try:
+            import urllib.request
+            import json as _json
+            payload = _json.dumps({"text": text, "voice": voice_id or "af_bella"}).encode()
+            req = urllib.request.Request(
+                f"{self.base_url}/v1/audio/speech",
+                data=payload,
+                headers={"Content-Type": "application/json"},
+            )
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                data = resp.read()
+            wav_dir = os.path.join(ASSET_DIR, "voice")
+            os.makedirs(wav_dir, exist_ok=True)
+            wav_path = os.path.join(wav_dir, f"{character}_{hash(text) % 10000}.wav")
+            with open(wav_path, "wb") as f:
+                f.write(data)
+            return VoiceLine(text=text, character=character, emotion=emotion,
+                             wav_path=wav_path, duration_ms=len(data) // 32)
+        except Exception as e:
+            print(f"[voice] Kokoro failed: {e}")
+            return VoiceLine(text=text, character=character, emotion=emotion)
+
+
+class ChatterboxVoiceProvider(VoiceProvider):
+    """Emotion-rich voice via Chatterbox-Turbo."""
+
+    def __init__(self, base_url: str = "http://localhost:11437"):
+        self.base_url = base_url
+        self._name = "chatterbox"
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    def speak(self, text: str, character: str, emotion: str = "neutral",
+              voice_id: Optional[str] = None) -> VoiceLine:
+        try:
+            import urllib.request
+            import json as _json
+            payload = _json.dumps({
+                "text": text,
+                "speaker": voice_id or character,
+                "emotion": emotion,
+            }).encode()
+            req = urllib.request.Request(
+                f"{self.base_url}/tts",
+                data=payload,
+                headers={"Content-Type": "application/json"},
+            )
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                data = resp.read()
+            wav_dir = os.path.join(ASSET_DIR, "voice")
+            os.makedirs(wav_dir, exist_ok=True)
+            wav_path = os.path.join(wav_dir, f"{character}_{emotion}_{hash(text) % 10000}.wav")
+            with open(wav_path, "wb") as f:
+                f.write(data)
+            return VoiceLine(text=text, character=character, emotion=emotion,
+                             wav_path=wav_path, duration_ms=len(data) // 32)
+        except Exception as e:
+            print(f"[voice] Chatterbox failed: {e}")
+            return VoiceLine(text=text, character=character, emotion=emotion)
+
+
+class MockVoiceProvider(VoiceProvider):
+    """No actual TTS — returns a voice line with just metadata (for testing)."""
+
+    def __init__(self):
+        self._name = "mock"
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    def speak(self, text: str, character: str, emotion: str = "neutral",
+              voice_id: Optional[str] = None) -> VoiceLine:
+        return VoiceLine(
+            text=text,
+            character=character,
+            emotion=emotion,
+            duration_ms=int(len(text) * 60),  # ~60ms per character
+        )
+
+
+def get_voice_provider(backend: str = "mock") -> VoiceProvider:
+    """Factory: returns the appropriate VoiceProvider based on backend name.
+
+    Args:
+        backend: "mock", "kokoro", "chatterbox"
+
+    Returns:
+        VoiceProvider instance.
+    """
+    if backend == "kokoro":
+        return KokoroVoiceProvider()
+    elif backend == "chatterbox":
+        return ChatterboxVoiceProvider()
+    return MockVoiceProvider()
+
+
+def get_background_provider(backend: str = "preset") -> BackgroundProvider:
+    """Factory: returns the appropriate BackgroundProvider.
+
+    Args:
+        backend: "preset", "comfyui"
+
+    Returns:
+        BackgroundProvider instance.
+    """
+    if backend == "comfyui":
+        return ComfyUIBackgroundProvider()
+    return PresetBackgroundProvider()
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 0000000000000000000000000000000000000000..11d980b7afd5997702e92fdae6405babbe45755e
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1,7 @@
+torch
+transformers>=4.56
+accelerate
+spaces
+requests
+pillow
+numpy
diff --git a/static/bg/_placeholder.png b/static/bg/_placeholder.png
new file mode 100644
index 0000000000000000000000000000000000000000..400bb47849e6afa6d1e5d642bbe3e8fec84e2e18
Binary files /dev/null and b/static/bg/_placeholder.png differ
diff --git a/static/bg/bg_cafe.png b/static/bg/bg_cafe.png
new file mode 100644
index 0000000000000000000000000000000000000000..e8b80e19abd9755dca371d50868628b542465932
Binary files /dev/null and b/static/bg/bg_cafe.png differ
diff --git a/static/bg/bg_classroom.png b/static/bg/bg_classroom.png
new file mode 100644
index 0000000000000000000000000000000000000000..b39811c3dd4acf90d78a79cbc8da7cbe9d321a4f
--- /dev/null
+++ b/static/bg/bg_classroom.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bd9c85536a58b40c153057884a7888fbca3d677bdcf7feac22c83e3a45f3d7ec
+size 211051
diff --git a/static/bg/bg_courtyard.png b/static/bg/bg_courtyard.png
new file mode 100644
index 0000000000000000000000000000000000000000..dc0e2b81a5d1c69658bbe9b98252ddf1a4f97517
Binary files /dev/null and b/static/bg/bg_courtyard.png differ
diff --git a/static/bg/bg_gate.png b/static/bg/bg_gate.png
new file mode 100644
index 0000000000000000000000000000000000000000..21976d2a8d62253ee491e4c2fadef2727c6ea0c9
Binary files /dev/null and b/static/bg/bg_gate.png differ
diff --git a/static/bg/bg_hallway.png b/static/bg/bg_hallway.png
new file mode 100644
index 0000000000000000000000000000000000000000..3883d7f43f795bbfbb813e839740307af78b1b16
--- /dev/null
+++ b/static/bg/bg_hallway.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:37d8cbbd1d512641baf2e05cea96aa85bcfee63b096f9514b89e3a46dee65f1e
+size 602652
diff --git a/static/bg/bg_home_room.png b/static/bg/bg_home_room.png
new file mode 100644
index 0000000000000000000000000000000000000000..a0a00353139fc35b08368d8389b885e2ace17a50
Binary files /dev/null and b/static/bg/bg_home_room.png differ
diff --git a/static/bg/bg_library.png b/static/bg/bg_library.png
new file mode 100644
index 0000000000000000000000000000000000000000..814aa264bd338a120d8e60357853bee6442ab139
--- /dev/null
+++ b/static/bg/bg_library.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f4e0afd77c6b4693c0dea3fe1a034345e1ac3612822e327495954ad2a27e1248
+size 270124
diff --git a/static/bg/bg_park.png b/static/bg/bg_park.png
new file mode 100644
index 0000000000000000000000000000000000000000..0c0c417b6dd5d6c7cfdcf881b237ddf27bcdc39b
Binary files /dev/null and b/static/bg/bg_park.png differ
diff --git a/static/bg/bg_rooftop.png b/static/bg/bg_rooftop.png
new file mode 100644
index 0000000000000000000000000000000000000000..91b86eb878bd5a9e0059bc40eb83ce358a0fe877
Binary files /dev/null and b/static/bg/bg_rooftop.png differ
diff --git a/static/bg/bg_sunset_hill.png b/static/bg/bg_sunset_hill.png
new file mode 100644
index 0000000000000000000000000000000000000000..66335c088f346ed45213ad69db1c06a468c708d7
Binary files /dev/null and b/static/bg/bg_sunset_hill.png differ
diff --git a/static/bg/classroom_bg.png b/static/bg/classroom_bg.png
new file mode 100644
index 0000000000000000000000000000000000000000..b39811c3dd4acf90d78a79cbc8da7cbe9d321a4f
--- /dev/null
+++ b/static/bg/classroom_bg.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bd9c85536a58b40c153057884a7888fbca3d677bdcf7feac22c83e3a45f3d7ec
+size 211051
diff --git a/static/sprites/curated/marie/_facegate_mask.png b/static/sprites/curated/marie/_facegate_mask.png
new file mode 100644
index 0000000000000000000000000000000000000000..2ba4d9ab9296712162207fe5cd9fe476898362fb
Binary files /dev/null and b/static/sprites/curated/marie/_facegate_mask.png differ
diff --git a/static/sprites/curated/marie/_preframe/marie_angry.png b/static/sprites/curated/marie/_preframe/marie_angry.png
new file mode 100644
index 0000000000000000000000000000000000000000..91f0976426c24fda1ff8b419ebb0996bd25b55d1
--- /dev/null
+++ b/static/sprites/curated/marie/_preframe/marie_angry.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:082d70483c0d05bdc41f58c1bd146afa1b81200423c80e077820581a290e12b5
+size 361496
diff --git a/static/sprites/curated/marie/_preframe/marie_embarrassed.png b/static/sprites/curated/marie/_preframe/marie_embarrassed.png
new file mode 100644
index 0000000000000000000000000000000000000000..aafa3c7868a1a42f1f1440131c129db3822ea1f2
--- /dev/null
+++ b/static/sprites/curated/marie/_preframe/marie_embarrassed.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:01a3c7e1f32bf84d0beed8ec41919978fcb7f75b80a90bb5afc7d2450ac15086
+size 361904
diff --git a/static/sprites/curated/marie/_preframe/marie_laugh.png b/static/sprites/curated/marie/_preframe/marie_laugh.png
new file mode 100644
index 0000000000000000000000000000000000000000..9da088d2d8e3ec9c69c41c845884d2f565907b94
--- /dev/null
+++ b/static/sprites/curated/marie/_preframe/marie_laugh.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ecf4ad2e44915da7a87688dd8b096be49a8a5af342f8fa25979ee179ca8eca86
+size 361608
diff --git a/static/sprites/curated/marie/_preframe/marie_neutral.png b/static/sprites/curated/marie/_preframe/marie_neutral.png
new file mode 100644
index 0000000000000000000000000000000000000000..6dff7dbb480ecf608d4175826f2630a0b620044e
--- /dev/null
+++ b/static/sprites/curated/marie/_preframe/marie_neutral.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:37ea9052905c58b62acc8262d97530efb014a43047ca7b41ec0b61483b7a191e
+size 361748
diff --git a/static/sprites/curated/marie/_preframe/marie_sad.png b/static/sprites/curated/marie/_preframe/marie_sad.png
new file mode 100644
index 0000000000000000000000000000000000000000..557cc8f2ca7c39e27778752ce4ee896b0e475928
--- /dev/null
+++ b/static/sprites/curated/marie/_preframe/marie_sad.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4c4c97af6e429b83baa2d2acfdbaf2cea948769808eaea86720ff864c2ffcb2f
+size 361210
diff --git a/static/sprites/curated/marie/_preframe/marie_smile.png b/static/sprites/curated/marie/_preframe/marie_smile.png
new file mode 100644
index 0000000000000000000000000000000000000000..34d98cbce4b1ee42f2040c839ec1dd424e21fc45
--- /dev/null
+++ b/static/sprites/curated/marie/_preframe/marie_smile.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bbef51574fd1594eaf076e13e10722963486cdcf0b79cd11e7c76aa5bd8ade1a
+size 361373
diff --git a/static/sprites/curated/marie/_preframe/marie_surprised.png b/static/sprites/curated/marie/_preframe/marie_surprised.png
new file mode 100644
index 0000000000000000000000000000000000000000..882e1681f042635a9d6d324a3dc1a6364fa88578
--- /dev/null
+++ b/static/sprites/curated/marie/_preframe/marie_surprised.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d45737f7972fce06ea0242ea46c1e610eefabeeeeaaf52b5aa917e75ac2a56dd
+size 361723
diff --git a/static/sprites/curated/marie/marie_angry.png b/static/sprites/curated/marie/marie_angry.png
new file mode 100644
index 0000000000000000000000000000000000000000..ef3c0d276387f723d815b59cfeeb01049eea78da
--- /dev/null
+++ b/static/sprites/curated/marie/marie_angry.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3eafdee475aa29e0220ac8f64b7dcbf9df2dc3af359475cc47e6cdcd4f28540e
+size 594310
diff --git a/static/sprites/curated/marie/marie_base.png b/static/sprites/curated/marie/marie_base.png
new file mode 100644
index 0000000000000000000000000000000000000000..56bfcfdf9a0825165860eadaac10233e140e5242
--- /dev/null
+++ b/static/sprites/curated/marie/marie_base.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c216419dcb2376b932016ff7a80f85016077d4b6f79718c161ecbb63e2d6d26d
+size 305194
diff --git a/static/sprites/curated/marie/marie_embarrassed.png b/static/sprites/curated/marie/marie_embarrassed.png
new file mode 100644
index 0000000000000000000000000000000000000000..0b83f86e4308b9224ede3b1e23d21becf814c845
--- /dev/null
+++ b/static/sprites/curated/marie/marie_embarrassed.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8691392cbd3e6112a7a49f03dc4e09a7e7ea7eb3d3531b75ef393bbb3d38159e
+size 595393
diff --git a/static/sprites/curated/marie/marie_laugh.png b/static/sprites/curated/marie/marie_laugh.png
new file mode 100644
index 0000000000000000000000000000000000000000..bf1c50a074f00657b151390bafe6508b9b9dba09
--- /dev/null
+++ b/static/sprites/curated/marie/marie_laugh.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c472d1f3a4f820da7f999fa1a5cb9f190892a2ffa2dd2eba326c183379202fcb
+size 594567
diff --git a/static/sprites/curated/marie/marie_neutral.png b/static/sprites/curated/marie/marie_neutral.png
new file mode 100644
index 0000000000000000000000000000000000000000..6638d9a7a1638d6adde8a2a1968e7e191a393ab4
--- /dev/null
+++ b/static/sprites/curated/marie/marie_neutral.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3c7be07288d554497f64f94278c1dea3f3c0b8d7e7daa6cfeea85117531b15a8
+size 595129
diff --git a/static/sprites/curated/marie/marie_sad.png b/static/sprites/curated/marie/marie_sad.png
new file mode 100644
index 0000000000000000000000000000000000000000..f290881c4b6ededd0375703e28f95ebe2b7e9a26
--- /dev/null
+++ b/static/sprites/curated/marie/marie_sad.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0b5cdf3b94a7d5b2a1688b431014d199af975839a59793c3745b5e1c28389aaf
+size 593701
diff --git a/static/sprites/curated/marie/marie_smile.png b/static/sprites/curated/marie/marie_smile.png
new file mode 100644
index 0000000000000000000000000000000000000000..9ac394e89a5250599ac2e98b4e2897531f2e6c00
--- /dev/null
+++ b/static/sprites/curated/marie/marie_smile.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9e758678fd3c9c6b615b2b7dba3ff2310dea3298f677d657b21a3be3aff3814d
+size 593977
diff --git a/static/sprites/curated/marie/marie_surprised.png b/static/sprites/curated/marie/marie_surprised.png
new file mode 100644
index 0000000000000000000000000000000000000000..8ad27bd11f47ec918bbbac60603d69968065ced9
--- /dev/null
+++ b/static/sprites/curated/marie/marie_surprised.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6a5c71a52347e64180fb89606a10556d970f488a518e22b27ae741b22566be8e
+size 595130
diff --git a/static/sprites/curated/sakura/_facegate_mask.png b/static/sprites/curated/sakura/_facegate_mask.png
new file mode 100644
index 0000000000000000000000000000000000000000..5bfb65f7c6572ccfc7fcecc2491195df843b0680
Binary files /dev/null and b/static/sprites/curated/sakura/_facegate_mask.png differ
diff --git a/static/sprites/curated/sakura/_preframe/sakura_angry.png b/static/sprites/curated/sakura/_preframe/sakura_angry.png
new file mode 100644
index 0000000000000000000000000000000000000000..8e0588df47d308290f933e62b7d31a23d219388a
--- /dev/null
+++ b/static/sprites/curated/sakura/_preframe/sakura_angry.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e893a6009916f6b303ba13b07945b6781d0cd4e4bce78435482f8241f6035016
+size 215408
diff --git a/static/sprites/curated/sakura/_preframe/sakura_embarrassed.png b/static/sprites/curated/sakura/_preframe/sakura_embarrassed.png
new file mode 100644
index 0000000000000000000000000000000000000000..12f3a5436b3dc151725cde2a00bda24b33dcb418
--- /dev/null
+++ b/static/sprites/curated/sakura/_preframe/sakura_embarrassed.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:39704879f941714a464b7fe60c31b1ea625e7c9b624bad63c9e318de9e29fd6f
+size 216006
diff --git a/static/sprites/curated/sakura/_preframe/sakura_laugh.png b/static/sprites/curated/sakura/_preframe/sakura_laugh.png
new file mode 100644
index 0000000000000000000000000000000000000000..01f39dadf7f371e6d15894c10506ee34998c310d
--- /dev/null
+++ b/static/sprites/curated/sakura/_preframe/sakura_laugh.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a76cc1f841ae8ac5b44d48fc17f446b9a890dff3fa42a65103c5272b9ffe5110
+size 215769
diff --git a/static/sprites/curated/sakura/_preframe/sakura_neutral.png b/static/sprites/curated/sakura/_preframe/sakura_neutral.png
new file mode 100644
index 0000000000000000000000000000000000000000..14c93c91e546a3d76c556ccf76f89b19f0577d9d
--- /dev/null
+++ b/static/sprites/curated/sakura/_preframe/sakura_neutral.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d6e1c2922127fa3769a409f3954db6de4808fe92497a176dd7302070b22af07f
+size 215784
diff --git a/static/sprites/curated/sakura/_preframe/sakura_sad.png b/static/sprites/curated/sakura/_preframe/sakura_sad.png
new file mode 100644
index 0000000000000000000000000000000000000000..63134929be4438ede460e2904e308f8545c69869
--- /dev/null
+++ b/static/sprites/curated/sakura/_preframe/sakura_sad.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b3d6bd0114cab5681ec23d2ebb06a0638446d29cbae02b0bd80bc9e3fd2f8051
+size 215199
diff --git a/static/sprites/curated/sakura/_preframe/sakura_smile.png b/static/sprites/curated/sakura/_preframe/sakura_smile.png
new file mode 100644
index 0000000000000000000000000000000000000000..f56b175ea43de293c702eb058252930cfd5b9616
--- /dev/null
+++ b/static/sprites/curated/sakura/_preframe/sakura_smile.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ed5877bb5c6a08056dffc09896148fd8dec020f277e1e91ff09f5f758c019370
+size 215395
diff --git a/static/sprites/curated/sakura/_preframe/sakura_surprised.png b/static/sprites/curated/sakura/_preframe/sakura_surprised.png
new file mode 100644
index 0000000000000000000000000000000000000000..e6d14f308f36f9e0bac5609674f377e1f9ca4d55
--- /dev/null
+++ b/static/sprites/curated/sakura/_preframe/sakura_surprised.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0d8089232495891aaf7472f070c48f497653f66e3c5a05a1edb876fb51dcdb62
+size 215423
diff --git a/static/sprites/curated/sakura/sakura_angry.png b/static/sprites/curated/sakura/sakura_angry.png
new file mode 100644
index 0000000000000000000000000000000000000000..e9d3ef3ae58ea8d7d32659396575ac3d946ce324
--- /dev/null
+++ b/static/sprites/curated/sakura/sakura_angry.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1f345d0375b6035ea8f3e030d214ab82580d7b124dc7cf6f1078112a7f5d8992
+size 350518
diff --git a/static/sprites/curated/sakura/sakura_base.png b/static/sprites/curated/sakura/sakura_base.png
new file mode 100644
index 0000000000000000000000000000000000000000..af5301fe94b3153412729060efd3d65b436a7fa4
--- /dev/null
+++ b/static/sprites/curated/sakura/sakura_base.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3f9c7881ae2005cb996430c4ee105f785468053607ffce736bdf7b76ad75e1eb
+size 236110
diff --git a/static/sprites/curated/sakura/sakura_embarrassed.png b/static/sprites/curated/sakura/sakura_embarrassed.png
new file mode 100644
index 0000000000000000000000000000000000000000..108bbbb371b6bfbe895d035c21db327f55a0ef5b
--- /dev/null
+++ b/static/sprites/curated/sakura/sakura_embarrassed.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f72d41bb54889df079ad1b676fde4b34ddf2528608fc13485f324b92b03188df
+size 351854
diff --git a/static/sprites/curated/sakura/sakura_laugh.png b/static/sprites/curated/sakura/sakura_laugh.png
new file mode 100644
index 0000000000000000000000000000000000000000..353a0c1051e5d360ec871b21727e7e0378724cf8
--- /dev/null
+++ b/static/sprites/curated/sakura/sakura_laugh.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:15048efc5ddd1c57b16c471b93ea8bdcf989d26c252450bbf3f7a51ad1903587
+size 351343
diff --git a/static/sprites/curated/sakura/sakura_neutral.png b/static/sprites/curated/sakura/sakura_neutral.png
new file mode 100644
index 0000000000000000000000000000000000000000..f60a1498191dc2f3c26601834c288d96e9b18879
--- /dev/null
+++ b/static/sprites/curated/sakura/sakura_neutral.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d94cef78eb928a4e57a62259c71be8f85ab5ed6df8045386f82e5ab280312663
+size 351850
diff --git a/static/sprites/curated/sakura/sakura_sad.png b/static/sprites/curated/sakura/sakura_sad.png
new file mode 100644
index 0000000000000000000000000000000000000000..612973de638a953d999c9211e25132f0dea5d56d
--- /dev/null
+++ b/static/sprites/curated/sakura/sakura_sad.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:de0880b2790c1eeffa2844af1b1cd83efd34f3cafc87882b1be9211dc1285435
+size 350184
diff --git a/static/sprites/curated/sakura/sakura_smile.png b/static/sprites/curated/sakura/sakura_smile.png
new file mode 100644
index 0000000000000000000000000000000000000000..3339903b08c1e62d657f04532b07a099c3c18742
--- /dev/null
+++ b/static/sprites/curated/sakura/sakura_smile.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9a24cfecbbc3e0293571fc926b3df58f828212b44735612ec54fef87f809a170
+size 350595
diff --git a/static/sprites/curated/sakura/sakura_surprised.png b/static/sprites/curated/sakura/sakura_surprised.png
new file mode 100644
index 0000000000000000000000000000000000000000..2fa33147c251766f2640b44b605b84ef5b1e52a3
--- /dev/null
+++ b/static/sprites/curated/sakura/sakura_surprised.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:456449800cb8054d19b646e58b80ac298ce7a8dbbbd0b8963e66181abdaeb853
+size 350603
diff --git a/static/sprites/curated/yuki/_facegate_mask.png b/static/sprites/curated/yuki/_facegate_mask.png
new file mode 100644
index 0000000000000000000000000000000000000000..d2a7b63425572b35a5764019ad1b43cefffd3d1a
Binary files /dev/null and b/static/sprites/curated/yuki/_facegate_mask.png differ
diff --git a/static/sprites/curated/yuki/_preframe/yuki_angry.png b/static/sprites/curated/yuki/_preframe/yuki_angry.png
new file mode 100644
index 0000000000000000000000000000000000000000..938362d9c854468d036995c922803dc10fb462ed
--- /dev/null
+++ b/static/sprites/curated/yuki/_preframe/yuki_angry.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:76013955025a5cb32da91c34861cc2057c2ed28de00d27c1e50b5e4431082455
+size 211861
diff --git a/static/sprites/curated/yuki/_preframe/yuki_embarrassed.png b/static/sprites/curated/yuki/_preframe/yuki_embarrassed.png
new file mode 100644
index 0000000000000000000000000000000000000000..3fb04985877ca3ecfd0f30c02dbd8757a546ecbb
--- /dev/null
+++ b/static/sprites/curated/yuki/_preframe/yuki_embarrassed.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:767236f269aae5483483659434091eb7531519079a84b710dde70d413dec5c1d
+size 212117
diff --git a/static/sprites/curated/yuki/_preframe/yuki_laugh.png b/static/sprites/curated/yuki/_preframe/yuki_laugh.png
new file mode 100644
index 0000000000000000000000000000000000000000..205a4721f1cf7212f40671070a764ebca242cba3
--- /dev/null
+++ b/static/sprites/curated/yuki/_preframe/yuki_laugh.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d94095652cbec5070e61148e082544d538dcd8c3240397e3dc9ef4091cd8b567
+size 212171
diff --git a/static/sprites/curated/yuki/_preframe/yuki_neutral.png b/static/sprites/curated/yuki/_preframe/yuki_neutral.png
new file mode 100644
index 0000000000000000000000000000000000000000..ec7f9b6f2cad578283e973c2b8c52d51cde6189c
--- /dev/null
+++ b/static/sprites/curated/yuki/_preframe/yuki_neutral.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3c0fba92d4d4802b4e74af75d01ca54a80486842cded8cf3590f7d5c389334a9
+size 211588
diff --git a/static/sprites/curated/yuki/_preframe/yuki_sad.png b/static/sprites/curated/yuki/_preframe/yuki_sad.png
new file mode 100644
index 0000000000000000000000000000000000000000..6638cd8eeb1afd049a6825f9dcfdb2cbb479bfad
--- /dev/null
+++ b/static/sprites/curated/yuki/_preframe/yuki_sad.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:871bbc7b7a85bf1759cfcaaddf21803090e013c2bfbf66f3e922ea8584bff5ca
+size 211619
diff --git a/static/sprites/curated/yuki/_preframe/yuki_smile.png b/static/sprites/curated/yuki/_preframe/yuki_smile.png
new file mode 100644
index 0000000000000000000000000000000000000000..1da0dd7a74189e415c67cb2ced6f9ad6a8c46c39
--- /dev/null
+++ b/static/sprites/curated/yuki/_preframe/yuki_smile.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8b9f3c3b9024da31b2dc629fdbab1d412deb63d474b814bdb48df4937db7422e
+size 211669
diff --git a/static/sprites/curated/yuki/_preframe/yuki_surprised.png b/static/sprites/curated/yuki/_preframe/yuki_surprised.png
new file mode 100644
index 0000000000000000000000000000000000000000..dee85e5aa279de156951f239a4c02e1fb3485556
--- /dev/null
+++ b/static/sprites/curated/yuki/_preframe/yuki_surprised.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:85e87a400bb23f286212b6601c9f76f4fe22799635b411ecd75512752b433d22
+size 211883
diff --git a/static/sprites/curated/yuki/yuki_angry.png b/static/sprites/curated/yuki/yuki_angry.png
new file mode 100644
index 0000000000000000000000000000000000000000..513746478d090e332923de29769b850079085a3d
--- /dev/null
+++ b/static/sprites/curated/yuki/yuki_angry.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bd934ce3ba707c1dcdf48bb47fbc40daa9154dbed0634c6c566b9441356e1b36
+size 352737
diff --git a/static/sprites/curated/yuki/yuki_base.png b/static/sprites/curated/yuki/yuki_base.png
new file mode 100644
index 0000000000000000000000000000000000000000..be37d71da3a3b5269e5748f12a6e3d1299455a35
--- /dev/null
+++ b/static/sprites/curated/yuki/yuki_base.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8fc16201edd074b6a944f8fdecbcb54540e2c82360763928b14b053aaeafd79f
+size 235532
diff --git a/static/sprites/curated/yuki/yuki_embarrassed.png b/static/sprites/curated/yuki/yuki_embarrassed.png
new file mode 100644
index 0000000000000000000000000000000000000000..38aa29e949600ab936d6a2ce60288305e07139df
--- /dev/null
+++ b/static/sprites/curated/yuki/yuki_embarrassed.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:18fbc392f12ff278e06cb2f389e9690f627684317a1b843f51dcb0d65fb2c229
+size 353357
diff --git a/static/sprites/curated/yuki/yuki_laugh.png b/static/sprites/curated/yuki/yuki_laugh.png
new file mode 100644
index 0000000000000000000000000000000000000000..373c7bc4f5a6a706631aba5505b267b459a73e3a
--- /dev/null
+++ b/static/sprites/curated/yuki/yuki_laugh.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:60a76a6d0ef04bc9742d5d8337fa9a8c3d5478a78323f297ccff9d674bab4594
+size 353543
diff --git a/static/sprites/curated/yuki/yuki_neutral.png b/static/sprites/curated/yuki/yuki_neutral.png
new file mode 100644
index 0000000000000000000000000000000000000000..0840402fb9159ef9754a93fdbd5059bf989db581
--- /dev/null
+++ b/static/sprites/curated/yuki/yuki_neutral.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:078bd5841a0ce00931e20f19fb2abdaf09460e0ffda87b3996d3b170dc2f4aaa
+size 352493
diff --git a/static/sprites/curated/yuki/yuki_sad.png b/static/sprites/curated/yuki/yuki_sad.png
new file mode 100644
index 0000000000000000000000000000000000000000..74db579befa085c21de3e4b0930a0c447354cd47
--- /dev/null
+++ b/static/sprites/curated/yuki/yuki_sad.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:65787317ddb33836b77ce008ec611b3983432a46e8b5c512c18a09b2614bd6f6
+size 352271
diff --git a/static/sprites/curated/yuki/yuki_smile.png b/static/sprites/curated/yuki/yuki_smile.png
new file mode 100644
index 0000000000000000000000000000000000000000..6fcc92a7e5391a7442766e62bf5fcf11c9b498b5
--- /dev/null
+++ b/static/sprites/curated/yuki/yuki_smile.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:96b511830990b74ae02cb01456a6aaecc7c362185301a45fcb5b7e5b01f197af
+size 352372
diff --git a/static/sprites/curated/yuki/yuki_surprised.png b/static/sprites/curated/yuki/yuki_surprised.png
new file mode 100644
index 0000000000000000000000000000000000000000..c78c3338292abd2762f8a3e2d7b5bb21647f6089
--- /dev/null
+++ b/static/sprites/curated/yuki/yuki_surprised.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:38ba56655d1eec7723930281e5cdf4eefca27a4b4d2e901d68dee40488530445
+size 353023
diff --git a/trace_log.py b/trace_log.py
new file mode 100644
index 0000000000000000000000000000000000000000..c04abd52a6becdbcea65d4473934749d167516b7
--- /dev/null
+++ b/trace_log.py
@@ -0,0 +1,68 @@
+"""
+trace_log.py — capture model prompt→response traces for later fine-tuning.
+
+Every real narration turn is appended as one JSON line to a dated file under
+the trace directory. Each record is already in the standard SFT chat shape
+(a `messages` list ending in the assistant's raw response), with extra
+`context` fields alongside for curating/filtering the dataset later:
+
+    {"ts": "...", "model": "...", "context": {...},
+     "messages": [{"role":"system",...},{"role":"user",...},
+                  {"role":"assistant","content": "<raw model output>"}]}
+
+To build a training set, read the lines and keep `record["messages"]`
+(drop the trailing assistant turn at inference time).
+
+Controls:
+  ARS_FABULA_TRACE      = "1"|"on" (default) to log, "0"|"off"|"false" to disable
+  ARS_FABULA_TRACE_DIR  = output directory (default: "logs/traces")
+
+Mock/scripted responses are NOT logged — the engine skips logging when the
+model reports `is_mock` (see run_turn), so tests and mock fallbacks don't
+pollute the dataset.
+"""
+from __future__ import annotations
+import os
+import json
+from datetime import datetime, date
+from pathlib import Path
+from typing import Optional
+
+
+_DISABLED = {"0", "off", "false", "no", ""}
+
+
+def traces_enabled() -> bool:
+    return os.getenv("ARS_FABULA_TRACE", "1").strip().lower() not in _DISABLED
+
+
+def _trace_dir() -> Path:
+    return Path(os.getenv("ARS_FABULA_TRACE_DIR", "logs/traces"))
+
+
+def log_turn(messages: list[dict], response: str, *,
+             model: str = "", context: Optional[dict] = None) -> None:
+    """Append one prompt→response trace as a JSON line.
+
+    Best-effort: any IO/serialization error is swallowed so a logging
+    problem can never break a turn. `messages` is the prompt sent to the
+    model (system + user); the assistant's raw `response` is appended so the
+    stored `messages` list is directly usable for supervised fine-tuning.
+    """
+    if not traces_enabled():
+        return
+    try:
+        rec = {
+            "ts": datetime.now().isoformat(timespec="seconds"),
+            "model": model,
+            "context": context or {},
+            "messages": list(messages) + [{"role": "assistant", "content": response}],
+        }
+        out_dir = _trace_dir()
+        out_dir.mkdir(parents=True, exist_ok=True)
+        path = out_dir / f"turns-{date.today().isoformat()}.jsonl"
+        with open(path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(rec, ensure_ascii=False) + "\n")
+    except Exception:
+        # Never let trace logging interfere with the turn loop.
+        pass
diff --git a/ui/__init__.py b/ui/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..34d84f7e04cfdbb617bc9dd718430c8fdfed6315
--- /dev/null
+++ b/ui/__init__.py
@@ -0,0 +1 @@
+"""UI layer for the Ars-Fabula VN (Gradio)."""
diff --git a/ui/beats.py b/ui/beats.py
new file mode 100644
index 0000000000000000000000000000000000000000..45b89a36aa428c28cc9fc950d023b25d8ed4bdfd
--- /dev/null
+++ b/ui/beats.py
@@ -0,0 +1,294 @@
+"""Response → display beats: strip protocol markers, split a turn into paced
+narration/dialogue beats, and render the screen for a given beat.
+"""
+from __future__ import annotations
+import os
+import re
+from typing import Optional
+
+from vn_contracts import CastMember, SceneState
+from providers import BackgroundProvider
+
+from .screens import _cast_panel_html_inner, _vn_screen_html
+
+
+_MARKER_PREFIXES = ("TOOL", "Engine", "CAST-LOCK", "STATE", "ENDSTATE")
+
+
+def clean_narration(text: str) -> str:
+    """Strip protocol/engine markers from narration for player-facing display.
+
+    The engine returns the raw model response as the transcript, which still
+    contains the `[TOOL: ...]` calls (the protocol) plus any `[Engine: ...]` /
+    `[CAST-LOCK ...]` notes. Those are machine markers, not prose — remove them
+    before the text reaches the dialogue box or the Scene Log.
+
+    Bracket-depth + quote aware, so the JSON inside an offer_choices call
+    (which carries its own [ ] { } and quoted strings) is removed as one unit
+    rather than truncated at the first ']'.
+    """
+    if not text:
+        return text
+    out = []
+    i, n = 0, len(text)
+    while i < n:
+        if text[i] == '[':
+            m = re.match(r'\[\s*([A-Za-z-]+)', text[i:])
+            if m and m.group(1) in _MARKER_PREFIXES:
+                depth = in_str = esc = 0
+                j = i
+                while j < n:
+                    c = text[j]
+                    if esc:
+                        esc = 0
+                    elif c == '\\':
+                        esc = 1
+                    elif in_str:
+                        if c == '"':
+                            in_str = 0
+                    elif c == '"':
+                        in_str = 1
+                    elif c == '[':
+                        depth += 1
+                    elif c == ']':
+                        depth -= 1
+                        if depth == 0:
+                            j += 1
+                            break
+                    j += 1
+                i = j
+                continue
+        out.append(text[i])
+        i += 1
+    # Collapse the blank lines left where markers were removed.
+    return re.sub(r'\n[ \t]*(?:\n[ \t]*)+\n', '\n\n', "".join(out)).strip()
+
+
+def _split_markers(text: str) -> list[tuple[str, str]]:
+    """Walk a model response into ordered ('marker'|'text', chunk) segments.
+
+    Markers are the [TOOL:]/[Engine:]/[CAST-LOCK:]… spans (bracket + quote
+    aware so an offer_choices JSON blob is one span). Dialogue lines like
+    `[Yuki]: "..."` are NOT markers — their prefix isn't in _MARKER_PREFIXES —
+    so they stay in the text segments where the beat splitter can see them.
+    """
+    segs: list[tuple[str, str]] = []
+    buf: list[str] = []
+    i, n = 0, len(text)
+
+    def flush():
+        if buf:
+            segs.append(("text", "".join(buf)))
+            buf.clear()
+
+    while i < n:
+        if text[i] == '[':
+            m = re.match(r'\[\s*([A-Za-z-]+)', text[i:])
+            if m and m.group(1) in _MARKER_PREFIXES:
+                depth = in_str = esc = 0
+                j = i
+                while j < n:
+                    c = text[j]
+                    if esc:
+                        esc = 0
+                    elif c == '\\':
+                        esc = 1
+                    elif in_str:
+                        if c == '"':
+                            in_str = 0
+                    elif c == '"':
+                        in_str = 1
+                    elif c == '[':
+                        depth += 1
+                    elif c == ']':
+                        depth -= 1
+                        if depth == 0:
+                            j += 1
+                            break
+                    j += 1
+                flush()
+                segs.append(("marker", text[i:j]))
+                i = j
+                continue
+        buf.append(text[i])
+        i += 1
+    flush()
+    return segs
+
+
+# Speaker line: an optionally-bracketed name prefix ("Yuki:", "[Yuki]:") then
+# the line. We do NOT trust the bracket/quote shape — the captured name is
+# validated against the locked cast in _segment_beats, and only a real cast
+# member makes it a speaker (and gets highlighted). This keeps the highlight
+# consistent no matter how the model punctuated the line. Group 2 is the rest
+# of the line (wrapping quotes stripped separately).
+_SPEAKER_RE = re.compile(r'^\s*\[?\s*([^\[\]:]{1,40}?)\s*\]?\s*:\s*(.+)$')
+
+
+def _strip_wrapping_quotes(text: str) -> str:
+    """Drop one layer of matching wrapping quotes (straight or smart)."""
+    t = text.strip()
+    for a, b in (('"', '"'), ("'", "'"), ("“", "”"), ("‘", "’")):
+        if len(t) >= 2 and t[0] == a and t[-1] == b:
+            return t[1:-1].strip()
+    return t
+
+# Narration pacing: cap each narration beat so the dialogue box never holds a
+# wall of text. Whichever limit hits first ends the chunk; the rest becomes
+# the next click-through beat (content is split, never truncated).
+NARR_MAX_SENTENCES = 2
+NARR_MAX_CHARS = 240
+_SENTENCE_RE = re.compile(r'[^.!?…]*[.!?…]+["”\')\]]?|\S[^.!?…]*$')
+
+
+def _chunk_narration(text: str) -> list[str]:
+    """Split narration into <=NARR_MAX_SENTENCES, <=NARR_MAX_CHARS chunks."""
+    text = text.strip()
+    if not text:
+        return []
+    sentences = [s.strip() for s in _SENTENCE_RE.findall(text) if s.strip()]
+    if not sentences:
+        return [text]
+    chunks, cur = [], ""
+    n = 0
+    for s in sentences:
+        candidate = (cur + " " + s).strip() if cur else s
+        if cur and (n >= NARR_MAX_SENTENCES or len(candidate) > NARR_MAX_CHARS):
+            chunks.append(cur)
+            cur, n = s, 1
+        else:
+            cur, n = candidate, n + 1
+    if cur:
+        chunks.append(cur)
+    return chunks
+
+
+def _segment_beats(response: str, cast: dict[str, CastMember],
+                   init_expr: dict[str, str], init_bg: str,
+                   init_present: list[str] | None = None,
+                   voice_line=None) -> list[dict]:
+    """Split a turn's response into ordered display beats for paced reading.
+
+    A beat is one narration paragraph or one dialogue line, tagged with the
+    sprite expressions, background, and present characters in effect at that
+    point — so a set_expression or enter_character that PRECEDES a line lands
+    on that line's beat (the VN's emotional lever). Tool/engine markers are
+    consumed to advance the running visual state, never shown. The single
+    voiced line (if any) is attached to the beat whose dialogue it matches.
+
+    Args:
+        response: Raw model response text.
+        cast: The locked cast.
+        init_expr: Initial expression state before processing this response.
+        init_bg: Initial background before processing this response.
+        init_present: Initial present list before processing this response.
+            If None, starts empty (characters must be called in).
+        voice_line: Optional VoiceLine from the engine.
+    """
+    from vn_engine import parse_tool_calls, _check_cast_lock
+
+    expr = dict(init_expr or {})
+    bg = init_bg or "classroom"
+    present = list(init_present) if init_present is not None else []
+    beats: list[dict] = []
+    narr: list[str] = []
+
+    def flush_narr():
+        text = " ".join(s for s in narr).strip()
+        narr.clear()
+        # One beat per <=2-sentence chunk so long narration paces out
+        # instead of cluttering the box.
+        for chunk in _chunk_narration(text):
+            beats.append({"speaker": "", "text": chunk,
+                          "expressions": dict(expr), "background": bg,
+                          "present": list(present), "voice": None})
+
+    for kind, chunk in _split_markers(response):
+        if kind == "marker":
+            for call in parse_tool_calls(chunk):
+                tool = call.get("tool")
+                if tool == "set_expression":
+                    canon = _check_cast_lock(call.get("character", ""), cast)
+                    e = call.get("expression", "")
+                    if canon and canon in cast and e in cast[canon].expression_map:
+                        expr[canon] = e
+                elif tool in ("advance_scene", "set_background") and call.get("background"):
+                    bg = call["background"]
+                elif tool == "enter_character":
+                    canon = _check_cast_lock(call.get("character", ""), cast)
+                    if canon and canon not in present:
+                        present.append(canon)
+                elif tool == "exit_character":
+                    canon = _check_cast_lock(call.get("character", ""), cast)
+                    if canon and canon in present:
+                        present.remove(canon)
+            continue
+        for line in chunk.split("\n"):
+            s = line.strip()
+            if not s:
+                flush_narr()
+                continue
+            m = _SPEAKER_RE.match(s)
+            canon = _check_cast_lock(m.group(1).strip(), cast) if m else None
+            if canon:
+                flush_narr()
+                beats.append({"speaker": canon,
+                              "text": _strip_wrapping_quotes(m.group(2)),
+                              "expressions": dict(expr), "background": bg,
+                              "present": list(present), "voice": None})
+            else:
+                narr.append(s)
+        flush_narr()
+
+    if voice_line and getattr(voice_line, "wav_path", None) and os.path.exists(voice_line.wav_path):
+        target = (voice_line.text or "").strip()
+        for b in beats:
+            if b["speaker"] and b["text"].strip() == target:
+                b["voice"] = voice_line.wav_path
+                break
+
+    return beats
+
+
+def _render_beats_screen(beats: list[dict], idx: int, scene: SceneState,
+                         bg_provider: BackgroundProvider,
+                         prev_bg_path: str,
+                         log_text: str = "") -> tuple[str, str, Optional[str]]:
+    """Render the VN screen for beat `idx`. Choices appear only on the final
+    beat; earlier beats show the ▼ continue hint. The HUD, scene-log panel and
+    cast panel are baked into the canvas HTML. Returns
+    (screen_html, new_prev_bg_path, voice_path)."""
+    cast_html = _cast_panel_html_inner(scene.cast)
+
+    if not beats:
+        bg_info = bg_provider.get_background(scene.background)
+        screen = _vn_screen_html(bg_info.path, scene.cast, scene.present,
+                                 scene.expressions, choices=scene.choices,
+                                 prev_bg_path=prev_bg_path,
+                                 log_text=log_text, cast_html=cast_html)
+        return screen, bg_info.path, None
+
+    idx = max(0, min(idx, len(beats) - 1))
+    beat = beats[idx]
+    is_last = idx == len(beats) - 1
+    bg_info = bg_provider.get_background(beat["background"])
+
+    screen = _vn_screen_html(
+        bg_path=bg_info.path,
+        cast=scene.cast,
+        present=beat.get("present", scene.present),
+        expressions=beat["expressions"],
+        dialogue_speaker=beat["speaker"],
+        dialogue_text=beat["text"] if beat["speaker"] else "",
+        narration=beat["text"] if not beat["speaker"] else "",
+        choices=scene.choices if is_last else None,
+        prev_bg_path=prev_bg_path,
+        more=not is_last,
+        log_text=log_text,
+        cast_html=cast_html,
+    )
+
+    voice_path = beat.get("voice")
+    if voice_path and not os.path.exists(voice_path):
+        voice_path = None
+    return screen, bg_info.path, voice_path
diff --git a/ui/bootstrap.py b/ui/bootstrap.py
new file mode 100644
index 0000000000000000000000000000000000000000..75256009b8ca24e2066993b43230cd6f1c1fb5fe
--- /dev/null
+++ b/ui/bootstrap.py
@@ -0,0 +1,201 @@
+"""App bootstrap: constants, the initial scene, and engine construction
+(real LLM if reachable, mock otherwise).
+"""
+from __future__ import annotations
+import os
+
+from vn_contracts import SceneState, CastMember, cast_to_dict
+from vn_engine import VNEngine
+from cast_pipeline import load_curated_cast
+from providers import get_voice_provider
+from model_client import get_model, ModelConfig, MockModel
+
+
+# ── Constants ─────────────────────────────────────────────────────────
+
+PROJECT_DIR = os.path.dirname(__file__)
+STATIC_DIR = os.path.join(PROJECT_DIR, "static")
+
+# Default cast (loaded at startup) — pipeline returns list (frozen contract);
+# SceneState wants the name->member dict.
+DEFAULT_CAST = cast_to_dict(load_curated_cast())
+
+
+def make_initial_scene(cast=None, player_name: str = "Player") -> SceneState:
+    if cast is None:
+        cast = DEFAULT_CAST
+    return SceneState(
+        cast=cast,
+        present=[],  # characters enter via enter_character as they appear
+        background="classroom",
+        mood="peaceful",
+        turn=0,
+        chapter="Prologue",
+        player_name=player_name,
+    )
+
+
+
+# ── Mock VN LLM ───────────────────────────────────────────────────────
+
+def _make_mock_engine(cast: dict[str, CastMember], player_name: str = "Player") -> MockModel:
+    """Create a MockModel that generates varied multi-character VN scenes.
+
+    Exercises enter_character/exit_character across beats to verify per-beat
+    presence tracking manually. Each branch produces a different character
+    lineup so the tester can see characters pop in/out visually.
+    """
+    char_names = list(cast.keys())
+    # Expect Yuki (idx 0), Haruki (idx 1), Sakura (idx 2), Ryo (idx 3)
+    yuki = char_names[0] if len(char_names) > 0 else "Yuki"
+    haruki = char_names[1] if len(char_names) > 1 else "Haruki"
+    sakura = char_names[2] if len(char_names) > 2 else "Sakura"
+    ryo = char_names[3] if len(char_names) > 3 else "Ryo"
+
+    def handler(messages, tools):
+        user_msgs = [m for m in messages if m["role"] == "user"]
+        raw_choice = user_msgs[-1]["content"] if user_msgs else ""
+        # Extract just the player's choice text after [CHOICE MADE]
+        choice_match = __import__("re").search(r"\[CHOICE MADE\]\n(.+?)\n\nWrite the next scene", raw_choice, __import__("re").DOTALL)
+        choice_text = choice_match.group(1).strip() if choice_match else ""
+        choice_lower = choice_text.lower()
+
+        # ── "talk" → Yuki + Haruki enter one-by-one ──────────────
+        if "talk" in choice_lower or yuki.lower() in choice_lower:
+            return (
+                f'[TOOL: enter_character character="{yuki}"]\n\n'
+                f'[TOOL: set_expression character="{yuki}" expression="surprised"]\n\n'
+                f'[TOOL: advance_scene description="The afternoon sun filters through the classroom windows, casting warm rectangles of light across the wooden floor. The scent of chalk dust and summer lingers in the air." background="classroom" mood="cheerful"]\n\n'
+                f'[TOOL: set_expression character="{yuki}" expression="smile"]\n\n'
+                f'[{yuki}]: "Oh, hey! I didn\'t expect you to come over today. What\'s up?"\n\n'
+                f'Her smile is warm and genuine, the afternoon light catching in her hair.\n\n'
+                f'[TOOL: enter_character character="{haruki}"]\n\n'
+                f'[TOOL: set_expression character="{yuki}" expression="surprised"]\n\n'
+                f'The door slides open and {haruki} pokes their head in, eyebrows raising as they spot the two of you.\n\n'
+                f'[TOOL: set_expression character="{haruki}" expression="laugh"]\n\n'
+                f'[{haruki}]: "Am I interrupting something? Should I come back later?"\n\n'
+                f'They\'re clearly teasing, a playful glint in their eye.\n\n'
+                f'[TOOL: set_expression character="{yuki}" expression="embarrassed"]\n\n'
+                f'[{yuki}]: "No! I mean — we were just talking. Come sit down."\n\n'
+                f'The atmosphere shifts into something lighter, the three of you settling into the familiar rhythm of friends.\n\n'
+                f'[TOOL: offer_choices choices=\'[{{"id":"ask","text":"\\\"So what did you want to talk about?\\\"","consequence":"get serious"}},{{"id":"tease","text":"\\\"Look who\'s getting protective~\\\"","consequence":"tease them both"}},{{"id":"group","text":"\\\"Let\'s all hang out after school!\\\"","consequence":"make plans together"}}]\']'
+            )
+
+        # ── "look" / "alone" → Yuki enters, exits, then Sakura enters ──
+        # NOTE: no offer_choices — exercises the free-text fallback!
+        elif "look" in choice_lower or "alone" in choice_lower:
+            return (
+                f'[TOOL: enter_character character="{yuki}"]\n\n'
+                f'[TOOL: set_expression character="{yuki}" expression="sad"]\n\n'
+                f'[TOOL: advance_scene description="The classroom feels emptier than usual. Through the window, the courtyard buzzes with laughter muffled by glass." background="classroom" mood="melancholic"]\n\n'
+                f'[{yuki}]: "I\'ve been thinking a lot lately. About everything, really."\n\n'
+                f'They stare out the window, their reflection overlapping with the clouds drifting past.\n\n'
+                f'[TOOL: exit_character character="{yuki}"]\n\n'
+                f'The door clicks shut. The room settles into silence, dust motes dancing in the slanted light.\n\n'
+                f'[TOOL: enter_character character="{sakura}"]\n\n'
+                f'[TOOL: set_expression character="{sakura}" expression="smile"]\n\n'
+                f'[{sakura}]: "Hey. I saw {yuki} heading to the roof. They looked kinda down."\n\n'
+                f'She leans against the doorframe, concern flickering behind her cheerful demeanour. The silence stretches, waiting for you to fill it.'
+            )
+
+        # ── "confess" / "love" → Rooftop with interrupted confession ──
+        elif "confess" in choice_lower or "love" in choice_lower:
+            return (
+                f'[TOOL: enter_character character="{yuki}"]\n\n'
+                f'[TOOL: set_expression character="{yuki}" expression="surprised"]\n\n'
+                f'[TOOL: advance_scene description="Time seems to slow. The rooftop stretches out before you, the city glittering in the distance. Cherry blossom petals drift lazily on the warm breeze." background="rooftop" mood="romantic"]\n\n'
+                f'[TOOL: set_expression character="{yuki}" expression="embarrassed"]\n\n'
+                f'[{yuki}]: "I… I\'ve been wanting to tell you something for a while now."\n\n'
+                f'For a long, breathless moment, neither of you speaks. The wind carries petals between you.\n\n'
+                f'[TOOL: enter_character character="{haruki}"]\n\n'
+                f'[TOOL: set_expression character="{yuki}" expression="surprised"]\n\n'
+                f'[TOOL: set_expression character="{haruki}" expression="laugh"]\n\n'
+                f'[{haruki}]: "Whoa — sorry, sorry! I didn\'t mean to walk in on… whatever this is."\n\n'
+                f'They back away with their hands up, grinning, and disappear back through the door.\n\n'
+                f'[TOOL: exit_character character="{haruki}"]\n\n'
+                f'The moment hangs in the air again, fragile and electric.\n\n'
+                f'[TOOL: set_expression character="{yuki}" expression="smile"]\n\n'
+                f'[{yuki}]: "As I was saying… I really like you. I have for a long time."\n\n'
+                f'The sunset paints the world in shades of gold and pink.\n\n'
+                f'[TOOL: offer_choices choices=\'[{{"id":"hold_hands","text":"Take their hand","consequence":"a gentle touch","next_background":"sunset_hill","next_mood":"romantic","affection_flag":["{yuki}","confession"]}},{{"id":"hug","text":"Pull them into a hug","consequence":"embrace","next_background":"rooftop","next_mood":"romantic"}},{{"id":"speak","text":"\\\"I\'ve wanted to say it for so long too…\\\"","consequence":"vulnerable truth","next_background":"rooftop","next_mood":"romantic"}}]\']'
+            )
+
+        # ── Default / first turn → three characters gradually enter ──
+        else:
+            return (
+                f'[TOOL: enter_character character="{yuki}"]\n\n'
+                f'[TOOL: advance_scene description="The bell rings, signalling the end of another school day. Students begin packing their bags, the air filled with chatter and the shuffle of papers. Sunlight streams through the tall windows." background="classroom" mood="peaceful"]\n\n'
+                f'[TOOL: set_expression character="{yuki}" expression="smile"]\n\n'
+                f'[{yuki}]: "Hey {player_name}! Ready to head out?"\n\n'
+                f'They pack their bag with practiced ease, glancing at you expectantly.\n\n'
+                f'[TOOL: enter_character character="{haruki}"]\n\n'
+                f'[TOOL: set_expression character="{haruki}" expression="laugh"]\n\n'
+                f'[{haruki}]: "Leaving without me? I\'m hurt, really."\n\n'
+                f'They saunter over, slinging their bag over one shoulder, a familiar teasing grin on their face.\n\n'
+                f'[TOOL: set_expression character="{yuki}" expression="laugh"]\n\n'
+                f'[{yuki}]: "You take forever, {haruki}. We were about to send a search party."\n\n'
+                f'[TOOL: enter_character character="{sakura}"]\n\n'
+                f'[TOOL: set_expression character="{sakura}" expression="smile"]\n\n'
+                f'[{sakura}]: "Are we doing the café thing? I\'m starving."\n\n'
+                f'She appears from the hallway, already halfway out the door, flipping her hair with practiced nonchalance.\n\n'
+                f'[TOOL: set_expression character="{haruki}" expression="smile"]\n\n'
+                f'[{haruki}]: "Café sounds perfect. My treat — I just got paid for that tutoring gig."\n\n'
+                f'The three of them look at you, waiting, the late afternoon light pooling around them like a scene from a movie.\n\n'
+                f'[TOOL: offer_choices choices=\'[{{"id":"yes_cafe","text":"\\\"Sure, let\'s go!\\\"","consequence":"go to the cafe together"}},{{"id":"rain_check","text":"\\\"Maybe tomorrow? I\'ve got stuff to do.\\\"","consequence":"politely decline"}},{{"id":"walk","text":"\\\"I\'ll walk with you guys but I can\'t stay long.\\\"","consequence":"partial join"}}]\']'
+            )
+
+    return MockModel(handler=handler)
+
+
+# ── LLM / engine builders ─────────────────────────────────────────────
+
+def _try_real_llm():
+    """Try to connect to the real model server. Returns client or None,
+    and says exactly WHY it fell back when it does.
+
+    Uses ensure_llm() under the hood so the server gets a chance to
+    finish loading its model before we give up — the one-shot /health
+    check is too fragile when the 26B MoE takes 2-3 minutes to load."""
+    from model_client import ensure_llm
+
+    cfg = ModelConfig.from_env()
+    if cfg.backend == "mock":
+        print("[app] ARS_FABULA_BACKEND=mock is set — mock engine forced "
+              "(unset the env var for the real model)")
+        return None
+    if cfg.backend == "transformers":
+        # In-process model (HF Spaces / ZeroGPU) — no server, no /health.
+        client = get_model(cfg)
+        if client.health():
+            print("[app] In-process transformers model ready")
+            return client
+        print("[app] transformers backend configured but no model loaded "
+              "— falling back to mock")
+        return None
+    try:
+        if ensure_llm(cfg, timeout=300):
+            client = get_model(cfg)
+            print(f"[app] Connected to LLM server at {cfg.base_url}")
+            return client
+        base = cfg.base_url.rsplit("/v1", 1)[0]
+        print(f"[app] No model server at {cfg.base_url} "
+              f"(GET {base}/health got no healthy reply after 300s).")
+        print("[app] Start llama-server on that port, or set "
+              "ARS_FABULA_BASE_URL to where it lives.")
+    except Exception as e:
+        print(f"[app] LLM server check failed: {e}")
+    return None
+
+
+def build_engine(cast: dict[str, CastMember], scene: SceneState) -> tuple[VNEngine, str]:
+    """Build the VN engine: real model if reachable, mock otherwise.
+    Voice provider comes from ARS_FABULA_VOICE (mock/kokoro/chatterbox)."""
+    voice = get_voice_provider(os.getenv("ARS_FABULA_VOICE", "mock"))
+
+    real = _try_real_llm()
+    if real:
+        return VNEngine(model=real, cast=cast, scene=scene, voice=voice), "real LLM"
+
+    mock = _make_mock_engine(cast, player_name=scene.player_name)
+    print("[app] Using MOCK VN engine (no server needed)")
+    return VNEngine(model=mock, cast=cast, scene=scene, voice=voice), "mock LLM"
diff --git a/ui/callbacks.py b/ui/callbacks.py
new file mode 100644
index 0000000000000000000000000000000000000000..fc0052b32f09a7b1527ab533ec6504d10dbb48f7
--- /dev/null
+++ b/ui/callbacks.py
@@ -0,0 +1,425 @@
+"""Gradio event callbacks — casting beat, turns, save/load, advance, reset.
+Built by make_callbacks(bg_provider), closing over the background provider.
+"""
+from __future__ import annotations
+import os
+import time
+
+import gradio as gr
+
+from vn_contracts import SceneState, CastMember
+from providers import BackgroundProvider
+from cast_pipeline import load_curated_cast
+from vn_engine import read_save, load_cast_card
+
+from .bootstrap import make_initial_scene, build_engine
+from .screens import (_title_screen_html, _cast_panel_html,
+                      _casting_screen_html, _review_screen_html,
+                      _slot_rows_html)
+from .beats import clean_narration, _segment_beats, _render_beats_screen
+
+
+def make_callbacks(bg_provider: BackgroundProvider):
+    # All turn callbacks return/yield 11-tuples:
+    # (scene, engine, screen, cast, cast_panel, log, info, audio, prev_bg,
+    #  beats, beat_idx)   ← the last two drive read-at-your-own-pace.
+
+    def _empty(scene_state=None):
+        """No active scene → the title screen (also what Reset restores)."""
+        scene = scene_state or make_initial_scene()
+        return (scene, None,
+                _title_screen_html(),
+                {}, _cast_panel_html({}),
+                "", "No active scene", None, "", [], 0)
+
+    def on_start(cast_preset: str,
+                 casting_state,
+                 player_name: str = "Player",
+                 n1: str = "", c1: str = "", t1: str = "",
+                 n2: str = "", c2: str = "", t2: str = "",
+                 n3: str = "", c3: str = "", t3: str = "",
+                 fast: bool = False):
+        """The CASTING BEAT — generator for curated, state-machine init for generated.
+
+        Curated mode: yields progress screens as before (casting → portraits → scene).
+        Generated mode: designs characters, yields a loading screen, generates the
+        first base, yields the review screen, and ends — on_casting_confirm/redo
+        take over the interactive review loop from there.
+        """
+        cards = [{"name": n, "concept": c, "tags": t}
+                 for n, c, t in ((n1, c1, t1), (n2, c2, t2), (n3, c3, t3))
+                 if (n or "").strip()]
+
+        if cast_preset == "generated":
+            # Live sprite gen needs ComfyUI, which can't exist on HF Spaces /
+            # ZeroGPU (no external GPU servers) — use the curated cast there
+            # instead of walking the review flow with placeholder art.
+            from cast_pipeline import _comfy_health
+            if not _comfy_health():
+                print("[cast] ComfyUI unreachable — generated cast falls "
+                      "back to curated")
+                cast_preset = "curated"
+
+        if cast_preset == "generated":
+            from cast_pipeline import (set_fast_generation, build_custom_specs,
+                                       _generate_base_with_face_gate, _char_dir,
+                                       PRESET_CHARACTERS)
+            from model_client import release_vram
+
+            set_fast_generation(fast)
+
+            # Build specs: custom cards override presets
+            if cards:
+                specs = build_custom_specs(cards)
+                if not specs:
+                    specs = [(k, PRESET_CHARACTERS[k]) for k in ["yuki", "marie", "sakura"]]
+            else:
+                specs = [(k, PRESET_CHARACTERS[k]) for k in ["yuki", "marie", "sakura"]]
+
+            if not specs:
+                yield (*_empty(), None)
+                return
+
+            # VRAM: evict LLM so ComfyUI can load its models
+            char_keys = [k for k, _ in specs]
+            yield (None, None,
+                   _casting_screen_html(char_keys, {},
+                                        "Waking the artists…"),
+                   {}, _cast_panel_html({}), "", "Preparing…", None, "", [], 0, None)
+
+            release_vram()
+
+            # Generate first base for review
+            key, preset = specs[0]
+            char_dir = _char_dir(key)
+            base_path = _generate_base_with_face_gate(key, preset, char_dir)
+
+            new_state = {"specs": specs, "idx": 0, "phase": "review", "fast": fast}
+
+            screen = _review_screen_html(key, preset, base_path or "", 1, len(specs))
+            info = f"Review: {preset.get('name', key)} · 1/{len(specs)}"
+
+            yield (None, None, screen, {}, _cast_panel_html({}), "", info, None, "",
+                   [], 0, new_state)
+            return  # generator ends; on_casting_confirm / on_casting_redo takes over
+
+        # ── Curated mode (unchanged behaviour) ──────────────────────
+        char_keys = ["yuki", "marie", "sakura"]
+        # load_curated_cast returns [] for any key missing from PRESET_CHARACTERS
+        # — fall back to None so a bad key skips its portrait instead of crashing.
+        loader = lambda k: (load_curated_cast([k]) or [None])[0]
+
+        resolved: dict[str, CastMember] = {}
+
+        # Beat 1 — the casting screen, empty portraits
+        yield (None, None,
+               _casting_screen_html(char_keys, resolved),
+               {}, _cast_panel_html({}),
+               "", "Casting…", None, "", [], 0, None)
+
+        # Beat 2 — portraits resolve
+        for key in char_keys:
+            member = loader(key)
+            if member:
+                resolved[member.character.name] = member
+            time.sleep(0.45)
+            yield (None, None,
+                   _casting_screen_html(char_keys, resolved),
+                   {}, _cast_panel_html(resolved),
+                   "", "Casting…", None, "", [], 0, None)
+
+        cast = resolved
+        if not cast:
+            yield (*_empty(), None)
+            return
+
+        # Open the scene
+        scene = SceneState(
+            cast=cast, present=[],
+            background="classroom", mood="peaceful",
+            turn=0, chapter="Prologue",
+            player_name=player_name,
+        )
+        engine, status = build_engine(cast, scene)
+        pre_expr, pre_bg = dict(scene.expressions), scene.background
+        pre_present = list(scene.present)
+        raw, scene = engine.run_turn("")
+        beats = _segment_beats(raw, scene.cast, pre_expr, pre_bg,
+                               init_present=pre_present, voice_line=engine.last_voice)
+
+        log = clean_narration(raw)
+        screen, prev_bg, voice_path = _render_beats_screen(
+            beats, 0, scene, bg_provider, "", log_text=log)
+        yield (scene, engine, screen, cast, _cast_panel_html(cast),
+               log,
+               f"{scene.chapter} · {scene.background} ({scene.mood}) · {status}",
+               voice_path, prev_bg, beats, 0, None)
+
+    def on_casting_confirm(casting_state, casting_prompt: str,
+                           _scene: SceneState, _engine, _prev_bg: str):
+        """Confirm the current character's base and advance.
+
+        If more characters remain: generate the next base, return review screen.
+        If all confirmed: bake expressions, VRAM swap, start the VN scene.
+        """
+        if not casting_state or casting_state.get("phase") != "review":
+            return (*_empty(), None)
+
+        specs = casting_state["specs"]
+        idx = casting_state["idx"]
+        fast = casting_state.get("fast", False)
+
+        # Update current character's prompt from the (possibly edited) textbox
+        key, preset = specs[idx]
+        if casting_prompt and casting_prompt.strip():
+            preset["identity_prompt"] = casting_prompt.strip()
+            # Update the seed to reflect prompt changes (so redo gets fresh results)
+            from cast_pipeline import _stable_seed
+            preset["seed"] = _stable_seed(preset.get("name", key), preset["identity_prompt"])
+
+        # Advance to next character
+        next_idx = idx + 1
+        if next_idx < len(specs):
+            # More characters — generate next base
+            from cast_pipeline import (_generate_base_with_face_gate, _char_dir,
+                                       set_fast_generation)
+            set_fast_generation(fast)
+
+            next_key, next_preset = specs[next_idx]
+            char_dir = _char_dir(next_key)
+            base_path = _generate_base_with_face_gate(next_key, next_preset, char_dir)
+
+            new_state = {"specs": specs, "idx": next_idx, "phase": "review", "fast": fast}
+
+            screen = _review_screen_html(next_key, next_preset, base_path or "",
+                                         next_idx + 1, len(specs))
+            info = f"Review: {next_preset.get('name', next_key)} · {next_idx + 1}/{len(specs)}"
+
+            return (None, None, screen, {}, _cast_panel_html({}), "", info, None, "",
+                    [], 0, new_state)
+
+        # All confirmed — bake expressions, swap VRAM, start the VN
+        from cast_pipeline import (_generate_one_via_comfy, _char_dir,
+                                   comfy_free_vram, set_fast_generation)
+        from model_client import ensure_llm, ModelConfig
+
+        set_fast_generation(fast)
+
+        # Bake expressions for all characters (UNET still hot from base gen)
+        members = []
+        for skey, spreset in specs:
+            char_dir = _char_dir(skey)
+            base = os.path.join(char_dir, f"{skey}_base.png")
+            try:
+                member = _generate_one_via_comfy(skey, spreset,
+                                                 base_path=(base if os.path.exists(base) else ""))
+                members.append(member)
+            except Exception as e:
+                print(f"  [cast] Expression bake failed for {skey}: {e}")
+                # Fall back to placeholder
+                from cast_pipeline import _placeholder_member
+                members.append(_placeholder_member(skey, spreset))
+
+        cast = {m.character.name: m for m in members}
+        if not cast:
+            return (*_empty(), None)
+
+        # VRAM swap: unload ComfyUI, load LLM
+        comfy_free_vram()
+        ensure_llm(ModelConfig.from_env(), timeout=300)
+
+        # Start the VN
+        scene = SceneState(
+            cast=cast, present=[],
+            background="classroom", mood="peaceful",
+            turn=0, chapter="Prologue",
+            player_name=_scene.player_name if _scene else "Player",
+        )
+        engine, status = build_engine(cast, scene)
+        pre_expr, pre_bg = dict(scene.expressions), scene.background
+        pre_present = list(scene.present)
+        raw, scene = engine.run_turn("")
+        beats = _segment_beats(raw, scene.cast, pre_expr, pre_bg,
+                               init_present=pre_present, voice_line=engine.last_voice)
+
+        log = clean_narration(raw)
+        screen, new_prev_bg, voice_path = _render_beats_screen(
+            beats, 0, scene, bg_provider, "", log_text=log)
+
+        return (scene, engine, screen, cast, _cast_panel_html(cast),
+                log,
+                f"{scene.chapter} · {scene.background} ({scene.mood}) · {status}",
+                voice_path, new_prev_bg, beats, 0, None)
+
+    def on_casting_redo(casting_state, casting_prompt: str):
+        """Regenerate the current character's base with the edited prompt."""
+        if not casting_state or casting_state.get("phase") != "review":
+            return (_title_screen_html(), "No active review", None, "")
+
+        from cast_pipeline import (set_fast_generation, _generate_base_with_face_gate,
+                                   _char_dir, build_identity_prompt)
+
+        specs = casting_state["specs"]
+        idx = casting_state["idx"]
+        fast = casting_state.get("fast", False)
+        key, preset = specs[idx]
+
+        set_fast_generation(fast)
+
+        # Update prompt from the textbox
+        if casting_prompt and casting_prompt.strip():
+            preset["identity_prompt"] = casting_prompt.strip()
+
+        # Bump seed for a genuinely different result
+        preset["seed"] = preset.get("seed", 42) + 1
+
+        char_dir = _char_dir(key)
+        base_path = _generate_base_with_face_gate(key, preset, char_dir)
+
+        screen = _review_screen_html(key, preset, base_path or "",
+                                     idx + 1, len(specs))
+        info = f"Review: {preset.get('name', key)} · {idx + 1}/{len(specs)}"
+
+        # Clear the prompt box so it shows the new prompt on next load
+        return (screen, info, casting_state, preset["identity_prompt"])
+
+    def _append_log(prev_log: str, player_name: str, player_text: str,
+                    narration: str) -> str:
+        """Grow the session register: previous turns, then the player's
+        answer (marked with ▸), then the new turn's narration."""
+        parts = []
+        if (prev_log or "").strip():
+            parts.append(prev_log.rstrip())
+        if (player_text or "").strip():
+            parts.append(f"▸ {player_name}: {player_text.strip()}")
+        if (narration or "").strip():
+            parts.append(narration.strip())
+        return "\n\n".join(parts)
+
+    def on_choice(choice_id: str, choice_text: str,
+                  scene: SceneState, engine, prev_bg: str, prev_log: str = ""):
+        """A choice click → THE SCENE TURN."""
+        if not engine or not scene or not choice_id:
+            return _empty(scene)
+
+        for choice in scene.choices:
+            if choice.id == choice_id:
+                engine.apply_choice_effects(choice)
+                break
+
+        # Snapshot the visual state going INTO the turn so the beat splitter
+        # can replay expression/background changes in order.
+        pre_expr, pre_bg = dict(scene.expressions), scene.background
+        pre_present = list(scene.present)
+        raw, scene = engine.run_turn(choice_text or choice_id)
+        beats = _segment_beats(raw, scene.cast, pre_expr, pre_bg,
+                               init_present=pre_present, voice_line=engine.last_voice)
+
+        # The Scene Log is a full-session register: every turn's narration
+        # plus the player's answer that triggered it.
+        log = _append_log(prev_log, scene.player_name,
+                          choice_text or "", clean_narration(raw))
+        screen, new_prev_bg, voice_path = _render_beats_screen(
+            beats, 0, scene, bg_provider, prev_bg, log_text=log)
+
+        return (scene, engine, screen, scene.cast, _cast_panel_html(scene.cast),
+                log,
+                f"Turn {scene.turn} · {scene.background} ({scene.mood})",
+                voice_path, new_prev_bg, beats, 0)
+
+    def on_save(slot: float, save_name: str, log_text: str,
+                scene: SceneState, engine):
+        """Save into a slot with an optional player-given name (the session
+        log goes along). Also returns fresh slot rows for the hidden mirror,
+        so the open save panel's slot descriptions update without a full
+        screen re-render."""
+        if not engine:
+            return "Nothing to save — start a story first.", gr.skip()
+        engine.save(int(slot), save_name=save_name or "", log_text=log_text or "")
+        return f"Saved · slot {int(slot) + 1}", _slot_rows_html()
+
+    def _loaded_view(scene: SceneState, engine, slot: int, prev_bg: str,
+                     log_text: str = ""):
+        """The 12-tuple shown after a successful load (panel or main menu).
+
+        A restored save has no per-beat tool sequence — show it as a single
+        static beat (the saved description) with its choices already visible.
+        The session register resumes from the save's log_text.
+        """
+        log = log_text or scene.description or ""
+        beats = [{"speaker": "", "text": scene.description or "",
+                  "expressions": dict(scene.expressions),
+                  "background": scene.background,
+                  "present": list(scene.present), "voice": None}]
+        screen, new_prev_bg, _ = _render_beats_screen(
+            beats, 0, scene, bg_provider, prev_bg, log_text=log)
+        return (scene, engine, screen, scene.cast, _cast_panel_html(scene.cast),
+                log,
+                f"Loaded · slot {slot + 1} · Turn {scene.turn} · {scene.background} ({scene.mood})",
+                None, new_prev_bg, beats, 0,
+                f"Loaded · slot {slot + 1}")
+
+    def on_load(slot: float, scene: SceneState, engine, prev_bg: str):
+        if not engine:
+            return (*_empty(scene), "Nothing to load into — start a story first.")
+        try:
+            scene = engine.load(int(slot))
+        except FileNotFoundError:
+            return (scene, engine, gr.skip(), scene.cast,
+                    _cast_panel_html(scene.cast), gr.skip(),
+                    f"Slot {int(slot) + 1} is empty.", None, prev_bg, gr.skip(), gr.skip(),
+                    f"Slot {int(slot) + 1} is empty.")
+        data = read_save(int(slot))
+        return _loaded_view(scene, engine, int(slot), prev_bg,
+                            log_text=(data.log_text if data else ""))
+
+    def on_menu_load(slot: float):
+        """Load a save from the MAIN MENU — no engine exists yet, so the cast
+        is rebuilt from the save's cast card (saves/cast/<hash>.json) and a
+        fresh engine is constructed around it before the snapshot applies."""
+        slot = int(slot)
+        data = read_save(slot)
+        if data is None:
+            return (*_empty(), f"Slot {slot + 1} is empty.")
+        cast = load_cast_card(data.cast_hash)
+        if not cast:
+            return (*_empty(),
+                    f"Slot {slot + 1}: its cast card is missing — "
+                    "this save predates cast cards or the card was deleted.")
+        scene = SceneState(cast=cast, player_name=data.player_name)
+        engine, _status = build_engine(cast, scene)
+        scene = engine.load(slot)
+        return _loaded_view(scene, engine, slot, "", log_text=data.log_text)
+
+    def on_advance(beats, idx, scene: SceneState, prev_bg: str, log_text: str):
+        """Reveal the next beat (click-the-screen / Space / Enter).
+
+        log_text comes from the hidden narration_log sink so the in-canvas
+        Scene Log panel keeps its content across beat re-renders.
+        """
+        if not beats:
+            return gr.skip(), gr.skip(), None, gr.skip(), gr.skip()
+        new_idx = min((idx or 0) + 1, len(beats) - 1)
+        screen, new_prev_bg, voice_path = _render_beats_screen(
+            beats, new_idx, scene, bg_provider, prev_bg, log_text=log_text or "")
+        info = f"Turn {scene.turn} · {scene.background} ({scene.mood})"
+        return screen, new_idx, voice_path, info, new_prev_bg
+
+    def on_free_submit(text: str, scene: SceneState, engine, prev_bg: str,
+                       prev_log: str = ""):
+        """Free-text action → a scene turn. Wraps on_choice and ALSO clears
+        the input box server-side (returns "" into free_input) — no JS race.
+
+        Returns the 11 turn_outputs + the cleared free_input value.
+        """
+        if not (text or "").strip() or not engine or not scene:
+            # Nothing to do — keep the box contents, change nothing else
+            return tuple(gr.skip() for _ in range(12))
+        result = on_choice("__free__", text.strip(), scene, engine, prev_bg, prev_log)
+        return (*result, "")   # clear free_input
+
+    def on_reset():
+        return _empty()
+
+    return (on_start, on_choice, on_save, on_load, on_reset, on_advance, on_free_submit,
+            on_casting_confirm, on_casting_redo, on_menu_load)
diff --git a/ui/media.py b/ui/media.py
new file mode 100644
index 0000000000000000000000000000000000000000..9127f1708820a6eca0066a7b89524141d1c20a1f
--- /dev/null
+++ b/ui/media.py
@@ -0,0 +1,53 @@
+"""Image embedding helpers — data: URIs so sprites/backgrounds always render
+without a Gradio file-route dependency.
+"""
+from __future__ import annotations
+import base64
+import io
+import os
+from functools import lru_cache
+from typing import Optional
+
+
+@lru_cache(maxsize=256)
+def _data_uri_cached(path: str, mtime: float) -> str:
+    with open(path, "rb") as f:
+        b64 = base64.b64encode(f.read()).decode("ascii")
+    return f"data:image/png;base64,{b64}"
+
+
+def data_uri(path: Optional[str]) -> str:
+    """Return a data: URI for an image path, or '' if unavailable."""
+    if not path or not os.path.exists(path):
+        return ""
+    try:
+        return _data_uri_cached(path, os.path.getmtime(path))
+    except OSError:
+        return ""
+
+
+@lru_cache(maxsize=64)
+def _thumb_uri_cached(path: str, mtime: float, height: int) -> str:
+    try:
+        from PIL import Image
+        with Image.open(path) as img:
+            img = img.convert("RGBA")
+            w = max(1, int(img.width * height / img.height))
+            img = img.resize((w, height), Image.LANCZOS)
+            buf = io.BytesIO()
+            img.save(buf, format="PNG")
+        b64 = base64.b64encode(buf.getvalue()).decode("ascii")
+        return f"data:image/png;base64,{b64}"
+    except Exception:
+        # Fall back to the full image (bigger payload, still works)
+        return _data_uri_cached(path, mtime)
+
+
+def thumb_data_uri(path: Optional[str], height: int = 160) -> str:
+    """Downscaled data: URI — keeps the cast-panel payload small."""
+    if not path or not os.path.exists(path):
+        return ""
+    try:
+        return _thumb_uri_cached(path, os.path.getmtime(path), height)
+    except OSError:
+        return ""
diff --git a/ui/screens.py b/ui/screens.py
new file mode 100644
index 0000000000000000000000000000000000000000..343635b4e8982db4c53d435655a436102362413a
--- /dev/null
+++ b/ui/screens.py
@@ -0,0 +1,432 @@
+"""HTML builders for the VN canvas — title, casting, review, cast panel,
+and the main scene screen.
+"""
+from __future__ import annotations
+import html as _html
+
+from vn_contracts import CastMember, Choice
+from vn_engine import list_saves
+
+from .media import data_uri, thumb_data_uri
+
+
+def _slot_rows_html(selectable_empty: bool = True) -> str:
+    """Rich save-slot rows: name, chapter · turn, cast and timestamp.
+
+    Used by both the in-game save panel (all slots selectable) and the
+    main-menu load list (empty slots rendered but not clickable)."""
+    rows = []
+    for meta in list_saves():
+        i = meta["slot"]
+        if meta.get("empty"):
+            cls = "vn-slot-btn empty" + ("" if selectable_empty else " disabled")
+            rows.append(
+                f'<button class="{cls}" data-slot="{i}" data-empty="1">'
+                f'<span class="vn-slot-name">Slot {i + 1} — Empty</span>'
+                f'</button>'
+            )
+            continue
+        name = _html.escape(meta["name"] or f"Slot {i + 1}")
+        cast = _html.escape(", ".join(meta["cast_names"]) or "—")
+        when = _html.escape(meta["saved_at"] or "")
+        chapter = _html.escape(meta["chapter"] or "")
+        rows.append(
+            f'<button class="vn-slot-btn" data-slot="{i}" data-empty="0">'
+            f'<span class="vn-slot-name">{name}</span>'
+            f'<span class="vn-slot-meta">{chapter} · Turn {meta["turn"]}</span>'
+            f'<span class="vn-slot-cast">{cast}</span>'
+            f'<span class="vn-slot-time">{when}</span>'
+            f'</button>'
+        )
+    return "\n".join(rows)
+
+
+def _title_screen_html() -> str:
+    """The title card + cast-setup step + load list, rendered inside the canvas.
+
+    Three sections, toggled by body classes:
+      - `.vn-title-content` — the title screen (visible by default).
+      - `.vn-cast-setup`    — the cast-setup step (body.cast-setup-active).
+      - `.vn-menu-load`     — the load-save list (body.menu-load-active).
+
+    ONLOAD_JS bridges the HTML inputs to hidden Gradio controls so the
+    card fields reach the backend when Generate Cast is clicked.
+    """
+    has_saves = any(not m.get("empty") for m in list_saves())
+    load_btn = ('<button class="vn-title-load">Load</button>' if has_saves
+                else '<button class="vn-title-load disabled" disabled>Load</button>')
+    return f"""
+    <div class="vn-screen vn-title-screen">
+        <div class="vn-title-content">
+            <div class="vn-title-main">ARS-FABULA</div>
+            <div class="vn-title-sub">A Slice-of-Life Visual Novel</div>
+            <div class="vn-title-cast-choice">
+                <button class="vn-title-opt active" data-preset="generated">Generated Cast</button>
+                <button class="vn-title-opt" data-preset="curated">Curated Cast</button>
+            </div>
+            <div class="vn-title-name-row">
+                <input type="text" class="vn-title-name-input" placeholder="Your name…" maxlength="24" value="Player">
+            </div>
+            <div class="vn-title-actions">
+                <button class="vn-title-begin">Start</button>
+                {load_btn}
+            </div>
+        </div>
+        <div class="vn-menu-load">
+            <div class="vn-ml-title">Load Save</div>
+            <div class="vn-slot-list vn-ml-list">{_slot_rows_html(selectable_empty=False)}</div>
+            <button class="vn-ml-back">Back</button>
+        </div>
+        <div class="vn-cast-setup">
+            <div class="vn-cs-header">
+                <div class="vn-cs-title">Cast Setup</div>
+                <div class="vn-cs-desc">
+                    <p>Leave every card blank to generate the default cast
+                    (Yuki, Marie, Sakura). Otherwise fill <strong>Name + Concept</strong>
+                    and the story model designs the character (e.g. concept
+                    <em>childhood friend</em> becomes a warm, brown-haired genki design).</p>
+                    <p><strong>Advanced tags</strong> override the designer with your own
+                    Danbooru appearance tags (start with <code>1girl</code>/<code>1boy</code>;
+                    hair, eyes, clothing, accessories only). Only the framing essentials
+                    are locked on — body attitude is yours (add stance tags like
+                    <code>hand on hip</code>, <code>arms crossed</code>).
+                    Editing a design auto-invalidates that character's sprite cache.</p>
+                </div>
+            </div>
+            <div class="vn-cs-cards">
+                <div class="vn-cs-card" data-cs-idx="0">
+                    <div class="vn-cs-card-row">
+                        <div class="vn-cs-field vn-cs-field-name">
+                            <label>Name</label>
+                            <input class="vn-cs-input vn-cs-name" data-cs-field="name" data-cs-idx="0"
+                                   placeholder="e.g. Mio" maxlength="24">
+                        </div>
+                        <div class="vn-cs-field vn-cs-field-concept">
+                            <label>Concept</label>
+                            <input class="vn-cs-input vn-cs-concept" data-cs-field="concept" data-cs-idx="0"
+                                   placeholder="e.g. shy bookworm childhood friend" maxlength="64">
+                        </div>
+                    </div>
+                    <div class="vn-cs-tags-row">
+                        <input class="vn-cs-input vn-cs-tags-input" data-cs-field="tags" data-cs-idx="0"
+                               placeholder="Advanced tags: 1girl, silver hair, long hair, blue eyes, ..." maxlength="256">
+                    </div>
+                </div>
+                <div class="vn-cs-card" data-cs-idx="1">
+                    <div class="vn-cs-card-row">
+                        <div class="vn-cs-field vn-cs-field-name">
+                            <label>Name</label>
+                            <input class="vn-cs-input vn-cs-name" data-cs-field="name" data-cs-idx="1"
+                                   placeholder="e.g. Rin" maxlength="24">
+                        </div>
+                        <div class="vn-cs-field vn-cs-field-concept">
+                            <label>Concept</label>
+                            <input class="vn-cs-input vn-cs-concept" data-cs-field="concept" data-cs-idx="1"
+                                   placeholder="e.g. tsundere rival" maxlength="64">
+                        </div>
+                    </div>
+                    <div class="vn-cs-tags-row">
+                        <input class="vn-cs-input vn-cs-tags-input" data-cs-field="tags" data-cs-idx="1"
+                               placeholder="Advanced tags: 1girl, silver hair, long hair, blue eyes, ..." maxlength="256">
+                    </div>
+                </div>
+                <div class="vn-cs-card" data-cs-idx="2">
+                    <div class="vn-cs-card-row">
+                        <div class="vn-cs-field vn-cs-field-name">
+                            <label>Name</label>
+                            <input class="vn-cs-input vn-cs-name" data-cs-field="name" data-cs-idx="2"
+                                   placeholder="e.g. Aoi" maxlength="24">
+                        </div>
+                        <div class="vn-cs-field vn-cs-field-concept">
+                            <label>Concept</label>
+                            <input class="vn-cs-input vn-cs-concept" data-cs-field="concept" data-cs-idx="2"
+                                   placeholder="e.g. mysterious senpai" maxlength="64">
+                        </div>
+                    </div>
+                    <div class="vn-cs-tags-row">
+                        <input class="vn-cs-input vn-cs-tags-input" data-cs-field="tags" data-cs-idx="2"
+                               placeholder="Advanced tags: 1girl, silver hair, long hair, blue eyes, ..." maxlength="256">
+                    </div>
+                </div>
+            </div>
+            <label class="vn-cs-fast">
+                <input type="checkbox" class="vn-cs-fast-cb">
+                <span>Fast generation (lower resolution — quicker bake, softer detail)</span>
+            </label>
+            <div class="vn-cs-actions">
+                <button class="vn-cs-btn vn-cs-back" data-action="cast-setup-back">Back</button>
+                <button class="vn-cs-btn vn-cs-go" data-action="cast-setup-go">Generate Cast</button>
+            </div>
+        </div>
+    </div>
+    """
+
+
+def _cast_panel_html_inner(cast: dict[str, CastMember]) -> str:
+    """Inner HTML for the in-canvas cast overlay (thumb + identity)."""
+    if not cast:
+        return '<div class="cast-panel-empty">No cast — start a story.</div>'
+    parts = []
+    for name, member in cast.items():
+        char = member.character
+        thumb_uri = thumb_data_uri(member.get_sprite("neutral"), height=280)
+        thumb = (f'<img class="cast-panel-thumb" src="{thumb_uri}" alt="{name}">'
+                 if thumb_uri else '<div class="cast-panel-thumb"></div>')
+        parts.append(
+            f'<div class="cast-panel-card">{thumb}'
+            f'<div class="cast-panel-info">'
+            f'<div class="cast-panel-name">{char.name}</div>'
+            f'<div class="cast-panel-role">{char.role}</div>'
+            f'<div class="cast-panel-personality">{char.personality}</div>'
+            f'</div></div>'
+        )
+    return "\n".join(parts)
+
+
+_ICON_TRAY_HTML = """
+<div class="vn-icon-tray">
+  <button class="vn-tray-btn" data-action="log">Log</button>
+  <button class="vn-tray-btn" data-action="cast">Cast</button>
+  <button class="vn-tray-btn" data-action="save">Save</button>
+  <button class="vn-tray-btn" data-action="reset"><span class="vn-tray-normal">Reset</span><span
+    class="vn-tray-confirm-row"><span class="vn-reset-confirm">Confirm</span>&nbsp;/&nbsp;<span
+    class="vn-reset-cancel">Cancel</span></span></button>
+</div>
+"""
+
+
+
+
+
+def _review_screen_html(key: str, preset: dict, base_path: str,
+                         char_num: int, total: int) -> str:
+    """Per-character review screen during interactive casting.
+
+    Shows the generated base image alongside the full prompt text
+    (editable) and Confirm/Redo buttons. The JS bridge writes the
+    textarea value to the hidden #casting-prompt-box before clicking
+    the hidden confirm/redo Gradio buttons.
+    """
+    name = preset.get("name", key.capitalize())
+    prompt = preset.get("identity_prompt", "")
+    img_uri = data_uri(base_path) if base_path else ""
+
+    img_html = (f'<img src="{img_uri}" alt="{name} base">'
+                if img_uri
+                else '<div class="review-no-image">Generation failed — try Redo</div>')
+
+    # The designed character: role + personality, as the story model wrote them
+    role = _html.escape(preset.get("role", "") or "")
+    personality = _html.escape(preset.get("personality", "") or "")
+    desc_html = ""
+    if role or personality:
+        role_html = f'<span class="review-role">{role}</span>' if role else ""
+        desc_html = (f'<div class="review-desc">{role_html}'
+                     f'<p class="review-personality">{personality}</p></div>')
+
+    return f"""
+    <div class="vn-screen vn-casting-review">
+      <div class="casting-review-title">Cast Review · {char_num}/{total}</div>
+      <div class="review-layout">
+        <div class="review-image">{img_html}</div>
+        <div class="review-panel">
+          <div class="review-name">{name}</div>
+          {desc_html}
+          <div class="review-prompt-label">Prompt — edit and Redo to regenerate</div>
+          <textarea class="review-prompt" id="review-prompt-text" rows="6">{_html.escape(prompt)}</textarea>
+          <div class="review-actions">
+            <button class="review-btn confirm" data-action="casting-confirm">&#10003; Confirm</button>
+            <button class="review-btn redo" data-action="casting-redo">&#8635; Redo</button>
+          </div>
+        </div>
+      </div>
+    </div>
+    """
+
+
+def _log_html(log_text: str) -> str:
+    """Escape the session register; player-answer lines (▸-prefixed, written
+    by the turn callbacks) get their own accent styling."""
+    lines = []
+    for line in (log_text or "").split("\n"):
+        esc = _html.escape(line)
+        if line.startswith("▸ "):
+            esc = f'<span class="vn-log-answer">{esc}</span>'
+        lines.append(esc)
+    return "\n".join(lines)
+
+
+def _panels_html(log_text: str, cast_html: str) -> str:
+    """The three overlay panels, rendered inside .vn-screen."""
+    slots = _slot_rows_html()
+    return f"""
+    <div class="vn-panel vn-panel-log">
+        <button class="vn-panel-close">✕</button>
+        <div class="vn-panel-title">Scene Log</div>
+        <div class="vn-log-text">{_log_html(log_text)}</div>
+    </div>
+    <div class="vn-panel vn-panel-cast">
+        <button class="vn-panel-close">✕</button>
+        <div class="vn-panel-title">Cast</div>
+        {cast_html}
+    </div>
+    <div class="vn-panel vn-panel-save">
+        <button class="vn-panel-close">✕</button>
+        <div class="vn-panel-title">Save / Load</div>
+        <div class="vn-slot-list">{slots}</div>
+        <input class="vn-save-name" type="text" maxlength="48"
+               placeholder="Save name (optional)…">
+        <div class="vn-save-actions">
+            <button class="vn-save-action" data-which="save">Save</button>
+            <button class="vn-save-action" data-which="load">Load</button>
+        </div>
+        <div class="vn-save-status"></div>
+    </div>
+    """
+
+
+def _vn_screen_html(bg_path: str, cast: dict[str, CastMember],
+                    present: list[str], expressions: dict[str, str],
+                    dialogue_speaker: str = "", dialogue_text: str = "",
+                    choices: list[Choice] | None = None,
+                    narration: str = "",
+                    prev_bg_path: str = "",
+                    more: bool = False,
+                    log_text: str = "",
+                    cast_html: str = "") -> str:
+    """Build the VN screen HTML: crossfading bg layers, sprites, dialogue, choices.
+
+    `more=True` marks the screen as having further beats to read this turn:
+    it adds a ▼ continue hint and a `data-more="1"` flag the JS click/keyboard
+    hook uses to advance the reader one beat at a time.
+    """
+    bg_layers = ""
+    prev_uri = data_uri(prev_bg_path) if prev_bg_path and prev_bg_path != bg_path else ""
+    curr_uri = data_uri(bg_path)
+    if prev_uri:
+        bg_layers += f'<img class="vn-bg old" src="{prev_uri}" alt="">'
+    if curr_uri:
+        bg_layers += f'<img class="vn-bg new" src="{curr_uri}" alt="">'
+
+    # Sprites — the speaking character is .active, the rest .inactive (dimmed).
+    # During pure narration (no speaker) everyone stays normal.
+    sprite_html = ""
+    for name in present:
+        member = cast.get(name)
+        if not member:
+            continue
+        expr = expressions.get(name, "neutral")
+        sprite_uri = data_uri(member.get_sprite(expr))
+        if sprite_uri:
+            state = ""
+            if dialogue_speaker:
+                state = " active" if name == dialogue_speaker else " inactive"
+            sprite_html += (f'<img class="vn-sprite{state}" data-expr="{name}:{expr}" '
+                            f'src="{sprite_uri}" alt="{name} ({expr})">')
+
+    # Dialogue — name plate, then text (HUD removed)
+    dialogue_html = ""
+    if dialogue_text or narration:
+        dialogue_html += '<div class="vn-dialogue-inner">'
+        if dialogue_text:
+            if dialogue_speaker:
+                dialogue_html += f'<div class="vn-name-plate">{dialogue_speaker}</div>'
+            dialogue_html += f'<p class="vn-text{" narrator" if not dialogue_speaker else ""}">{dialogue_text}</p>'
+        elif narration:
+            dialogue_html += f'<p class="vn-text narrator">{narration}</p>'
+        dialogue_html += '</div>'
+    if more:
+        dialogue_html += '<div class="vn-continue">▼</div>'
+    dialogue_html += _ICON_TRAY_HTML
+
+    # Interaction cluster — shown on the LAST beat (not while there are more
+    # beats to read): the offered choices (if any) plus a free-text capsule as
+    # the final item, so the whole set reads as one centered column. It lives
+    # INSIDE the canvas, so it scales with the frame (not the page) and centers
+    # with the choices; the typing-done CSS gate hides it until the line ends.
+    choices_html = ""
+    if not more:
+        parts = ['<div class="vn-choices">']
+        for c in (choices or []):
+            safe_text = c.text.replace('"', '&quot;')
+            parts.append(
+                f'<button class="vn-choice-btn" '
+                f'data-choice-id="{c.id}" data-choice-text="{safe_text}">'
+                f'{c.text}</button>'
+            )
+        # Free-text capsule — always the last item, so the player is never
+        # locked to the offered choices. Wired to the hidden Gradio bridge by JS.
+        parts.append(
+            '<div class="vn-free-capsule">'
+            '<input class="vn-free-text" type="text" autocomplete="off" '
+            'placeholder="Your choice…">'
+            '<button class="vn-free-go" data-action="free-send" '
+            'aria-label="Send">➤</button>'
+            '</div>'
+        )
+        parts.append('</div>')
+        choices_html = "\n".join(parts)
+
+    return f"""
+    <div class="vn-screen{' advancing' if more else ''}" data-more="{'1' if more else '0'}" data-choices="{'1' if choices_html else '0'}" data-typing="pending">
+        {bg_layers}
+        <div class="vn-chars">{sprite_html}</div>
+        {choices_html}
+        <div class="vn-dialogue{' has-speaker' if dialogue_speaker else ''}">{dialogue_html}</div>
+        {_panels_html(log_text, cast_html)}
+    </div>"""
+
+
+def _casting_screen_html(char_keys: list[str],
+                         resolved: dict[str, CastMember],
+                         message: str = "Assembling your cast…") -> str:
+    """The casting-beat screen: portraits resolve one by one."""
+    portraits = []
+    for key in char_keys:
+        # Preset keys are lowercase slugs; custom names arrive display-ready
+        name = key.capitalize() if key.islower() else key
+        member = resolved.get(name)
+        if member:
+            uri = data_uri(member.get_sprite("neutral"))
+            inner = (f'<img src="{uri}" alt="{name}">' if uri
+                     else f'<div class="pname">{name}</div>')
+            portraits.append(
+                f'<div class="portrait-wrap">'
+                f'<div class="vn-portrait">{inner}</div>'
+                f'<div class="pname">{name}</div></div>'
+            )
+        else:
+            portraits.append(
+                f'<div class="portrait-wrap">'
+                f'<div class="vn-portrait pending">…</div>'
+                f'<div class="pname pending">?</div></div>'
+            )
+
+    return f"""
+    <div class="vn-screen">
+        <div class="vn-casting">
+            <div class="casting-title">✦ {message}</div>
+            <div class="portraits">{''.join(portraits)}</div>
+        </div>
+    </div>
+    """
+
+
+def _cast_panel_html(cast: dict[str, CastMember]) -> str:
+    """Build HTML for the cast info panel."""
+    if not cast:
+        return '<div class="cast-panel-empty">No cast yet — start a story.</div>'
+    parts = ['<div style="padding:8px;">']
+    for name, member in cast.items():
+        char = member.character
+        parts.append(
+            f'<div class="cast-card">'
+            f'<div class="name">{char.name}</div>'
+            f'<div class="role">{char.role} · ♪ {char.voice_id}</div>'
+            f'<div class="personality">{char.personality}</div>'
+            f'<div class="cast-expressions">'
+            f'Expressions: {", ".join(member.expression_map.keys())}'
+            f'</div></div>'
+        )
+    parts.append('</div>')
+    return "\n".join(parts)
diff --git a/ui/styles.py b/ui/styles.py
new file mode 100644
index 0000000000000000000000000000000000000000..b87d81c18c3f8a666bd66d273968cf2958dd282c
--- /dev/null
+++ b/ui/styles.py
@@ -0,0 +1,1947 @@
+"""CSS and onload JS for the VN UI. Pure presentation strings — no logic.
+
+Installed via launch(css=..., js=...).
+"""
+import os
+
+# Font for CHARACTER dialogue lines (the narrator keeps --font-dialogue).
+# Env-overridable — pass a full CSS font-family stack, e.g.
+#   ARS_FABULA_DIALOGUE_FONT="'Sazanami Gothic', monospace"
+CHARACTER_FONT = os.getenv(
+    "ARS_FABULA_DIALOGUE_FONT",
+    "'MS Gothic', 'MS PGothic', 'Osaka-Mono', monospace",
+)
+
+# ═══════════════════════════════════════════════════════════════════════
+# CSS — VN themed (incl. scene-turn crossfade + sprite swap animations)
+# ═══════════════════════════════════════════════════════════════════════
+
+CSS = """
+/* ── Fonts ── */
+@import url('https://fonts.googleapis.com/css2?family=Cormorant+Garamond:ital,wght@0,400;0,600;1,400;1,600&family=Cinzel:wght@400;600&family=Noto+Sans+JP:wght@300;400&display=swap');
+
+/* ── Tokens ── */
+:root {
+  --bg-void:       #0d0d1a;
+  --bg-surface:    #13132a;
+  --bg-raised:     #1c1c38;
+  --bg-screen:     #08081a;
+  --border-subtle: #252545;
+  --border-mid:    #3a3a62;
+  --border-accent: #e8a87c;
+  --border-glow:   rgba(232,168,124,0.35);
+  /* One warm text family + gold accent — cool purples are reserved for
+     surfaces/borders only, so no text sinks into the dark box. */
+  --text-primary:  #ede5da;
+  --text-secondary:#b9b0a1;
+  --text-muted:    #8f8779;
+  --text-accent:   #e8a87c;
+  --text-narrator: #c6bdac;
+  /* One shared panel fill for the dialogue box, choice pills and input bar
+     so they're all the exact same colour + opacity. */
+  --dialogue-bg:   rgba(15, 15, 25, 0.68);
+  --font-display:  'Cinzel', 'Georgia', serif;
+  --font-dialogue: 'Cormorant Garamond', 'Georgia', serif;
+  --font-ui:       'Noto Sans JP', 'Georgia', serif;
+  --font-character: __FONT_CHARACTER__;   /* injected from ARS_FABULA_DIALOGUE_FONT */
+}
+
+/* ── Global Reset ── */
+.gradio-container {
+  background: var(--bg-void) !important;
+  color: var(--text-primary) !important;
+  font-family: var(--font-ui) !important;
+  /* Size the frame to the LARGEST 16:9 that fits the viewport: as wide as
+     ~90vw, but capped at 1700px AND at the width whose 16:9 height is ~88vh
+     (88vh × 16/9 ≈ 156vh). The height cap is what reclaims the empty band that
+     appeared below an 80%-width frame on a 16:9 screen. */
+  width: min(90vw, 1900px, 156vh) !important;
+  min-width: 720px !important;       /* prevent collapse on small viewports */
+  margin: 0 auto !important;
+}
+body { background: var(--bg-void) !important; }
+*:focus { outline: 2px solid var(--border-accent) !important; outline-offset: 2px; }
+
+/* Cast Setup — a STEP shown AFTER Begin → Generated (between the title and the
+   character-design phase). Hidden by default; when active it replaces the title
+   content inside the canvas. JS toggles body.cast-setup-active.
+   NOTE: The doubled `.vn-title-content.vn-title-content` selector beats Gradio 6's
+   scoped-prefix specificity issue (same reason #cast-setup#cast-setup was needed). */
+/* !important is required: Gradio 6 re-emits every custom rule with a
+   `.gradio-container-... .contain` scope prefix. The scoped copy of the
+   base `.vn-title-content { display:flex }` outranks this rule, while the
+   scoped copy of THIS rule can never match (body is outside .contain) —
+   so without !important the title stayed visible beside the cast setup. */
+body.cast-setup-active .vn-title-content { display: none !important; }
+body.cast-setup-active .vn-cast-setup {
+  display: flex !important;
+}
+/* But when NOT in cast-setup-active, the cast setup is always hidden. */
+.vn-cast-setup { display: none; }
+
+/* ── VN Screen ── */
+.vn-screen {
+  position: relative;
+  width: 100%;
+  aspect-ratio: 16 / 9;             /* 16:9, height derived purely from width */
+  min-height: 380px;                /* (no vh cap — height tracks the frame, not
+                                       the page, so overlays never displace on
+                                       zoom/resize) */
+  background: var(--bg-screen);
+  border: 1px solid var(--border-mid);
+  border-radius: 6px;
+  overflow: hidden;
+  margin-bottom: 8px;
+  container-type: inline-size;      /* lets dialogue/choice text size in cqw —
+                                       i.e. scale with the screen (and thus the
+                                       text box), not the page root font */
+}
+
+/* Background layers */
+.vn-bg {
+  position: absolute;
+  top: 0; left: 0;
+  width: 100%; height: 100%;
+  object-fit: cover;
+}
+/* Only crossfade when the background ACTUALLY changed (an .old layer is present
+   to fade over). Otherwise every beat re-rendered the canvas and the bg faded
+   up from black again — the "blackish" flash on each advance. */
+.vn-bg.old + .vn-bg.new { animation: vnBgFade 1.3s ease both; }
+@keyframes vnBgFade { from { opacity: 0; } to { opacity: 1; } }
+
+/* Sprites — anchored to the SCREEN bottom and layered BEHIND the dialogue
+   box (z 2 < dialogue 4), per VN staging: the box overlaps the sprites'
+   lower torso, concealing the raw bottom edge of upper-body renders.
+   The container spans the full screen so percentage heights resolve. */
+.vn-chars {
+  position: absolute;
+  top: 0; bottom: 0; left: 0;
+  width: 100%;
+  display: flex;
+  justify-content: center;
+  align-items: flex-end;     /* feet on the screen bottom */
+  gap: 24px;
+  pointer-events: none;
+  z-index: 2;
+}
+.vn-sprite {
+  height: 86%;               /* heads near the top, torso behind the box */
+  width: auto;
+  max-width: 34%;            /* must exceed the widest bake canvas's display
+                                width — if this cap binds, object-fit:contain
+                                letterboxes the sprite and SHRINKS that
+                                character's face below the equal-face target.
+                                Bake canvases now widen to fit wide poses
+                                (cast_pipeline fig_w), so keep headroom here. */
+  object-fit: contain;
+  object-position: bottom center;
+  /* No per-render entrance animation: the canvas HTML is rebuilt every beat,
+     so an entrance keyframe replayed (and "dragged") on each advance. The
+     active/inactive filter still animates below. */
+  transition: filter 0.35s ease;
+}
+/* Active/inactive: the speaker is bright, the rest gently shadowed.
+   Dimming is FILTER-only — sprites are never made translucent. */
+.vn-sprite.active   { filter: none; }
+.vn-sprite.inactive {
+  filter: brightness(0.6) saturate(0.85) contrast(0.95);
+}
+/* Choice state: once the line finishes typing and the choice cluster fades in,
+   EVERY sprite (active speaker included) takes the inactive dimming, so the
+   semi-transparent capsules and the free-text bar read cleanly over bright
+   costumes. Same gate as .vn-choices visibility; the existing 0.35s
+   filter transition makes it fade in with the capsules. */
+.vn-screen[data-choices="1"][data-typing="0"] .vn-sprite,
+.vn-screen[data-choices="1"][data-typing="0"] .vn-sprite.active {
+  filter: brightness(0.6) saturate(0.85) contrast(0.95);
+}
+@keyframes vnSpriteIn {
+  from { opacity: 0.2; transform: translateY(10px) scale(0.97); }
+  to   { opacity: 1;   transform: translateY(0)    scale(1); }
+}
+
+/* ── Dialogue Box ── (a wide, centered panel with a LOCKED height — it never
+   grows or shrinks with the line length — one flat scrim, not a gradient) */
+.vn-dialogue {
+  position: absolute;
+  bottom: 20px; left: 20%; right: 20%; /* 60% width, centered */
+  height: clamp(130px, 13.5cqw, 230px); /* scales with the screen width (never
+                                           with line length) so it stays in
+                                           proportion to the cqw-sized text */
+  background: var(--dialogue-bg);       /* shared panel colour */
+  border: 1px solid var(--border-subtle);
+  border-radius: 8px;
+  padding: 14px 16px 36px;
+  overflow: hidden;                     /* clip rather than expand */
+}
+.vn-dialogue.has-speaker {
+  border-left: 3px solid var(--border-accent);
+}
+/* Centered column — the box itself is already narrow (60% of the screen),
+   so the text uses most of it. */
+.vn-dialogue-inner {
+  max-width: min(94%, 960px);
+  margin: 0 auto;
+}
+.vn-name-plate {
+  display: inline-block;
+  font-family: var(--font-display);
+  font-size: clamp(0.7rem, 1.1cqw, 1.2rem);
+  letter-spacing: 0.08em;
+  color: var(--text-accent);
+  background: rgba(232,168,124,0.1);
+  border: 1px solid var(--border-accent);
+  border-radius: 3px;
+  padding: 2px 10px;
+  margin-bottom: 8px;
+}
+.vn-name {
+  font-family: var(--font-display);
+  font-weight: 600;
+  color: var(--text-accent);
+  font-size: clamp(0.75rem, 1.2cqw, 1.3rem);
+  margin-bottom: 6px;
+  letter-spacing: 0.06em;
+}
+/* Character dialogue uses --font-character (MS Gothic by default, env-set). */
+.vn-text {
+  font-family: var(--font-character);
+  color: var(--text-primary);
+  /* Scales with the screen/text-box width: ≈ the old 1.15rem on a ~1300px
+     frame, smaller on regular resolutions, larger on big frames. */
+  font-size: clamp(0.85rem, 1.4cqw, 1.5rem);
+  line-height: 1.7;
+  text-align: left;
+  padding: 0 16px;
+  text-indent: 0;
+}
+/* Narration is set in Georgia serif (distinct from the MS Gothic dialogue). */
+.vn-text.narrator {
+  font-family: Georgia, 'Times New Roman', serif;
+  font-style: italic;
+  color: var(--text-narrator);
+}
+
+/* Typewriter cursor */
+.vn-text.typing::after {
+  content: '▌';
+  animation: vnBlink 0.7s step-end infinite;
+  color: var(--text-accent);
+  margin-left: 1px;
+}
+@keyframes vnBlink { 50% { opacity: 0; } }
+
+/* Click-to-advance affordance */
+.vn-screen.advancing { cursor: pointer; }
+.vn-continue {
+  position: absolute;
+  right: 16px; bottom: 10px;
+  color: var(--text-accent);
+  font-size: 1rem;
+  animation: vnPulse 1.2s ease infinite;
+  pointer-events: none;
+}
+@keyframes vnPulse { 0%,100% { opacity: 0.4; } 50% { opacity: 1; } }
+
+/* ── Choices ── (raised so the free-text bar docks directly beneath them
+   in the same centered column — one interaction cluster, not two) */
+/* Independent vertical column, centered in the open scene area ABOVE the
+   dialogue box. The container spans the area but passes clicks through
+   (pointer-events:none) so only the pills are interactive. */
+.vn-choices {
+  position: absolute;
+  inset: 0;                     /* span the whole canvas … */
+  display: flex;
+  flex-direction: column;
+  justify-content: center;      /* … so the stack sits dead-center vertically */
+  align-items: center;          /* horizontal center; pills size to content */
+  gap: 0.75rem;
+  pointer-events: none;
+}
+.vn-choices .vn-choice-btn { pointer-events: auto; }
+/* Choices only appear once the line has finished typing (data-typing flips to
+   "0"); hidden during 'pending' and '1' so they never precede the text. They
+   fade in (opacity only — no transform) so the appearance is deliberate. */
+.vn-screen:not([data-typing="0"]) .vn-choices { display: none; }
+.vn-screen[data-typing="0"] .vn-choices { animation: vnChoicesIn 0.22s ease both; }
+@keyframes vnChoicesIn { from { opacity: 0; } to { opacity: 1; } }
+/* Choices are standalone rounded capsules — solid (opaque) dark fill so they
+   pop over the scene without stacking transparent layers, centered text, and
+   the MS Gothic character font (--font-character). */
+.vn-choice-btn {
+  background: var(--dialogue-bg) !important;          /* same fill as the text box */
+  border: 1px solid rgba(255,255,255,0.2) !important;
+  border-radius: 30px !important;
+  color: var(--text-primary) !important;
+  font-family: var(--font-character) !important;     /* MS Gothic */
+  font-style: normal !important;
+  font-size: clamp(0.8rem, 1.25cqw, 1.35rem) !important;
+  padding: 0.75em 2em !important;          /* tracks the scaled font */
+  width: auto !important;                            /* size to content, not full width */
+  text-align: center !important;
+  cursor: pointer !important;
+  transition: background 0.15s, border-color 0.15s, transform 0.12s !important;
+}
+.vn-choice-btn:hover {
+  background: rgba(40, 40, 62, 0.82) !important;
+  border-color: var(--border-accent) !important;
+  transform: translateY(-1px);
+  color: #fff !important;
+}
+/* Free-text capsule — the last item in the choice column. Same fill/shape as
+   the pills, with an inline input + send arrow. */
+.vn-free-capsule {
+  display: flex;
+  align-items: center;
+  width: min(60%, 460px);
+  background: var(--dialogue-bg);
+  border: 1px solid rgba(255,255,255,0.2);
+  border-radius: 30px;
+  overflow: hidden;
+  pointer-events: auto;
+  transition: border-color 0.15s, background 0.15s;
+}
+.vn-free-capsule:focus-within {
+  border-color: var(--border-accent);   /* accent the rim only — keep the fill */
+}
+.vn-free-text,
+.vn-free-text:focus {
+  flex: 1 1 auto;
+  min-width: 0;
+  background: transparent !important;    /* no Gradio/browser fill on focus */
+  border: none !important;
+  outline: none !important;
+  box-shadow: none !important;
+  color: var(--text-primary);
+  font-family: var(--font-character);
+  font-size: clamp(0.8rem, 1.25cqw, 1.35rem);
+  padding: 0.7em 0.5em 0.7em 1.5em;        /* tracks the scaled font */
+}
+.vn-free-text::placeholder { color: var(--text-muted); font-style: italic; }
+.vn-free-go {
+  flex: 0 0 auto;
+  background: transparent;
+  border: none;
+  color: var(--text-accent);
+  font-size: clamp(0.85rem, 1.3cqw, 1.4rem);
+  cursor: pointer;
+  padding: 0 1.1em;
+}
+.vn-free-go:hover { color: #fff; }
+
+/* ── Casting beat ── */
+.vn-casting {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  gap: 24px;
+  background: radial-gradient(ellipse at center, #1c1c38 0%, var(--bg-screen) 70%);
+}
+.vn-casting .casting-title {
+  font-family: var(--font-display);
+  color: var(--text-accent);
+  font-size: 1.1rem;
+  letter-spacing: 0.15em;
+  animation: vnPulse 1.6s ease infinite;
+}
+.vn-casting .portraits { display: flex; gap: 24px; }
+.vn-portrait {
+  width: 110px; height: 160px;
+  border-radius: 6px;
+  border: 1px solid var(--border-mid);
+  background: var(--bg-surface);
+  overflow: hidden;
+  display: flex; align-items: center; justify-content: center;
+}
+.vn-portrait.pending { border-style: dashed; border-color: var(--border-subtle); }
+.vn-portrait img {
+  width: 100%; height: 100%;
+  object-fit: cover; object-position: top;
+  animation: portraitReveal 0.5s ease both;
+}
+@keyframes portraitReveal {
+  from { opacity: 0; transform: scale(0.92) translateY(4px); }
+  to   { opacity: 1;   transform: scale(1)    translateY(0); }
+}
+.pname {
+  font-family: var(--font-ui);
+  font-size: 0.78rem;
+  color: var(--text-accent);
+  margin-top: 4px;
+  letter-spacing: 0.06em;
+}
+.pname.pending {
+  color: var(--text-muted);
+}
+.portrait-wrap {
+  text-align: center;
+}
+
+/* ── Interactive Casting Review ── */
+.vn-casting-review {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  background: radial-gradient(ellipse at center, #1c1c38 0%, var(--bg-screen) 70%);
+  padding: 20px;
+}
+.casting-review-title {
+  font-family: var(--font-display);
+  color: var(--text-accent);
+  font-size: 0.85rem;
+  letter-spacing: 0.15em;
+  margin-bottom: 18px;
+}
+.review-layout {
+  display: flex;
+  gap: 28px;
+  align-items: flex-start;
+  width: 100%;
+  max-width: 800px;
+  justify-content: center;
+}
+.review-image {
+  width: 220px;
+  height: 380px;
+  border: 1px solid var(--border-mid);
+  border-radius: 6px;
+  overflow: hidden;
+  background: var(--bg-surface);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+}
+.review-image img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  object-position: top;
+}
+.review-no-image {
+  color: var(--text-muted);
+  font-style: italic;
+  font-size: 0.82rem;
+  text-align: center;
+  padding: 16px;
+}
+.review-panel {
+  flex: 1;
+  min-width: 260px;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.review-name {
+  font-family: var(--font-display);
+  color: var(--text-accent);
+  font-size: clamp(1.15rem, 1.5cqw, 1.6rem);
+  letter-spacing: 0.06em;
+}
+/* Designed character description — role badge + personality paragraph */
+.review-desc { display: flex; flex-direction: column; gap: 6px; }
+.review-role {
+  align-self: flex-start;
+  font-family: var(--font-ui);
+  font-size: clamp(0.66rem, 0.85cqw, 0.92rem);
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+  color: var(--text-accent);
+  background: rgba(232,168,124,0.1);
+  border: 1px solid var(--border-accent);
+  border-radius: 3px;
+  padding: 2px 10px;
+}
+.review-personality {
+  font-family: var(--font-dialogue);
+  font-style: italic;
+  font-size: clamp(0.82rem, 1.05cqw, 1.15rem);
+  line-height: 1.55;
+  color: var(--text-secondary);
+  margin: 0;
+}
+.review-prompt-label {
+  font-family: var(--font-ui);
+  font-size: 0.68rem;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: var(--text-muted);
+}
+.review-prompt {
+  width: 100%;
+  background: var(--bg-surface) !important;
+  border: 1px solid var(--border-mid) !important;
+  border-radius: 4px !important;
+  color: var(--text-primary) !important;
+  font-family: var(--font-dialogue) !important;
+  font-size: 0.9rem !important;
+  line-height: 1.5 !important;
+  padding: 10px 12px !important;
+  resize: vertical;
+  caret-color: var(--text-accent) !important;
+}
+.review-prompt:focus {
+  border-color: var(--border-accent) !important;
+  outline: none !important;
+  box-shadow: 0 0 0 2px var(--border-glow) !important;
+}
+.review-actions {
+  display: flex;
+  gap: 12px;
+  margin-top: 4px;
+}
+.review-btn {
+  flex: 1;
+  padding: 10px 0 !important;
+  border-radius: 4px !important;
+  font-family: var(--font-display) !important;
+  font-size: 0.82rem !important;
+  letter-spacing: 0.1em !important;
+  cursor: pointer !important;
+  transition: background 0.18s ease, color 0.18s ease, border-color 0.18s ease, box-shadow 0.18s ease !important;
+  border: 1px solid var(--border-mid) !important;
+}
+.review-btn.confirm {
+  background: linear-gradient(135deg, #c07840, #e8a87c) !important;
+  border-color: var(--border-accent) !important;
+  color: #0d0d1a !important;
+  font-weight: 600 !important;
+}
+.review-btn.confirm:hover {
+  box-shadow: 0 0 14px var(--border-glow) !important;
+}
+.review-btn.redo {
+  background: var(--bg-surface) !important;
+  color: var(--text-secondary) !important;
+}
+.review-btn.redo:hover {
+  border-color: var(--border-accent) !important;
+  color: var(--text-accent) !important;
+}
+
+/* ── Cast Panel extras ── */
+.cast-expressions {
+  font-family: var(--font-ui);
+  font-size: 0.72rem;
+  color: var(--text-muted);
+  margin-top: 4px;
+}
+.cast-panel-empty {
+  padding: 8px;
+  color: var(--text-muted);
+  font-family: var(--font-dialogue);
+  font-style: italic;
+  font-size: clamp(0.88rem, 1.1cqw, 1.2rem);
+}
+
+/* ── Cast Cards (sidebar) ── */
+.cast-card {
+  background: var(--bg-surface);
+  border: 1px solid var(--border-subtle);
+  border-left: 3px solid var(--border-accent);
+  border-radius: 5px;
+  padding: 9px 12px;
+  margin-bottom: 6px;
+  transition: border-color 0.15s;
+}
+.cast-card:hover { border-color: var(--border-mid); }
+.cast-card .name {
+  font-family: var(--font-display);
+  font-size: 0.88rem;
+  color: var(--text-accent);
+  letter-spacing: 0.06em;
+}
+.cast-card .role {
+  font-family: var(--font-ui);
+  font-size: 0.72rem;
+  color: var(--text-muted);
+  margin-top: 2px;
+}
+.cast-card .personality {
+  font-family: var(--font-dialogue);
+  font-style: italic;
+  font-size: 0.82rem;
+  color: var(--text-secondary);
+  margin-top: 5px;
+  line-height: 1.4;
+}
+
+/* ── Header ── */
+.vn-header { padding: 14px 0 12px; margin-bottom: 14px; }
+.vn-title-main {
+  font-family: var(--font-display);
+  font-size: 1.9rem;
+  font-weight: 600;
+  color: var(--text-accent);
+  letter-spacing: 0.3em;
+  text-shadow: 0 0 40px rgba(232,168,124,0.25);
+}
+.vn-title-sub {
+  font-family: var(--font-dialogue);
+  font-style: italic;
+  font-size: 0.82rem;
+  color: var(--text-muted);
+  letter-spacing: 0.04em;
+  margin-top: 2px;
+}
+.vn-header-rule {
+  height: 1px;
+  background: linear-gradient(to right, var(--border-accent), transparent);
+  margin-top: 10px;
+  opacity: 0.35;
+}
+
+/* ── Sidebar ── */
+.sidebar-col { border-right: 1px solid var(--border-subtle); padding-right: 14px !important; }
+.sidebar-section-label {
+  font-family: var(--font-display);
+  font-size: 0.68rem;
+  letter-spacing: 0.2em;
+  text-transform: uppercase;
+  color: var(--text-accent);
+  border-bottom: 1px solid var(--border-subtle);
+  padding-bottom: 4px;
+  margin: 16px 0 10px;
+}
+
+/* ── Scene Info HUD ── */
+.scene-info p, .scene-info {
+  font-family: var(--font-ui) !important;
+  font-size: 0.72rem !important;
+  color: var(--text-muted) !important;
+  letter-spacing: 0.06em !important;
+  text-transform: uppercase !important;
+  border-left: 2px solid var(--border-subtle);
+  padding-left: 8px;
+  margin: 4px 0 !important;
+}
+
+/* ── Buttons ── */
+/* Scope button transitions to colour only — `transition: all` animated layout
+   geometry (transform/size/position) whenever buttons relaid out (e.g. the
+   choice column appearing), which read as a dark element "dragging" in. */
+button { border-radius: 3px !important; transition: background 0.18s ease, color 0.18s ease, border-color 0.18s ease, box-shadow 0.18s ease !important; }
+.gradio-container button:not(.vn-choice-btn) {
+  font-family: var(--font-display) !important;
+  font-size: 0.72rem !important;
+  letter-spacing: 0.1em !important;
+  text-transform: uppercase !important;
+  background: var(--bg-surface) !important;
+  border: 1px solid var(--border-mid) !important;
+  color: var(--text-secondary) !important;
+}
+.gradio-container button:not(.vn-choice-btn):hover {
+  border-color: var(--border-accent) !important;
+  color: var(--text-accent) !important;
+  background: var(--bg-raised) !important;
+}
+button[variant="primary"] {
+  background: linear-gradient(135deg, #c07840, #e8a87c) !important;
+  border-color: var(--border-accent) !important;
+  color: #0d0d1a !important;
+  font-weight: 600 !important;
+}
+button[variant="primary"]:hover {
+  box-shadow: 0 0 14px var(--border-glow) !important;
+}
+button[variant="stop"] { border-color: #c06060 !important; color: #c06060 !important; }
+
+/* ── Free-text input ── */
+#free-input-row { margin-top: 8px; border-top: 1px solid var(--border-subtle); padding-top: 8px; }
+#free-input textarea, #free-input input {
+  background: var(--bg-surface) !important;
+  border: 1px solid var(--border-mid) !important;
+  color: var(--text-primary) !important;
+  font-family: var(--font-dialogue) !important;
+  font-size: 1rem !important;
+  font-style: italic !important;
+  caret-color: var(--text-accent) !important;
+  border-radius: 3px !important;
+}
+#free-input textarea:focus, #free-input input:focus {
+  border-color: var(--border-accent) !important;
+  box-shadow: 0 0 0 2px var(--border-glow) !important;
+}
+#free-input label {
+  font-family: var(--font-ui) !important;
+  font-size: 0.7rem !important;
+  letter-spacing: 0.1em !important;
+  text-transform: uppercase !important;
+  color: var(--text-muted) !important;
+}
+#free-submit-btn button {
+  background: linear-gradient(135deg, #c07840, #e8a87c) !important;
+  border-color: var(--border-accent) !important;
+  color: #0d0d1a !important;
+  font-weight: 600 !important;
+}
+#free-submit-btn button:hover {
+  box-shadow: 0 0 14px var(--border-glow) !important;
+}
+
+/* ── Narration Log ── */
+.gr-textbox textarea {
+  background: var(--bg-void) !important;
+  border: 1px solid var(--border-subtle) !important;
+  color: var(--text-narrator) !important;
+  font-family: var(--font-dialogue) !important;
+  font-style: italic !important;
+  font-size: 0.88rem !important;
+  line-height: 1.65 !important;
+  border-radius: 4px !important;
+}
+label {
+  font-family: var(--font-ui) !important;
+  font-size: 0.72rem !important;
+  letter-spacing: 0.1em !important;
+  text-transform: uppercase !important;
+  color: var(--text-muted) !important;
+}
+
+/* ── Number input (save slot) ── */
+.gr-number input {
+  background: var(--bg-surface) !important;
+  border: 1px solid var(--border-mid) !important;
+  color: var(--text-primary) !important;
+  font-family: var(--font-ui) !important;
+  border-radius: 3px !important;
+  text-align: center !important;
+}
+
+/* ── Hide audio widget (audio still plays via autoplay) ── */
+.gr-audio { height: 2px !important; overflow: hidden !important; opacity: 0 !important; pointer-events: none !important; margin: 0 !important; }
+
+/* ── Gradio headings ── */
+h1, h2, h3 { font-family: var(--font-display) !important; color: var(--text-accent) !important; }
+
+/* ════════════════════════════════════════════════════════════════
+   REDESIGN — everything lives inside the screen (Ren'Py grammar)
+   ════════════════════════════════════════════════════════════════ */
+
+/* Stacking order: dialogue 4 · choices 5 · tray 10 · panels 20 */
+.vn-dialogue { z-index: 4; }
+.vn-choices  { z-index: 5; }
+
+/* ── Icon tray (top-right of dialogue box) ── */
+.vn-icon-tray {
+  position: absolute;
+  bottom: 7px; left: 50%;
+  transform: translateX(-50%);
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  z-index: 10;
+}
+.vn-tray-btn {
+  background: rgba(255,255,255,0.05) !important;
+  border: 1px solid var(--border-mid) !important;
+  color: var(--text-secondary) !important;
+  font-family: var(--font-ui) !important;
+  font-size: clamp(0.6rem, 0.75cqw, 0.85rem) !important;
+  letter-spacing: 0.1em !important;
+  text-transform: uppercase !important;
+  padding: 2px 8px !important;
+  cursor: pointer !important;
+  border-radius: 3px !important;
+  transition: color 0.15s, border-color 0.15s, background 0.15s !important;
+}
+.vn-tray-btn:hover, .vn-tray-btn.active {
+  color: var(--text-accent) !important;
+  border-color: var(--border-accent) !important;
+  background: rgba(232,168,124,0.1) !important;
+}
+.vn-icon-tray .vn-tray-confirm-row { display: none; }
+.vn-icon-tray.confirming .vn-tray-normal { display: none; }
+.vn-icon-tray.confirming .vn-tray-confirm-row { display: inline !important; }
+.vn-reset-confirm { cursor: pointer; color: #c06060; }
+.vn-reset-confirm:hover { color: #e07070; }
+.vn-reset-cancel { cursor: pointer; color: var(--text-muted); }
+.vn-reset-cancel:hover { color: var(--text-secondary); }
+
+/* ── Overlay panels ── */
+.vn-panel {
+  position: absolute;
+  z-index: 20;
+  background: rgba(10, 10, 28, 0.97);
+  font-family: var(--font-ui);
+}
+.vn-panel-title {
+  font-family: var(--font-display);
+  font-size: clamp(0.75rem, 0.95cqw, 1.05rem);
+  letter-spacing: 0.2em;
+  text-transform: uppercase;
+  color: var(--text-accent);
+  border-bottom: 1px solid var(--border-subtle);
+  padding-bottom: 6px;
+  margin-bottom: 12px;
+}
+.vn-panel-close {
+  position: absolute;
+  top: 10px; right: 12px;
+  background: transparent !important;
+  border: none !important;
+  color: var(--text-muted) !important;
+  font-size: clamp(0.9rem, 1.15cqw, 1.3rem) !important;
+  cursor: pointer !important;
+  padding: 2px 6px !important;
+}
+.vn-panel-close:hover { color: var(--text-accent) !important; }
+
+/* Log panel — slides up over the dialogue box.
+   Closed panels are visibility:hidden, NOT just translated out of the clip:
+   during Gradio's canvas-HTML swap the browser could paint the off-canvas
+   panels unclipped for a few frames (seen as dark log/cast sheets "dragging"
+   across the page each turn). visibility doesn't depend on overflow clipping
+   or compositor timing, so a closed panel can never paint. The 0s visibility
+   transition is DELAYED by the slide duration on close (so the slide-out
+   stays visible) and instant on open. */
+.vn-panel-log {
+  bottom: 0; left: 0; right: 0;
+  height: 55%;
+  border-top: 1px solid var(--border-mid);
+  transform: translateY(102%);
+  visibility: hidden;
+  transition: transform 0.3s ease, visibility 0s linear 0.3s;
+  overflow-y: auto;
+  padding: 18px 28px;
+}
+.vn-panel-log.open {
+  transform: translateY(0);
+  visibility: visible;
+  transition: transform 0.3s ease, visibility 0s;
+}
+.vn-log-text {
+  font-family: var(--font-dialogue);
+  font-style: italic;
+  font-size: clamp(0.85rem, 1.25cqw, 1.35rem);
+  line-height: 1.7;
+  color: var(--text-narrator);
+  white-space: pre-wrap;
+}
+/* Player answers inside the session register (▸-prefixed lines) */
+.vn-log-answer {
+  font-style: normal;
+  color: var(--text-accent);
+}
+
+/* Cast panel — slides in from the right */
+.vn-panel-cast {
+  top: 0; right: 0; bottom: 0;
+  width: 40%;
+  min-width: 260px;
+  border-left: 1px solid var(--border-mid);
+  transform: translateX(102%);
+  visibility: hidden;            /* unpaintable when closed — see log panel note */
+  transition: transform 0.3s ease, visibility 0s linear 0.3s;
+  overflow-y: auto;
+  padding: 18px 16px;
+}
+.vn-panel-cast.open {
+  transform: translateX(0);
+  visibility: visible;
+  transition: transform 0.3s ease, visibility 0s;
+}
+.cast-panel-card {
+  display: flex;
+  gap: 14px;
+  background: var(--bg-surface);
+  border: 1px solid var(--border-subtle);
+  border-left: 3px solid var(--border-accent);
+  border-radius: 5px;
+  padding: 12px 14px;
+  margin-bottom: 10px;
+}
+.cast-panel-thumb {
+  width: clamp(78px, 8cqw, 130px); height: clamp(112px, 11.5cqw, 188px);
+  object-fit: cover; object-position: top;
+  border-radius: 3px;
+  flex-shrink: 0;
+  background: var(--bg-raised);
+}
+.cast-panel-name {
+  font-family: var(--font-display);
+  font-size: clamp(1rem, 1.3cqw, 1.45rem);
+  color: var(--text-accent);
+  letter-spacing: 0.06em;
+}
+.cast-panel-role {
+  font-size: clamp(0.76rem, 1cqw, 1.1rem);
+  color: var(--text-muted);
+  margin-top: 2px;
+}
+.cast-panel-personality {
+  font-family: var(--font-dialogue);
+  font-style: italic;
+  font-size: clamp(0.85rem, 1.1cqw, 1.2rem);
+  color: var(--text-secondary);
+  margin-top: 6px;
+  line-height: 1.45;
+}
+
+/* Save panel — centered modal */
+.vn-panel-save {
+  top: 50%; left: 50%;
+  transform: translate(-50%, -50%) scale(0.95);
+  opacity: 0;
+  visibility: hidden;            /* unpaintable when closed — see log panel note */
+  pointer-events: none;
+  transition: opacity 0.2s, transform 0.2s, visibility 0s linear 0.2s;
+  width: clamp(380px, 34cqw, 560px);
+  max-height: 86%;
+  overflow-y: auto;
+  border: 1px solid var(--border-mid);
+  border-radius: 6px;
+  padding: 22px 24px;
+  box-shadow: 0 8px 60px rgba(0,0,0,0.6);
+}
+.vn-panel-save.open {
+  opacity: 1;
+  transform: translate(-50%, -50%) scale(1);
+  visibility: visible;
+  pointer-events: auto;
+  transition: opacity 0.2s, transform 0.2s, visibility 0s;
+}
+/* Rich slot rows — one full-width card per slot: name, chapter · turn,
+   cast names, timestamp. Shared by the save panel and the menu load list. */
+.vn-slot-list {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  margin-bottom: 14px;
+  width: 100%;
+}
+.vn-slot-btn {
+  display: grid !important;
+  grid-template-columns: 1fr auto;
+  row-gap: 2px;
+  width: 100% !important;
+  background: var(--bg-surface) !important;
+  border: 1px solid var(--border-mid) !important;
+  border-radius: 4px !important;
+  padding: 8px 12px !important;
+  cursor: pointer !important;
+  text-align: left !important;
+  transition: border-color 0.15s, background 0.15s !important;
+}
+.vn-slot-btn:hover {
+  border-color: var(--border-accent) !important;
+}
+.vn-slot-btn.active {
+  border-color: var(--border-accent) !important;
+  background: rgba(232,168,124,0.1) !important;
+}
+.vn-slot-btn.empty .vn-slot-name { color: var(--text-muted); font-style: italic; }
+.vn-slot-btn.disabled { opacity: 0.45 !important; cursor: default !important; }
+.vn-slot-name {
+  font-family: var(--font-display);
+  font-size: clamp(0.82rem, 1.05cqw, 1.15rem);
+  color: var(--text-accent);
+  letter-spacing: 0.05em;
+  grid-column: 1;
+}
+.vn-slot-time {
+  font-family: var(--font-ui);
+  font-size: clamp(0.66rem, 0.85cqw, 0.92rem);
+  color: var(--text-muted);
+  grid-column: 2; grid-row: 1;
+  align-self: center;
+}
+.vn-slot-meta {
+  font-family: var(--font-ui);
+  font-size: clamp(0.7rem, 0.9cqw, 1rem);
+  color: var(--text-secondary);
+  grid-column: 1 / -1;
+}
+.vn-slot-cast {
+  font-family: var(--font-dialogue);
+  font-style: italic;
+  font-size: clamp(0.7rem, 0.9cqw, 1rem);
+  color: var(--text-muted);
+  grid-column: 1 / -1;
+}
+/* Save-name input — sits between the slots and the Save/Load actions. */
+.vn-save-name {
+  width: 100%;
+  box-sizing: border-box;
+  background: rgba(255,255,255,0.04);
+  border: 1px solid var(--border-mid);
+  border-radius: 3px;
+  color: var(--text-primary);
+  font-family: var(--font-ui);
+  font-size: clamp(0.78rem, 1cqw, 1.1rem);
+  padding: 7px 10px;
+  margin-bottom: 10px;
+  transition: border-color 0.15s;
+}
+.vn-save-name:focus {
+  border-color: var(--border-accent);
+  outline: none;
+  box-shadow: 0 0 0 2px var(--border-glow);
+}
+.vn-save-name::placeholder { color: var(--text-muted); font-style: italic; }
+.vn-save-actions { display: flex; gap: 10px; }
+.vn-save-action {
+  flex: 1;
+  background: var(--bg-surface) !important;
+  border: 1px solid var(--border-mid) !important;
+  color: var(--text-secondary) !important;
+  font-family: var(--font-display) !important;
+  font-size: clamp(0.72rem, 0.95cqw, 1rem) !important;
+  letter-spacing: 0.12em !important;
+  text-transform: uppercase !important;
+  padding: 9px 0 !important;
+  border-radius: 3px !important;
+  cursor: pointer !important;
+}
+.vn-save-action:hover {
+  border-color: var(--border-accent) !important;
+  color: var(--text-accent) !important;
+}
+.vn-save-status {
+  margin-top: 12px;
+  font-size: clamp(0.74rem, 0.95cqw, 1rem);
+  color: var(--text-muted);
+  font-style: italic;
+  min-height: 1.1em;
+}
+
+/* ── Title screen ── */
+.vn-title-screen {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: linear-gradient(160deg, #0d0d1a 0%, #16162e 60%, #0a0a20 100%);
+}
+.vn-title-content {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 22px;
+}
+.vn-title-screen .vn-title-main { font-size: 3rem; letter-spacing: 0.35em; }
+.vn-title-screen .vn-title-sub  { font-size: 0.95rem; margin-top: -14px; }
+.vn-title-cast-choice {
+  display: flex;
+  gap: 0;
+  border: 1px solid var(--border-mid);
+  border-radius: 3px;
+  overflow: hidden;
+}
+.vn-title-opt {
+  background: transparent !important;
+  border: none !important;
+  border-radius: 0 !important;
+  color: var(--text-muted) !important;
+  font-family: var(--font-ui) !important;
+  font-size: 0.72rem !important;
+  letter-spacing: 0.12em !important;
+  text-transform: uppercase !important;
+  padding: 8px 18px !important;
+  cursor: pointer !important;
+  transition: background 0.15s, color 0.15s !important;
+}
+.vn-title-opt.active {
+  background: rgba(232,168,124,0.12) !important;
+  color: var(--text-accent) !important;
+}
+.vn-title-begin {
+  font-family: var(--font-display) !important;
+  font-size: 0.9rem !important;
+  letter-spacing: 0.22em !important;
+  text-transform: uppercase !important;
+  background: linear-gradient(135deg, #c07840, #e8a87c) !important;
+  border: none !important;
+  color: #0d0d1a !important;
+  padding: 12px 44px !important;
+  border-radius: 3px !important;
+  cursor: pointer !important;
+  font-weight: 600 !important;
+  transition: box-shadow 0.2s !important;
+}
+.vn-title-begin:hover { box-shadow: 0 0 22px var(--border-glow) !important; }
+.vn-title-actions { display: flex; gap: 14px; align-items: center; }
+.vn-title-load {
+  font-family: var(--font-display) !important;
+  font-size: 0.9rem !important;
+  letter-spacing: 0.22em !important;
+  text-transform: uppercase !important;
+  background: var(--bg-surface) !important;
+  border: 1px solid var(--border-mid) !important;
+  color: var(--text-secondary) !important;
+  padding: 12px 36px !important;
+  border-radius: 3px !important;
+  cursor: pointer !important;
+  transition: color 0.15s, border-color 0.15s !important;
+}
+.vn-title-load:hover {
+  color: var(--text-accent) !important;
+  border-color: var(--border-accent) !important;
+}
+.vn-title-load.disabled {
+  opacity: 0.35 !important;
+  cursor: default !important;
+}
+
+/* ── Main-menu Load list — a third title-screen section, like cast setup.
+   Toggled by body.menu-load-active; !important beats Gradio 6's scoped
+   re-emission of the base rules (see the cast-setup note above). ── */
+.vn-menu-load { display: none; }
+body.menu-load-active .vn-title-content { display: none !important; }
+body.menu-load-active .vn-cast-setup { display: none !important; }
+body.menu-load-active .vn-menu-load {
+  display: flex !important;
+  flex-direction: column;
+  align-items: center;
+  justify-content: flex-start;
+  width: 100%;
+  height: 100%;
+  padding: 28px 36px;
+  overflow-y: auto;
+  gap: 16px;
+  background: linear-gradient(160deg, #0d0d1a 0%, #16162e 60%, #0a0a20 100%);
+}
+.vn-ml-title {
+  font-family: var(--font-display);
+  font-size: clamp(1.3rem, 2cqw, 2.1rem);
+  letter-spacing: 0.28em;
+  color: var(--text-accent);
+  text-shadow: 0 0 30px rgba(232,168,124,0.2);
+}
+.vn-ml-list { width: 100%; max-width: min(620px, 80%); }
+.vn-ml-back {
+  font-family: var(--font-display) !important;
+  font-size: clamp(0.82rem, 1.05cqw, 1.15rem) !important;
+  letter-spacing: 0.18em !important;
+  text-transform: uppercase !important;
+  background: var(--bg-surface) !important;
+  border: 1px solid var(--border-mid) !important;
+  color: var(--text-secondary) !important;
+  padding: 10px 32px !important;
+  border-radius: 3px !important;
+  cursor: pointer !important;
+}
+.vn-ml-back:hover {
+  color: var(--text-accent) !important;
+  border-color: var(--border-accent) !important;
+}
+
+/* ── Title screen — player name input ── */
+.vn-title-name-row { margin-top: 8px; }
+.vn-title-name-input {
+  background: rgba(255,255,255,0.04);
+  border: 1px solid var(--border-mid);
+  color: var(--text-primary);
+  font-family: var(--font-ui);
+  font-size: 0.85rem;
+  letter-spacing: 0.06em;
+  padding: 8px 14px;
+  border-radius: 3px;
+  text-align: center;
+  width: 220px;
+  transition: border-color 0.15s;
+}
+.vn-title-name-input:focus {
+  border-color: var(--border-accent);
+  outline: none;
+  box-shadow: 0 0 0 2px var(--border-glow);
+}
+.vn-title-name-input::placeholder { color: var(--text-muted); }
+
+/* ── Cast Setup ── */
+.vn-cast-setup {
+  display: none;
+  flex-direction: column;
+  align-items: center;
+  justify-content: flex-start;
+  width: 100%;
+  height: 100%;
+  padding: 28px 36px;
+  overflow-y: auto;
+  gap: 14px;
+  background: linear-gradient(160deg, #0d0d1a 0%, #16162e 60%, #0a0a20 100%);
+}
+.vn-cs-header { text-align: center; max-width: min(820px, 78%); }
+.vn-cs-title {
+  font-family: var(--font-display);
+  font-size: clamp(1.3rem, 2cqw, 2.1rem);
+  letter-spacing: 0.28em;
+  color: var(--text-accent);
+  text-shadow: 0 0 30px rgba(232,168,124,0.2);
+  margin-bottom: 8px;
+}
+.vn-cs-desc {
+  font-family: var(--font-dialogue);
+  font-size: clamp(0.85rem, 1.15cqw, 1.25rem);
+  line-height: 1.65;
+  color: var(--text-secondary);
+  text-align: left;
+  margin-top: 4px;
+}
+.vn-cs-desc p { margin: 6px 0; }
+.vn-cs-desc code {
+  background: rgba(232,168,124,0.1);
+  color: var(--text-accent);
+  padding: 0 4px;
+  border-radius: 2px;
+  font-size: 0.92em;          /* tracks the scaled description text */
+}
+.vn-cs-cards {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  width: 100%;
+  max-width: min(860px, 80%);
+}
+.vn-cs-card {
+  background: var(--bg-surface);
+  border: 1px solid var(--border-subtle);
+  border-radius: 6px;
+  padding: 12px 14px;
+  transition: border-color 0.15s;
+}
+.vn-cs-card:focus-within { border-color: var(--border-accent); }
+.vn-cs-card-row {
+  display: flex;
+  gap: 10px;
+  margin-bottom: 8px;
+}
+.vn-cs-field {
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+  flex: 1;
+}
+.vn-cs-field label {
+  font-family: var(--font-ui);
+  font-size: clamp(0.68rem, 0.85cqw, 0.95rem);
+  letter-spacing: 0.15em;
+  text-transform: uppercase;
+  color: var(--text-muted);
+}
+.vn-cs-input {
+  background: rgba(255,255,255,0.04);
+  border: 1px solid var(--border-mid);
+  border-radius: 3px;
+  color: var(--text-primary);
+  font-family: var(--font-ui);
+  font-size: clamp(0.88rem, 1.15cqw, 1.25rem);
+  padding: 7px 10px;
+  transition: border-color 0.15s;
+  width: 100%;
+  box-sizing: border-box;
+}
+.vn-cs-input:focus {
+  border-color: var(--border-accent);
+  outline: none;
+  box-shadow: 0 0 0 2px var(--border-glow);
+}
+.vn-cs-input::placeholder { color: var(--text-muted); font-style: italic; font-size: 0.9em; }
+.vn-cs-tags-row { width: 100%; }
+.vn-cs-tags-input {
+  font-family: monospace;
+  font-size: clamp(0.8rem, 1.05cqw, 1.15rem);
+}
+.vn-cs-fast {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  cursor: pointer;
+  max-width: min(860px, 80%);
+  width: 100%;
+  padding: 6px 0;
+}
+.vn-cs-fast input[type="checkbox"] {
+  accent-color: var(--border-accent);
+  width: 15px; height: 15px;
+  cursor: pointer;
+  flex-shrink: 0;
+}
+.vn-cs-fast span {
+  font-family: var(--font-ui);
+  font-size: clamp(0.78rem, 1cqw, 1.05rem);
+  color: var(--text-muted);
+  letter-spacing: 0.04em;
+}
+.vn-cs-actions {
+  display: flex;
+  gap: 14px;
+  justify-content: center;
+  width: 100%;
+  max-width: min(860px, 80%);
+  padding-top: 6px;
+}
+.vn-cs-btn {
+  font-family: var(--font-display) !important;
+  font-size: clamp(0.82rem, 1.05cqw, 1.15rem) !important;
+  letter-spacing: 0.18em !important;
+  text-transform: uppercase !important;
+  padding: 10px 32px !important;
+  border-radius: 3px !important;
+  cursor: pointer !important;
+  transition: background 0.18s ease, color 0.18s ease, border-color 0.18s ease, box-shadow 0.18s ease !important;
+  border: 1px solid var(--border-mid) !important;
+}
+.vn-cs-btn.vn-cs-back {
+  background: var(--bg-surface) !important;
+  color: var(--text-secondary) !important;
+}
+.vn-cs-btn.vn-cs-back:hover {
+  border-color: var(--border-accent) !important;
+  color: var(--text-accent) !important;
+}
+.vn-cs-btn.vn-cs-go {
+  background: linear-gradient(135deg, #c07840, #e8a87c) !important;
+  border-color: var(--border-accent) !important;
+  color: #0d0d1a !important;
+  font-weight: 600 !important;
+}
+.vn-cs-btn.vn-cs-go:hover {
+  box-shadow: 0 0 14px var(--border-glow) !important;
+}
+
+/* Choice pills are styled in the "rounded capsules" block above. */
+
+/* ── Stage wrapper — the relative containing block for the canvas + the
+   free-text bar. The bar overlays INSIDE the canvas frame, anchored to this
+   wrapper (an earlier version had no positioned ancestor and the box flew
+   across the viewport). ── */
+#stage { position: relative !important; gap: 0 !important; padding: 0 !important;
+         margin-bottom: 8px !important; width: 100% !important; }
+/* The gr.HTML wrapper insets the canvas by 12px each side; remove it so the
+   canvas spans the full stage width and the free-text bar (70% of the stage)
+   lines up with the choices (70% of the canvas). */
+#stage .html-container { padding: 0 !important; }
+#stage .vn-screen { margin-bottom: 0 !important; }
+
+/* ── Free-text action bar — docked inside the canvas, in the same centered
+   column as the choices (which sit just above it) and styled to match the
+   choice buttons, so it reads as part of the interaction cluster rather than
+   a glued-on pill. Hidden until the END of a turn — revealed only on the last
+   beat once the text has finished revealing, together with the choices (JS
+   sets body.vn-playing; see syncStage). ── */
+/* The bar is styled to be visually identical to a .vn-choice-btn (see the
+   "Choice restyle" block above): the same translucent void-scrim, blur(4px),
+   borderless 2px accent left bar, sharp corners and italic dialogue voice —
+   so it reads as just one more option in the stack, not a separate widget. */
+/* The free-text input now lives INSIDE the canvas as .vn-free-capsule (the
+   last item in the centered choice column). This Gradio row is kept only as
+   the hidden value/submit bridge — never shown. */
+#free-input-row { display: none !important; }
+
+/* The textbox fills the bar with no inner chrome — every Gradio wrapper
+   background is forced transparent so only the row's scrim shows (otherwise
+   the opaque .block fill makes the bar look solid). NOTE: in this Gradio
+   version the <input> is nested INSIDE the <label>, so the label must stay
+   laid out (only its caption span is hidden — Gradio tags it .hide). The
+   empty default .wrap is collapsed so the input claims the full width. */
+#free-input { flex: 8 1 auto; min-width: 0; display: flex !important; align-items: stretch; }
+#free-input, #free-input .wrap, #free-input label, #free-input .label-wrap,
+#free-input .input-container, #free-input .form, #free-input .block {
+  background: transparent !important;
+  border: none !important;
+  box-shadow: none !important;
+}
+#free-input > .wrap { display: none !important; }
+#free-input label, #free-input .label-wrap {
+  display: flex !important;
+  flex: 1 1 auto; min-width: 0;
+  margin: 0 !important; padding: 0 !important;
+}
+#free-input label > span { display: none !important; }   /* the caption text */
+#free-input .input-container { display: flex !important; flex: 1 1 auto; min-width: 0; }
+#free-input textarea, #free-input input {
+  flex: 1 1 auto; width: 100% !important;
+  background: transparent !important;
+  border: none !important;
+  border-radius: 0 !important;
+  box-shadow: none !important;
+  outline: none !important;
+  color: var(--text-primary) !important;
+  font-family: var(--font-dialogue) !important;
+  font-style: italic !important;
+  font-size: 1.05rem !important;
+  caret-color: var(--text-accent) !important;
+  padding: 9px 16px !important;
+}
+#free-input input::placeholder, #free-input textarea::placeholder {
+  color: var(--text-muted) !important; opacity: 1;
+}
+/* The ➤ send button is part of the same scrim — transparent, just an accent
+   glyph that brightens on hover (no filled chip, no divider). The elem_id is
+   on the <button> itself in this Gradio version, so target both it and any
+   wrapper to stay version-resilient. */
+#free-submit-btn, #free-submit-btn button {
+  flex: 0 0 auto !important;
+  align-self: stretch;
+  min-width: 44px !important; width: 44px !important;
+  height: auto !important;
+  background: transparent !important;
+  border: none !important;
+  border-radius: 0 !important;
+  color: var(--text-accent) !important;
+  font-size: 1.1rem !important;
+  font-weight: 600 !important;
+  opacity: 0.8;
+  cursor: pointer !important;
+  transition: color 0.15s, opacity 0.15s;
+}
+#free-submit-btn:hover, #free-submit-btn button:hover {
+  background: transparent !important;
+  color: #fff !important;
+  opacity: 1;
+  box-shadow: none !important;
+}
+
+/* ── Turn-pending indicator ── replaces Gradio's overlay as the "thinking"
+   feedback: JS adds body.vn-waiting when a choice / free-text is submitted
+   and removes it when the next screen render lands. The choice column dims
+   and locks (no double submits) and a pulsing ✦ marks the wait.
+   !important is load-bearing twice over: it beats the PREFIXED copies of the
+   base rules (the body.…-keyed prefixed twins never match) AND the lingering
+   fill-mode opacity of the vnChoicesIn animation. */
+body.vn-waiting .vn-choices { opacity: 0.35 !important; }
+body.vn-waiting .vn-choices .vn-choice-btn,
+body.vn-waiting .vn-free-capsule { pointer-events: none !important; }
+body.vn-waiting .vn-screen::after {
+  content: '✦';
+  position: absolute;
+  right: 18px; bottom: 14px;
+  color: var(--text-accent);
+  font-size: 1.05rem;
+  z-index: 30;
+  animation: vnPulse 1.2s ease infinite;
+}
+
+/* ── Kill Gradio's queue-progress chrome inside the stage ── Gradio overlays
+   each output component with .wrap.full (a cover) + .eta-bar (a dark,
+   inset:0, opacity-.8 layer that GROWS across the component via a transform)
+   and dims the component to opacity .2 via .pending while a callback runs.
+   Over the canvas this read as the whole UI — sprites included — "dragging"
+   diagonally whenever a turn was processing. The event listeners pass
+   show_progress="hidden"; this is the belt-and-braces for any that don't. */
+#stage .eta-bar { display: none !important; }
+#stage .progress-text { display: none !important; }
+#stage .wrap.full { background: transparent !important; }
+#stage .pending { opacity: 1 !important; animation: none !important; }
+#stage .generating { animation: none !important; border: none !important; }
+
+/* ── Collapse the audio widget (autoplay still fires) ── */
+#voice-audio {
+  height: 2px !important;
+  overflow: hidden !important;
+  opacity: 0 !important;
+  pointer-events: none !important;
+  margin: 0 !important;
+  padding: 0 !important;
+}
+"""
+
+# Inject the env-configured character-dialogue font into the --font-character token.
+CSS = CSS.replace("__FONT_CHARACTER__", CHARACTER_FONT)
+
+# Installed via launch(js=...) — gr.HTML strips <script> tags, so a page
+# load hook is the reliable way to wire the in-screen choice buttons.
+#
+# IMPORTANT (Gradio 6): the js string is run as a FUNCTION BODY
+# (`new Function(...args, <js>)` then called), NOT eval'd as an expression.
+# So it must be plain statements — an `() => {...}` arrow wrapper would just
+# be constructed and discarded, and the listener would never attach.
+ONLOAD_JS = """
+// ── Typewriter: reveals text char-by-char, two-stage click ─────
+const TYPING_SPEED = 35;  // ms per character
+let _typewriterTimer = null;
+
+function startTypewriter(screen) {
+    // Already completed (e.g. user clicked during the settle delay) — don't restart
+    if (screen.getAttribute('data-typing') === '0') return;
+
+    // Clear any running timer
+    if (_typewriterTimer) { clearInterval(_typewriterTimer); _typewriterTimer = null; }
+
+    const textEl = screen.querySelector('.vn-text');
+    if (!textEl) { screen.setAttribute('data-typing', '0'); return; }
+
+    const fullText = textEl.getAttribute('data-full-text') || textEl.textContent || '';
+    if (!fullText) { screen.setAttribute('data-typing', '0'); return; }
+    textEl.setAttribute('data-full-text', fullText);
+
+    // If reduced-motion, reveal instantly
+    if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+        textEl.textContent = fullText;
+        textEl.classList.remove('typing');
+        screen.setAttribute('data-typing', '0');
+        return;
+    }
+
+    let idx = 0;
+    textEl.textContent = '';
+    textEl.classList.add('typing');
+    screen.setAttribute('data-typing', '1');
+
+    _typewriterTimer = setInterval(function() {
+        idx++;
+        if (idx >= fullText.length) {
+            clearInterval(_typewriterTimer);
+            _typewriterTimer = null;
+            textEl.textContent = fullText;
+            textEl.classList.remove('typing');
+            screen.setAttribute('data-typing', '0');
+        } else {
+            textEl.textContent = fullText.slice(0, idx);
+        }
+    }, TYPING_SPEED);
+}
+
+function completeTypewriter(screen) {
+    if (_typewriterTimer) { clearInterval(_typewriterTimer); _typewriterTimer = null; }
+    const textEl = screen.querySelector('.vn-text');
+    if (!textEl) return;
+    const fullText = textEl.getAttribute('data-full-text') || textEl.textContent || '';
+    textEl.textContent = fullText;
+    textEl.classList.remove('typing');
+    screen.setAttribute('data-typing', '0');
+}
+
+// Watch for VN screen changes: start typewriter, restore overlay-panel UI
+// state (the canvas HTML is replaced wholesale each beat/turn), and mirror
+// the hidden save status into the save panel.
+const _typewriterObserver = new MutationObserver(function() {
+    // 'pending' marks a freshly rendered screen that hasn't started typing.
+    // ('1' = typing now, '0' = done — neither must retrigger, or the
+    // typewriter's own text mutations would restart it in a loop.)
+    const screen = document.querySelector('.vn-screen');
+    if (screen && screen.getAttribute('data-typing') === 'pending') {
+        // A fresh render arrived — the turn the user was waiting on is here.
+        if (document.body.classList.contains('vn-waiting')) setWaiting(false);
+        screen.setAttribute('data-typing', '1');
+        // Small delay so the DOM settles
+        setTimeout(function() { startTypewriter(screen); }, 50);
+    }
+    // A title-screen render also ends any pending wait (e.g. a menu load
+    // that failed back to the title — it has no data-typing attribute).
+    if (screen && screen.classList.contains('vn-title-screen')
+        && document.body.classList.contains('vn-waiting')) {
+        setWaiting(false);
+    }
+    restoreUiState();
+    syncSaveStatus();
+    syncSlotRows();
+    syncStage();
+});
+
+// Reveal the free-text bar only at the END of a turn: when we're on the last
+// beat (data-more != "1") and the text has finished revealing (data-typing
+// "0") — or as soon as choices are offered. It stays hidden mid-turn, while
+// earlier beats are still being clicked through or typed out, and on the
+// title/casting screens. Pure class toggle on <body>.
+function syncStage() {
+    const canvas = document.querySelector('.vn-screen');
+    const inScene = !!(canvas && canvas.querySelector('.vn-dialogue'));
+    const lastBeat = inScene && canvas.getAttribute('data-more') !== '1';
+    const typingDone = inScene && canvas.getAttribute('data-typing') === '0';
+    // Reveal only after the line finishes typing — choices and the bar appear
+    // together once the text is fully shown, never before it.
+    const showBar = lastBeat && typingDone;
+    document.body.classList.toggle('vn-playing', showBar);
+}
+
+// Enter in the in-canvas free-text capsule submits via the hidden bridge.
+document.addEventListener('keydown', function(e) {
+    if (e.key !== 'Enter') return;
+    const active = document.activeElement;
+    if (active && active.classList && active.classList.contains('vn-free-text')) {
+        e.preventDefault();
+        submitFreeText(active);
+    }
+});
+// Start observing once the body is ready
+(function waitBody() {
+    if (document.body) {
+        // attributeFilter keeps class-toggle churn (restoreUiState) from
+        // re-firing the observer; only data-typing flips matter here.
+        _typewriterObserver.observe(document.body, {
+            childList: true, subtree: true,
+            attributes: true, attributeFilter: ['data-typing'],
+        });
+    } else {
+        setTimeout(waitBody, 100);
+    }
+})();
+
+// ── Click bridge ───────────────────────────────────────────────
+const clickHidden = (sel) => {
+    const el = document.querySelector(sel + ' button') || document.querySelector(sel);
+    if (el) el.click();
+};
+
+// Write a value into a hidden Gradio textbox so the server callback reads it
+// (React-style: use the prototype setter + dispatch 'input', or Gradio drops it).
+const setBoxValue = (boxId, val) => {
+    const ta = document.querySelector('#' + boxId + ' textarea, #' + boxId + ' input');
+    if (!ta) return;
+    const proto = ta.tagName === 'TEXTAREA'
+        ? window.HTMLTextAreaElement.prototype
+        : window.HTMLInputElement.prototype;
+    const setter = Object.getOwnPropertyDescriptor(proto, 'value');
+    if (setter && setter.set) { setter.set.call(ta, val); }
+    else { ta.value = val; }
+    ta.dispatchEvent(new Event('input', { bubbles: true }));
+};
+
+// Turn-pending indicator: body.vn-waiting dims/locks the choice column and
+// pulses a ✦ while the server thinks (a real-LLM turn takes seconds, and the
+// Gradio progress overlay is suppressed — show_progress="hidden"). Cleared
+// when the next screen render arrives; the timeout is a stuck-state guard
+// (e.g. the callback errored and no re-render ever comes).
+const setWaiting = (on) => {
+    document.body.classList.toggle('vn-waiting', on);
+    clearTimeout(window._vnWaitTimer);
+    if (on) {
+        window._vnWaitTimer = setTimeout(function() {
+            document.body.classList.remove('vn-waiting');
+        }, 120000);
+    }
+};
+
+// Submit the in-canvas free-text capsule via the hidden Gradio bridge.
+const submitFreeText = (input) => {
+    const val = ((input && input.value) || '').trim();
+    if (!val) return;
+    setBoxValue('free-input', val);
+    setWaiting(true);
+    setTimeout(() => clickHidden('#free-submit-btn'), 120);
+};
+
+document.addEventListener('click', function(e) {
+    // Free-text send arrow inside the choice column
+    const go = e.target.closest('.vn-free-go');
+    if (go) {
+        e.preventDefault();
+        const cap = go.closest('.vn-free-capsule');
+        submitFreeText(cap && cap.querySelector('.vn-free-text'));
+        return;
+    }
+
+    const btn = e.target.closest('.vn-choice-btn');
+    if (btn) {
+        e.preventDefault();
+        const id = btn.getAttribute('data-choice-id');
+        const text = btn.getAttribute('data-choice-text');
+        if (!id) return;
+
+        setBoxValue('choice-id-box', id);
+        setBoxValue('choice-text-box', text);
+
+        setWaiting(true);
+        setTimeout(() => clickHidden('#submit-choice-btn'), 150);
+        return;
+    }
+
+    // Two-stage click: if typing, complete text; else advance
+    const screen = e.target.closest('.vn-screen');
+    if (screen) {
+        if (screen.getAttribute('data-typing') === '1') {
+            e.preventDefault();
+            completeTypewriter(screen);
+            return;
+        }
+        // If no more beats and choices visible, don't advance (let choice buttons work)
+        // A click while a panel is open closes the panel instead of advancing.
+        if (screen.getAttribute('data-more') === '1'
+            && !(window._vnUi && window._vnUi.panel)
+            && !e.target.closest('.vn-choices')
+            && !e.target.closest('.vn-panel')
+            && !e.target.closest('.vn-icon-tray')) {
+            e.preventDefault();
+            clickHidden('#advance-btn');
+        }
+    }
+});
+
+// Space / Enter: complete typewriter or advance
+document.addEventListener('keydown', function(e) {
+    if (e.key !== ' ' && e.key !== 'Enter') return;
+    const tag = (document.activeElement && document.activeElement.tagName) || '';
+    if (tag === 'INPUT' || tag === 'TEXTAREA') return;
+
+    const screen = document.querySelector('.vn-screen');
+    if (!screen) return;
+
+    if (screen.getAttribute('data-typing') === '1') {
+        e.preventDefault();
+        completeTypewriter(screen);
+        return;
+    }
+
+    if (screen.getAttribute('data-more') === '1') {
+        e.preventDefault();
+        clickHidden('#advance-btn');
+    }
+});
+
+// NOTE: the free-text box is cleared SERVER-SIDE (on_free_submit returns ""
+// into it) — never with a JS timeout, which raced Gradio's value capture and
+// caused submits to be read as empty and silently dropped.
+
+// ════════════════════════════════════════════════════════════════
+// REDESIGN — title screen, icon tray, overlay panels
+// ════════════════════════════════════════════════════════════════
+
+// Shared helper: write a value into a hidden gradio Textbox/Number
+function setHiddenVal(rootSel, val) {
+    const el = document.querySelector(rootSel + ' textarea, ' + rootSel + ' input');
+    if (!el) return;
+    const proto = el.tagName === 'TEXTAREA'
+        ? window.HTMLTextAreaElement.prototype
+        : window.HTMLInputElement.prototype;
+    const setter = Object.getOwnPropertyDescriptor(proto, 'value');
+    if (setter && setter.set) { setter.set.call(el, val); }
+    else { el.value = val; }
+    el.dispatchEvent(new Event('input', { bubbles: true }));
+}
+
+// UI state that must survive canvas re-renders (the HTML is replaced
+// wholesale every beat/turn, which would otherwise close panels and
+// reset the slot pills).
+window._vnUi = window._vnUi || { panel: null, slot: '0' };
+
+function restoreUiState() {
+    const screen = document.querySelector('.vn-screen');
+    if (!screen) return;
+    // Re-open the remembered panel
+    screen.querySelectorAll('.vn-panel').forEach(function(p) {
+        const isOpen = window._vnUi.panel && p.classList.contains(window._vnUi.panel);
+        p.classList.toggle('open', !!isOpen);
+        // The log is a full-session register — land on the newest entry.
+        if (isOpen && p.classList.contains('vn-panel-log')) {
+            p.scrollTop = p.scrollHeight;
+        }
+    });
+    // Re-mark the active slot pill
+    screen.querySelectorAll('.vn-slot-btn').forEach(function(s) {
+        s.classList.toggle('active', s.getAttribute('data-slot') === window._vnUi.slot);
+    });
+}
+
+function syncSaveStatus() {
+    const src = document.querySelector('#save-status-hidden');
+    const dst = document.querySelector('.vn-save-status');
+    if (!src || !dst) return;
+    const text = (src.textContent || '').trim();
+    // Write-only-if-different: setting textContent mutates childList and
+    // would re-trigger the observer in a loop otherwise.
+    if (dst.textContent !== text) { dst.textContent = text; }
+}
+
+// Mirror the hidden slot-rows HTML (refreshed by on_save) into the open
+// save panel, so slot descriptions update right after a save without a
+// full canvas re-render. The applied string is remembered as a JS property
+// (dst._mirrorHtml) — NOT compared against live innerHTML, which diverges
+// as soon as restoreUiState marks a row .active and would loop the
+// observer (assign → mutate → fire → assign…), freezing the page.
+function syncSlotRows() {
+    const src = document.querySelector('#slots-meta-hidden');
+    const dst = document.querySelector('.vn-panel-save .vn-slot-list');
+    if (!src || !dst) return;
+    const firstBtn = src.querySelector('.vn-slot-btn');
+    if (!firstBtn) return;          // mirror not populated yet
+    const html = firstBtn.parentElement.innerHTML;
+    if (dst._mirrorHtml !== html) {
+        dst._mirrorHtml = html;
+        dst.innerHTML = html;
+        restoreUiState();           // re-mark the active slot row
+    }
+}
+
+function togglePanel(panelClass) {
+    window._vnUi.panel = (window._vnUi.panel === panelClass) ? null : panelClass;
+    restoreUiState();
+}
+
+document.addEventListener('click', function(e) {
+    // ── Title screen ─────────────────────────────────────────
+    const opt = e.target.closest('.vn-title-opt');
+    if (opt) {
+        e.preventDefault();
+        document.querySelectorAll('.vn-title-opt').forEach(function(o) {
+            o.classList.toggle('active', o === opt);
+        });
+        setHiddenVal('#preset-box', opt.getAttribute('data-preset') || 'curated');
+        return;
+    }
+    const begin = e.target.closest('.vn-title-begin');
+    if (begin) {
+        e.preventDefault();
+        window._vnUi.panel = null;
+        // Sync the name input to the hidden Gradio textbox before starting
+        const nameInput = document.querySelector('.vn-title-name-input');
+        if (nameInput) setHiddenVal('#player-name-box', nameInput.value.trim() || 'Player');
+        const activeOpt = document.querySelector('.vn-title-opt.active');
+        const preset = activeOpt ? (activeOpt.getAttribute('data-preset') || 'curated') : 'curated';
+        if (preset === 'generated') {
+            // Generated → show the Cast Setup step; generation starts from its
+            // own button. (Curated has no setup — start immediately.)
+            document.body.classList.add('cast-setup-active');
+        } else {
+            // 150ms lets the preset input event reach the server first
+            setTimeout(function() { clickHidden('#start-btn-hidden'); }, 150);
+        }
+        return;
+    }
+
+    // ── Cast Setup step: Generate proceeds to design; Back returns to title ──
+    const csGo = e.target.closest('.vn-cs-go');
+    if (csGo) {
+        e.preventDefault();
+        // Read all card fields from the HTML and bridge them into hidden Gradio controls
+        document.querySelectorAll('.vn-cs-card').forEach(function(card) {
+            const idx = card.getAttribute('data-cs-idx');
+            const nameEl = card.querySelector('[data-cs-field="name"]');
+            const conceptEl = card.querySelector('[data-cs-field="concept"]');
+            const tagsEl = card.querySelector('[data-cs-field="tags"]');
+            if (nameEl) setHiddenVal('#cs-n-' + idx, nameEl.value || '');
+            if (conceptEl) setHiddenVal('#cs-c-' + idx, conceptEl.value || '');
+            if (tagsEl) setHiddenVal('#cs-t-' + idx, tagsEl.value || '');
+        });
+        // Read fast generation checkbox
+        const fastCb = document.querySelector('.vn-cs-fast-cb');
+        if (fastCb) {
+            // Look for the hidden Gradio checkbox's native input
+            const hiddenFast = document.querySelector('#cs-fast input[type="checkbox"]');
+            if (hiddenFast) {
+                hiddenFast.checked = fastCb.checked;
+                hiddenFast.dispatchEvent(new Event('change', { bubbles: true }));
+            }
+        }
+        // Hide cast setup, reveal the canvas
+        document.body.classList.remove('cast-setup-active');
+        // Fire the hidden Generate Cast button with a small delay for input propagation
+        setTimeout(function() { clickHidden('#generate-cast-btn'); }, 150);
+        return;
+    }
+    if (e.target.closest('.vn-cs-back')) {
+        e.preventDefault();
+        document.body.classList.remove('cast-setup-active');
+        return;
+    }
+
+    // ── Icon tray ────────────────────────────────────────────
+    const tray = e.target.closest('.vn-tray-btn');
+    if (tray) {
+        // Reset confirm/cancel live INSIDE the reset tray button
+        const confirmEl = e.target.closest('.vn-reset-confirm');
+        const cancelEl = e.target.closest('.vn-reset-cancel');
+        const trayWrap = document.querySelector('.vn-icon-tray');
+        e.preventDefault();
+        e.stopPropagation();
+        if (confirmEl) {
+            if (trayWrap) trayWrap.classList.remove('confirming');
+            window._vnUi.panel = null;
+            clickHidden('#reset-btn-hidden');
+            return;
+        }
+        if (cancelEl) {
+            if (trayWrap) trayWrap.classList.remove('confirming');
+            return;
+        }
+        const action = tray.getAttribute('data-action');
+        if (action === 'log')  togglePanel('vn-panel-log');
+        if (action === 'cast') togglePanel('vn-panel-cast');
+        if (action === 'save') togglePanel('vn-panel-save');
+        if (action === 'reset' && trayWrap) trayWrap.classList.toggle('confirming');
+        return;
+    }
+
+    // ── Panel close button (cast panel ✕) ────────────────────
+    const close = e.target.closest('.vn-panel-close');
+    if (close) {
+        e.preventDefault();
+        window._vnUi.panel = null;
+        restoreUiState();
+        return;
+    }
+
+    // ── Main-menu Load list ──────────────────────────────────
+    const mlOpen = e.target.closest('.vn-title-load');
+    if (mlOpen) {
+        e.preventDefault();
+        if (!mlOpen.classList.contains('disabled')) {
+            document.body.classList.add('menu-load-active');
+        }
+        return;
+    }
+    if (e.target.closest('.vn-ml-back')) {
+        e.preventDefault();
+        document.body.classList.remove('menu-load-active');
+        return;
+    }
+    const mlSlot = e.target.closest('.vn-menu-load .vn-slot-btn');
+    if (mlSlot) {
+        e.preventDefault();
+        if (mlSlot.getAttribute('data-empty') === '1') return;
+        window._vnUi.slot = mlSlot.getAttribute('data-slot') || '0';
+        setHiddenVal('#save-slot-hidden', window._vnUi.slot);
+        document.body.classList.remove('menu-load-active');
+        setWaiting(true);
+        setTimeout(function() { clickHidden('#menu-load-btn'); }, 150);
+        return;
+    }
+
+    // ── Save panel: slot rows + actions ─────────────────────
+    const slot = e.target.closest('.vn-slot-btn');
+    if (slot) {
+        e.preventDefault();
+        window._vnUi.slot = slot.getAttribute('data-slot') || '0';
+        restoreUiState();
+        setHiddenVal('#save-slot-hidden', window._vnUi.slot);
+        return;
+    }
+    const action = e.target.closest('.vn-save-action');
+    if (action) {
+        e.preventDefault();
+        const which = action.getAttribute('data-which');
+        if (which === 'save') {
+            // Bridge the in-panel save-name input to the hidden Gradio box
+            const nameEl = document.querySelector('.vn-save-name');
+            setHiddenVal('#save-name-box', nameEl ? nameEl.value.trim() : '');
+        }
+        clickHidden(which === 'save' ? '#save-btn-hidden' : '#load-btn-hidden');
+        return;
+    }
+
+    // ── Casting Review buttons ───────────────────────────────
+    const reviewConfirm = e.target.closest('.review-btn.confirm');
+    const reviewRedo    = e.target.closest('.review-btn.redo');
+    if (reviewConfirm || reviewRedo) {
+        e.preventDefault();
+        const promptEl = document.querySelector('#review-prompt-text');
+        if (promptEl) setHiddenVal('#casting-prompt-box', promptEl.value);
+        clickHidden(reviewConfirm ? '#casting-confirm-btn' : '#casting-redo-btn');
+        return;
+    }
+
+    // ── Click anywhere outside an open panel closes it ────────
+    const scr = e.target.closest('.vn-screen');
+    if (scr && window._vnUi.panel
+        && !e.target.closest('.vn-panel')
+        && !e.target.closest('.vn-icon-tray')) {
+        window._vnUi.panel = null;
+        restoreUiState();
+    }
+});
+
+// Escape closes any open panel
+document.addEventListener('keydown', function(e) {
+    if (e.key === 'Escape' && window._vnUi.panel) {
+        window._vnUi.panel = null;
+        restoreUiState();
+        const trayWrap = document.querySelector('.vn-icon-tray');
+        if (trayWrap) trayWrap.classList.remove('confirming');
+    }
+});
+"""
diff --git a/vn_contracts.py b/vn_contracts.py
new file mode 100644
index 0000000000000000000000000000000000000000..27a42406bf79d21d053ef471349c0d6d6d7f3039
--- /dev/null
+++ b/vn_contracts.py
@@ -0,0 +1,282 @@
+"""
+vn_contracts.py — Wave 0.5 freeze: data structures for the VN PoC.
+
+Every subagent codes against these shapes. Immutable where noted.
+"""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+# ── Standard expression set every cast member must have ──────────────
+# Every generated or curated character gets these 7 expressions.
+# The sprite-path map keys are these strings.
+STANDARD_EXPRESSIONS = [
+    "neutral", "smile", "laugh", "sad", "angry", "surprised", "embarrassed",
+]
+
+
+# ── Character / Cast ─────────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class Character:
+    """Immutable character identity — the soul of a cast member."""
+    name: str
+    identity_prompt: str              # e.g. "1girl, long silver hair, red eyes, ..."
+    seed: int                         # Anima seed for reproducibility
+    personality: str                  # 2-3 sentence personality for the LLM to use
+    voice_id: str                     # key into VoiceProvider voices
+    role: str = "student"             # narrative role: student, teacher, senpai, etc.
+
+
+@dataclass
+class CastMember:
+    """A locked character + their rendered expression sprites.
+
+    The expression_map is a dict: expr_name -> absolute or relative path to RGBA PNG.
+    Every member must have at least the STANDARD_EXPRESSIONS set.
+    """
+    character: Character
+    expression_map: dict[str, str] = field(default_factory=dict)
+    sprite_width: int = 512
+    sprite_height: int = 768
+
+    def get_sprite(self, expression: str) -> Optional[str]:
+        """Get the sprite path for a given expression. Falls back to neutral."""
+        if expression in self.expression_map:
+            return self.expression_map[expression]
+        return self.expression_map.get("neutral")
+
+    def has_expression(self, expression: str) -> bool:
+        return expression in self.expression_map
+
+
+def cast_to_dict(members: list["CastMember"]) -> dict[str, "CastMember"]:
+    """Build the name -> CastMember dict used by SceneState from the
+    list[CastMember] that the cast pipeline returns (frozen contract:
+    generate_cast(prefs) -> list[CastMember])."""
+    return {m.character.name: m for m in members}
+
+
+# ── Cast cards — serializable character snapshots keyed by hash ───────
+# A "cast card" is the full JSON form of a cast (identity + sprite paths),
+# written once per unique cast and referenced from saves by fingerprint, so
+# a save can be loaded from the main menu without an engine or a re-bake.
+
+def member_to_dict(member: "CastMember") -> dict:
+    c = member.character
+    return {
+        "name": c.name,
+        "identity_prompt": c.identity_prompt,
+        "seed": c.seed,
+        "personality": c.personality,
+        "voice_id": c.voice_id,
+        "role": c.role,
+        "expression_map": dict(member.expression_map),
+        "sprite_width": member.sprite_width,
+        "sprite_height": member.sprite_height,
+    }
+
+
+def member_from_dict(d: dict) -> "CastMember":
+    character = Character(
+        name=d["name"],
+        identity_prompt=d.get("identity_prompt", ""),
+        seed=d.get("seed", 0),
+        personality=d.get("personality", ""),
+        voice_id=d.get("voice_id", ""),
+        role=d.get("role", "student"),
+    )
+    return CastMember(
+        character=character,
+        expression_map=dict(d.get("expression_map", {})),
+        sprite_width=d.get("sprite_width", 512),
+        sprite_height=d.get("sprite_height", 768),
+    )
+
+
+def cast_fingerprint(cast: dict[str, "CastMember"]) -> str:
+    """Stable short hash of a cast's identity (name + prompt + seed per
+    member, order-independent). Saves reference their cast card by this."""
+    import hashlib
+    import json as _json
+    ident = sorted(
+        (m.character.name, m.character.identity_prompt, m.character.seed)
+        for m in cast.values()
+    )
+    blob = _json.dumps(ident, ensure_ascii=False)
+    return hashlib.sha1(blob.encode("utf-8")).hexdigest()[:12]
+
+
+# ── Scene state ──────────────────────────────────────────────────────
+
+@dataclass
+class AffectionFlag:
+    """A named binary flag for affection/like tracking."""
+    character_name: str
+    flag: str          # e.g. "first_meeting", "confided_in", "gave_gift"
+    value: bool = True
+
+
+@dataclass
+class SceneState:
+    """The full mutable state of a VN session.
+
+    Everything a scene turn needs: who's present, what's the mood,
+    what choices matter, where we are.
+    """
+    # Cast
+    cast: dict[str, CastMember] = field(default_factory=dict)   # name -> CastMember
+    present: list[str] = field(default_factory=list)             # which characters are on screen
+
+    # Scene
+    background: str = "classroom"    # key into BackgroundProvider
+    description: str = ""            # current scene narration text
+    dialogue: list[dict] = field(default_factory=list)  # [{"speaker","text","expression"}]
+    mood: str = "peaceful"           # current mood tag for music/atmosphere
+    expressions: dict[str, str] = field(default_factory=dict)  # char name -> current expression key
+
+    # Progression
+    turn: int = 0
+    choices: list[Choice] = field(default_factory=list)
+    affection_flags: list[AffectionFlag] = field(default_factory=list)
+    player_name: str = "Player"
+
+    # Save slot metadata
+    save_slot: Optional[int] = None
+    chapter: str = "Prologue"
+
+    def active_affection(self, character_name: str) -> list[str]:
+        """Get all affection flags set for a character."""
+        return [af.flag for af in self.affection_flags
+                if af.character_name == character_name and af.value]
+
+    def set_affection(self, character_name: str, flag: str):
+        """Set a named affection flag for a character."""
+        for af in self.affection_flags:
+            if af.character_name == character_name and af.flag == flag:
+                af.value = True
+                return
+        self.affection_flags.append(AffectionFlag(character_name, flag))
+
+    def has_affection(self, character_name: str, flag: str) -> bool:
+        return any(af.character_name == character_name
+                   and af.flag == flag and af.value
+                   for af in self.affection_flags)
+
+
+# ── Choice ────────────────────────────────────────────────────────────
+
+@dataclass
+class Choice:
+    """A player-facing choice in the VN."""
+    id: str                    # unique within the scene
+    text: str                  # displayed text
+    consequence: str = ""      # brief description of what happens (for the engine)
+    affection_flag: Optional[tuple[str, str]] = None  # (char_name, flag) if choice triggers affection
+    next_background: Optional[str] = None
+    next_mood: Optional[str] = None
+    expression_changes: dict[str, str] = field(default_factory=dict)  # char -> expression key
+
+
+# ── Tool results ─────────────────────────────────────────────────────
+
+@dataclass
+class ActionResult:
+    """Result of a VN tool execution."""
+    success: bool = True
+    message: str = ""
+    data: dict = field(default_factory=dict)
+
+
+# ── Save/Load ─────────────────────────────────────────────────────────
+
+@dataclass
+class SaveData:
+    """JSON-serializable snapshot for saving/loading.
+
+    The cast itself is NOT serialized (it's locked and immutable for the
+    session); only cast_names are stored so a load can sanity-check that
+    the save matches the current cast.
+    """
+    chapter: str
+    turn: int
+    background: str
+    mood: str
+    description: str
+    present: list[str]
+    cast_names: list[str]
+    dialogue_snapshot: list[dict]
+    affection_snapshot: list[tuple[str, str, bool]]
+    expressions: dict[str, str] = field(default_factory=dict)
+    choices_snapshot: list[dict] = field(default_factory=list)
+    player_name: str = "Player"
+    # Slot metadata (shown in the save/load UIs)
+    save_name: str = ""              # player-given save title
+    saved_at: str = ""               # local "YYYY-MM-DD HH:MM"
+    cast_hash: str = ""              # fingerprint of the cast card this save uses
+    log_text: str = ""               # full-session scene log (turns + player answers)
+
+    @classmethod
+    def from_scene(cls, scene: SceneState) -> "SaveData":
+        return cls(
+            chapter=scene.chapter,
+            turn=scene.turn,
+            background=scene.background,
+            mood=scene.mood,
+            description=scene.description,
+            present=list(scene.present),
+            cast_names=list(scene.cast.keys()),
+            dialogue_snapshot=list(scene.dialogue),
+            affection_snapshot=[(af.character_name, af.flag, af.value)
+                                for af in scene.affection_flags],
+            expressions=dict(scene.expressions),
+            choices_snapshot=[{
+                "id": c.id, "text": c.text, "consequence": c.consequence,
+                "affection_flag": list(c.affection_flag) if c.affection_flag else None,
+                "next_background": c.next_background,
+                "next_mood": c.next_mood,
+                "expression_changes": dict(c.expression_changes),
+            } for c in scene.choices],
+            player_name=scene.player_name,
+        )
+
+    def to_dict(self) -> dict:
+        from dataclasses import asdict
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "SaveData":
+        data = dict(data)
+        data["affection_snapshot"] = [tuple(t) for t in data.get("affection_snapshot", [])]
+        # Tolerate unknown keys so newer saves still open in older code.
+        from dataclasses import fields as _fields
+        allowed = {f.name for f in _fields(cls)}
+        return cls(**{k: v for k, v in data.items() if k in allowed})
+
+    def apply_to(self, scene: SceneState) -> SceneState:
+        """Restore this snapshot into an existing scene (cast is kept)."""
+        scene.chapter = self.chapter
+        scene.turn = self.turn
+        scene.background = self.background
+        scene.mood = self.mood
+        scene.description = self.description
+        scene.present = list(self.present)
+        scene.dialogue = list(self.dialogue_snapshot)
+        scene.affection_flags = [AffectionFlag(c, f, v)
+                                 for c, f, v in self.affection_snapshot]
+        scene.expressions = dict(self.expressions)
+        scene.player_name = self.player_name
+        scene.choices = []
+        for cd in self.choices_snapshot:
+            choice = Choice(
+                id=cd["id"], text=cd["text"],
+                consequence=cd.get("consequence", ""),
+                next_background=cd.get("next_background"),
+                next_mood=cd.get("next_mood"),
+                expression_changes=cd.get("expression_changes") or {},
+            )
+            if cd.get("affection_flag"):
+                choice.affection_flag = (cd["affection_flag"][0], cd["affection_flag"][1])
+            scene.choices.append(choice)
+        return scene
diff --git a/vn_engine.py b/vn_engine.py
new file mode 100644
index 0000000000000000000000000000000000000000..4ee0ebdb0a5fd953f92b992e50cb2ce90886778c
--- /dev/null
+++ b/vn_engine.py
@@ -0,0 +1,817 @@
+"""
+vn_engine.py — The VN tool loop.
+
+Wraps an LLM ModelClient and the locked cast. Processes player choices
+through the model, enforces cast-lock, and returns scene mutations.
+
+Architecture (same pattern as the DM):
+  1. Player makes a choice
+  2. Engine builds prompt with [STATE] banner + choice text
+  3. Sends to model
+  4. Parses [TOOL: ...] calls from response
+  5. Mutates SceneState accordingly
+  6. Returns (narration, updated_scene)
+"""
+from __future__ import annotations
+import json
+import re
+from typing import Optional
+
+import os
+
+from vn_contracts import (SceneState, CastMember, Choice, ActionResult,
+                          AffectionFlag, SaveData,
+                          member_to_dict, member_from_dict, cast_fingerprint)
+from vn_prompt import build_full_prompt, build_state_banner
+from model_client import ModelClient
+from trace_log import log_turn
+
+SAVE_DIR = os.path.join(os.path.dirname(__file__), "saves")
+CAST_DIR = os.path.join(SAVE_DIR, "cast")    # cast cards, keyed by fingerprint
+NUM_SLOTS = 5
+
+
+# ── Cast cards + slot metadata (module-level: usable without an engine) ──
+
+def save_cast_card(cast: dict[str, CastMember]) -> str:
+    """Persist the cast as a card under saves/cast/<hash>.json (idempotent —
+    the fingerprint covers identity, so an existing card is reused).
+    Returns the fingerprint."""
+    fp = cast_fingerprint(cast)
+    os.makedirs(CAST_DIR, exist_ok=True)
+    path = os.path.join(CAST_DIR, f"{fp}.json")
+    if not os.path.exists(path):
+        card = {"hash": fp,
+                "members": [member_to_dict(m) for m in cast.values()]}
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(card, f, ensure_ascii=False, indent=2)
+    return fp
+
+
+def load_cast_card(cast_hash: str) -> Optional[dict[str, CastMember]]:
+    """Rebuild a cast dict from its card. None if the card doesn't exist."""
+    path = os.path.join(CAST_DIR, f"{cast_hash}.json")
+    if not (cast_hash and os.path.exists(path)):
+        return None
+    with open(path, "r", encoding="utf-8") as f:
+        card = json.load(f)
+    members = [member_from_dict(d) for d in card.get("members", [])]
+    return {m.character.name: m for m in members} or None
+
+
+def read_save(slot: int, save_dir: Optional[str] = None) -> Optional[SaveData]:
+    """Read a slot's SaveData without an engine. None if the slot is empty
+    or unreadable."""
+    path = os.path.join(save_dir or SAVE_DIR, f"slot_{slot}.json")
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return SaveData.from_dict(json.load(f))
+    except (OSError, json.JSONDecodeError, TypeError):
+        return None
+
+
+def list_saves(save_dir: Optional[str] = None) -> list[dict]:
+    """Slot metadata for the save/load UIs — one entry per slot, in order.
+    Empty/unreadable slots get {"slot": i, "empty": True}."""
+    out = []
+    for i in range(NUM_SLOTS):
+        data = read_save(i, save_dir)
+        if data is None:
+            out.append({"slot": i, "empty": True})
+            continue
+        out.append({
+            "slot": i, "empty": False,
+            "name": data.save_name or "",
+            "chapter": data.chapter, "turn": data.turn,
+            "cast_names": list(data.cast_names),
+            "saved_at": data.saved_at or "",
+            "cast_hash": data.cast_hash or "",
+        })
+    return out
+
+# Expression -> voice emotion mapping (selective voicing of the emotional beat)
+_EXPRESSION_EMOTION = {
+    "neutral": "neutral", "smile": "happy", "laugh": "happy",
+    "sad": "sad", "angry": "angry", "surprised": "surprised",
+    "embarrassed": "embarrassed",
+}
+
+
+# ── Regex for parsing [TOOL: ...] calls ──────────────────────────────
+_TOOL_CALL_RE = re.compile(r'\[TOOL:')
+
+
+def _scan_balanced(text: str, start: int) -> int:
+    """Scan text from an opening bracket at `start` to its balanced close.
+
+    Honors JSON double-quoted strings (brackets inside them don't count)
+    and backslash escapes. Returns the index AFTER the closing bracket,
+    or -1 if unbalanced.
+    """
+    depth = 0
+    in_str = False
+    esc = False
+    for i in range(start, len(text)):
+        c = text[i]
+        if esc:
+            esc = False
+        elif c == '\\':
+            esc = True
+        elif in_str:
+            if c == '"':
+                in_str = False
+        elif c == '"':
+            in_str = True
+        elif c in '[{':
+            depth += 1
+        elif c in ']}':
+            depth -= 1
+            if depth == 0:
+                return i + 1
+    return -1
+
+
+def _parse_tool_args(args_str: str) -> dict:
+    """Parse `key=value` pairs from a tool-call argument string.
+
+    Values may be:
+      - 'single-quoted'  — if the value starts with [ or { (JSON), it is
+        scanned bracket-aware so apostrophes inside JSON strings (e.g.
+        "I've") do NOT terminate the value; otherwise scans to the next '.
+      - "double-quoted"  — scans to the closing quote, honoring \\" escapes
+        (apostrophes inside are fine).
+      - bare             — integer or word.
+    """
+    result: dict = {}
+    i, n = 0, len(args_str)
+    key_re = re.compile(r'(\w+)\s*=\s*')
+
+    while i < n:
+        while i < n and args_str[i].isspace():
+            i += 1
+        m = key_re.match(args_str, i)
+        if not m:
+            break
+        key = m.group(1)
+        i = m.end()
+        if i >= n:
+            result[key] = ""
+            break
+
+        ch = args_str[i]
+        if ch == "'":
+            i += 1
+            if i < n and args_str[i] in '[{':
+                end = _scan_balanced(args_str, i)
+                if end == -1:
+                    result[key] = args_str[i:]
+                    break
+                result[key] = args_str[i:end]
+                i = end
+                if i < n and args_str[i] == "'":
+                    i += 1
+            else:
+                # Plain single-quoted value. A bare apostrophe inside the
+                # value (e.g. character='O'Brien') must NOT end it. Treat a
+                # quote as the closing delimiter only when it is followed by
+                # end-of-args or by the next key (whitespace* + word + '=').
+                # Otherwise it is a literal apostrophe; keep scanning.
+                j = i
+                while True:
+                    j = args_str.find("'", j)
+                    if j == -1:
+                        result[key] = args_str[i:]
+                        i = n
+                        break
+                    if re.match(r"\s*(\w+\s*=|$)", args_str[j + 1:]):
+                        result[key] = args_str[i:j]
+                        i = j + 1
+                        break
+                    j += 1  # apostrophe inside the value
+        elif ch == '"':
+            i += 1
+            buf = []
+            esc = False
+            while i < n:
+                c = args_str[i]
+                if esc:
+                    buf.append(c)
+                    esc = False
+                elif c == '\\':
+                    esc = True
+                elif c == '"':
+                    break
+                else:
+                    buf.append(c)
+                i += 1
+            result[key] = "".join(buf)
+            i += 1  # past the closing quote
+        elif ch in '[{':
+            # Bare (unquoted) JSON value, e.g. choices=[{...}]. Some models
+            # omit the single-quote wrapper the prompt asks for; scan the
+            # balanced blob just as we do for the quoted-JSON case.
+            end = _scan_balanced(args_str, i)
+            if end == -1:
+                result[key] = args_str[i:]
+                i = n
+            else:
+                result[key] = args_str[i:end]
+                i = end
+        else:
+            m2 = re.match(r'(\d+)|(\w+)', args_str[i:])
+            if not m2:
+                i += 1
+                continue
+            if m2.group(1) is not None:
+                result[key] = int(m2.group(1))
+            else:
+                result[key] = m2.group(2)
+            i += m2.end()
+
+    return result
+
+
+def parse_tool_calls(response: str) -> list[dict]:
+    """Extract ALL tool calls from the model's response.
+
+    Supports [TOOL: name key="value" key='[json]' key=123 key=word] format.
+    Robust to apostrophes in dialogue/JSON text ("I've", "don't") — the
+    end-of-call scanner tracks only double-quoted strings (with escapes)
+    and bracket depth, never single quotes.
+
+    Returns a list of dicts with keys:
+      - "tool": the tool name
+      - any parsed keyword arguments
+    """
+    calls = []
+    for m in _TOOL_CALL_RE.finditer(response):
+        start = m.end()
+        # Find the matching closing bracket: depth starts at 1 ([TOOL:).
+        # Double-quoted strings are skipped (escape-aware); single quotes
+        # are NOT treated as string delimiters here — apostrophes in prose
+        # would corrupt the state.
+        depth = 1
+        in_str = False
+        esc = False
+        end_pos = -1
+
+        for i in range(start, len(response)):
+            ch = response[i]
+            if esc:
+                esc = False
+                continue
+            if ch == '\\':
+                esc = True
+                continue
+            if in_str:
+                if ch == '"':
+                    in_str = False
+                continue
+            if ch == '"':
+                in_str = True
+            elif ch == '[':
+                depth += 1
+            elif ch == ']':
+                depth -= 1
+                if depth == 0:
+                    end_pos = i
+                    break
+
+        if end_pos == -1:
+            continue  # Malformed tool call, skip
+
+        # Extract the content between [TOOL: and the matching ]
+        inner = response[m.end():end_pos].strip()
+
+        # First token is the tool name
+        space_idx = inner.find(' ')
+        if space_idx == -1:
+            tool_name = inner
+            args_str = ""
+        else:
+            tool_name = inner[:space_idx]
+            args_str = inner[space_idx + 1:].strip()
+
+        result = {"tool": tool_name}
+        if args_str:
+            result.update(_parse_tool_args(args_str))
+
+        calls.append(result)
+
+    return calls
+
+
+# ── Cast-lock enforcement ────────────────────────────────────────────
+
+def _check_cast_lock(character_name: str, cast: dict[str, CastMember]) -> Optional[str]:
+    """Validate a character name against the locked cast.
+
+    Returns the canonical name (properly cased) if found,
+    or None if the character doesn't exist in the cast.
+    """
+    # Direct match
+    if character_name in cast:
+        return character_name
+
+    # Case-insensitive match
+    for name in cast:
+        if name.lower() == character_name.lower():
+            return name
+
+    return None
+
+
+def _find_cast_violations(response: str, cast: dict[str, CastMember]) -> list[str]:
+    """Find non-cast character names used as dialogue speakers.
+
+    We look for the [character_name]: pattern in dialogue lines.
+    Returns the list of violating names (deduped, in order of appearance).
+    """
+    dialogue_refs = re.findall(r'\[(\w+)\]:\s*"', response)
+    violations = []
+    for ref in dialogue_refs:
+        if not _check_cast_lock(ref, cast) and ref not in violations:
+            violations.append(ref)
+    return violations
+
+
+def _repair_cast_violation(response: str, cast: dict[str, CastMember]) -> str:
+    """Check a model response for non-cast character names and flag them.
+
+    Returns the response with violations flagged via [CAST-LOCK VIOLATION].
+    Does NOT stop execution — just flags for the engine to handle.
+    """
+    violations = _find_cast_violations(response, cast)
+    if not violations:
+        return response
+
+    # Append violation warning
+    violation_msg = (
+        "\n\n[CAST-LOCK VIOLATION: The following character names are not in the "
+        f"locked cast and will be ignored: {', '.join(violations)}. "
+        "Only use characters from the cast list.]"
+    )
+    return response + violation_msg
+
+
+def _clean_noncast_dialogue(response: str, cast: dict[str, CastMember]) -> str:
+    """Remove dialogue lines from non-cast characters.
+
+    If a line is tagged with a character not in the cast, strip that line.
+    This is the enforcement mechanism — the model CANNOT speak through
+    a character that doesn't have a sprite.
+    """
+    lines = response.split("\n")
+    cleaned = []
+    for line in lines:
+        m = re.match(r'^\[(\w+)\]:', line)
+        if m:
+            char_name = m.group(1)
+            if not _check_cast_lock(char_name, cast):
+                # Replace with a narration mention instead
+                cleaned.append(f"*(someone speaks)*")
+                continue
+        cleaned.append(line)
+    return "\n".join(cleaned)
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# Tool handlers
+# ═══════════════════════════════════════════════════════════════════════
+
+def _handle_advance_scene(tool_data: dict, scene: SceneState) -> ActionResult:
+    """Handle advance_scene tool call.
+
+    Mutates scene: background, mood, description, present characters.
+    """
+    description = tool_data.get("description", "")
+    background = tool_data.get("background", scene.background)
+    mood = tool_data.get("mood", scene.mood)
+
+    if description:
+        scene.description = description
+    scene.background = background
+    scene.mood = mood
+
+    return ActionResult(
+        success=True,
+        message=f"Scene advanced: {background} ({mood})",
+        data={"background": background, "mood": mood},
+    )
+
+
+def _handle_set_background(tool_data: dict, scene: SceneState) -> ActionResult:
+    """Handle set_background tool call.
+
+    Changes only the background — narration/mood untouched.
+    """
+    background = tool_data.get("background", "")
+    if not background:
+        return ActionResult(success=False, message="set_background: no background key given")
+
+    scene.background = background
+    return ActionResult(
+        success=True,
+        message=f"Background set: {background}",
+        data={"background": background},
+    )
+
+
+def _handle_set_expression(tool_data: dict, scene: SceneState, cast: dict[str, CastMember]) -> ActionResult:
+    """Handle set_expression tool call.
+
+    Validates that the character exists and the expression is valid,
+    then records it as the character's current expression in scene state.
+    """
+    char_name = tool_data.get("character", "")
+    expression = tool_data.get("expression", "")
+
+    canonical = _check_cast_lock(char_name, cast)
+    if not canonical:
+        return ActionResult(
+            success=False,
+            message=f"Cast-lock violation: '{char_name}' is not in the cast. Ignored.",
+        )
+
+    if expression not in cast[canonical].expression_map:
+        return ActionResult(
+            success=False,
+            message=f"Expression '{expression}' not available for {canonical}. Available: {list(cast[canonical].expression_map.keys())}",
+        )
+
+    scene.expressions[canonical] = expression
+    return ActionResult(
+        success=True,
+        message=f"Expression set: {canonical} -> {expression}",
+        data={"character": canonical, "expression": expression},
+    )
+
+
+def _handle_enter_character(tool_data: dict, scene: SceneState, cast: dict[str, CastMember]) -> ActionResult:
+    """Handle enter_character tool call.
+
+    Validates cast-lock, then appends to scene.present if not already present.
+    """
+    char_name = tool_data.get("character", "")
+
+    canonical = _check_cast_lock(char_name, cast)
+    if not canonical:
+        return ActionResult(
+            success=False,
+            message=f"Cast-lock violation: '{char_name}' is not in the cast. Ignored.",
+        )
+
+    if canonical not in scene.present:
+        scene.present.append(canonical)
+    return ActionResult(
+        success=True,
+        message=f"{canonical} entered the scene",
+        data={"character": canonical, "present": "enter"},
+    )
+
+
+def _handle_exit_character(tool_data: dict, scene: SceneState, cast: dict[str, CastMember]) -> ActionResult:
+    """Handle exit_character tool call.
+
+    Removes from scene.present. No-op if not present.
+    """
+    char_name = tool_data.get("character", "")
+
+    canonical = _check_cast_lock(char_name, cast)
+    if not canonical:
+        return ActionResult(
+            success=False,
+            message=f"Cast-lock violation: '{char_name}' is not in the cast. Ignored.",
+        )
+
+    if canonical in scene.present:
+        scene.present.remove(canonical)
+    return ActionResult(
+        success=True,
+        message=f"{canonical} exited the scene",
+        data={"character": canonical, "present": "exit"},
+    )
+
+
+def _loads_lenient(blob: str):
+    """json.loads with a best-effort repair for common model deviations.
+
+    Weaker models emit loosely-formatted JSON — most often unquoted object
+    keys (`{id: 1, text: ...}` instead of `{"id": 1, "text": ...}`). Try a
+    strict parse first; on failure, quote bare keys and retry. Raises
+    json.JSONDecodeError if even the repaired form is unparseable.
+    """
+    try:
+        return json.loads(blob)
+    except json.JSONDecodeError:
+        # Quote bare object keys following '{' or ','. The lookbehind anchor
+        # (a brace/comma + optional space) keeps us from touching colons that
+        # live inside string values like "go to the cafe: now".
+        repaired = re.sub(r'([{,]\s*)([A-Za-z_]\w*)(\s*:)', r'\1"\2"\3', blob)
+        return json.loads(repaired)
+
+
+def _handle_offer_choices(tool_data: dict, scene: SceneState) -> ActionResult:
+    """Handle offer_choices tool call.
+
+    Parses the choices JSON and sets them on the scene state. Tolerates the
+    loose JSON weaker models tend to emit (unquoted keys, numeric ids).
+    """
+    choices_json = tool_data.get("choices", "")
+    if not choices_json:
+        return ActionResult(success=False, message="No choices provided")
+
+    try:
+        choices_data = _loads_lenient(choices_json)
+    except json.JSONDecodeError:
+        return ActionResult(success=False, message="Invalid choices JSON")
+
+    if not isinstance(choices_data, list):
+        return ActionResult(success=False, message="choices must be a JSON array")
+
+    choices = []
+    for cd in choices_data:
+        if not isinstance(cd, dict):
+            continue
+        choice = Choice(
+            # ids are matched against the player's click (a string), so coerce
+            # numeric ids like {"id": 1} to "1" — otherwise 1 == "1" is False.
+            id=str(cd.get("id", f"c_{len(choices)}")),
+            text=cd.get("text", ""),
+            consequence=cd.get("consequence", ""),
+            next_background=cd.get("next_background"),
+            next_mood=cd.get("next_mood"),
+            expression_changes=cd.get("expression_changes", {}),
+        )
+        # Affection flag if present
+        if "affection_flag" in cd:
+            flag_data = cd["affection_flag"]
+            if isinstance(flag_data, list) and len(flag_data) == 2:
+                choice.affection_flag = (flag_data[0], flag_data[1])
+        choices.append(choice)
+
+    scene.choices = choices
+    return ActionResult(
+        success=True,
+        message=f"Offered {len(choices)} choices",
+        data={"choice_count": len(choices)},
+    )
+
+
+def _handle_save_checkpoint(tool_data: dict, scene: SceneState) -> ActionResult:
+    """Handle save_checkpoint tool call.
+
+    Marks the scene for auto-save (no-op in engine, UI handles actual serialization).
+    """
+    scene.save_slot = 0  # auto-save slot
+    return ActionResult(success=True, message="Checkpoint saved")
+
+
+# ── Tool router ──────────────────────────────────────────────────────
+
+_TOOL_HANDLERS = {
+    "advance_scene": _handle_advance_scene,
+    "set_background": _handle_set_background,
+    "set_expression": _handle_set_expression,
+    "enter_character": _handle_enter_character,
+    "exit_character": _handle_exit_character,
+    "offer_choices": _handle_offer_choices,
+    "save_checkpoint": _handle_save_checkpoint,
+}
+
+
+def _route_tool(tool_data: dict, scene: SceneState, cast: dict[str, CastMember]) -> ActionResult:
+    """Route a tool call to the appropriate handler."""
+    tool_name = tool_data.get("tool", "")
+    handler = _TOOL_HANDLERS.get(tool_name)
+    if not handler:
+        return ActionResult(success=False, message=f"Unknown tool: {tool_name}")
+
+    # Different handlers need different signatures
+    cast_tools = ("set_expression", "enter_character", "exit_character")
+    if tool_name in cast_tools:
+        return handler(tool_data, scene, cast)
+    return handler(tool_data, scene)
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# VN Engine
+# ═══════════════════════════════════════════════════════════════════════
+
+class VNEngine:
+    """The VN tool loop.
+
+    Wraps a ModelClient and a locked cast. Processes player choices
+    through the model, enforces cast-lock, and returns scene mutations.
+
+    Usage:
+        engine = VNEngine(model=my_client, cast=my_cast, scene=initial_scene)
+        narration, updated_scene = engine.run_turn("I choose to talk to Yuki")
+    """
+
+    def __init__(self, model: ModelClient, cast: dict[str, CastMember],
+                 scene: SceneState, voice=None):
+        """
+        Args:
+            model: Any ModelClient (real or mock).
+            cast: The locked cast (name -> CastMember).
+            scene: Initial scene state.
+            voice: Optional VoiceProvider for selective voicing of key
+                   emotional lines. None disables voicing.
+        """
+        self.model = model
+        self.cast = cast
+        self.scene = scene
+        self.voice = voice
+        self.last_voice = None  # VoiceLine of the most recent voiced beat (or None)
+
+    def run_turn(self, player_choice_text: str) -> tuple[str, SceneState]:
+        """Run one VN turn.
+
+        1. Build prompt with [STATE] banner + choice text
+        2. Send to model
+        3. Parse tool calls from response
+        4. Route each tool call to mutate scene
+        5. Enforce cast-lock
+        6. Return (narration, updated_scene)
+
+        Args:
+            player_choice_text: The choice text the player selected.
+
+        Returns:
+            (narration_text, updated_scene_state)
+        """
+        # 0. The previous turn's choices are consumed by making one
+        self.scene.choices = []
+
+        # 1. Build prompt
+        system, user = build_full_prompt(self.scene, self.cast, player_choice_text,
+                                         player_name=self.scene.player_name)
+
+        # Also inject the current scene description for context
+        if self.scene.description:
+            user = f"Current scene: {self.scene.description}\n\n{user}"
+
+        messages = [
+            {"role": "system", "content": system},
+            {"role": "user", "content": user},
+        ]
+
+        # 2. Send to model
+        response = self.model.generate(messages) or ""
+
+        # 3. Cast-lock check — detect violations BEFORE cleaning removes them
+        violations = _find_cast_violations(response, self.cast)
+
+        # Trace the raw prompt→response for fine-tuning (real models only;
+        # mock/scripted output is skipped). Best-effort, never raises.
+        if not getattr(self.model, "is_mock", False):
+            log_turn(
+                messages, response,
+                model=getattr(getattr(self.model, "cfg", None), "model", ""),
+                context={
+                    "turn": self.scene.turn,
+                    "scene": self.scene.description,
+                    "mood": self.scene.mood,
+                    "present": list(self.scene.present),
+                    "player_input": player_choice_text,
+                    "cast_violations": violations,
+                },
+            )
+
+        # 4. Parse tool calls
+        tool_calls = parse_tool_calls(response)
+
+        # 5. Route tool calls (in order)
+        tool_results = []
+        for tc in tool_calls:
+            result = _route_tool(tc, self.scene, self.cast)
+            tool_results.append(result)
+
+        # 6. Clean non-cast dialogue from the response (enforcement),
+        #    then surface the violation as an engine note so it is visible
+        #    in the transcript and in the next prompt's history.
+        narration = _clean_noncast_dialogue(response, self.cast)
+        if violations:
+            narration += (
+                "\n\n[Engine: CAST-LOCK removed non-cast speaker(s): "
+                f"{', '.join(violations)}]"
+            )
+
+        # If there were tool results, append failures as engine notes
+        engine_notes = []
+        for tr in tool_results:
+            if not tr.success:
+                engine_notes.append(f"[Engine: {tr.message}]")
+
+        if engine_notes:
+            narration += "\n\n" + "\n".join(engine_notes)
+
+        # 7. Record dialogue lines into scene state
+        for m in re.finditer(r'^\[(\w+)\]:\s*"([^"]*)"', narration, re.MULTILINE):
+            speaker = _check_cast_lock(m.group(1), self.cast)
+            if speaker:
+                self.scene.dialogue.append({
+                    "speaker": speaker,
+                    "text": m.group(2),
+                    "expression": self.scene.expressions.get(speaker, "neutral"),
+                })
+
+        # 8. Selective voicing — voice the key emotional beat of this turn:
+        #    the first dialogue line spoken by a character whose expression
+        #    changed during this turn (per shipped-VN convention, not full voicing).
+        self.last_voice = None
+        if self.voice is not None:
+            changed = {tr.data["character"] for tr in tool_results
+                       if tr.success and "expression" in tr.data}
+            for m in re.finditer(r'^\[(\w+)\]:\s*"([^"]*)"', narration, re.MULTILINE):
+                speaker = _check_cast_lock(m.group(1), self.cast)
+                if speaker and speaker in changed and m.group(2).strip():
+                    expr = self.scene.expressions.get(speaker, "neutral")
+                    emotion = _EXPRESSION_EMOTION.get(expr, "neutral")
+                    try:
+                        self.last_voice = self.voice.speak(
+                            m.group(2), speaker, emotion=emotion,
+                            voice_id=self.cast[speaker].character.voice_id,
+                        )
+                    except TypeError:
+                        # Provider without voice_id kwarg (older interface)
+                        self.last_voice = self.voice.speak(m.group(2), speaker, emotion=emotion)
+                    except Exception as e:
+                        print(f"[engine] voice failed: {e}")
+                    break
+
+        # 9. Increment turn
+        self.scene.turn += 1
+
+        return narration, self.scene
+
+    def apply_choice_effects(self, choice: Choice):
+        """Apply the effects of a player-selected choice.
+
+        Mutates scene state: background, mood, affection flags, expressions.
+
+        Args:
+            choice: The Choice the player picked.
+        """
+        if choice.next_background:
+            self.scene.background = choice.next_background
+        if choice.next_mood:
+            self.scene.mood = choice.next_mood
+        if choice.affection_flag:
+            char_name, flag = choice.affection_flag
+            self.scene.set_affection(char_name, flag)
+        for char_name, expr in (choice.expression_changes or {}).items():
+            canonical = _check_cast_lock(char_name, self.cast)
+            if canonical and expr in self.cast[canonical].expression_map:
+                self.scene.expressions[canonical] = expr
+
+    # ── Save / Load ──────────────────────────────────────────────────
+
+    def save(self, slot: int = 0, save_dir: Optional[str] = None,
+             save_name: str = "", log_text: str = "") -> str:
+        """Serialize the current scene to a JSON save slot.
+
+        Also writes the cast card (saves/cast/<hash>.json) and stamps the
+        save with its fingerprint, a player-given name, and the local time —
+        so the slot can be described in the UI and loaded from the main menu.
+        Returns the path of the written save file.
+        """
+        save_dir = save_dir or SAVE_DIR
+        os.makedirs(save_dir, exist_ok=True)
+        path = os.path.join(save_dir, f"slot_{slot}.json")
+        data = SaveData.from_scene(self.scene)
+        data.save_name = (save_name or "").strip()[:48]
+        from datetime import datetime
+        data.saved_at = datetime.now().strftime("%Y-%m-%d %H:%M")
+        data.cast_hash = save_cast_card(self.scene.cast)
+        data.log_text = log_text or ""
+        self.scene.save_slot = slot
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(data.to_dict(), f, ensure_ascii=False, indent=2)
+        return path
+
+    def load(self, slot: int = 0, save_dir: Optional[str] = None) -> SceneState:
+        """Restore scene state from a JSON save slot (cast stays locked).
+
+        Raises FileNotFoundError if the slot doesn't exist.
+        """
+        save_dir = save_dir or SAVE_DIR
+        path = os.path.join(save_dir, f"slot_{slot}.json")
+        with open(path, "r", encoding="utf-8") as f:
+            data = SaveData.from_dict(json.load(f))
+        data.apply_to(self.scene)
+        self.scene.save_slot = slot
+        return self.scene
+
+    def reset_scene(self) -> SceneState:
+        """Reset the scene to a fresh state with the same cast."""
+        self.scene = SceneState(
+            cast=self.cast,
+            present=[],
+            background="classroom",
+            mood="peaceful",
+            turn=0,
+            chapter="Prologue",
+        )
+        return self.scene
diff --git a/vn_prompt.py b/vn_prompt.py
new file mode 100644
index 0000000000000000000000000000000000000000..a970099ddfca3fc62d141484fdbce7b8020a9055
--- /dev/null
+++ b/vn_prompt.py
@@ -0,0 +1,239 @@
+"""
+vn_prompt.py — System prompt for the VN story generation model.
+
+Frozen at Wave 0.5. Every subagent that calls the LLM uses this prompt.
+
+The [STATE] banner is appended dynamically each turn with current scene data.
+"""
+from __future__ import annotations
+
+VN_SYSTEM_PROMPT = """You are the narrator of a Japanese-style anime visual novel — a slice-of-life romance set in a high school. Your tone is warm, emotionally perceptive, and gently dramatic. You write natural dialogue, believable character reactions, and choices that carry emotional weight.
+
+## THE CAST (locked — immutable)
+
+The following characters exist in this story. They are the ENTIRE cast. You may NEVER introduce a new character who does not have a sprite. Every line of dialogue, every reaction, every named character must be one of these:
+
+{cast_descriptions}
+
+## THE PLAYER
+
+The player is named {player_name}. They are the protagonist — the characters speak to them directly, react to their choices, and form relationships with them. The player is not a sprite; they are the first-person perspective of the story. When characters address the player, use direct address or "you" naturally. Do not give the player a physical description unless the user explicitly provides one.
+
+## CAST-LOCK RULE — STRICT ENFORCEMENT
+
+This is the most important rule: you may ONLY reference characters listed above. If you want a character to react, speak, or appear, they must already be in the cast. Never invent a new classmate, teacher, family member, or stranger without an existing sprite. If the story needs an unnamed background presence (crowd noise, distant voice), use "someone" or a generic description — never give them a name or personality.
+
+## YOUR TOOLS
+
+You have the following tools to control the VN. Call them using the exact format shown. You may call multiple tools at the start or end of your response.
+
+1. **advance_scene** — Describe the scene setting and general atmosphere.
+   `[TOOL: advance_scene description="<vivid scene description>" background="<key>" mood="<mood_tag>"]`
+
+2. **set_background** — Change only the background (when the place shifts but the scene continues).
+   `[TOOL: set_background background="<key>"]`
+
+3. **set_expression** — Change a character's expression.
+   `[TOOL: set_expression character="<name>" expression="<expression_key>"]`
+   Valid expressions: neutral, smile, laugh, sad, angry, surprised, embarrassed
+
+4. **enter_character** — Bring a character onto the screen. Call this the first time a character appears or when they re-enter mid-scene. Characters NOT in the present list do not render.
+   `[TOOL: enter_character character="<name>"]`
+
+5. **exit_character** — Remove a character from the screen. Call this when a character leaves the scene.
+   `[TOOL: exit_character character="<name>"]`
+
+6. **offer_choices** — Present the player with a set of choices.
+   `[TOOL: offer_choices choices="<json array of {{id, text, consequence}}>"]`
+   Each choice must have a unique id and display text. Consequence is the engine note.
+
+5. **save_checkpoint** — Auto-save the current state.
+   `[TOOL: save_checkpoint]`
+
+## RESPONSE FORMAT
+
+Your response is a VN scene. It follows this structure:
+
+1. **Narration** — Describe the setting, what's happening, the atmosphere. Keep each narration beat SHORT: at most 2 sentences before a dialogue line or another beat. Show don't tell, with one or two sensory details (cherry blossoms past the window, the distant school bell, afternoon light through the blinds). Do not write long paragraphs — the dialogue box is small; break longer description across multiple short beats.
+
+2. **Dialogue** — If characters are speaking, write their dialogue tagged with their name:
+   `[character_name]: "Their dialogue here."`
+
+3. **Expression changes** — Call set_expression when a character's emotions shift mid-scene. This is the VN's key emotional lever — a well-timed expression change makes the scene feel alive.
+
+4. **Choices** — End the scene with offer_choices to let the player decide what happens next.
+
+5. **Background changes** — Call advance_scene with a new background when the setting shifts.
+
+## THE SCENE TURN BEAT
+
+The most important moment in the VN is the scene turn. When the player makes a choice, the world should respond visibly:
+- The background changes if appropriate (call advance_scene with new background/mood)
+- The character reacts (call set_expression — their face should reflect their response)
+- The mood shifts if appropriate (update the mood tag)
+- Write the character's reaction as voiced dialogue with emotional weight
+
+This is the VN's soul beat. Make it count every time.
+
+## EXPRESSION TIMING
+
+Expression changes are the VN's emotional punctuation. Change them at moments of emotional impact:
+- A character hears unexpected news → surprised
+- A character receives a compliment → embarrassed or smile
+- A character remembers something sad → sad
+- A character gets frustrated → angry
+- A happy moment → laugh or smile
+
+Don't spam expression changes. One or two per scene turn, placed at the emotional pivot, is ideal.
+
+## CHARACTER ENTERING AND EXITING
+
+Characters start the scene off-screen (not present). Use **enter_character** when they first appear or walk into the scene. Use **exit_character** when they leave. A character must be on screen to speak or be seen — if they're not in `present`, their sprite doesn't render. You do NOT need to enter_character for characters already present (check [STATE] banner for who's present).
+
+## MOOD TAGS
+
+Available moods: peaceful, cheerful, romantic, melancholic, tense, playful, bittersweet, cozy
+
+## BACKGROUND KEYS
+
+Available backgrounds (call advance_scene with one of these):
+`classroom` — A typical Japanese high school classroom
+`hallway` — School corridor with lockers
+`rooftop` — School rooftop with view of the city
+`courtyard` — School courtyard with cherry blossom trees
+`cafe` — A cozy café near the school
+`park` — A city park with benches and trees
+`library` — The school library, quiet and book-scented
+`home_room` — A character's bedroom
+`gate` — The school gate at the end of the day
+`sunset_hill` — A hill overlooking the city at sunset
+
+## IMPORTANT CONSTRAINTS
+
+- Cast-lock: NEVER invent a character who isn't in the cast list above.
+- Call tools at the START or END of your response (not in the middle of narration).
+- Each tool call on its own line, wrapped in [TOOL: ...] brackets.
+- End each response with either continuing narration or choices — the player should always have something to react to.
+- Write in the style of a slice-of-life anime: warm, character-focused, with emotional depth beneath everyday moments.
+"""
+
+VN_SYSTEM_PROMPT_SHORT = """You're an anime visual novel narrator. Write slice-of-life/romance scenes for the locked cast below. NEVER invent new characters.
+
+CAST (locked):
+{cast_descriptions}
+
+PLAYER: {player_name} is the protagonist. Characters address them directly.
+
+Tools available (use [TOOL: name args=val] format):
+- advance_scene description="..." background="key" mood="tag"
+- set_background background="key"
+- set_expression character="name" expression="key"
+- enter_character character="name"
+- exit_character character="name"
+- offer_choices choices='[{"id":"a","text":"...","consequence":"..."}]'
+- save_checkpoint
+
+Expressions: neutral, smile, laugh, sad, angry, surprised, embarrassed
+Moods: peaceful, cheerful, romantic, melancholic, tense, playful, bittersweet, cozy
+Backgrounds: classroom, hallway, rooftop, courtyard, cafe, park, library, home_room, gate, sunset_hill
+
+Rules:
+- Cast-lock: can only use characters listed above. No new characters.
+- Expression timing: change at emotional pivots, not randomly. 1-2 per scene.
+- Scene turn: on choice, change bg + expression + mood to show the world reacts.
+- Write warm, character-focused, emotionally perceptive narration.
+- End with either narration or choices — always give the player something to react to.
+"""
+
+
+CHARACTER_DESIGNER_PROMPT = """You design anime visual novel characters. Given a character name and a short concept phrase, you output the character's visual design as danbooru tags plus a personality.
+
+Respond with STRICT JSON only — no prose, no markdown fences:
+{"gender": "girl" or "boy", "tags": "<danbooru appearance tags>", "personality": "<2-3 sentence personality for a story engine>", "role": "<1-3 word narrative role>"}
+
+TAG RULES (important):
+- 12 to 22 comma-separated danbooru-style appearance tags.
+- Tags must start with "1girl" or "1boy".
+- Describe ONLY the character: hair (color, length, style), eye color, skin, build, clothing (school uniform variant, casual wear, accessories), and one or two aura/mood words.
+- You MAY include one or two body-attitude tags that fit the personality (e.g. hand on hip, arms crossed, hands behind back, head tilt, hands in pockets) — VN sprites usually stand at a slight angle with a characterful stance, not dead-frontal.
+- Plain comma-separated tags ONLY. Do NOT use weighted syntax like (tag:1.2) — weighting is unreliable on this model.
+- DO NOT include framing, camera, expression, or background tags (e.g. upper body, full body, portrait, profile, from behind, looking at viewer, simple background) — the pipeline locks those automatically.
+- Slice-of-life school setting: prefer school uniforms unless the concept says otherwise.
+- Eye and hair color are a must in every design. Vary them across characters to help visual distinction.
+Design sensibly from the concept: "childhood friend" suggests warm and approachable (e.g. brown hair, medium hair, ahoge, bright eyes, cheerful aura); "cool senpai" suggests tall, sharp eyes, composed; "shy bookworm" suggests glasses, long bangs, cardigan, timid aura. Invent a coherent, distinctive design — vary hair colors across requests when plausible.
+"""
+
+
+def build_cast_descriptions(cast: dict) -> str:
+    """Build the cast-description block for the system prompt.
+
+    Args:
+        cast: dict[str, CastMember] — the locked cast.
+
+    Returns:
+        Formatted string for insertion into the system prompt.
+    """
+    lines = []
+    for name, member in sorted(cast.items()):
+        char = member.character
+        lines.append(f"- {char.name} ({char.role}): {char.personality}")
+    return "\n".join(lines)
+
+
+def build_state_banner(scene) -> str:
+    """Build a compact [STATE] banner for the current VN scene.
+
+    Args:
+        scene: SceneState instance.
+
+    Returns:
+        Formatted [STATE] banner string.
+    """
+    from vn_contracts import SceneState
+
+    lines = ["[STATE]"]
+    lines.append(f"Chapter: {scene.chapter} · Turn: {scene.turn}")
+    lines.append(f"Player: {scene.player_name}")
+    lines.append(f"Background: {scene.background} · Mood: {scene.mood}")
+    lines.append(f"Present: {', '.join(scene.present) if scene.present else '(none)'}")
+
+    if scene.expressions:
+        expr_parts = [f"{name}: {expr}" for name, expr in scene.expressions.items()
+                      if name in scene.cast]
+        if expr_parts:
+            lines.append("Expressions: " + " | ".join(expr_parts))
+
+    # Affection flags
+    flags = []
+    for name in scene.cast:
+        char_flags = scene.active_affection(name)
+        if char_flags:
+            flags.append(f"{name}: {', '.join(char_flags)}")
+    if flags:
+        lines.append("Affection: " + " | ".join(flags))
+
+    lines.append("[ENDSTATE]")
+    return "\n".join(lines)
+
+
+def build_full_prompt(scene, cast, player_choice_text: str = "", player_name: str = "Player") -> tuple[str, str]:
+    """Build the system + user prompt pair for a model call.
+
+    Args:
+        scene: Current SceneState.
+        cast: dict[str, CastMember] — the locked cast.
+        player_choice_text: The choice the player made (empty for first scene).
+
+    Returns:
+        (system_prompt, user_prompt) tuple.
+    """
+    cast_desc = build_cast_descriptions(cast)
+    system = VN_SYSTEM_PROMPT.format(cast_descriptions=cast_desc, player_name=player_name)
+    state_banner = build_state_banner(scene)
+
+    if player_choice_text:
+        user = f"{state_banner}\n\n[CHOICE MADE]\n{player_choice_text}\n\nWrite the next scene in response to this choice. Show how the world reacts. Change background, expressions, and mood as appropriate."
+    else:
+        user = f"{state_banner}\n\nWrite the opening scene of this chapter. Set the atmosphere, introduce the setting, and let the story begin."
+
+    return system, user