Deploy Ars Fabula VN (ZeroGPU)

.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

.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

.pytest_cache/.gitignore

@@ -0,0 +1,2 @@
+# Created by pytest automatically.
+*

.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

.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.

.pytest_cache/v/cache/lastfailed

@@ -0,0 +1 @@
+{}

.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"
+]

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
+```

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,
+    )

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

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)

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()

requirements.txt

@@ -0,0 +1,7 @@
+torch
+transformers>=4.56
+accelerate
+spaces
+requests
+pillow
+numpy