feat: initial FloodDiffusion streaming demo for HF Space

Docker-based Space with T4 GPU for real-time streaming motion generation.
Model loaded from ShandaAI/FloodDiffusionTiny via HF Hub.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Dockerfile

@@ -0,0 +1,26 @@
+FROM nvidia/cuda:12.1.0-cudnn8-runtime-ubuntu22.04
+
+RUN apt-get update && apt-get install -y \
+    python3 python3-pip git \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN pip3 install --no-cache-dir \
+    flask flask-cors \
+    torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 \
+    numpy transformers accelerate sentencepiece protobuf
+
+# Create non-root user (HF Spaces runs as uid 1000)
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    HF_HOME=/home/user/.cache/huggingface
+
+WORKDIR /home/user/app
+COPY --chown=user:user . .
+
+# Pre-download model during build (avoids slow cold start)
+RUN python3 -c "from transformers import AutoModel; AutoModel.from_pretrained('ShandaAI/FloodDiffusionTiny', trust_remote_code=True)"
+
+EXPOSE 7860
+CMD ["python3", "app.py", "--port", "7860"]

README.md

@@ -1,10 +1,11 @@
 ---
-title: FloodDiffusion Streaming
-emoji: 😻
-colorFrom: red
+title: FloodDiffusion Streaming Demo
+emoji: "\U0001F30A"
+colorFrom: blue
 colorTo: purple
 sdk: docker
-pinned: false
+app_port: 7860
+hardware: t4-small
+pinned: true
+license: apache-2.0
 ---
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

app.py

@@ -0,0 +1,571 @@
+"""
+Flask server for real-time 3D motion generation demo (HF Space version)
+"""
+
+import argparse
+import threading
+import time
+
+from flask import Flask, jsonify, render_template, request
+from flask_cors import CORS
+from model_manager import get_model_manager
+
+
+def _coerce_value(value, reference):
+    """Coerce a value to match the type of a reference value"""
+    if isinstance(reference, bool):
+        return value if isinstance(value, bool) else str(value).lower() in ("true", "1")
+    elif isinstance(reference, int):
+        return int(value)
+    elif isinstance(reference, float):
+        return float(value)
+    return str(value)
+
+
+app = Flask(__name__)
+CORS(app)
+
+# Global model manager (loaded eagerly on startup)
+model_manager = None
+model_name_global = None  # Will be set once at startup
+
+# Session tracking - only one active session can generate at a time
+active_session_id = None  # The session ID currently generating
+session_lock = threading.Lock()
+
+# Frame consumption monitoring - detect if client disconnected by tracking frame consumption
+last_frame_consumed_time = None
+consumption_timeout = (
+    5.0  # If no frame consumed for 5 seconds, assume client disconnected
+)
+consumption_monitor_thread = None
+consumption_monitor_lock = threading.Lock()
+
+
+def init_model():
+    """Initialize model manager"""
+    global model_manager
+    if model_manager is None:
+        if model_name_global is None:
+            raise RuntimeError(
+                "model_name_global not set. Server not properly initialized."
+            )
+        print(f"Initializing model manager with model: {model_name_global}")
+        model_manager = get_model_manager(model_name=model_name_global)
+        print("Model manager ready!")
+    return model_manager
+
+
+def consumption_monitor():
+    """Monitor frame consumption and auto-reset if client stops consuming"""
+    global last_frame_consumed_time, active_session_id, model_manager
+
+    while True:
+        time.sleep(2.0)  # Check every 2 seconds
+
+        # Read state with proper locking - no nested locks!
+        should_reset = False
+        current_session = None
+        time_since_last_consumption = 0
+
+        # First, check consumption time
+        with consumption_monitor_lock:
+            if last_frame_consumed_time is not None:
+                time_since_last_consumption = time.time() - last_frame_consumed_time
+                if time_since_last_consumption > consumption_timeout:
+                    # Need to check if still generating before reset
+                    if model_manager and model_manager.is_generating:
+                        should_reset = True
+
+        # Then, get current session (separate lock)
+        if should_reset:
+            with session_lock:
+                current_session = active_session_id
+
+        # Perform reset outside of locks to avoid deadlock
+        if should_reset and current_session is not None:
+            print(
+                f"No frame consumed for {time_since_last_consumption:.1f}s - client disconnected, auto-resetting..."
+            )
+
+            if model_manager:
+                model_manager.reset()
+                print(
+                    "Generation reset due to client disconnect (no frame consumption)"
+                )
+
+            # Clear state with proper locking - no nested locks!
+            with session_lock:
+                if active_session_id == current_session:
+                    active_session_id = None
+
+            with consumption_monitor_lock:
+                last_frame_consumed_time = None
+
+
+def start_consumption_monitor():
+    """Start the consumption monitoring thread if not already running"""
+    global consumption_monitor_thread
+
+    if consumption_monitor_thread is None or not consumption_monitor_thread.is_alive():
+        consumption_monitor_thread = threading.Thread(
+            target=consumption_monitor, daemon=True
+        )
+        consumption_monitor_thread.start()
+        print("Consumption monitor started")
+
+
+@app.route("/")
+def index():
+    """Main page"""
+    return render_template("index.html")
+
+
+@app.route("/api/config", methods=["GET"])
+def get_config():
+    """Get current config"""
+    try:
+        if model_manager:
+            model = model_manager.model
+            base_sched_keys = set(model_manager._base_schedule_config.keys())
+            base_cfg_keys = set(model_manager._base_cfg_config.keys())
+            return jsonify(
+                {
+                    "schedule_config": {
+                        k: v
+                        for k, v in model.schedule_config.items()
+                        if k in base_sched_keys
+                    },
+                    "cfg_config": {
+                        k: v
+                        for k, v in model.cfg_config.items()
+                        if k in base_cfg_keys
+                    },
+                    "history_length": model_manager.history_length,
+                    "smoothing_alpha": float(model_manager.smoothing_alpha),
+                }
+            )
+        else:
+            # Model not loaded yet - return defaults
+            return jsonify(
+                {
+                    "schedule_config": {},
+                    "cfg_config": {},
+                    "history_length": 30,
+                    "smoothing_alpha": 0.5,
+                }
+            )
+    except Exception as e:
+        import traceback
+
+        traceback.print_exc()
+        return jsonify({"status": "error", "message": str(e)}), 500
+
+
+@app.route("/api/config", methods=["POST"])
+def update_config():
+    """Update model config in memory"""
+    try:
+        global active_session_id, last_frame_consumed_time
+
+        if not model_manager or not model_manager.model:
+            return jsonify({"status": "error", "message": "Model not loaded yet"}), 400
+
+        data = request.json
+        new_schedule_config = data.get("schedule_config")
+        new_cfg_config = data.get("cfg_config")
+        history_length = data.get("history_length")
+        smoothing_alpha = data.get("smoothing_alpha")
+
+        valid_schedule_keys = set(model_manager._base_schedule_config.keys())
+        valid_cfg_keys = set(model_manager._base_cfg_config.keys())
+
+        # Validate and update schedule_config
+        if new_schedule_config:
+            for key in new_schedule_config:
+                if key not in valid_schedule_keys:
+                    return jsonify(
+                        {
+                            "status": "error",
+                            "message": f"Unknown schedule_config key: {key}",
+                        }
+                    ), 400
+            for key, value in new_schedule_config.items():
+                model_manager._base_schedule_config[key] = _coerce_value(
+                    value, model_manager._base_schedule_config[key]
+                )
+
+        # Validate and update cfg_config
+        if new_cfg_config:
+            for key in new_cfg_config:
+                if key not in valid_cfg_keys:
+                    return jsonify(
+                        {"status": "error", "message": f"Unknown cfg_config key: {key}"}
+                    ), 400
+            for key, value in new_cfg_config.items():
+                model_manager._base_cfg_config[key] = _coerce_value(
+                    value, model_manager._base_cfg_config[key]
+                )
+
+        # Reset with new parameters
+        model_manager.reset(
+            history_length=history_length,
+            smoothing_alpha=smoothing_alpha,
+        )
+
+        # Clear active session
+        with session_lock:
+            active_session_id = None
+        with consumption_monitor_lock:
+            last_frame_consumed_time = None
+
+        return jsonify({"status": "success"})
+    except Exception as e:
+        import traceback
+
+        traceback.print_exc()
+        return jsonify({"status": "error", "message": str(e)}), 500
+
+
+@app.route("/api/start", methods=["POST"])
+def start_generation():
+    """Start generation with given text"""
+    try:
+        global active_session_id, last_frame_consumed_time
+
+        data = request.json
+        session_id = data.get("session_id")
+        text = data.get("text", "walk in a circle.")
+        history_length = data.get("history_length")
+        smoothing_alpha = data.get(
+            "smoothing_alpha", None
+        )  # Optional smoothing parameter
+        force = data.get("force", False)  # Allow force takeover
+
+        if not session_id:
+            return jsonify(
+                {"status": "error", "message": "session_id is required"}
+            ), 400
+
+        print(
+            f"[Session {session_id}] Starting generation with text: {text}, history_length: {history_length}, force: {force}"
+        )
+
+        # Initialize model if needed
+        mm = init_model()
+
+        # Check if another session is already generating
+        need_force_takeover = False
+
+        with session_lock:
+            if active_session_id and active_session_id != session_id:
+                if not force:
+                    # Another session is active, return conflict
+                    return jsonify(
+                        {
+                            "status": "error",
+                            "message": "Another session is already generating.",
+                            "conflict": True,
+                            "active_session_id": active_session_id,
+                        }
+                    ), 409
+                else:
+                    # Force takeover
+                    print(
+                        f"[Session {session_id}] Force takeover from session {active_session_id}"
+                    )
+                    need_force_takeover = True
+
+            if mm.is_generating and active_session_id == session_id:
+                return jsonify(
+                    {
+                        "status": "error",
+                        "message": "Generation is already running for this session.",
+                    }
+                ), 400
+
+            # Set this session as active
+            active_session_id = session_id
+
+        # Clear previous session's consumption tracking if force takeover (no nested locks)
+        if need_force_takeover:
+            with consumption_monitor_lock:
+                last_frame_consumed_time = None
+
+        # Reset and start generation
+        mm.reset(history_length=history_length, smoothing_alpha=smoothing_alpha)
+        mm.start_generation(text, history_length=history_length)
+
+        # Initialize consumption tracking (no nested locks)
+        with consumption_monitor_lock:
+            last_frame_consumed_time = time.time()
+
+        # Start consumption monitoring
+        start_consumption_monitor()
+        print(f"[Session {session_id}] Consumption monitoring activated")
+
+        return jsonify(
+            {
+                "status": "success",
+                "message": f"Generation started with text: {text}, history_length: {history_length}",
+                "session_id": session_id,
+            }
+        )
+    except Exception as e:
+        print(f"Error in start_generation: {e}")
+        import traceback
+
+        traceback.print_exc()
+        return jsonify({"status": "error", "message": str(e)}), 500
+
+
+@app.route("/api/update_text", methods=["POST"])
+def update_text():
+    """Update the generation text"""
+    try:
+        data = request.json
+        session_id = data.get("session_id")
+        text = data.get("text", "")
+
+        if not session_id:
+            return jsonify(
+                {"status": "error", "message": "session_id is required"}
+            ), 400
+
+        # Verify this is the active session
+        with session_lock:
+            if active_session_id != session_id:
+                return jsonify(
+                    {"status": "error", "message": "Not the active session"}
+                ), 403
+
+        if model_manager is None:
+            return jsonify({"status": "error", "message": "Model not initialized"}), 400
+
+        model_manager.update_text(text)
+
+        return jsonify({"status": "success", "message": f"Text updated to: {text}"})
+    except Exception as e:
+        return jsonify({"status": "error", "message": str(e)}), 500
+
+
+@app.route("/api/pause", methods=["POST"])
+def pause_generation():
+    """Pause generation (keeps state for resume)"""
+    try:
+        data = request.json if request.json else {}
+        session_id = data.get("session_id")
+
+        if not session_id:
+            return jsonify(
+                {"status": "error", "message": "session_id is required"}
+            ), 400
+
+        # Verify this is the active session
+        with session_lock:
+            if active_session_id != session_id:
+                return jsonify(
+                    {"status": "error", "message": "Not the active session"}
+                ), 403
+
+        if model_manager:
+            model_manager.pause_generation()
+
+        return jsonify({"status": "success", "message": "Generation paused"})
+    except Exception as e:
+        return jsonify({"status": "error", "message": str(e)}), 500
+
+
+@app.route("/api/resume", methods=["POST"])
+def resume_generation():
+    """Resume generation from paused state"""
+    try:
+        global last_frame_consumed_time
+
+        data = request.json if request.json else {}
+        session_id = data.get("session_id")
+
+        if not session_id:
+            return jsonify(
+                {"status": "error", "message": "session_id is required"}
+            ), 400
+
+        # Verify this is the active session
+        with session_lock:
+            if active_session_id != session_id:
+                return jsonify(
+                    {"status": "error", "message": "Not the active session"}
+                ), 403
+
+        if model_manager is None:
+            return jsonify({"status": "error", "message": "Model not initialized"}), 400
+
+        model_manager.resume_generation()
+
+        # Reset consumption tracking when resuming
+        with consumption_monitor_lock:
+            last_frame_consumed_time = time.time()
+
+        return jsonify({"status": "success", "message": "Generation resumed"})
+    except Exception as e:
+        return jsonify({"status": "error", "message": str(e)}), 500
+
+
+@app.route("/api/reset", methods=["POST"])
+def reset():
+    """Reset generation state"""
+    try:
+        global active_session_id, last_frame_consumed_time
+
+        data = request.json if request.json else {}
+        session_id = data.get("session_id")
+        history_length = data.get("history_length")
+        smoothing_alpha = data.get("smoothing_alpha")
+
+        # If session_id provided, verify it's the active session
+        if session_id:
+            with session_lock:
+                if active_session_id and active_session_id != session_id:
+                    return jsonify(
+                        {"status": "error", "message": "Not the active session"}
+                    ), 403
+
+        if model_manager:
+            model_manager.reset(
+                history_length=history_length, smoothing_alpha=smoothing_alpha
+            )
+
+        # Clear the active session
+        with session_lock:
+            if active_session_id == session_id or not session_id:
+                active_session_id = None
+
+        # Clear consumption tracking
+        with consumption_monitor_lock:
+            last_frame_consumed_time = None
+
+        print(f"[Session {session_id}] Reset complete, session cleared")
+
+        return jsonify(
+            {
+                "status": "success",
+                "message": "Reset complete",
+            }
+        )
+    except Exception as e:
+        return jsonify({"status": "error", "message": str(e)}), 500
+
+
+@app.route("/api/get_frame", methods=["GET"])
+def get_frame():
+    """Get the next frame"""
+    try:
+        global last_frame_consumed_time
+
+        session_id = request.args.get("session_id")
+
+        if not session_id:
+            return jsonify(
+                {"status": "error", "message": "session_id is required"}
+            ), 400
+
+        # Verify this is the active session
+        with session_lock:
+            if active_session_id != session_id:
+                return jsonify(
+                    {"status": "error", "message": "Not the active session"}
+                ), 403
+
+        if model_manager is None:
+            return jsonify({"status": "error", "message": "Model not initialized"}), 400
+
+        # Get next frame from buffer
+        joints = model_manager.get_next_frame()
+
+        if joints is not None:
+            # Update last consumption time
+            with consumption_monitor_lock:
+                last_frame_consumed_time = time.time()
+
+            # Convert numpy array to list for JSON
+            joints_list = joints.tolist()
+            return jsonify(
+                {
+                    "status": "success",
+                    "joints": joints_list,
+                    "buffer_size": model_manager.frame_buffer.size(),
+                }
+            )
+        else:
+            return jsonify(
+                {
+                    "status": "waiting",
+                    "message": "No frame available yet",
+                    "buffer_size": model_manager.frame_buffer.size(),
+                }
+            )
+    except Exception as e:
+        print(f"Error in get_frame: {e}")
+        import traceback
+
+        traceback.print_exc()
+        return jsonify({"status": "error", "message": str(e)}), 500
+
+
+@app.route("/api/status", methods=["GET"])
+def get_status():
+    """Get generation status"""
+    try:
+        session_id = request.args.get("session_id")
+
+        with session_lock:
+            is_active_session = session_id and active_session_id == session_id
+            current_active_session = active_session_id
+
+        if model_manager is None:
+            return jsonify(
+                {
+                    "initialized": False,
+                    "buffer_size": 0,
+                    "is_generating": False,
+                    "is_active_session": is_active_session,
+                    "active_session_id": current_active_session,
+                }
+            )
+
+        status = model_manager.get_buffer_status()
+        status["initialized"] = True
+        status["is_active_session"] = is_active_session
+        status["active_session_id"] = current_active_session
+
+        return jsonify(status)
+    except Exception as e:
+        return jsonify({"status": "error", "message": str(e)}), 500
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Flask server for real-time 3D motion generation"
+    )
+    parser.add_argument(
+        "--model_name",
+        type=str,
+        default="ShandaAI/FloodDiffusionTiny",
+        help="HF Hub model name (default: ShandaAI/FloodDiffusionTiny)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=7860,
+        help="Port to run the server on (default: 7860)",
+    )
+    args = parser.parse_args()
+
+    model_name_global = args.model_name
+
+    # Load model eagerly on startup (pre-downloaded in Docker)
+    print(f"Loading model: {model_name_global}")
+    init_model()
+
+    print("Starting Flask server...")
+    app.run(host="0.0.0.0", port=args.port, debug=False, threaded=True)

model_manager.py

@@ -0,0 +1,318 @@
+"""
+Model Manager for real-time motion generation (HF Space version)
+Loads model from Hugging Face Hub instead of local checkpoints.
+"""
+
+import threading
+import time
+from collections import deque
+
+import numpy as np
+import torch
+
+from motion_process import StreamJointRecovery263
+
+
+class FrameBuffer:
+    """
+    Thread-safe frame buffer that maintains a queue of generated frames
+    """
+
+    def __init__(self, target_buffer_size=4):
+        self.buffer = deque(maxlen=100)  # Max 100 frames in buffer
+        self.target_size = target_buffer_size
+        self.lock = threading.Lock()
+
+    def add_frame(self, joints):
+        """Add a frame to the buffer"""
+        with self.lock:
+            self.buffer.append(joints)
+
+    def get_frame(self):
+        """Get the next frame from buffer"""
+        with self.lock:
+            if len(self.buffer) > 0:
+                return self.buffer.popleft()
+            return None
+
+    def size(self):
+        """Get current buffer size"""
+        with self.lock:
+            return len(self.buffer)
+
+    def clear(self):
+        """Clear the buffer"""
+        with self.lock:
+            self.buffer.clear()
+
+    def needs_generation(self):
+        """Check if buffer needs more frames"""
+        return self.size() < self.target_size
+
+
+class ModelManager:
+    """
+    Manages model loading from HF Hub and real-time frame generation
+    """
+
+    def __init__(self, model_name):
+        self.device = "cuda" if torch.cuda.is_available() else "cpu"
+        print(f"Using device: {self.device}")
+
+        # Load models from HF Hub
+        self.vae, self.model = self._load_models(model_name)
+
+        # Save clean copies of user-facing configs (before any runtime injection)
+        self._base_schedule_config = dict(self.model.schedule_config)
+        self._base_cfg_config = dict(self.model.cfg_config)
+
+        # Frame buffer
+        self.frame_buffer = FrameBuffer(target_buffer_size=4)
+
+        # Stream joint recovery with smoothing
+        self.smoothing_alpha = 0.5  # Default: medium smoothing
+        self.stream_recovery = StreamJointRecovery263(
+            joints_num=22, smoothing_alpha=self.smoothing_alpha
+        )
+
+        # Generation state
+        self.current_text = ""
+        self.is_generating = False
+        self.generation_thread = None
+        self.should_stop = False
+
+        # Model generation state
+        self.first_chunk = True
+        self.history_length = 30
+
+        print("ModelManager initialized successfully")
+
+    def _load_models(self, model_name):
+        """Load VAE and diffusion models from HF Hub"""
+        torch.set_float32_matmul_precision("high")
+
+        print(f"Loading model from HF Hub: {model_name}")
+        from transformers import AutoModel
+
+        hf_model = AutoModel.from_pretrained(model_name, trust_remote_code=True)
+        hf_model.to(self.device)
+
+        # Trigger lazy loading / warmup
+        print("Warming up model...")
+        _ = hf_model("test", length=1)
+
+        # Access underlying streaming components
+        model = hf_model.ldf_model
+        vae = hf_model.vae
+
+        model.eval()
+        vae.eval()
+
+        print("Models loaded successfully")
+        return vae, model
+
+    def start_generation(self, text, history_length=None):
+        """Start or update generation with new text"""
+        self.current_text = text
+
+        if history_length is not None:
+            self.history_length = history_length
+
+        if not self.is_generating:
+            # Reset state before starting (only once at the beginning)
+            self.frame_buffer.clear()
+            self.stream_recovery.reset()
+            self.vae.clear_cache()
+            self.first_chunk = True
+            # Restore clean config before init (clears runtime-injected keys)
+            self.model.schedule_config.clear()
+            self.model.schedule_config.update(self._base_schedule_config)
+            self.model.init_generated(
+                self.history_length,
+                batch_size=1,
+                schedule_config=self.model.schedule_config,
+            )
+            print(
+                f"Model initialized with history length: {self.history_length}, schedule_config: {self.model.schedule_config}"
+            )
+
+            # Start generation thread
+            self.should_stop = False
+            self.generation_thread = threading.Thread(target=self._generation_loop)
+            self.generation_thread.daemon = True
+            self.generation_thread.start()
+            self.is_generating = True
+
+    def update_text(self, text):
+        """Update text without resetting state (continuous generation with new text)"""
+        if text != self.current_text:
+            old_text = self.current_text
+            self.current_text = text
+            # Don't reset first_chunk, stream_recovery, or vae cache
+            # This allows continuous generation with text changes
+            print(f"Text updated: '{old_text}' -> '{text}' (continuous generation)")
+
+    def pause_generation(self):
+        """Pause generation (keeps all state)"""
+        self.should_stop = True
+        if self.generation_thread:
+            self.generation_thread.join(timeout=2.0)
+        self.is_generating = False
+        print("Generation paused (state preserved)")
+
+    def resume_generation(self):
+        """Resume generation from paused state"""
+        if self.is_generating:
+            print("Already generating, ignoring resume")
+            return
+
+        # Restart generation thread with existing state
+        self.should_stop = False
+        self.generation_thread = threading.Thread(target=self._generation_loop)
+        self.generation_thread.daemon = True
+        self.generation_thread.start()
+        self.is_generating = True
+        print("Generation resumed")
+
+    def reset(self, history_length=None, smoothing_alpha=None):
+        """Reset generation state completely
+
+        Args:
+            history_length: History window length for the model
+            smoothing_alpha: EMA smoothing factor (0.0 to 1.0)
+                - 1.0 = no smoothing (default)
+                - 0.0 = infinite smoothing
+                - Recommended: 0.3-0.7 for visible smoothing
+        """
+        # Stop if running
+        if self.is_generating:
+            self.pause_generation()
+
+        # Clear everything
+        self.frame_buffer.clear()
+        self.vae.clear_cache()
+        self.first_chunk = True
+
+        if history_length is not None:
+            self.history_length = history_length
+
+        # Update smoothing alpha if provided and recreate stream recovery
+        if smoothing_alpha is not None:
+            self.smoothing_alpha = np.clip(smoothing_alpha, 0.0, 1.0)
+            print(f"Smoothing alpha updated to: {self.smoothing_alpha}")
+
+        # Recreate stream recovery with new smoothing alpha
+        self.stream_recovery = StreamJointRecovery263(
+            joints_num=22, smoothing_alpha=self.smoothing_alpha
+        )
+
+        # Restore clean configs before init (clears runtime-injected keys)
+        self.model.schedule_config.clear()
+        self.model.schedule_config.update(self._base_schedule_config)
+        self.model.cfg_config.clear()
+        self.model.cfg_config.update(self._base_cfg_config)
+
+        # Initialize model (reads steps/chunk_size from model.schedule_config directly)
+        self.model.init_generated(
+            self.history_length,
+            batch_size=1,
+            schedule_config=self.model.schedule_config,
+        )
+        print(
+            f"Model reset - history: {self.history_length}, smoothing: {self.smoothing_alpha}, schedule_config: {self.model.schedule_config}"
+        )
+
+    def _generation_loop(self):
+        """Main generation loop that runs in background thread"""
+        print("Generation loop started")
+
+        step_count = 0
+        total_gen_time = 0
+
+        with torch.no_grad():
+            while not self.should_stop:
+                # Check if buffer needs more frames
+                if self.frame_buffer.needs_generation():
+                    try:
+                        step_start = time.time()
+
+                        # Generate one token (produces 4 frames from VAE)
+                        text_key = self.model.input_keys["text"]
+                        x = {text_key: [self.current_text]}
+
+                        # Generate from model (1 token)
+                        output = self.model.stream_generate_step(x)
+                        generated = output["generated"]
+
+                        # Skip if no frames committed yet
+                        if generated[0].shape[0] == 0:
+                            continue
+
+                        # Decode with VAE (1 token -> 4 frames)
+                        decoded = self.vae.stream_decode(
+                            generated[0][None, :], first_chunk=self.first_chunk
+                        )[0]
+
+                        self.first_chunk = False
+
+                        # Convert each frame to joints
+                        for i in range(decoded.shape[0]):
+                            frame_data = decoded[i].cpu().numpy()
+                            joints = self.stream_recovery.process_frame(frame_data)
+                            self.frame_buffer.add_frame(joints)
+
+                        step_time = time.time() - step_start
+                        total_gen_time += step_time
+                        step_count += 1
+
+                        # Print performance stats every 10 steps
+                        if step_count % 10 == 0:
+                            avg_time = total_gen_time / step_count
+                            fps = decoded.shape[0] / avg_time
+                            print(
+                                f"[Generation] Step {step_count}: {step_time * 1000:.1f}ms, "
+                                f"Avg: {avg_time * 1000:.1f}ms, "
+                                f"FPS: {fps:.1f}, "
+                                f"Buffer: {self.frame_buffer.size()}"
+                            )
+
+                    except Exception as e:
+                        print(f"Error in generation: {e}")
+                        import traceback
+
+                        traceback.print_exc()
+                        time.sleep(0.1)
+                else:
+                    # Buffer is full, wait a bit
+                    time.sleep(0.01)
+
+        print("Generation loop stopped")
+
+    def get_next_frame(self):
+        """Get the next frame from buffer"""
+        return self.frame_buffer.get_frame()
+
+    def get_buffer_status(self):
+        """Get buffer status"""
+        return {
+            "buffer_size": self.frame_buffer.size(),
+            "target_size": self.frame_buffer.target_size,
+            "is_generating": self.is_generating,
+            "current_text": self.current_text,
+            "smoothing_alpha": self.smoothing_alpha,
+            "history_length": self.history_length,
+            "schedule_config": dict(self.model.schedule_config),
+            "cfg_config": dict(self.model.cfg_config),
+        }
+
+
+# Global model manager instance
+_model_manager = None
+
+
+def get_model_manager(model_name=None):
+    """Get or create the global model manager instance"""
+    global _model_manager
+    if _model_manager is None:
+        _model_manager = ModelManager(model_name)
+    return _model_manager

motion_process.py

@@ -0,0 +1,143 @@
+"""
+Streaming joint recovery from 263-dim motion features.
+Extracted from FloodDiffusion utils for standalone use (only numpy + torch).
+"""
+
+import numpy as np
+import torch
+
+
+def qinv(q):
+    assert q.shape[-1] == 4, "q must be a tensor of shape (*, 4)"
+    mask = torch.ones_like(q)
+    mask[..., 1:] = -mask[..., 1:]
+    return q * mask
+
+
+def qrot(q, v):
+    assert q.shape[-1] == 4
+    assert v.shape[-1] == 3
+    assert q.shape[:-1] == v.shape[:-1]
+
+    original_shape = list(v.shape)
+    q = q.contiguous().view(-1, 4)
+    v = v.contiguous().view(-1, 3)
+
+    qvec = q[:, 1:]
+    uv = torch.cross(qvec, v, dim=1)
+    uuv = torch.cross(qvec, uv, dim=1)
+    return (v + 2 * (q[:, :1] * uv + uuv)).view(original_shape)
+
+
+class StreamJointRecovery263:
+    """
+    Stream version of recover_joint_positions_263 that processes one frame at a time.
+    Maintains cumulative state for rotation angles and positions.
+
+    Key insight: The batch version uses PREVIOUS frame's velocity for the current frame,
+    so we need to delay the velocity application by one frame.
+
+    Args:
+        joints_num: Number of joints in the skeleton
+        smoothing_alpha: EMA smoothing factor (0.0 to 1.0)
+            - 1.0 = no smoothing (default), output follows input exactly
+            - 0.0 = infinite smoothing, output never changes
+            - Recommended values: 0.3-0.7 for visible smoothing
+            - Formula: smoothed = alpha * current + (1 - alpha) * previous
+    """
+
+    def __init__(self, joints_num: int, smoothing_alpha: float = 1.0):
+        self.joints_num = joints_num
+        self.smoothing_alpha = np.clip(smoothing_alpha, 0.0, 1.0)
+        self.reset()
+
+    def reset(self):
+        """Reset the accumulated state"""
+        self.r_rot_ang_accum = 0.0
+        self.r_pos_accum = np.array([0.0, 0.0, 0.0])
+        # Store previous frame's velocities for delayed application
+        self.prev_rot_vel = 0.0
+        self.prev_linear_vel = np.array([0.0, 0.0])
+        # Store previous smoothed joints for EMA
+        self.prev_smoothed_joints = None
+
+    def process_frame(self, frame_data: np.ndarray) -> np.ndarray:
+        """
+        Process a single frame and return joint positions for that frame.
+
+        Args:
+            frame_data: numpy array of shape (263,) for a single frame
+
+        Returns:
+            joints: numpy array of shape (joints_num, 3) representing joint positions
+        """
+        # Convert to torch tensor
+        feature_vec = torch.from_numpy(frame_data).float()
+
+        # Extract current frame's velocities (will be used in NEXT frame)
+        curr_rot_vel = feature_vec[0].item()
+        curr_linear_vel = feature_vec[1:3].numpy()
+
+        # Update accumulated rotation angle with PREVIOUS frame's velocity FIRST
+        # This matches the batch processing: r_rot_ang[i] uses rot_vel[i-1]
+        self.r_rot_ang_accum += self.prev_rot_vel
+
+        # Calculate current rotation quaternion using updated accumulated angle
+        r_rot_quat = torch.zeros(4)
+        r_rot_quat[0] = np.cos(self.r_rot_ang_accum)
+        r_rot_quat[2] = np.sin(self.r_rot_ang_accum)
+
+        # Create velocity vector with Y=0 using PREVIOUS frame's velocity
+        r_vel = np.array([self.prev_linear_vel[0], 0.0, self.prev_linear_vel[1]])
+
+        # Apply inverse rotation to velocity using CURRENT rotation
+        r_vel_torch = torch.from_numpy(r_vel).float()
+        r_vel_rotated = qrot(qinv(r_rot_quat).unsqueeze(0), r_vel_torch.unsqueeze(0))
+        r_vel_rotated = r_vel_rotated.squeeze(0).numpy()
+
+        # Update accumulated position with rotated velocity
+        self.r_pos_accum += r_vel_rotated
+
+        # Get Y position from data
+        r_pos = self.r_pos_accum.copy()
+        r_pos[1] = feature_vec[3].item()
+
+        # Extract local joint positions
+        positions = feature_vec[4 : (self.joints_num - 1) * 3 + 4]
+        positions = positions.view(-1, 3)
+
+        # Apply inverse rotation to local joints
+        r_rot_quat_expanded = (
+            qinv(r_rot_quat).unsqueeze(0).expand(positions.shape[0], 4)
+        )
+        positions = qrot(r_rot_quat_expanded, positions)
+
+        # Add root XZ to joints
+        positions[:, 0] += r_pos[0]
+        positions[:, 2] += r_pos[2]
+
+        # Concatenate root and joints
+        r_pos_torch = torch.from_numpy(r_pos).float()
+        positions = torch.cat([r_pos_torch.unsqueeze(0), positions], dim=0)
+
+        # Convert to numpy
+        joints_np = positions.detach().cpu().numpy()
+
+        # Apply EMA smoothing if enabled
+        if self.smoothing_alpha < 1.0:
+            if self.prev_smoothed_joints is None:
+                # First frame, no smoothing possible
+                self.prev_smoothed_joints = joints_np.copy()
+            else:
+                # EMA: smoothed = alpha * current + (1 - alpha) * previous
+                joints_np = (
+                    self.smoothing_alpha * joints_np
+                    + (1.0 - self.smoothing_alpha) * self.prev_smoothed_joints
+                )
+                self.prev_smoothed_joints = joints_np.copy()
+
+        # Store current velocities for next frame
+        self.prev_rot_vel = curr_rot_vel
+        self.prev_linear_vel = curr_linear_vel
+
+        return joints_np

static/css/style.css

@@ -0,0 +1,451 @@
+* {
+    margin: 0;
+    padding: 0;
+    box-sizing: border-box;
+}
+
+body {
+    font-family: 'SF Pro Display', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    background: #f5f5f5;  /* Light gray background */
+    min-height: 100vh;
+    padding: 20px;
+    color: #333;
+}
+
+.container {
+    max-width: 1400px;
+    margin: 0 auto;
+    background: #ffffff;  /* Pure white container */
+    border-radius: 16px;
+    border: 1px solid #e0e0e0;
+    overflow: hidden;
+    box-shadow: 0 4px 20px rgba(0, 0, 0, 0.08);
+}
+
+.header {
+    background: #ffffff;
+    color: #000000;  /* Black text */
+    padding: 30px;
+    text-align: center;
+    border-bottom: 1px solid #e0e0e0;
+}
+
+.header h1 {
+    font-size: 2.2em;
+    margin-bottom: 8px;
+    font-weight: 600;
+    letter-spacing: -0.5px;
+}
+
+.subtitle {
+    font-size: 1em;
+    opacity: 0.6;
+    font-weight: 400;
+}
+
+.controls {
+    padding: 25px 30px;
+    background: #fafafa;  /* Very light gray */
+    border-bottom: 1px solid #e0e0e0;
+}
+
+.input-group {
+    margin-bottom: 15px;
+}
+
+.input-group label {
+    display: block;
+    font-weight: 500;
+    margin-bottom: 8px;
+    color: #666;
+    font-size: 0.95em;
+    letter-spacing: 0.3px;
+}
+
+.input-group input {
+    width: 100%;
+    padding: 12px 16px;
+    border: 1px solid #ddd;
+    border-radius: 8px;
+    font-size: 1em;
+    background: #ffffff;
+    color: #333;
+    transition: all 0.3s;
+}
+
+.input-group input:focus {
+    outline: none;
+    border-color: #999;
+    background: #fff;
+}
+
+.param-hint {
+    font-size: 0.75em;
+    color: #999;
+    font-style: italic;
+}
+
+/* Description box */
+.description-box {
+    background: #f8f8f8;
+    border: 1px solid #e0e0e0;
+    border-radius: 8px;
+    padding: 10px 14px;
+    margin-bottom: 12px;
+    font-size: 0.85em;
+    color: #666;
+    line-height: 1.5;
+}
+
+.description-box strong {
+    color: #333;
+    font-weight: 600;
+}
+
+.button-group {
+    display: flex;
+    gap: 10px;
+    margin-bottom: 15px;
+    flex-wrap: wrap;
+}
+
+.btn {
+    padding: 12px 24px;
+    border: 1px solid #ddd;
+    border-radius: 8px;
+    font-size: 0.95em;
+    font-weight: 500;
+    cursor: pointer;
+    transition: all 0.2s;
+    flex: 1;
+    min-width: 120px;
+    background: #ffffff;
+    color: #333;
+}
+
+.btn:hover:not(:disabled) {
+    background: #f5f5f5;
+    border-color: #999;
+    transform: translateY(-1px);
+}
+
+.btn:active:not(:disabled) {
+    transform: translateY(0);
+}
+
+.btn:disabled {
+    opacity: 0.3;
+    cursor: not-allowed;
+}
+
+.btn-primary {
+    background: #000;  /* Black primary button */
+    color: #fff;
+    border-color: #000;
+}
+
+.btn-primary:hover:not(:disabled) {
+    background: #333;
+    border-color: #333;
+}
+
+.btn-secondary {
+    background: #666;
+    color: #fff;
+    border-color: #666;
+}
+
+.btn-danger {
+    background: #fff;
+    border-color: #ddd;
+    color: #d33;
+}
+
+.btn-danger:hover:not(:disabled) {
+    background: #fee;
+    border-color: #d33;
+}
+
+.btn-warning {
+    background: #fff;
+    border-color: #ddd;
+    color: #f90;
+}
+
+.btn-warning:hover:not(:disabled) {
+    background: #fff5e6;
+    border-color: #f90;
+}
+
+.btn-success {
+    background: #fff;
+    border-color: #ddd;
+    color: #0a0;
+}
+
+.btn-success:hover:not(:disabled) {
+    background: #e6ffe6;
+    border-color: #0a0;
+}
+
+.status-group {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(120px, 1fr));
+    gap: 12px;
+    background: #ffffff;
+    padding: 16px;
+    border-radius: 8px;
+    border: 1px solid #e0e0e0;
+    margin-bottom: 15px;
+}
+
+.status-item {
+    display: flex;
+    flex-direction: column;
+    gap: 5px;
+}
+
+.status-label {
+    font-size: 0.8em;
+    color: #999;
+    font-weight: 500;
+    text-transform: uppercase;
+    letter-spacing: 0.8px;
+}
+
+.status-value {
+    font-size: 1.4em;
+    font-weight: 600;
+    color: #000;
+    font-variant-numeric: tabular-nums;
+}
+
+#canvas-container {
+    width: 100%;
+    height: 600px;
+    background: #ffffff;  /* White background */
+    position: relative;
+    overflow: hidden;
+    border-top: 1px solid #e0e0e0;
+    border-bottom: 1px solid #e0e0e0;
+}
+
+#renderCanvas {
+    width: 100%;
+    height: 100%;
+    display: block;
+}
+
+.info {
+    padding: 20px 30px;
+    background: #fafafa;
+    border-top: 1px solid #e0e0e0;
+}
+
+.note {
+    padding: 12px 16px;
+    background: #fff;
+    border-left: 3px solid #666;
+    border-radius: 4px;
+    color: #666;
+    font-size: 0.9em;
+    margin: 0;
+}
+
+/* Responsive */
+@media (max-width: 768px) {
+    .header h1 {
+        font-size: 1.8em;
+    }
+    
+    .button-group {
+        flex-direction: column;
+    }
+    
+    .btn {
+        width: 100%;
+    }
+    
+    #canvas-container {
+        height: 400px;
+    }
+}
+
+/* Conflict Warning */
+.conflict-warning {
+    background: #fff3cd;
+    border: 2px solid #ffc107;
+    border-radius: 8px;
+    padding: 20px;
+    margin-top: 20px;
+    text-align: center;
+}
+
+.conflict-warning p {
+    margin: 10px 0;
+    color: #856404;
+}
+
+.conflict-warning strong {
+    font-size: 1.1em;
+}
+
+.conflict-warning button {
+    margin: 10px 5px 0;
+}
+
+input[type="range"]::-webkit-slider-thumb {
+    -webkit-appearance: none;
+    appearance: none;
+    width: 18px;
+    height: 18px;
+    border-radius: 50%;
+    background: #000;
+    cursor: pointer;
+    transition: all 0.2s;
+}
+
+input[type="range"]::-webkit-slider-thumb:hover {
+    transform: scale(1.2);
+    background: #333;
+}
+
+input[type="range"]::-moz-range-thumb {
+    width: 18px;
+    height: 18px;
+    border-radius: 50%;
+    background: #000;
+    cursor: pointer;
+    border: none;
+    transition: all 0.2s;
+}
+
+input[type="range"]::-moz-range-thumb:hover {
+    transform: scale(1.2);
+    background: #333;
+}
+
+/* Config Modal */
+.modal-overlay {
+    position: fixed;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    background: rgba(0, 0, 0, 0.5);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    z-index: 1000;
+}
+
+.modal-content {
+    background: #fff;
+    border-radius: 12px;
+    width: 90%;
+    max-width: 600px;
+    max-height: 80vh;
+    overflow-y: auto;
+    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.2);
+}
+
+.modal-header {
+    padding: 20px 24px;
+    border-bottom: 1px solid #e0e0e0;
+}
+
+.modal-header h2 {
+    font-size: 1.3em;
+    font-weight: 600;
+    color: #333;
+    margin: 0;
+}
+
+.modal-body {
+    padding: 20px 24px;
+}
+
+.config-section {
+    margin-bottom: 20px;
+}
+
+.config-section:last-child {
+    margin-bottom: 0;
+}
+
+.config-section h3 {
+    font-size: 0.9em;
+    font-weight: 600;
+    color: #666;
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+    margin-bottom: 12px;
+    padding-bottom: 8px;
+    border-bottom: 1px solid #eee;
+}
+
+.config-field {
+    margin-bottom: 12px;
+}
+
+.config-field label {
+    display: block;
+    font-size: 0.85em;
+    font-weight: 500;
+    color: #666;
+    margin-bottom: 4px;
+}
+
+.config-field input[type="number"],
+.config-field input[type="text"],
+.config-field select {
+    width: 100%;
+    padding: 8px 12px;
+    border: 1px solid #ddd;
+    border-radius: 6px;
+    font-size: 0.95em;
+    background: #fff;
+    color: #333;
+}
+
+.config-field input:focus,
+.config-field select:focus {
+    outline: none;
+    border-color: #999;
+}
+
+.config-field .slider-container {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+}
+
+.config-field .slider-container input[type="range"] {
+    flex: 1;
+    height: 6px;
+    border-radius: 3px;
+    background: #ddd;
+    outline: none;
+    -webkit-appearance: none;
+}
+
+.config-field .slider-value {
+    min-width: 50px;
+    font-weight: 600;
+    color: #000;
+    font-size: 0.95em;
+}
+
+.modal-footer {
+    padding: 16px 24px;
+    border-top: 1px solid #e0e0e0;
+    display: flex;
+    justify-content: flex-end;
+    gap: 10px;
+}
+
+.modal-footer .btn {
+    flex: 0;
+    min-width: 140px;
+}
+

static/js/main.js

@@ -0,0 +1,777 @@
+/**
+ * Main application logic
+ * Handles UI interactions, API calls, and 3D rendering loop
+ */
+
+class MotionApp {
+    constructor() {
+        this.isRunning = false;
+        this.targetFps = 20; // Model generates data at 20fps
+        this.frameInterval = 1000 / this.targetFps; // 50ms
+        this.nextFetchTime = 0;  // Scheduled time for next fetch
+        this.frameCount = 0;
+
+        // Motion FPS tracking (frame consumption rate)
+        this.motionFpsCounter = 0;
+        this.motionFpsUpdateTime = 0;
+        
+        // Request throttling
+        this.isFetchingFrame = false;  // Prevent concurrent requests
+        this.consecutiveWaiting = 0;   // Count consecutive 'waiting' responses
+        
+        // Session management
+        this.sessionId = this.generateSessionId();
+        
+        // Camera follow settings
+        this.lastUserInteraction = 0;
+        this.autoFollowDelay = 2000; // Auto-follow after 2 seconds of inactivity (reduced from 3s)
+        this.currentRootPos = new THREE.Vector3(0, 1, 0);
+        
+        this.initThreeJS();
+        this.initUI();
+        this.updateStatus();
+        this.setupBeforeUnload();
+        
+        console.log('Session ID:', this.sessionId);
+    }
+    
+    generateSessionId() {
+        // Generate a simple unique session ID
+        return 'session_' + Date.now() + '_' + Math.random().toString(36).substr(2, 9);
+    }
+    
+    setupBeforeUnload() {
+        // Handle page close/refresh - send reset request
+        window.addEventListener('beforeunload', () => {
+            // Send synchronous reset if we're generating
+            if (!this.isIdle) {
+                // Use Blob to set correct Content-Type for JSON
+                const blob = new Blob(
+                    [JSON.stringify({session_id: this.sessionId})],
+                    {type: 'application/json'}
+                );
+                navigator.sendBeacon('/api/reset', blob);
+                console.log('Sent reset beacon on page unload');
+            }
+        });
+        
+        // Also handle visibility change (tab hidden, mobile app switch)
+        document.addEventListener('visibilitychange', () => {
+            if (document.hidden && !this.isIdle && this.isRunning) {
+                // User switched away while generating - they might not come back
+                // Note: Don't reset immediately, let the frame consumption monitor handle it
+                console.log('Tab hidden while generating - consumption monitor will auto-reset if needed');
+            }
+        });
+    }
+    
+    initThreeJS() {
+        // Get canvas
+        const canvas = document.getElementById('renderCanvas');
+        const container = document.getElementById('canvas-container');
+        
+        // Create scene
+        this.scene = new THREE.Scene();
+        this.scene.background = new THREE.Color(0xffffff);  // White background
+        
+        // Create camera
+        this.camera = new THREE.PerspectiveCamera(
+            60,
+            container.clientWidth / container.clientHeight,
+            0.1,
+            1000
+        );
+        this.camera.position.set(3, 1.5, 3);
+        this.camera.lookAt(0, 1, 0);
+        
+        // Create renderer
+        this.renderer = new THREE.WebGLRenderer({
+            canvas: canvas,
+            antialias: true
+        });
+        this.renderer.setSize(container.clientWidth, container.clientHeight);
+        this.renderer.shadowMap.enabled = true;
+        this.renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+        this.renderer.toneMapping = THREE.ACESFilmicToneMapping;
+        this.renderer.toneMappingExposure = 1.0;
+        
+        // Add lights - bright and soft
+        const ambientLight = new THREE.AmbientLight(0xffffff, 0.7);
+        this.scene.add(ambientLight);
+        
+        const keyLight = new THREE.DirectionalLight(0xffffff, 0.8);
+        keyLight.position.set(5, 8, 3);
+        keyLight.castShadow = true;
+        keyLight.shadow.mapSize.width = 2048;
+        keyLight.shadow.mapSize.height = 2048;
+        keyLight.shadow.camera.near = 0.5;
+        keyLight.shadow.camera.far = 50;
+        keyLight.shadow.camera.left = -5;
+        keyLight.shadow.camera.right = 5;
+        keyLight.shadow.camera.top = 5;
+        keyLight.shadow.camera.bottom = -5;
+        keyLight.shadow.bias = -0.0001;
+        this.scene.add(keyLight);
+        
+        // Fill light
+        const fillLight = new THREE.DirectionalLight(0xffffff, 0.4);
+        fillLight.position.set(-3, 5, -3);
+        this.scene.add(fillLight);
+        
+        // Add ground plane - light gray, very large
+        const groundGeometry = new THREE.PlaneGeometry(1000, 1000);
+        const groundMaterial = new THREE.ShadowMaterial({
+            opacity: 0.15
+        });
+        const ground = new THREE.Mesh(groundGeometry, groundMaterial);
+        ground.rotation.x = -Math.PI / 2;
+        ground.position.y = 0;
+        ground.receiveShadow = true;
+        this.scene.add(ground);
+        
+        // Add infinite-looking grid - very large grid
+        const gridHelper = new THREE.GridHelper(1000, 1000, 0xdddddd, 0xeeeeee);
+        gridHelper.position.y = 0.01;
+        this.scene.add(gridHelper);
+        
+        // Add orbit controls
+        this.controls = new THREE.OrbitControls(this.camera, canvas);
+        this.controls.target.set(0, 1, 0);
+        this.controls.enableDamping = true;
+        this.controls.dampingFactor = 0.05;
+        this.controls.update();
+        
+        // Listen for user interaction - record time
+        const updateInteractionTime = () => {
+            this.lastUserInteraction = Date.now();
+        };
+        canvas.addEventListener('mousedown', updateInteractionTime);
+        canvas.addEventListener('wheel', updateInteractionTime);
+        canvas.addEventListener('touchstart', updateInteractionTime);
+        
+        // Create skeleton
+        this.skeleton = new Skeleton3D(this.scene);
+        
+        // Handle window resize
+        window.addEventListener('resize', () => this.onWindowResize());
+        
+        // Start render loop
+        this.animate();
+    }
+    
+    initUI() {
+        // Get UI elements
+        this.motionText = document.getElementById('motionText');
+        this.currentSmoothing = document.getElementById('currentSmoothing');
+        this.currentHistory = document.getElementById('currentHistory');
+        this.startResetBtn = document.getElementById('startResetBtn');
+        this.updateBtn = document.getElementById('updateBtn');
+        this.pauseResumeBtn = document.getElementById('pauseResumeBtn');
+        this.configBtn = document.getElementById('configBtn');
+        this.statusEl = document.getElementById('status');
+        this.bufferSizeEl = document.getElementById('bufferSize');
+        this.fpsEl = document.getElementById('fps');
+        this.frameCountEl = document.getElementById('frameCount');
+        this.conflictWarning = document.getElementById('conflictWarning');
+        this.forceTakeoverBtn = document.getElementById('forceTakeoverBtn');
+        this.cancelTakeoverBtn = document.getElementById('cancelTakeoverBtn');
+
+        // Stored runtime parameter values (updated by Config modal)
+        this.historyLengthValue = null;
+        this.smoothingAlphaValue = 0.5;  // Default
+
+        // Track state
+        this.isPaused = false;
+        this.isIdle = true;
+        this.isProcessing = false;  // Prevent concurrent API calls
+        this.pendingStartRequest = null;  // Store pending start request data
+
+        // Attach event listeners
+        this.startResetBtn.addEventListener('click', () => this.toggleStartReset());
+        this.updateBtn.addEventListener('click', () => this.updateText());
+        this.pauseResumeBtn.addEventListener('click', () => this.togglePauseResume());
+        this.configBtn.addEventListener('click', () => this.openConfigEditor());
+        this.forceTakeoverBtn.addEventListener('click', () => this.handleForceTakeover());
+        this.cancelTakeoverBtn.addEventListener('click', () => this.handleCancelTakeover());
+
+        // Modal event listeners
+        document.getElementById('configDiscardBtn').addEventListener('click', () => this.closeConfigEditor());
+        document.getElementById('configSaveBtn').addEventListener('click', () => this.saveConfigAndReset());
+        document.getElementById('modalSmoothingAlpha').addEventListener('input', (e) => {
+            document.getElementById('modalSmoothingValue').textContent = parseFloat(e.target.value).toFixed(2);
+        });
+
+        // Fetch config from server on page load
+        fetch('/api/config')
+            .then(r => {
+                if (!r.ok) throw new Error(`HTTP ${r.status}`);
+                return r.json();
+            })
+            .then(data => {
+                if (data.status === 'error') throw new Error(data.message);
+                this.historyLengthValue = data.history_length;
+                this.smoothingAlphaValue = data.smoothing_alpha;
+            })
+            .catch(e => {
+                this.statusEl.textContent = 'Error: failed to load config';
+                this.startResetBtn.disabled = true;
+                console.error('Failed to fetch config:', e);
+            });
+    }
+    
+    async toggleStartReset() {
+        if (this.isProcessing) return;  // Prevent concurrent operations
+        
+        if (this.isIdle) {
+            // Currently idle, so start
+            await this.startGeneration();
+        } else {
+            // Currently running/paused, so reset
+            await this.reset();
+        }
+    }
+    
+    async startGeneration(force = false) {
+        if (this.isProcessing) return;  // Prevent concurrent operations
+
+        const text = this.motionText.value.trim();
+        if (!text) {
+            alert('Please enter a motion description');
+            return;
+        }
+
+        const historyLength = this.historyLengthValue || 30;
+        const smoothingAlpha = this.smoothingAlphaValue;
+
+        this.isProcessing = true;
+        this.statusEl.textContent = 'Initializing...';
+
+        try {
+            const response = await fetch('/api/start', {
+                method: 'POST',
+                headers: {'Content-Type': 'application/json'},
+                body: JSON.stringify({
+                    session_id: this.sessionId,
+                    text: text,
+                    history_length: historyLength,
+                    smoothing_alpha: smoothingAlpha,
+                    force: force
+                })
+            });
+            
+            const data = await response.json();
+            
+            if (data.status === 'success') {
+                this.isRunning = true;
+                this.isPaused = false;
+                this.isIdle = false;
+                this.frameCount = 0;
+                this.motionFpsCounter = 0;
+                this.motionFpsUpdateTime = performance.now();
+                this.isFetchingFrame = false;
+                this.consecutiveWaiting = 0;
+                this.startResetBtn.textContent = 'Reset';
+                this.startResetBtn.classList.remove('btn-primary');
+                this.startResetBtn.classList.add('btn-danger');
+                this.updateBtn.disabled = false;
+                this.pauseResumeBtn.disabled = false;
+                this.pauseResumeBtn.textContent = 'Pause';
+                this.statusEl.textContent = 'Running';
+                this.startFrameLoop();
+            } else if (response.status === 409 && data.conflict) {
+                // Another session is running, show warning UI
+                this.statusEl.textContent = 'Conflict - Another user is generating';
+                this.conflictWarning.style.display = 'block';
+                
+                // Store request data for later
+                this.pendingStartRequest = {
+                    text: text,
+                    history_length: historyLength
+                };
+                
+                return;
+            } else {
+                // Other errors
+                alert('Error: ' + data.message);
+                this.statusEl.textContent = 'Idle';
+                this.isIdle = true;
+                this.isRunning = false;
+                this.isPaused = false;
+            }
+        } catch (error) {
+            console.error('Error starting generation:', error);
+            alert('Failed to start generation: ' + error.message);
+            this.statusEl.textContent = 'Idle';
+            // Keep idle state on error
+            this.isIdle = true;
+            this.isRunning = false;
+            this.isPaused = false;
+        } finally {
+            this.isProcessing = false;
+        }
+    }
+    
+    async updateText() {
+        if (this.isProcessing) return;  // Prevent concurrent operations
+        
+        const text = this.motionText.value.trim();
+        if (!text) {
+            alert('Please enter a motion description');
+            return;
+        }
+        
+        this.isProcessing = true;
+        try {
+            const response = await fetch('/api/update_text', {
+                method: 'POST',
+                headers: {'Content-Type': 'application/json'},
+                body: JSON.stringify({
+                    session_id: this.sessionId,
+                    text: text
+                })
+            });
+            
+            const data = await response.json();
+            
+            if (data.status === 'success') {
+                console.log('Text updated:', text);
+            } else {
+                alert('Error: ' + data.message);
+            }
+        } catch (error) {
+            console.error('Error updating text:', error);
+        } finally {
+            this.isProcessing = false;
+        }
+    }
+    
+    async togglePauseResume() {
+        if (this.isProcessing) return;  // Prevent concurrent operations
+        if (this.isPaused) {
+            // Currently paused, so resume
+            await this.resumeGeneration();
+        } else {
+            // Currently running, so pause
+            await this.pauseGeneration();
+        }
+    }
+    
+    async pauseGeneration() {
+        this.isProcessing = true;
+        try {
+            const response = await fetch('/api/pause', {
+                method: 'POST',
+                headers: {'Content-Type': 'application/json'},
+                body: JSON.stringify({session_id: this.sessionId})
+            });
+            
+            const data = await response.json();
+            
+            if (data.status === 'success') {
+                this.isRunning = false;
+                this.isPaused = true;
+                this.pauseResumeBtn.textContent = 'Resume';
+                this.pauseResumeBtn.classList.remove('btn-warning');
+                this.pauseResumeBtn.classList.add('btn-success');
+                this.updateBtn.disabled = true;
+                this.statusEl.textContent = 'Paused';
+                console.log('Generation paused (state preserved)');
+            }
+        } catch (error) {
+            console.error('Error pausing generation:', error);
+        } finally {
+            this.isProcessing = false;
+        }
+    }
+    
+    async resumeGeneration() {
+        this.isProcessing = true;
+        try {
+            const response = await fetch('/api/resume', {
+                method: 'POST',
+                headers: {'Content-Type': 'application/json'},
+                body: JSON.stringify({session_id: this.sessionId})
+            });
+            
+            const data = await response.json();
+            
+            if (data.status === 'success') {
+                this.isRunning = true;
+                this.isPaused = false;
+                this.pauseResumeBtn.textContent = 'Pause';
+                this.pauseResumeBtn.classList.remove('btn-success');
+                this.pauseResumeBtn.classList.add('btn-warning');
+                this.updateBtn.disabled = false;
+                this.statusEl.textContent = 'Running';
+                this.startFrameLoop();
+                console.log('Generation resumed');
+            }
+        } catch (error) {
+            console.error('Error resuming generation:', error);
+        } finally {
+            this.isProcessing = false;
+        }
+    }
+    
+    async reset() {
+        if (this.isProcessing) return;  // Prevent concurrent operations
+
+        const historyLength = this.historyLengthValue || 30;
+        const smoothingAlpha = this.smoothingAlphaValue;
+
+        this.isProcessing = true;
+        try {
+            const response = await fetch('/api/reset', {
+                method: 'POST',
+                headers: {'Content-Type': 'application/json'},
+                body: JSON.stringify({
+                    session_id: this.sessionId,
+                    history_length: historyLength,
+                    smoothing_alpha: smoothingAlpha,
+                })
+            });
+            
+            const data = await response.json();
+            
+            if (data.status === 'success') {
+                this._resetUIToIdle();
+                console.log('Reset complete - all state cleared');
+            }
+        } catch (error) {
+            console.error('Error resetting:', error);
+        } finally {
+            this.isProcessing = false;
+        }
+    }
+    
+    async handleForceTakeover() {
+        // Hide warning
+        this.conflictWarning.style.display = 'none';
+        
+        if (!this.pendingStartRequest) return;
+        
+        // Retry with force=true
+        this.isProcessing = false;
+        await this.startGeneration(true);
+        
+        this.pendingStartRequest = null;
+    }
+    
+    handleCancelTakeover() {
+        // Hide warning
+        this.conflictWarning.style.display = 'none';
+        this.statusEl.textContent = 'Idle';
+        this.isProcessing = false;
+        this.pendingStartRequest = null;
+    }
+    
+    startFrameLoop() {
+        const now = performance.now();
+        this.nextFetchTime = now + this.frameInterval;
+        this.fetchFrame();
+    }
+    
+    fetchFrame() {
+        if (!this.isRunning) return;
+        
+        const now = performance.now();
+        
+        // Check if it's time to fetch next frame AND we're not already fetching
+        if (now >= this.nextFetchTime && !this.isFetchingFrame) {
+            // Schedule next fetch (maintain fixed rate regardless of delays)
+            this.nextFetchTime += this.frameInterval;
+            
+            // If we've fallen behind, catch up
+            if (this.nextFetchTime < now) {
+                this.nextFetchTime = now + this.frameInterval;
+            }
+            
+            // Mark as fetching to prevent concurrent requests
+            this.isFetchingFrame = true;
+            
+            fetch(`/api/get_frame?session_id=${this.sessionId}`)
+                .then(response => response.json())
+                .then(data => {
+                    if (data.status === 'success') {
+                        this.skeleton.updatePose(data.joints);
+                        this.frameCount++;
+                        this.frameCountEl.textContent = this.frameCount;
+                        
+                        // Update motion FPS counter (only when frame consumed)
+
+
+                        this.motionFpsCounter++;
+                        
+                        // Update current root position
+                        this.currentRootPos.set(
+                            data.joints[0][0],
+                            data.joints[0][1],
+                            data.joints[0][2]
+                        );
+                        
+                        // Auto-follow (if user hasn't interacted for a while)
+                        this.updateAutoFollow();
+                        
+                        // Reset waiting counter on success
+                        this.consecutiveWaiting = 0;
+                    } else if (data.status === 'waiting') {
+                        // No frame available, slow down requests if this happens repeatedly
+                        this.consecutiveWaiting++;
+                        
+                        // If buffer is consistently empty, back off a bit
+                        if (this.consecutiveWaiting > 5) {
+                            // Add a small delay to reduce server load
+                            this.nextFetchTime = now + this.frameInterval * 1.5;
+                            this.consecutiveWaiting = 0;
+                        }
+                    }
+                })
+                .catch(error => {
+                    console.error('Error fetching frame:', error);
+                })
+                .finally(() => {
+                    // Always mark as done fetching
+                    this.isFetchingFrame = false;
+                });
+        }
+        
+        // Use requestAnimationFrame for continuous checking
+        requestAnimationFrame(() => this.fetchFrame());
+    }
+    
+    updateAutoFollow() {
+        const timeSinceInteraction = Date.now() - this.lastUserInteraction;
+        
+        // Auto-follow if user hasn't interacted for more than 3 seconds
+        if (timeSinceInteraction > this.autoFollowDelay) {
+            // Calculate camera offset relative to current target
+            const currentOffset = new THREE.Vector3().subVectors(
+                this.camera.position, 
+                this.controls.target
+            );
+            
+            // New target position (character position, waist height)
+            const newTarget = this.currentRootPos.clone();
+            newTarget.y = 1.0;
+            
+            // Calculate new camera position (maintain relative offset)
+            const newCameraPos = newTarget.clone().add(currentOffset);
+            
+            // Smooth interpolation follow (increased lerp factor for more obvious following)
+            // 0.2 = more aggressive following, 0.05 = gentle following
+            this.controls.target.lerp(newTarget, 0.2);
+            this.camera.position.lerp(newCameraPos, 0.2);
+            
+            // Debug log (comment out in production)
+            // console.log('Auto-follow active, tracking:', newTarget);
+        }
+    }
+    
+    _resetUIToIdle() {
+        this.isRunning = false;
+        this.isPaused = false;
+        this.isIdle = true;
+        this.frameCount = 0;
+        this.motionFpsCounter = 0;
+        this.isFetchingFrame = false;
+        this.consecutiveWaiting = 0;
+        this.startResetBtn.textContent = 'Start';
+        this.startResetBtn.classList.remove('btn-danger');
+        this.startResetBtn.classList.add('btn-primary');
+        this.updateBtn.disabled = true;
+        this.pauseResumeBtn.disabled = true;
+        this.pauseResumeBtn.textContent = 'Pause';
+        this.pauseResumeBtn.classList.remove('btn-success');
+        this.pauseResumeBtn.classList.add('btn-warning');
+        this.statusEl.textContent = 'Idle';
+        this.bufferSizeEl.textContent = '0 / 4';
+        this.frameCountEl.textContent = '0';
+        this.fpsEl.textContent = '0';
+        if (this.skeleton) this.skeleton.clearTrail();
+    }
+
+    // --- Config Editor ---
+
+    async openConfigEditor() {
+        try {
+            const response = await fetch('/api/config');
+            if (!response.ok) throw new Error(`HTTP ${response.status}`);
+            const data = await response.json();
+            if (data.status === 'error') throw new Error(data.message);
+
+            // Render schedule_config fields
+            this.renderConfigSection('schedule_config', data.schedule_config,
+                document.getElementById('scheduleConfigFields'));
+
+            // Render cfg_config fields
+            this.renderConfigSection('cfg_config', data.cfg_config,
+                document.getElementById('cfgConfigFields'));
+
+            // Populate runtime params
+            document.getElementById('modalHistoryLength').value = data.history_length;
+            const slider = document.getElementById('modalSmoothingAlpha');
+            slider.value = data.smoothing_alpha;
+            document.getElementById('modalSmoothingValue').textContent =
+                parseFloat(data.smoothing_alpha).toFixed(2);
+
+            // Show modal
+            document.getElementById('configModal').style.display = 'flex';
+        } catch (error) {
+            console.error('Error opening config editor:', error);
+            alert('Failed to load config: ' + error.message);
+        }
+    }
+
+    renderConfigSection(sectionName, obj, container) {
+        container.innerHTML = '';
+        for (const [key, value] of Object.entries(obj)) {
+            const field = document.createElement('div');
+            field.className = 'config-field';
+
+            const label = document.createElement('label');
+            label.textContent = key;
+            field.appendChild(label);
+
+            let input;
+            if (typeof value === 'boolean') {
+                input = document.createElement('select');
+                input.innerHTML =
+                    `<option value="true" ${value ? 'selected' : ''}>true</option>` +
+                    `<option value="false" ${!value ? 'selected' : ''}>false</option>`;
+            } else {
+                input = document.createElement('input');
+                input.type = typeof value === 'number' ? 'number' : 'text';
+                if (typeof value === 'number' && !Number.isInteger(value)) {
+                    input.step = 'any';
+                }
+                input.value = value;
+            }
+            input.dataset.section = sectionName;
+            input.dataset.key = key;
+            input.dataset.type = typeof value;
+            input.className = 'config-input';
+            field.appendChild(input);
+
+            container.appendChild(field);
+        }
+    }
+
+    async saveConfigAndReset() {
+        try {
+            // Collect config values from dynamically rendered fields
+            const scheduleConfig = {};
+            const cfgConfig = {};
+
+            document.querySelectorAll('.config-input').forEach(input => {
+                const section = input.dataset.section;
+                const key = input.dataset.key;
+                const type = input.dataset.type;
+
+                let value;
+                if (type === 'boolean') {
+                    value = input.value === 'true';
+                } else if (type === 'number') {
+                    value = Number(input.value);
+                } else {
+                    value = input.value;
+                }
+
+                if (section === 'schedule_config') {
+                    scheduleConfig[key] = value;
+                } else if (section === 'cfg_config') {
+                    cfgConfig[key] = value;
+                }
+            });
+
+            const historyLength = parseInt(document.getElementById('modalHistoryLength').value);
+            const smoothingAlpha = parseFloat(document.getElementById('modalSmoothingAlpha').value);
+
+            const response = await fetch('/api/config', {
+                method: 'POST',
+                headers: {'Content-Type': 'application/json'},
+                body: JSON.stringify({
+                    schedule_config: scheduleConfig,
+                    cfg_config: cfgConfig,
+                    history_length: historyLength,
+                    smoothing_alpha: smoothingAlpha,
+                })
+            });
+
+            const data = await response.json();
+
+            if (data.status === 'success') {
+                this.historyLengthValue = historyLength;
+                this.smoothingAlphaValue = smoothingAlpha;
+                this._resetUIToIdle();
+                this.closeConfigEditor();
+                console.log('Config updated and reset complete');
+            } else {
+                alert('Error: ' + data.message);
+            }
+        } catch (error) {
+            console.error('Error saving config:', error);
+            alert('Failed to save config: ' + error.message);
+        }
+    }
+
+    closeConfigEditor() {
+        document.getElementById('configModal').style.display = 'none';
+    }
+
+    async updateStatus() {
+        try {
+            const response = await fetch(`/api/status?session_id=${this.sessionId}`);
+            const data = await response.json();
+            
+            if (data.initialized) {
+                this.bufferSizeEl.textContent = `${data.buffer_size} / ${data.target_size}`;
+
+                // Update current smoothing display
+                if (data.smoothing_alpha !== undefined) {
+                    this.currentSmoothing.textContent = data.smoothing_alpha.toFixed(2);
+                }
+
+                // Update current history length display
+                if (data.history_length !== undefined) {
+                    this.currentHistory.textContent = data.history_length;
+                }
+            }
+            
+            // Update motion FPS (frame consumption rate)
+            const now = performance.now();
+            if (now - this.motionFpsUpdateTime > 1000) {
+                this.fpsEl.textContent = this.motionFpsCounter;
+                this.motionFpsCounter = 0;
+                this.motionFpsUpdateTime = now;
+            }
+        } catch (error) {
+            // Silently fail for status updates
+        }
+        
+        // Update status every 500ms
+        setTimeout(() => this.updateStatus(), 500);
+    }
+    
+    animate() {
+        requestAnimationFrame(() => this.animate());
+        
+        // Update controls
+        this.controls.update();
+        
+        // Render scene
+        this.renderer.render(this.scene, this.camera);
+    }
+    
+    onWindowResize() {
+        const container = document.getElementById('canvas-container');
+        this.camera.aspect = container.clientWidth / container.clientHeight;
+        this.camera.updateProjectionMatrix();
+        this.renderer.setSize(container.clientWidth, container.clientHeight);
+    }
+}
+
+// Initialize app when page loads
+window.addEventListener('DOMContentLoaded', () => {
+    window.app = new MotionApp();
+});
+

static/js/skeleton.js

@@ -0,0 +1,289 @@
+/**
+ * Skeleton visualization with capsule bones and sphere joints
+ * Based on HumanML3D skeleton structure (22 joints)
+ */
+
+class Skeleton3D {
+    constructor(scene) {
+        this.scene = scene;
+        this.joints = [];
+        this.bones = [];
+        
+        // Trail settings
+        this.trailPoints = [];  // Store root positions
+        this.maxTrailPoints = 200;  // Maximum trail length
+        this.trailLine = null;
+        this.trailGeometry = null;
+        this.trailMaterial = null;
+        
+        // HumanML3D skeleton chains (from render_skeleton.py)
+        this.chains = [
+            [0, 2, 5, 8, 11],      // Chain 0: spine
+            [0, 1, 4, 7, 10],      // Chain 1: left leg  
+            [0, 3, 6, 9, 12, 15],  // Chain 2: right leg + torso
+            [9, 14, 17, 19, 21],   // Chain 3: left arm
+            [9, 13, 16, 18, 20],   // Chain 4: right arm
+        ];
+        
+        // Convert chains to bone connections
+        this.boneConnections = [];
+        for (const chain of this.chains) {
+            for (let i = 0; i < chain.length - 1; i++) {
+                this.boneConnections.push([chain[i], chain[i + 1]]);
+            }
+        }
+        
+        // Bone and joint sizes - stick figure style (thin and small)
+        this.boneRadius = 0.015;  // Thin cylinder
+        this.jointSize = 0.03;    // Small sphere
+        
+        // Colors from render_skeleton.py
+        this.chainColors = [
+            0xFEB21A,  // orange (chain 0 - spine)
+            0x00AAFF,  // cyan (chain 1 - left leg)
+            0x134686,  // aquamarine (chain 2 - right leg)
+            0xFFB600,  // amber (chain 3 - left arm)
+            0x00D47E,  // aquamarine (chain 4 - right arm)
+        ];
+        
+        // Joint color: teal (0, 128, 157)
+        this.jointMaterial = new THREE.MeshStandardMaterial({
+            color: 0x00809D,  // teal
+            metalness: 0.2,
+            roughness: 0.5,
+        });
+        
+        // Will create multiple bone materials for different chains
+        this.boneMaterials = this.chainColors.map(color => 
+            new THREE.MeshStandardMaterial({
+                color: color,
+                metalness: 0.2,
+                roughness: 0.5,
+            })
+        );
+        
+        this.initSkeleton();
+        this.initTrail();
+    }
+    
+    initTrail() {
+        // Create trail line with gradient opacity
+        this.trailGeometry = new THREE.BufferGeometry();
+        
+        // Initialize with empty arrays
+        const positions = new Float32Array(this.maxTrailPoints * 3);
+        const colors = new Float32Array(this.maxTrailPoints * 4); // RGBA
+        
+        this.trailGeometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
+        this.trailGeometry.setAttribute('color', new THREE.BufferAttribute(colors, 4));
+        
+        this.trailMaterial = new THREE.LineBasicMaterial({
+            vertexColors: true,
+            transparent: true,
+            opacity: 1.0,
+            linewidth: 2,
+        });
+        
+        this.trailLine = new THREE.Line(this.trailGeometry, this.trailMaterial);
+        this.trailLine.frustumCulled = false;
+        this.scene.add(this.trailLine);
+    }
+    
+    initSkeleton() {
+        // Create 22 joint spheres - uniform small spheres
+        const jointGeometry = new THREE.SphereGeometry(this.jointSize, 16, 16);
+        
+        for (let i = 0; i < 22; i++) {
+            const joint = new THREE.Mesh(jointGeometry, this.jointMaterial);
+            joint.castShadow = true;
+            joint.receiveShadow = true;
+            this.joints.push(joint);
+            this.scene.add(joint);
+        }
+        
+        // Create bone cylinders - different color for each chain
+        let boneIndex = 0;
+        for (let chainIdx = 0; chainIdx < this.chains.length; chainIdx++) {
+            const chain = this.chains[chainIdx];
+            const material = this.boneMaterials[chainIdx];
+            
+            for (let i = 0; i < chain.length - 1; i++) {
+                const bone = this.createBone(material);
+                this.bones.push(bone);
+                this.scene.add(bone);
+                boneIndex++;
+            }
+        }
+    }
+    
+    createBone(material) {
+        // Create a simple thin cylinder with specified material
+        const geometry = new THREE.CylinderGeometry(this.boneRadius, this.boneRadius, 1, 8);
+        const bone = new THREE.Mesh(geometry, material);
+        bone.castShadow = true;
+        bone.receiveShadow = true;
+        return bone;
+    }
+    
+    updatePose(jointPositions) {
+        /**
+         * Update skeleton with new joint positions
+         * jointPositions: array of shape [22, 3]
+         */
+        if (!jointPositions || jointPositions.length !== 22) {
+            console.error('Invalid joint positions:', jointPositions);
+            return;
+        }
+        
+        // Update joint positions
+        for (let i = 0; i < 22; i++) {
+            const pos = jointPositions[i];
+            this.joints[i].position.set(pos[0], pos[1], pos[2]);
+        }
+        
+        // Update bone positions and orientations
+        for (let i = 0; i < this.boneConnections.length; i++) {
+            const [startIdx, endIdx] = this.boneConnections[i];
+            const startPos = new THREE.Vector3(
+                jointPositions[startIdx][0],
+                jointPositions[startIdx][1],
+                jointPositions[startIdx][2]
+            );
+            const endPos = new THREE.Vector3(
+                jointPositions[endIdx][0],
+                jointPositions[endIdx][1],
+                jointPositions[endIdx][2]
+            );
+            
+            this.updateBone(this.bones[i], startPos, endPos);
+        }
+        
+        // Update trail with root position (joint 0)
+        this.updateTrail(jointPositions[0]);
+    }
+    
+    updateTrail(rootPos) {
+        // Add new point to trail (project to ground y=0.01)
+        const trailPoint = {
+            x: rootPos[0],
+            y: 0.01,  // Slightly above ground to avoid z-fighting
+            z: rootPos[2]
+        };
+        
+        // Only add if moved significantly (avoid duplicate points)
+        if (this.trailPoints.length === 0) {
+            this.trailPoints.push(trailPoint);
+        } else {
+            const lastPoint = this.trailPoints[this.trailPoints.length - 1];
+            const dist = Math.sqrt(
+                Math.pow(trailPoint.x - lastPoint.x, 2) + 
+                Math.pow(trailPoint.z - lastPoint.z, 2)
+            );
+            if (dist > 0.02) {  // Minimum distance threshold
+                this.trailPoints.push(trailPoint);
+            }
+        }
+        
+        // Limit trail length
+        if (this.trailPoints.length > this.maxTrailPoints) {
+            this.trailPoints.shift();
+        }
+        
+        // Update geometry
+        const positions = this.trailGeometry.attributes.position.array;
+        const colors = this.trailGeometry.attributes.color.array;
+        
+        const numPoints = this.trailPoints.length;
+        
+        for (let i = 0; i < this.maxTrailPoints; i++) {
+            if (i < numPoints) {
+                const point = this.trailPoints[i];
+                positions[i * 3] = point.x;
+                positions[i * 3 + 1] = point.y;
+                positions[i * 3 + 2] = point.z;
+                
+                // Gradient: older points (lower index) are more transparent
+                const alpha = i / (numPoints - 1);  // 0 (oldest) to 1 (newest)
+                const opacity = Math.pow(alpha, 1.5) * 0.8;  // Fade out older points
+                
+                // Use cyan color (matching joint color)
+                colors[i * 4] = 0.0;      // R
+                colors[i * 4 + 1] = 0.67; // G (cyan)
+                colors[i * 4 + 2] = 0.85; // B
+                colors[i * 4 + 3] = opacity; // A
+            } else {
+                // Hide unused vertices
+                positions[i * 3] = 0;
+                positions[i * 3 + 1] = 0;
+                positions[i * 3 + 2] = 0;
+                colors[i * 4 + 3] = 0;
+            }
+        }
+        
+        this.trailGeometry.attributes.position.needsUpdate = true;
+        this.trailGeometry.attributes.color.needsUpdate = true;
+        this.trailGeometry.setDrawRange(0, numPoints);
+    }
+    
+    clearTrail() {
+        this.trailPoints = [];
+        this.trailGeometry.setDrawRange(0, 0);
+    }
+    
+    updateBone(bone, startPos, endPos) {
+        /**
+         * Update a bone's position, rotation, and scale to connect two joints
+         */
+        const direction = new THREE.Vector3().subVectors(endPos, startPos);
+        const length = direction.length();
+        
+        if (length < 0.001) return;
+        
+        // Position bone at midpoint
+        const midpoint = new THREE.Vector3().addVectors(startPos, endPos).multiplyScalar(0.5);
+        bone.position.copy(midpoint);
+        
+        // Scale bone to match distance
+        bone.scale.y = length;
+        
+        // Rotate bone to point from start to end
+        bone.quaternion.setFromUnitVectors(
+            new THREE.Vector3(0, 1, 0),
+            direction.normalize()
+        );
+    }
+    
+    setVisible(visible) {
+        this.joints.forEach(joint => joint.visible = visible);
+        this.bones.forEach(bone => bone.visible = visible);
+        if (this.trailLine) this.trailLine.visible = visible;
+    }
+    
+    dispose() {
+        // Clean up resources
+        this.joints.forEach(joint => {
+            this.scene.remove(joint);
+            joint.geometry.dispose();
+        });
+        
+        this.bones.forEach(bone => {
+            bone.children.forEach(child => {
+                if (child.geometry) child.geometry.dispose();
+            });
+            this.scene.remove(bone);
+        });
+        
+        if (this.trailLine) {
+            this.scene.remove(this.trailLine);
+            this.trailGeometry.dispose();
+            this.trailMaterial.dispose();
+        }
+        
+        this.jointMaterial.dispose();
+        this.boneMaterials.forEach(mat => mat.dispose());
+    }
+}
+
+// Export for use in main.js
+window.Skeleton3D = Skeleton3D;
+

templates/index.html

@@ -0,0 +1,122 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Real-time 3D Motion Generation</title>
+    <link rel="stylesheet" href="/static/css/style.css">
+</head>
+<body>
+    <div class="container">
+        <div class="header">
+            <h1>Real-time 3D Motion Generation</h1>
+            <p class="subtitle">AI-powered motion synthesis with streaming rendering</p>
+        </div>
+        
+        <div class="controls">
+            <div class="status-group">
+                <div class="status-item">
+                    <span class="status-label">Status:</span>
+                    <span id="status" class="status-value">Idle</span>
+                </div>
+                <div class="status-item">
+                    <span class="status-label">Buffer:</span>
+                    <span id="bufferSize" class="status-value">0 / 4</span>
+                </div>
+                <div class="status-item">
+                    <span class="status-label">Motion FPS:</span>
+                    <span id="fps" class="status-value">0</span>
+                </div>
+                <div class="status-item">
+                    <span class="status-label">Frames:</span>
+                    <span id="frameCount" class="status-value">0</span>
+                </div>
+                <div class="status-item">
+                    <span class="status-label">Smoothing α:</span>
+                    <span id="currentSmoothing" class="status-value">0.50</span>
+                </div>
+                <div class="status-item">
+                    <span class="status-label">History:</span>
+                    <span id="currentHistory" class="status-value">-</span>
+                </div>
+            </div>
+            
+            <div class="input-group">
+                <label for="motionText">Motion Description:</label>
+                <input type="text" id="motionText" placeholder="Enter motion description (e.g., walk forward, jump, dance)" value="walk in a circle.">
+            </div>
+            
+            <div class="button-group">
+                <button id="startResetBtn" class="btn btn-primary">Start</button>
+                <button id="updateBtn" class="btn btn-secondary" disabled>Update Text</button>
+                <button id="pauseResumeBtn" class="btn btn-warning" disabled>Pause</button>
+                <button id="configBtn" class="btn">Config</button>
+            </div>
+
+            <div id="conflictWarning" class="conflict-warning" style="display: none;">
+                <p><strong>⚠️ Another user is currently generating!</strong></p>
+                <p>Do you want to force stop their session and take over?</p>
+                <button id="forceTakeoverBtn" class="btn btn-danger">Force Takeover</button>
+                <button id="cancelTakeoverBtn" class="btn btn-secondary">Cancel</button>
+            </div>
+        </div>
+        
+        <div id="canvas-container">
+            <canvas id="renderCanvas"></canvas>
+        </div>
+        
+        <div class="info">
+            <div class="description-box">
+                <strong>Start/Reset:</strong> Start when idle, Reset when running (clears all state and applies new parameters) • 
+                <strong>Update Text:</strong> Change motion description on-the-fly (no reset needed) • 
+                <strong>Pause/Resume:</strong> Pause/resume generation (preserves all state)
+            </div>
+            <p class="note">💡 First generation requires model loading. Target Motion FPS: 20. Ground trail shows movement path. Use mouse to orbit camera.</p>
+        </div>
+    </div>
+    
+    <!-- Config Modal -->
+    <div id="configModal" class="modal-overlay" style="display: none;">
+        <div class="modal-content">
+            <div class="modal-header">
+                <h2>Config Editor</h2>
+            </div>
+            <div class="modal-body">
+                <div class="config-section">
+                    <h3>Schedule Config</h3>
+                    <div id="scheduleConfigFields"></div>
+                </div>
+                <div class="config-section">
+                    <h3>CFG Config</h3>
+                    <div id="cfgConfigFields"></div>
+                </div>
+                <div class="config-section">
+                    <h3>Runtime Parameters</h3>
+                    <div class="config-field">
+                        <label for="modalHistoryLength">History Length</label>
+                        <input type="number" id="modalHistoryLength" value="">
+                    </div>
+                    <div class="config-field">
+                        <label for="modalSmoothingAlpha">Smoothing α</label>
+                        <div class="slider-container">
+                            <input type="range" id="modalSmoothingAlpha" min="0" max="1" step="0.05" value="0.5">
+                            <span id="modalSmoothingValue" class="slider-value">0.50</span>
+                        </div>
+                        <span class="param-hint">0.0 = max smoothing, 1.0 = no smoothing</span>
+                    </div>
+                </div>
+            </div>
+            <div class="modal-footer">
+                <button class="btn btn-secondary" id="configDiscardBtn">Discard</button>
+                <button class="btn btn-primary" id="configSaveBtn">Update &amp; Reset</button>
+            </div>
+        </div>
+    </div>
+
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/three@0.128.0/examples/js/controls/OrbitControls.js"></script>
+    <script src="/static/js/skeleton.js"></script>
+    <script src="/static/js/main.js"></script>
+</body>
+</html>
+