Upload app code and config

.gitattributes

@@ -1,35 +1 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.mp4 filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,11 @@
+.venv/
+.gradio/
+__pycache__/
+*.pyc
+*.pyo
+*.tmp
+
+results/
+
+.DS_Store
+Thumbs.db

README.md

@@ -1,12 +1,92 @@
 ---
-title: Anyact User Study
-emoji: 📊
-colorFrom: green
-colorTo: red
+title: AnyAct User Study
+colorFrom: blue
+colorTo: indigo
 sdk: gradio
-sdk_version: 6.12.0
+python_version: "3.10"
 app_file: app.py
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# AnyAct User Study
+
+This repository contains a self-contained Gradio questionnaire for pairwise human motion reenactment evaluation.
+
+## Included Data
+
+The Space-ready copy already bundles all 30 study cases inside this repository:
+
+- `videos/reference`
+- `videos/anyact`
+- `videos/vlm_hy_motion`
+- `videos/echomotion`
+
+The app reads those files through `data/study_config.json`, so it no longer depends on directories outside the repository.
+
+## Runtime Storage
+
+By default, the app stores runtime files under:
+
+- `results/responses.csv`
+- `results/responses.jsonl`
+- `results/participants`
+- `results/plots`
+
+For Hugging Face Spaces, you should mount persistent storage and set:
+
+```bash
+USER_STUDY_RESULTS_DIR=/data/user_study_results
+```
+
+If the app is running inside a Space and `/data` exists, it automatically falls back to `/data/user_study_results` even without that variable.
+
+## Local Run
+
+```bash
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -r requirements.txt
+.\.venv\Scripts\python.exe app.py --share
+```
+
+## Hugging Face Spaces Deployment
+
+### Option 1: Browser Upload
+
+1. Create a new Hugging Face Space.
+2. Choose `Gradio` as the SDK.
+3. Upload the contents of this repository.
+4. In the Space settings, optionally add persistent storage and set `USER_STUDY_RESULTS_DIR=/data/user_study_results`.
+
+### Option 2: CLI
+
+```bash
+hf auth login
+deploy_to_hf_space.bat username/space-name
+```
+
+The helper script creates the Space if needed and uploads this repository while excluding `.venv`, `.gradio`, `__pycache__`, and `results`.
+
+## Files That Should Not Be Uploaded As Runtime Artifacts
+
+The repository includes `.gitignore` rules so that local environments and transient results are not pushed by mistake:
+
+- `.venv`
+- `.gradio`
+- `__pycache__`
+- `results`
+
+## Analysis
+
+To analyze collected responses:
+
+```bash
+.\.venv\Scripts\python.exe analyze_results.py
+```
+
+This writes:
+
+- `summary.csv`
+- `participant_overview.csv`
+- `plots/preference_barplot.png`
+
+inside the chosen results directory.

analyze_results.bat

@@ -0,0 +1,33 @@
+@echo off
+setlocal
+
+cd /d "%~dp0"
+
+echo Running result analysis with the project virtual environment...
+
+if not exist ".venv\Scripts\python.exe" (
+    echo [ERROR] Project virtual environment not found: .venv\Scripts\python.exe
+    echo Please create the virtual environment first or run the project setup again.
+    pause
+    exit /b 1
+)
+
+".venv\Scripts\python.exe" "analyze_results.py"
+if errorlevel 1 (
+    echo.
+    echo Analysis failed.
+    pause
+    exit /b 1
+)
+
+echo.
+echo Opening generated outputs...
+
+if exist "results\summary.csv" start "" "results\summary.csv"
+if exist "results\participant_overview.csv" start "" "results\participant_overview.csv"
+if exist "results\plots\preference_barplot.png" start "" "results\plots\preference_barplot.png"
+if exist "results" start "" explorer "results"
+
+echo.
+echo Analysis completed successfully.
+pause

analyze_results.py

@@ -0,0 +1,438 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Dict, List
+
+import matplotlib.pyplot as plt
+import pandas as pd
+
+from study_utils import CSV_COLUMNS, get_results_dir, load_study_config
+
+PROJECT_ROOT = Path(__file__).resolve().parent
+
+METRIC_COLUMNS = {
+    "similarity": "answer_similarity",
+    "quality": "answer_quality",
+    "overall_preference": "answer_preference",
+}
+
+METRIC_LABELS = {
+    "similarity": "Motion Similarity",
+    "quality": "Motion Quality",
+    "overall_preference": "Overall Preference",
+}
+
+METRIC_COLORS = {
+    "similarity": "#cfeedd",
+    "quality": "#cfe8f5",
+    "overall_preference": "#ddd0ee",
+}
+
+METHOD_COLORS = {
+    "anyact": "#7ea6e0",
+    "vlm_hy_motion": "#f2c27b",
+    "echomotion": "#9fd0b0",
+}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Analyze pairwise user study results.")
+    parser.add_argument(
+        "--config",
+        type=Path,
+        default=PROJECT_ROOT / "data" / "study_config.json",
+        help="Path to study_config.json.",
+    )
+    parser.add_argument(
+        "--input",
+        type=Path,
+        default=None,
+        help="Optional path to responses.csv or responses.jsonl. Defaults to results/responses.csv if available.",
+    )
+    parser.add_argument(
+        "--results-dir",
+        type=Path,
+        default=get_results_dir(PROJECT_ROOT),
+        help="Directory that stores responses and analysis outputs.",
+    )
+    parser.add_argument(
+        "--study-id",
+        type=str,
+        default=None,
+        help="Optional study_id to analyze. Defaults to the study_id in study_config.json.",
+    )
+    parser.add_argument(
+        "--include-incomplete",
+        action="store_true",
+        help="Include participants who have not answered every question in the selected study.",
+    )
+    return parser.parse_args()
+
+
+def load_canonical_dataframe(input_path: Path | None, results_dir: Path) -> pd.DataFrame:
+    if input_path is None:
+        csv_path = results_dir / "responses.csv"
+        jsonl_path = results_dir / "responses.jsonl"
+    else:
+        csv_path = input_path if input_path.suffix.lower() == ".csv" else None
+        jsonl_path = input_path if input_path.suffix.lower() == ".jsonl" else None
+
+    latest_records: Dict[tuple[str, str, str], tuple[tuple[str, str, str], Dict[str, object]]] = {}
+
+    if jsonl_path and jsonl_path.exists() and jsonl_path.stat().st_size > 0:
+        with jsonl_path.open("r", encoding="utf-8") as handle:
+            for line in handle:
+                if not line.strip():
+                    continue
+                try:
+                    record = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                if "participant_id" not in record or "question_id" not in record:
+                    continue
+                key = (
+                    str(record.get("study_id", "")),
+                    str(record["participant_id"]),
+                    str(record["question_id"]),
+                )
+                sort_key = (
+                    str(record.get("event_saved_at") or record.get("answered_at") or ""),
+                    str(record.get("updated_at") or ""),
+                    str(record.get("answered_at") or ""),
+                )
+                canonical_row = {column: record.get(column, "") for column in CSV_COLUMNS}
+                previous = latest_records.get(key)
+                if previous is None or sort_key >= previous[0]:
+                    latest_records[key] = (sort_key, canonical_row)
+
+    if csv_path and csv_path.exists() and csv_path.stat().st_size > 0:
+        df = pd.read_csv(csv_path)
+        if not df.empty:
+            for _, row in df.iterrows():
+                record = row.to_dict()
+                if "participant_id" not in record or "question_id" not in record:
+                    continue
+                key = (
+                    str(record.get("study_id", "")),
+                    str(record["participant_id"]),
+                    str(record["question_id"]),
+                )
+                sort_key = (
+                    str(record.get("event_saved_at") or record.get("answered_at") or ""),
+                    str(record.get("updated_at") or ""),
+                    str(record.get("answered_at") or ""),
+                )
+                canonical_row = {column: record.get(column, "") for column in CSV_COLUMNS}
+                previous = latest_records.get(key)
+                if previous is None or sort_key >= previous[0]:
+                    latest_records[key] = (sort_key, canonical_row)
+
+    if latest_records:
+        canonical_df = pd.DataFrame(row for _, row in latest_records.values())
+        if not canonical_df.empty:
+            return canonical_df
+
+    raise FileNotFoundError(
+        "No response file was found. Please ensure results/responses.csv or results/responses.jsonl exists."
+    )
+
+
+def normalize_dataframe(df: pd.DataFrame) -> pd.DataFrame:
+    df = df.copy()
+    for column in ["study_id", "participant_id", "question_id", "left_method", "right_method", "result_a_method", "result_b_method"]:
+        if column in df.columns:
+            df[column] = df[column].astype(str)
+    for column in METRIC_COLUMNS.values():
+        if column in df.columns:
+            df[column] = df[column].fillna("").astype(str).str.strip().str.lower()
+    if "question_position" in df.columns:
+        df["question_position"] = pd.to_numeric(df["question_position"], errors="coerce")
+    if "total_questions" in df.columns:
+        df["total_questions"] = pd.to_numeric(df["total_questions"], errors="coerce")
+    if "answered_at" in df.columns:
+        df["answered_at"] = pd.to_datetime(df["answered_at"], errors="coerce")
+    return df
+
+
+def normalize_choice_for_analysis(raw_value: object) -> str:
+    if pd.isna(raw_value):
+        return ""
+    cleaned = str(raw_value or "").strip().lower()
+    compact = cleaned.replace(" ", "").replace("_", "").replace("-", "")
+    if compact in {"", "nan", "none"}:
+        return ""
+    if compact in {"left", "resulta", "a"}:
+        return "resulta"
+    if compact in {"right", "resultb", "b"}:
+        return "resultb"
+    if compact in {"tie", "equal", "same"}:
+        return "tie"
+    return cleaned
+
+
+def filter_to_selected_study(df: pd.DataFrame, study_id: str) -> pd.DataFrame:
+    if "study_id" not in df.columns:
+        return df
+    filtered = df[df["study_id"].astype(str) == study_id].copy()
+    if filtered.empty:
+        raise ValueError(
+            f"No responses were found for study_id='{study_id}'. "
+            "Please check your study_config.json or pass --study-id explicitly."
+        )
+    return filtered
+
+
+def filter_to_completed_participants(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Keep only participants who answered every question in the selected study.
+    This avoids mixing partial pilot sessions into the final analysis.
+    """
+    rows: List[pd.DataFrame] = []
+
+    for participant_id, participant_df in df.groupby("participant_id", sort=False):
+        expected_questions = int(participant_df["total_questions"].dropna().max())
+        answered_questions = participant_df["question_id"].nunique()
+        if answered_questions >= expected_questions > 0:
+            rows.append(participant_df)
+
+    if not rows:
+        raise ValueError(
+            "No completed participants were found for the selected study. "
+            "Use --include-incomplete if you want to analyze partial responses."
+        )
+
+    return pd.concat(rows, ignore_index=True)
+
+
+def compute_method_percentages(df: pd.DataFrame, config: dict) -> pd.DataFrame:
+    rows: List[dict] = []
+    configured_pairs = [tuple(pair) for pair in config.get("pair_order", [])]
+
+    for pair in configured_pairs:
+        method_a, method_b = pair
+        pair_id = f"{method_a}_vs_{method_b}"
+        pair_df = df[df["pair_id"].astype(str) == pair_id].copy()
+        if pair_df.empty:
+            continue
+
+        pair_method_ids = [method_a, method_b]
+        pair_label = (
+            f"{config['methods'][method_a]['display_name']} vs "
+            f"{config['methods'][method_b]['display_name']}"
+        )
+
+        for metric_name, column_name in METRIC_COLUMNS.items():
+            selected_credit = {method_id: 0.0 for method_id in pair_method_ids}
+            appearances = {method_id: 0 for method_id in pair_method_ids}
+
+            for _, row in pair_df.iterrows():
+                result_a_method = str(row.get("result_a_method") or "").strip()
+                if not result_a_method or result_a_method.lower() == "nan":
+                    result_a_method = str(row.get("left_method") or "").strip()
+
+                result_b_method = str(row.get("result_b_method") or "").strip()
+                if not result_b_method or result_b_method.lower() == "nan":
+                    result_b_method = str(row.get("right_method") or "").strip()
+
+                selected_method = str(row.get(f"{column_name}_method", "") or "").strip()
+                if selected_method.lower() == "nan":
+                    selected_method = ""
+                answer = normalize_choice_for_analysis(row.get(column_name, ""))
+
+                if result_a_method not in selected_credit or result_b_method not in selected_credit:
+                    continue
+
+                appearances[result_a_method] += 1
+                appearances[result_b_method] += 1
+
+                if selected_method in selected_credit:
+                    selected_credit[selected_method] += 1.0
+                elif answer == "left" or answer == "resulta":
+                    selected_credit[result_a_method] += 1.0
+                elif answer == "right" or answer == "resultb":
+                    selected_credit[result_b_method] += 1.0
+                elif answer == "tie":
+                    selected_credit[result_a_method] += 0.5
+                    selected_credit[result_b_method] += 0.5
+
+            for method_id in pair_method_ids:
+                denominator = appearances[method_id]
+                percentage = (selected_credit[method_id] / denominator * 100.0) if denominator else 0.0
+                rows.append(
+                    {
+                        "pair_id": pair_id,
+                        "pair_label": pair_label,
+                        "metric": metric_name,
+                        "metric_label": METRIC_LABELS[metric_name],
+                        "method_id": method_id,
+                        "method_name": config["methods"][method_id]["display_name"],
+                        "selected_credit": round(selected_credit[method_id], 4),
+                        "appearances": denominator,
+                        "selected_percentage": round(percentage, 4),
+                    }
+                )
+
+    return pd.DataFrame(rows)
+
+
+def build_analysis_overview(df: pd.DataFrame, study_id: str) -> pd.DataFrame:
+    participant_stats = (
+        df.groupby("participant_id")
+        .agg(
+            answered_questions=("question_id", "nunique"),
+            total_questions=("total_questions", "max"),
+            first_answered_at=("answered_at", "min"),
+            last_answered_at=("answered_at", "max"),
+        )
+        .reset_index()
+    )
+    participant_stats.insert(1, "study_id", study_id)
+    return participant_stats
+
+
+def plot_summary(summary_df: pd.DataFrame, plot_path: Path, config: dict) -> None:
+    metric_order = ["similarity", "quality", "overall_preference"]
+    metric_positions = list(range(len(metric_order)))
+    pair_order = [tuple(pair) for pair in config.get("pair_order", [])]
+
+    plot_specs: List[dict] = []
+    for pair_index, pair in enumerate(pair_order):
+        method_a, method_b = pair
+        pair_id = f"{method_a}_vs_{method_b}"
+        method_a_name = config["methods"][method_a]["display_name"]
+        method_b_name = config["methods"][method_b]["display_name"]
+        plot_specs.append(
+            {
+                "pair_id": pair_id,
+                "method_id": method_a,
+                "legend_label": f"{method_a_name} (vs {method_b_name})",
+                "color": METHOD_COLORS.get(method_a, "#cbd5e1"),
+                "hatch": None if pair_index == 0 else "//",
+            }
+        )
+        plot_specs.append(
+            {
+                "pair_id": pair_id,
+                "method_id": method_b,
+                "legend_label": method_b_name,
+                "color": METHOD_COLORS.get(method_b, "#cbd5e1"),
+                "hatch": None,
+            }
+        )
+
+    bar_width = 0.16
+    if plot_specs:
+        center = (len(plot_specs) - 1) / 2
+        offsets = [(index - center) * 0.18 for index in range(len(plot_specs))]
+    else:
+        offsets = []
+
+    fig, ax = plt.subplots(figsize=(5.4, 3.5), dpi=300)
+    fig.patch.set_facecolor("white")
+    ax.set_facecolor("white")
+
+    for spec_index, spec in enumerate(plot_specs):
+        method_summary = (
+            summary_df[
+                (summary_df["pair_id"] == spec["pair_id"])
+                & (summary_df["method_id"] == spec["method_id"])
+            ].set_index("metric")
+            .reindex(metric_order)
+        )
+        positions = [center + offsets[spec_index] for center in metric_positions]
+        values = method_summary["selected_percentage"].tolist()
+        bars = ax.bar(
+            positions,
+            values,
+            width=bar_width * 0.92,
+            label=spec["legend_label"],
+            color=spec["color"],
+            edgecolor="white",
+            linewidth=0.6,
+            hatch=spec["hatch"],
+        )
+
+        for bar, value in zip(bars, values):
+            ax.text(
+                bar.get_x() + bar.get_width() / 2,
+                value + 1.4,
+                f"{value:.1f}%",
+                va="bottom",
+                ha="center",
+                fontsize=8,
+                color="#334155",
+            )
+
+    ax.set_xticks(metric_positions)
+    ax.set_xticklabels([METRIC_LABELS[metric_name] for metric_name in metric_order], fontsize=8)
+    ax.set_ylabel("Selection Rate When Shown (%)", fontsize=8)
+
+    x_max = max(100.0, float(summary_df["selected_percentage"].max()) + 8.0)
+    ax.set_ylim(0, x_max)
+    ax.tick_params(axis="y", labelsize=8)
+    ax.tick_params(axis="x", length=0)
+    ax.grid(axis="y", color="#edf2f7", linewidth=0.8)
+    ax.set_axisbelow(True)
+    ax.spines["top"].set_visible(False)
+    ax.spines["right"].set_visible(False)
+    ax.legend(
+        frameon=False,
+        fontsize=7.0,
+        loc="upper center",
+        bbox_to_anchor=(0.5, 1.12),
+        ncol=2,
+        handlelength=1.2,
+        columnspacing=1.2,
+    )
+    plt.tight_layout(pad=0.7)
+
+    plot_path.parent.mkdir(parents=True, exist_ok=True)
+    fig.savefig(plot_path, bbox_inches="tight", dpi=300)
+    pdf_path = plot_path.with_suffix(".pdf")
+    fig.savefig(pdf_path, bbox_inches="tight")
+    plt.close(fig)
+
+
+def main() -> None:
+    args = parse_args()
+    config = load_study_config(args.config)
+    study_id = args.study_id or config["study_id"]
+    results_dir = args.results_dir.resolve()
+    results_dir.mkdir(parents=True, exist_ok=True)
+    (results_dir / "plots").mkdir(parents=True, exist_ok=True)
+
+    df = load_canonical_dataframe(args.input, results_dir)
+    df = normalize_dataframe(df)
+    if df.empty:
+        raise ValueError("The response table is empty. No analysis output was generated.")
+
+    df = filter_to_selected_study(df, study_id)
+    if not args.include_incomplete:
+        df = filter_to_completed_participants(df)
+
+    summary_df = compute_method_percentages(df, config)
+    overview_df = build_analysis_overview(df, study_id)
+
+    summary_path = results_dir / "summary.csv"
+    overview_path = results_dir / "participant_overview.csv"
+    plot_path = results_dir / "plots" / "preference_barplot.png"
+
+    summary_df.to_csv(summary_path, index=False)
+    overview_df.to_csv(overview_path, index=False)
+    plot_summary(summary_df, plot_path, config)
+
+    participant_count = overview_df["participant_id"].nunique()
+    response_count = df["question_id"].nunique()
+
+    print(f"Study ID: {study_id}")
+    print(f"Participants analyzed: {participant_count}")
+    print(f"Unique questions covered: {response_count}")
+    print(f"Saved summary table to: {summary_path}")
+    print(f"Saved participant overview to: {overview_path}")
+    print(f"Saved plot to: {plot_path}")
+
+
+if __name__ == "__main__":
+    main()

app.py

@@ -0,0 +1,2092 @@
+from __future__ import annotations
+
+import argparse
+import base64
+import html
+import os
+import re
+import shutil
+import subprocess
+import warnings
+from pathlib import Path
+from typing import Any, Tuple
+
+import gradio as gr
+from gradio import processing_utils as gr_processing_utils
+
+try:
+    import imageio_ffmpeg
+except ImportError:  # pragma: no cover - optional runtime dependency
+    imageio_ffmpeg = None
+
+from study_utils import (
+    CHOICE_OPTIONS,
+    build_completion_markdown,
+    build_question_payload,
+    create_or_resume_participant,
+    ensure_runtime_dirs,
+    ensure_video_thumbnail,
+    generate_participant_id,
+    get_instruction_case,
+    get_results_dir,
+    load_study_config,
+    move_question_pointer,
+    prepare_reference_videos_for_web,
+    sanitize_participant_id,
+    save_current_answer,
+    ensure_synchronized_study_videos,
+    upgrade_existing_results_schema,
+)
+
+PROJECT_ROOT = Path(__file__).resolve().parent
+
+
+def default_server_name() -> str:
+    return "0.0.0.0" if os.environ.get("SPACE_ID") else "127.0.0.1"
+
+
+def ensure_local_ffmpeg() -> None:
+    if imageio_ffmpeg is None:
+        return
+
+    ffmpeg_source = Path(imageio_ffmpeg.get_ffmpeg_exe()).resolve()
+    runtime_bin = get_results_dir(PROJECT_ROOT) / "runtime_bin"
+    runtime_bin.mkdir(parents=True, exist_ok=True)
+    ffmpeg_target = runtime_bin / "ffmpeg.exe"
+
+    if not ffmpeg_target.exists():
+        shutil.copy2(ffmpeg_source, ffmpeg_target)
+
+    os.environ["IMAGEIO_FFMPEG_EXE"] = str(ffmpeg_target)
+    current_path = os.environ.get("PATH", "")
+    runtime_bin_str = str(runtime_bin)
+    if runtime_bin_str.lower() not in current_path.lower():
+        os.environ["PATH"] = runtime_bin_str + os.pathsep + current_path
+
+
+def _probe_video_codec_with_ffmpeg(video_path: str | Path) -> tuple[str, str]:
+    if imageio_ffmpeg is None:
+        return "", ""
+
+    path = Path(video_path)
+    ffmpeg_exe = imageio_ffmpeg.get_ffmpeg_exe()
+    result = subprocess.run(
+        [ffmpeg_exe, "-i", str(path)],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="ignore",
+    )
+    probe_text = result.stderr or ""
+    codec_match = re.search(r"Video:\s*([^\s,(]+)", probe_text)
+    codec_name = (codec_match.group(1) if codec_match else "").strip().lower()
+    return path.suffix.lower(), codec_name
+
+
+def patched_video_is_playable(video_filepath: str) -> bool:
+    """
+    Avoid Gradio's hard dependency on ffprobe by checking playability
+    with the bundled imageio-ffmpeg binary instead.
+    """
+    try:
+        container, video_codec = _probe_video_codec_with_ffmpeg(video_filepath)
+        return (container, video_codec) in {
+            (".mp4", "h264"),
+            (".mp4", "av1"),
+            (".ogg", "theora"),
+            (".webm", "vp9"),
+            (".webm", "vp8"),
+            (".webm", "av1"),
+        }
+    except Exception:
+        return True
+
+
+def patch_gradio_video_probe() -> None:
+    gr_processing_utils.video_is_playable = patched_video_is_playable
+
+warnings.filterwarnings(
+    "ignore",
+    message=r"The 'css' parameter in the Blocks constructor will be removed in Gradio 6\.0\..*",
+    category=DeprecationWarning,
+)
+warnings.filterwarnings(
+    "ignore",
+    message=r"The 'theme' parameter in the Blocks constructor will be removed in Gradio 6\.0\..*",
+    category=DeprecationWarning,
+)
+warnings.filterwarnings(
+    "ignore",
+    message=r"The 'head' parameter in the Blocks constructor will be removed in Gradio 6\.0\..*",
+    category=DeprecationWarning,
+)
+
+CUSTOM_HEAD = """
+<script>
+function anyactForceLightTheme() {
+  document.documentElement.classList.remove("dark");
+  document.body.classList.remove("dark");
+  document.documentElement.setAttribute("data-theme", "light");
+  document.body.setAttribute("data-theme", "light");
+  document.documentElement.style.colorScheme = "light";
+  document.body.style.colorScheme = "light";
+  try {
+    localStorage.setItem("theme", "light");
+    localStorage.setItem("gradio-theme", "light");
+    localStorage.setItem("gradio_mode", "light");
+  } catch (error) {}
+  document.querySelectorAll(".dark").forEach((node) => node.classList.remove("dark"));
+}
+
+function anyactForcePlayVideos() {
+  const videos = document.querySelectorAll("video");
+  videos.forEach((video) => {
+    if (!video) return;
+    const attemptPlay = () => video.play().catch(() => {
+      video.muted = true;
+      video.play().catch(() => {});
+    });
+    if (video.readyState >= 2) {
+      attemptPlay();
+    } else {
+      video.addEventListener("loadeddata", attemptPlay, { once: true });
+    }
+  });
+}
+
+function anyactGetStudyVideoElement(elemId) {
+  const root = document.getElementById(elemId);
+  return root ? root.querySelector("video") : null;
+}
+
+function anyactSetupStudyVideoSync() {
+  const reference = anyactGetStudyVideoElement("study-reference-video");
+  const left = anyactGetStudyVideoElement("study-left-video");
+  const right = anyactGetStudyVideoElement("study-right-video");
+
+  if (!reference || !left || !right) {
+    if (window.__anyactStudySync && typeof window.__anyactStudySync.cleanup === "function") {
+      window.__anyactStudySync.cleanup();
+    }
+    window.__anyactStudySync = null;
+    return;
+  }
+
+  const trio = [reference, left, right];
+  const signature = trio.map((video) => video.currentSrc || video.src || "").join("|");
+  if (window.__anyactStudySync && window.__anyactStudySync.signature === signature) {
+    return;
+  }
+
+  if (window.__anyactStudySync && typeof window.__anyactStudySync.cleanup === "function") {
+    window.__anyactStudySync.cleanup();
+  }
+
+  let suppressEvents = false;
+  let lastReferenceTime = 0;
+  const cleanupFns = [];
+
+  const withSuppressedEvents = (fn) => {
+    suppressEvents = true;
+    try {
+      fn();
+    } finally {
+      clearTimeout(window.__anyactStudySyncSuppressTimer);
+      window.__anyactStudySyncSuppressTimer = setTimeout(() => {
+        suppressEvents = false;
+      }, 120);
+    }
+  };
+
+  const syncTimes = (masterVideo, force = false) => {
+    const targetTime = Number.isFinite(masterVideo.currentTime) ? masterVideo.currentTime : 0;
+    trio.forEach((video) => {
+      if (video === masterVideo) return;
+      if (force || Math.abs((video.currentTime || 0) - targetTime) > 0.05) {
+        try {
+          video.currentTime = targetTime;
+        } catch (error) {}
+      }
+    });
+  };
+
+  const syncPlaybackRate = (masterVideo) => {
+    trio.forEach((video) => {
+      if (video === masterVideo) return;
+      if (video.playbackRate !== masterVideo.playbackRate) {
+        video.playbackRate = masterVideo.playbackRate;
+      }
+    });
+  };
+
+  const playAll = (masterVideo = reference) => {
+    withSuppressedEvents(() => {
+      syncTimes(masterVideo, true);
+      syncPlaybackRate(masterVideo);
+    });
+    trio.forEach((video) => {
+      video.loop = true;
+      video.muted = true;
+      video.playsInline = true;
+      const playPromise = video.play();
+      if (playPromise && typeof playPromise.catch === "function") {
+        playPromise.catch(() => {});
+      }
+    });
+  };
+
+  const pauseOthers = (sourceVideo) => {
+    trio.forEach((video) => {
+      if (video === sourceVideo) return;
+      if (!video.paused) {
+        try {
+          video.pause();
+        } catch (error) {}
+      }
+    });
+  };
+
+  const restartAll = () => {
+    withSuppressedEvents(() => {
+      trio.forEach((video) => {
+        try {
+          video.pause();
+        } catch (error) {}
+        try {
+          video.currentTime = 0;
+        } catch (error) {}
+      });
+    });
+    playAll(reference);
+  };
+
+  const bind = (video, eventName, handler) => {
+    video.addEventListener(eventName, handler);
+    cleanupFns.push(() => video.removeEventListener(eventName, handler));
+  };
+
+  trio.forEach((video) => {
+    video.loop = true;
+    video.muted = true;
+    video.playsInline = true;
+
+    bind(video, "play", () => {
+      if (suppressEvents) return;
+      playAll(video);
+    });
+
+    bind(video, "pause", () => {
+      if (suppressEvents) return;
+      withSuppressedEvents(() => {
+        pauseOthers(video);
+      });
+    });
+
+    bind(video, "seeked", () => {
+      if (suppressEvents) return;
+      withSuppressedEvents(() => {
+        syncTimes(video, true);
+      });
+    });
+
+    bind(video, "ratechange", () => {
+      if (suppressEvents) return;
+      withSuppressedEvents(() => {
+        syncPlaybackRate(video);
+      });
+    });
+
+    bind(video, "loadeddata", () => {
+      if (trio.every((item) => item.readyState >= 2)) {
+        playAll(reference);
+      }
+    });
+  });
+
+  bind(reference, "ended", () => {
+    if (suppressEvents) return;
+    restartAll();
+  });
+
+  const driftTimer = setInterval(() => {
+    const currentReferenceTime = Number.isFinite(reference.currentTime) ? reference.currentTime : 0;
+    const loopWrapped = lastReferenceTime > 0.35 && currentReferenceTime + 0.2 < lastReferenceTime;
+    if (loopWrapped) {
+      withSuppressedEvents(() => {
+        syncTimes(reference, true);
+        syncPlaybackRate(reference);
+      });
+      if (!reference.paused) {
+        trio.forEach((video) => {
+          const playPromise = video.play();
+          if (playPromise && typeof playPromise.catch === "function") {
+            playPromise.catch(() => {});
+          }
+        });
+      }
+    }
+    lastReferenceTime = currentReferenceTime;
+    if (document.hidden || reference.paused) return;
+    syncTimes(reference, false);
+  }, 200);
+  cleanupFns.push(() => clearInterval(driftTimer));
+
+  window.__anyactStudySync = {
+    signature,
+    cleanup: () => {
+      cleanupFns.forEach((cleanup) => {
+        try {
+          cleanup();
+        } catch (error) {}
+      });
+    },
+  };
+
+  if (trio.every((video) => video.readyState >= 2)) {
+    playAll(reference);
+  }
+}
+
+window.addEventListener("load", () => {
+  anyactForceLightTheme();
+  anyactForcePlayVideos();
+  anyactSetupStudyVideoSync();
+  const observer = new MutationObserver(() => {
+    clearTimeout(window.__anyactVideoTimer);
+    window.__anyactVideoTimer = setTimeout(() => {
+      anyactForceLightTheme();
+      anyactForcePlayVideos();
+      anyactSetupStudyVideoSync();
+    }, 250);
+  });
+  observer.observe(document.body, { childList: true, subtree: true, attributes: true });
+});
+</script>
+"""
+
+CUSTOM_CSS = """
+:root,
+html,
+body {
+    color-scheme: light !important;
+    background: #eef2f7 !important;
+    color: #0f172a !important;
+}
+
+.gradio-container {
+    max-width: 1380px !important;
+    margin: 0 auto !important;
+    padding-bottom: 32px !important;
+    font-family: "Segoe UI", "Helvetica Neue", sans-serif !important;
+    background:
+        radial-gradient(circle at top left, rgba(203, 213, 225, 0.26), transparent 28%),
+        linear-gradient(180deg, #f7f8fb 0%, #eef2f7 100%);
+}
+
+.gradio-container,
+.gradio-container *,
+.gradio-container .dark,
+.gradio-container .dark * {
+    --body-background-fill: #f7f8fb !important;
+    --body-background-fill-subdued: #eef2f7 !important;
+    --background-fill-primary: #ffffff !important;
+    --background-fill-secondary: #f8fafc !important;
+    --block-background-fill: #ffffff !important;
+    --block-border-color: #d8dee8 !important;
+    --panel-background-fill: #ffffff !important;
+    --panel-border-color: #d8dee8 !important;
+    --input-background-fill: #ffffff !important;
+    --input-border-color: #cbd5e1 !important;
+    --checkbox-background-color: #ffffff !important;
+    --checkbox-border-color: #94a3b8 !important;
+    --checkbox-label-text-color: #0f172a !important;
+    --body-text-color: #0f172a !important;
+    --block-label-text-color: #0f172a !important;
+    --block-title-text-color: #0f172a !important;
+    --button-secondary-background-fill: #ffffff !important;
+    --button-secondary-text-color: #1d4ed8 !important;
+}
+
+.gradio-container div,
+.gradio-container section,
+.gradio-container article,
+.gradio-container form,
+.gradio-container fieldset,
+.gradio-container label,
+.gradio-container [data-testid="block"],
+.gradio-container [data-testid="textbox"],
+.gradio-container [data-testid="checkbox"],
+.gradio-container [data-testid="radio"],
+.gradio-container [data-testid="markdown"],
+.gradio-container [data-testid="group"] {
+    color: #0f172a !important;
+}
+
+.gradio-container,
+.gradio-container .prose,
+.gradio-container .prose p,
+.gradio-container .prose li,
+.gradio-container .prose strong,
+.gradio-container .prose h1,
+.gradio-container .prose h2,
+.gradio-container .prose h3,
+.gradio-container .prose h4,
+.gradio-container label,
+.gradio-container p,
+.gradio-container li,
+.gradio-container h1,
+.gradio-container h2,
+.gradio-container h3,
+.gradio-container h4 {
+    color: #0f172a !important;
+}
+
+.block-title h1,
+.block-title h2,
+.section-heading {
+    font-family: "Libre Baskerville", Georgia, serif !important;
+}
+
+.hero-card,
+.panel-card,
+.form-card {
+    background: rgba(255, 255, 255, 0.96);
+    border: 1px solid #d8dee8;
+    border-radius: 20px;
+    box-shadow: 0 14px 40px rgba(15, 23, 42, 0.06);
+}
+
+.hero-card {
+    padding: 28px 30px;
+}
+
+.panel-card {
+    padding: 22px 24px;
+}
+
+.form-card {
+    padding: 18px;
+}
+
+.form-card textarea,
+.form-card input {
+    background: #ffffff !important;
+    color: #0f172a !important;
+}
+
+.form-card,
+.question-card,
+.form-card > div,
+.question-card > div,
+.form-card [data-testid],
+.question-card [data-testid],
+.form-card .prose,
+.question-card .prose,
+.hero-card [data-testid],
+.panel-card [data-testid] {
+    background: #ffffff !important;
+    color: #0f172a !important;
+}
+
+.gradio-container input,
+.gradio-container textarea,
+.gradio-container select {
+    background: #ffffff !important;
+    color: #0f172a !important;
+}
+
+.gradio-container [data-testid="checkbox"],
+.gradio-container [data-testid="checkbox"] * {
+    background: transparent !important;
+    color: #0f172a !important;
+}
+
+.gradio-container [data-testid="textbox"],
+.gradio-container [data-testid="textbox"] > *,
+.gradio-container [data-testid="textbox"] textarea,
+.gradio-container [data-testid="textbox"] input {
+    background: #ffffff !important;
+    color: #0f172a !important;
+}
+
+.gradio-container [data-testid="markdown"],
+.gradio-container [data-testid="markdown"] > *,
+.gradio-container [data-testid="group"],
+.gradio-container [data-testid="group"] > * {
+    background: transparent !important;
+    color: #0f172a !important;
+}
+
+.instruction-shell {
+    display: flex;
+    flex-direction: column;
+    gap: 20px;
+}
+
+.instruction-top {
+    display: grid;
+    grid-template-columns: 1.02fr 0.98fr;
+    gap: 20px;
+    align-items: start;
+}
+
+.instruction-copy {
+    display: flex;
+    flex-direction: column;
+    gap: 16px;
+}
+
+.instruction-top-right {
+    display: flex;
+    flex-direction: column;
+    gap: 16px;
+}
+
+.lead-text {
+    color: #334155;
+    font-size: 17px;
+    line-height: 1.6;
+    margin: 0;
+}
+
+.instruction-list {
+    margin: 0;
+    padding-left: 20px;
+    color: #334155;
+    line-height: 1.6;
+}
+
+.example-caption-note {
+    margin: 0 0 10px 0;
+    padding: 10px 14px;
+    border-radius: 14px;
+    border: 1px solid #d9e2ec;
+    background: #f8fbff;
+    color: #334155;
+    line-height: 1.6;
+}
+
+.instruction-bottom {
+    display: grid;
+    grid-template-columns: 1.08fr 0.92fr;
+    gap: 20px;
+    align-items: start;
+}
+
+.instruction-bottom-left,
+.instruction-bottom-right {
+    display: flex;
+    flex-direction: column;
+    gap: 14px;
+}
+
+.metric-card {
+    border: 1px solid #d9e2ec;
+    border-radius: 16px;
+    padding: 16px;
+    background: #fbfcfe;
+}
+
+.metric-card h4 {
+    margin: 0 0 8px 0;
+    font-size: 17px;
+    color: #0f172a;
+}
+
+.metric-card p {
+    margin: 0;
+    color: #475569;
+    line-height: 1.55;
+}
+
+.metric-stack {
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+    margin-top: 14px;
+}
+
+.diagram-card {
+    border: 1px solid #d9e2ec;
+    border-radius: 18px;
+    padding: 18px;
+    background: linear-gradient(180deg, #ffffff 0%, #f8fafc 100%);
+}
+
+.case-walkthrough {
+    display: flex;
+    flex-direction: column;
+    gap: 14px;
+}
+
+.case-walkthrough-head h3 {
+    margin: 0;
+    font-size: 24px;
+    color: #0f172a;
+    font-family: "Libre Baskerville", Georgia, serif !important;
+}
+
+.case-walkthrough-head p {
+    margin: 6px 0 0 0;
+    color: #475569;
+    line-height: 1.55;
+}
+
+.walkthrough-grid {
+    display: grid;
+    grid-template-columns: 1.15fr 1fr 1fr;
+    gap: 12px;
+}
+
+.thumb-card {
+    background: #ffffff;
+    border: 1px solid #d8e2ef;
+    border-radius: 16px;
+    overflow: hidden;
+    box-shadow: 0 10px 24px rgba(15, 23, 42, 0.05);
+}
+
+.thumb-card.ref-card {
+    border-color: #93c5fd;
+}
+
+.thumb-image {
+    aspect-ratio: 1.2 / 1;
+    background: #eef2f7;
+    overflow: hidden;
+}
+
+.thumb-image img {
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+    display: block;
+}
+
+.thumb-body {
+    padding: 12px 13px 14px;
+}
+
+.thumb-title {
+    display: inline-block;
+    font-size: 12px;
+    font-weight: 700;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+    color: #1d4ed8;
+    background: #dbeafe;
+    border-radius: 999px;
+    padding: 5px 9px;
+    margin-bottom: 8px;
+}
+
+.thumb-card.candidate-card .thumb-title {
+    color: #0f172a;
+    background: #eaf1fb;
+}
+
+.thumb-body h4 {
+    margin: 0 0 6px 0;
+    font-size: 17px;
+    color: #0f172a;
+}
+
+.thumb-body p {
+    margin: 0;
+    font-size: 14px;
+    color: #475569;
+    line-height: 1.5;
+}
+
+.walkthrough-note {
+    border: 1px solid #d9e2ec;
+    border-radius: 16px;
+    background: #ffffff;
+    padding: 14px 15px;
+}
+
+.walkthrough-note > strong {
+    display: block;
+    color: #0f172a;
+    margin-bottom: 6px;
+    font-size: 15px;
+}
+
+.walkthrough-note p {
+    margin: 0;
+    color: #475569;
+    line-height: 1.6;
+}
+
+.walkthrough-note p + p {
+    margin-top: 10px;
+}
+
+.walkthrough-note p strong {
+    display: inline;
+    margin: 0;
+    font-size: inherit;
+    color: #0f172a;
+}
+
+.walkthrough-note.accent-note {
+    background: linear-gradient(180deg, #eff6ff 0%, #ffffff 100%);
+    border-color: #bfdbfe;
+}
+
+.progress-chip {
+    display: inline-block;
+    padding: 8px 14px;
+    border-radius: 999px;
+    background: #0f172a;
+    color: white;
+    font-weight: 700;
+    letter-spacing: 0.01em;
+}
+
+.meta-line {
+    margin-top: 8px;
+    color: #475569;
+    font-size: 15px;
+}
+
+.study-shell .gr-video {
+    border-radius: 16px !important;
+    overflow: hidden !important;
+    border: 1px solid #dbe2ea !important;
+    background: #f8fafc !important;
+}
+
+.gradio-container video {
+    background: #0f172a !important;
+}
+
+.video-panel {
+    background: #ffffff;
+}
+
+.reference-panel {
+    border: 1px solid #bfdbfe !important;
+    box-shadow: 0 12px 28px rgba(37, 99, 235, 0.08);
+}
+
+.candidate-panel {
+    border: 1px solid #dbe4ee !important;
+}
+
+.video-caption {
+    color: #475569;
+    font-size: 14px;
+    margin-top: -4px;
+    margin-bottom: 10px;
+}
+
+.question-card {
+    padding: 18px 20px;
+    border-radius: 18px;
+    border: 1px solid #d9e2ec;
+    background: rgba(255, 255, 255, 0.9);
+}
+
+.choice-input {
+    margin-top: 8px;
+}
+
+.choice-input fieldset {
+    border: 1px solid #d7e3f4 !important;
+    border-radius: 16px !important;
+    background: #f8fbff !important;
+    padding: 12px 14px !important;
+}
+
+.choice-input label {
+    border: 1px solid #cbdcf5 !important;
+    border-radius: 12px !important;
+    background: #ffffff !important;
+    padding: 10px 12px !important;
+    color: #1e293b !important;
+    font-weight: 600 !important;
+    transition: all 0.2s ease !important;
+}
+
+.choice-input label:hover {
+    border-color: #60a5fa !important;
+    background: #eff6ff !important;
+}
+
+.choice-input label:has(input:checked) {
+    border-color: #3b82f6 !important;
+    background: linear-gradient(180deg, #dbeafe 0%, #eff6ff 100%) !important;
+    color: #1d4ed8 !important;
+    box-shadow: 0 0 0 1px rgba(59, 130, 246, 0.12) !important;
+}
+
+.choice-input input[type="radio"] {
+    accent-color: #2563eb !important;
+}
+
+.gradio-container button {
+    transition: transform 0.15s ease, box-shadow 0.15s ease !important;
+}
+
+.gradio-container button.primary {
+    background: linear-gradient(180deg, #2563eb 0%, #1d4ed8 100%) !important;
+    color: #ffffff !important;
+    border: none !important;
+    box-shadow: 0 8px 20px rgba(37, 99, 235, 0.18) !important;
+}
+
+.gradio-container button.primary:hover {
+    transform: translateY(-1px);
+    box-shadow: 0 12px 24px rgba(37, 99, 235, 0.22) !important;
+}
+
+.gradio-container button.secondary {
+    background: #ffffff !important;
+    color: #1d4ed8 !important;
+    border: 1px solid #bfdbfe !important;
+}
+
+.language-switch-row {
+    justify-content: flex-end;
+    margin-bottom: 8px;
+}
+
+.language-switch {
+    min-width: 210px;
+}
+
+.language-switch fieldset {
+    border: 1px solid #cfe0fb !important;
+    border-radius: 999px !important;
+    background: rgba(255, 255, 255, 0.92) !important;
+    padding: 6px !important;
+    box-shadow: 0 8px 20px rgba(37, 99, 235, 0.08) !important;
+}
+
+.language-switch label {
+    border: none !important;
+    border-radius: 999px !important;
+    background: transparent !important;
+    color: #475569 !important;
+    min-height: 38px !important;
+    padding: 8px 16px !important;
+    font-weight: 700 !important;
+    transition: all 0.18s ease !important;
+}
+
+.language-switch label:hover {
+    background: #eff6ff !important;
+    color: #1d4ed8 !important;
+}
+
+.language-switch label:has(input:checked) {
+    background: linear-gradient(180deg, #2563eb 0%, #1d4ed8 100%) !important;
+    color: #ffffff !important;
+    box-shadow: 0 8px 16px rgba(37, 99, 235, 0.18) !important;
+}
+
+.language-switch input[type="radio"] {
+    display: none !important;
+}
+
+.thank-card {
+    max-width: 760px;
+    margin: 0 auto;
+    padding: 28px 30px;
+    text-align: left;
+}
+
+.muted-caption {
+    color: #64748b;
+    font-size: 14px;
+}
+
+@media (max-width: 900px) {
+    .instruction-top,
+    .instruction-bottom,
+    .walkthrough-grid {
+        grid-template-columns: 1fr;
+    }
+}
+"""
+
+
+LANGUAGE_CHOICES = [("English", "en"), ("中文", "zh")]
+LANGUAGE_SWITCH_LABEL = "Language / 语言"
+
+TEXT = {
+    "en": {
+        "language_label": "Language",
+        "study_title": "Human Motion Reenactment User Study",
+        "example_comparison": "Example Comparison",
+        "reference_video": "Reference Video",
+        "candidate_a": "Result A",
+        "candidate_b": "Result B",
+        "reference_caption": "Reference",
+        "result_a_caption": "Result A",
+        "result_b_caption": "Result B",
+        "result_a_left": "Result A",
+        "result_b_right": "Result B",
+        "participant_id_label": "Participant ID (read-only)",
+        "participant_setup_title": "Participant Setup",
+        "generate_fresh_id": "Generate Fresh Participant ID",
+        "start_continue": "Start / Continue Study",
+        "previous": "Previous",
+        "next": "Next",
+        "submit_study": "Submit Study",
+        "question_similarity": "Which result better matches the reference motion?",
+        "question_quality": "Which result has better motion quality?",
+        "question_preference": "Which result do you overall prefer?",
+        "left_choice": "Result A",
+        "right_choice": "Result B",
+        "saved_progress_restored": "Saved progress restored.",
+        "answer_all_required": "Please answer all three questions before continuing.",
+        "session_empty": "Session state was empty. Please return to the start page and continue this browser session.",
+        "browser_saved_id_notice": (
+            "This browser already has a saved participant ID. Click **Start / Continue Study** "
+            "to resume the same session safely."
+        ),
+        "fresh_id_notice": (
+            "A fresh participant ID has been created for this browser. "
+            "Use it only if you are starting a brand-new session."
+        ),
+        "completed_id_notice": (
+            "This participant ID has already completed the study. "
+            "Generate a fresh ID if you need a brand-new session on this browser."
+        ),
+        "study_instruction": "Watch the reference clip and both anonymous results before answering the three questions on Motion Similarity, Motion Quality, and Overall Preference.",
+        "question_word": "Question",
+        "saved_responses": "Saved responses",
+        "participant_id_meta": "Participant ID",
+        "thank_you_title": "Thank you for completing the study.",
+        "thank_you_saved": "Your responses have been saved successfully.",
+        "thank_you_completed_at": "Completed at",
+        "thank_you_close": "You may now close this page.",
+    },
+    "zh": {
+        "language_label": "语言",
+        "study_title": "人体动作重演用户研究",
+        "example_comparison": "示例对比",
+        "reference_video": "参考视频",
+        "candidate_a": "结果 A",
+        "candidate_b": "结果 B",
+        "reference_caption": "参考视频",
+        "result_a_caption": "结果 A",
+        "result_b_caption": "结果 B",
+        "result_a_left": "结果 A",
+        "result_b_right": "结果 B",
+        "participant_id_label": "参与者编号（只读）",
+        "participant_setup_title": "参与者设置",
+        "generate_fresh_id": "生成新的参与者编号",
+        "start_continue": "开始 / 继续问卷",
+        "previous": "上一题",
+        "next": "下一题",
+        "submit_study": "提交问卷",
+        "question_similarity": "哪个结果与参考动作更匹配？",
+        "question_quality": "哪个结果的动作质量更好？",
+        "question_preference": "你整体更偏好哪个结果？",
+        "left_choice": "结果 A",
+        "right_choice": "结果 B",
+        "saved_progress_restored": "已恢复先前保存的进度。",
+        "answer_all_required": "请先回答完这三个问题，再继续下一题。",
+        "session_empty": "当前会话为空。请返回起始页后继续此浏览器中的问卷会话。",
+        "browser_saved_id_notice": (
+            "当前浏览器已保存参与者编号。点击 **开始 / 继续问卷** 可安全地恢复同一会话。"
+        ),
+        "fresh_id_notice": (
+            "当前浏览器已生成一个新的参与者编号。仅当你需要开始一个全新的问卷会话时再使用它。"
+        ),
+        "completed_id_notice": (
+            "该参与者编号已经完成本次问卷。若你需要在此浏览器中开始全新会话，请生成新的编号。"
+        ),
+        "study_instruction": "请先观看参考视频和两个匿名结果，再回答动作相似性、动作质量和整体偏好这三个问题。",
+        "question_word": "题目",
+        "saved_responses": "已保存回答",
+        "participant_id_meta": "参与者编号",
+        "thank_you_title": "感谢你完成本次问卷。",
+        "thank_you_saved": "你的回答已成功保存。",
+        "thank_you_completed_at": "完成时间",
+        "thank_you_close": "现在可以关闭此页面。",
+    },
+}
+
+
+def normalize_language(language: str | None) -> str:
+    return language if language in TEXT else "en"
+
+
+def tr(language: str | None, key: str, **kwargs: Any) -> str:
+    return TEXT[normalize_language(language)][key].format(**kwargs)
+
+
+def choice_options_for_language(language: str | None) -> list[tuple[str, str]]:
+    language = normalize_language(language)
+    return [
+        (tr(language, "left_choice"), "ResultA"),
+        (tr(language, "right_choice"), "ResultB"),
+    ]
+
+
+def video_caption_html(text: str) -> str:
+    return f"<div class='video-caption'>{html.escape(text)}</div>"
+
+
+def build_participant_setup_markdown(language: str | None) -> str:
+    language = normalize_language(language)
+    if language == "zh":
+        return """
+### 参与者设置
+
+当前公开问卷链接会为本浏览器自动创建并保存参与者编号。之后如果你仍使用同一浏览器再次访问，就可以自动恢复同一份作答进度，而无需手动输入编号。
+
+只有在你希望于当前浏览器中开始一个全新的作答会话时，才需要点击 **生成新的参与者编号**。请不要将下方显示的编号分享给其他参与者。
+""".strip()
+
+    return """
+### Participant Setup
+
+This public study link now creates and stores a participant ID automatically for the current browser. Returning on the
+same browser will safely continue the same session without asking you to type an ID manually.
+
+Use **Generate Fresh Participant ID** only when starting a completely new participation on this browser. Please do not
+share the ID shown below with other participants.
+""".strip()
+
+
+def build_progress_markdown(state: dict[str, Any], language: str | None) -> str:
+    question = state["questions"][state["current_index"]]
+    answered_count = len(state.get("answers", {}))
+    language = normalize_language(language)
+    if language == "zh":
+        return (
+            f"<div class='meta-line'>{tr(language, 'participant_id_meta')}: <code>{state['participant_id']}</code></div>"
+            f"<div class='meta-line'>{tr(language, 'saved_responses')}: {answered_count} / {question['total_questions']}</div>"
+        )
+
+    return (
+        f"<div class='meta-line'>{tr(language, 'participant_id_meta')}: <code>{state['participant_id']}</code></div>"
+        f"<div class='meta-line'>{tr(language, 'saved_responses')}: {answered_count} / {question['total_questions']}</div>"
+    )
+
+
+def build_completion_markdown_local(state: dict[str, Any], language: str | None) -> str:
+    completed_at = state.get("completed_at") or ""
+    total_questions = len(state.get("questions", []))
+    answered_count = len(state.get("answers", {}))
+    language = normalize_language(language)
+    if language == "zh":
+        return f"""
+## {tr(language, "thank_you_title")}
+
+{tr(language, "thank_you_saved")}
+
+- {tr(language, "participant_id_meta")}: `{state["participant_id"]}`
+- {tr(language, "saved_responses")}: `{answered_count} / {total_questions}`
+- {tr(language, "thank_you_completed_at")}: `{completed_at}`
+
+{tr(language, "thank_you_close")}
+""".strip()
+
+    return f"""
+## {tr(language, "thank_you_title")}
+
+{tr(language, "thank_you_saved")}
+
+- {tr(language, "participant_id_meta")}: `{state["participant_id"]}`
+- {tr(language, "saved_responses")}: `{answered_count} / {total_questions}`
+- {tr(language, "thank_you_completed_at")}: `{completed_at}`
+
+{tr(language, "thank_you_close")}
+""".strip()
+
+
+def image_to_data_uri(image_path: str | Path) -> str:
+    path = Path(image_path)
+    if not path.exists():
+        return ""
+    suffix = path.suffix.lower()
+    mime_type = "image/jpeg" if suffix in {".jpg", ".jpeg"} else "image/png"
+    encoded = base64.b64encode(path.read_bytes()).decode("ascii")
+    return f"data:{mime_type};base64,{encoded}"
+
+
+def build_instruction_case_html(intro_case: dict[str, Any], language: str | None) -> str:
+    reference_thumb = image_to_data_uri(ensure_video_thumbnail(intro_case["reference_video"], PROJECT_ROOT))
+    result_a_thumb = image_to_data_uri(
+        ensure_video_thumbnail(intro_case["method_videos"]["anyact"], PROJECT_ROOT)
+    )
+    result_b_thumb = image_to_data_uri(
+        ensure_video_thumbnail(intro_case["method_videos"]["vlm_hy_motion"], PROJECT_ROOT)
+    )
+    language = normalize_language(language)
+
+    if language == "zh":
+        return f"""
+<div class="case-walkthrough">
+  <div class="case-walkthrough-head">
+    <h3>示例对比</h3>
+    <p>
+      下图说明问卷如何进行比较。参与者需要将一个源角色的运动视频与两个人体重演结果进行比较，
+      页面上它们显示为 <strong>结果 A</strong> 和 <strong>结果 B</strong>。灰色区域表示地板。
+    </p>
+  </div>
+
+  <div class="walkthrough-grid">
+    <div class="thumb-card ref-card">
+      <div class="thumb-image"><img src="{reference_thumb}" alt="参考案例缩略图"></div>
+      <div class="thumb-body">
+        <div class="thumb-title">参考视频</div>
+        <h4>源角色运动视频</h4>
+        <p>该视频提供需要被模仿的角色运动，主要体现姿态和动作动态。</p>
+      </div>
+    </div>
+
+    <div class="thumb-card candidate-card">
+      <div class="thumb-image"><img src="{result_a_thumb}" alt="匿名结果 A 缩略图"></div>
+      <div class="thumb-body">
+        <div class="thumb-title">结果 A</div>
+        <h4>模仿参考角色运动的人体重演</h4>
+        <p>这是结果 A 对参考角色运动进行人体重演后的表现。</p>
+      </div>
+    </div>
+
+    <div class="thumb-card candidate-card">
+      <div class="thumb-image"><img src="{result_b_thumb}" alt="匿名结果 B 缩略图"></div>
+      <div class="thumb-body">
+        <div class="thumb-title">结果 B</div>
+        <h4>模仿参考角色运动的人体重演</h4>
+        <p>这是结果 B 对参考角色运动进行人体重演后的表现。</p>
+      </div>
+    </div>
+  </div>
+</div>
+""".strip()
+
+    return f"""
+<div class="case-walkthrough">
+  <div class="case-walkthrough-head">
+    <h3>Example Comparison</h3>
+    <p>
+      The figure below shows how the questionnaire works. Participants compare one video of the source character's motion against
+      two human reenactment results that imitate that motion, displayed as <strong>Result A</strong> and <strong>Result B</strong>.
+      The gray area indicates the floor.
+    </p>
+  </div>
+
+  <div class="walkthrough-grid">
+    <div class="thumb-card ref-card">
+      <div class="thumb-image"><img src="{reference_thumb}" alt="Reference case thumbnail"></div>
+      <div class="thumb-body">
+        <div class="thumb-title">Reference</div>
+        <h4>Source character motion video</h4>
+        <p>This video provides the character motion to be imitated, mainly in terms of pose and action dynamics.</p>
+      </div>
+    </div>
+
+    <div class="thumb-card candidate-card">
+      <div class="thumb-image"><img src="{result_a_thumb}" alt="Anonymous Result A thumbnail"></div>
+      <div class="thumb-body">
+        <div class="thumb-title">Result A</div>
+        <h4>Human reenactment imitating the reference character motion</h4>
+        <p>This is the human-motion reenactment shown as Result A.</p>
+      </div>
+    </div>
+
+    <div class="thumb-card candidate-card">
+      <div class="thumb-image"><img src="{result_b_thumb}" alt="Anonymous Result B thumbnail"></div>
+      <div class="thumb-body">
+        <div class="thumb-title">Result B</div>
+        <h4>Human reenactment imitating the reference character motion</h4>
+        <p>This is the human-motion reenactment shown as Result B.</p>
+      </div>
+    </div>
+  </div>
+</div>
+""".strip()
+
+
+def build_judging_instruction_html(language: str | None) -> str:
+    language = normalize_language(language)
+    if language == "zh":
+        return """
+<div class="walkthrough-note">
+  <strong>参与者需要判断什么</strong>
+  <p>
+    对于每一组对比，你都需要回答三个问题，分别对应 <strong>动作相似性</strong>、<strong>动作质量</strong> 和
+    <strong>整体偏好</strong>。请直接依据页面上显示的结果 A 和结果 B 进行判断。
+  </p>
+  <div class="metric-stack">
+    <div class="metric-card">
+      <h4>动作相似性</h4>
+      <p>哪个结果与参考动作更匹配，尤其是在姿态对齐和时间动态方面？</p>
+    </div>
+    <div class="metric-card">
+      <h4>动作质量</h4>
+      <p>哪个结果看起来更自然、更平滑，并且更符合人体动作的物理合理性？请主要关注全身动作、身体协调、平衡性和时间连续性，并可适当忽略面部表情与手指细节。</p>
+    </div>
+    <div class="metric-card">
+      <h4>整体偏好</h4>
+      <p>综合考虑动作相似性和动作质量后，你整体更偏好哪个结果？</p>
+    </div>
+  </div>
+</div>
+""".strip()
+
+    return """
+<div class="walkthrough-note">
+  <strong>What participants are asked to judge</strong>
+  <p>
+    For each comparison, please answer three questions covering <strong>Motion Similarity</strong>,
+    <strong>Motion Quality</strong>, and <strong>Overall Preference</strong>. Please base your choice directly on the
+    page labels, namely Result A and Result B.
+  </p>
+  <div class="metric-stack">
+    <div class="metric-card">
+      <h4>Motion Similarity</h4>
+      <p>Which result better matches the reference motion, especially in terms of pose alignment and temporal dynamics?</p>
+    </div>
+    <div class="metric-card">
+      <h4>Motion Quality</h4>
+      <p>Which result appears more natural, smooth, and physically plausible as a human motion sequence (mainly focusing on whole-body motion, body coordination, balance, and temporal continuity, while reasonably ignoring facial expressions and fine finger motion)?</p>
+    </div>
+    <div class="metric-card">
+      <h4>Overall Preference</h4>
+      <p>Considering both similarity and quality together, which result do you prefer overall?</p>
+    </div>
+  </div>
+</div>
+""".strip()
+
+
+def build_instruction_html(
+    config: dict[str, Any],
+    case_walkthrough_html: str,
+    judging_instruction_html: str,
+    language: str | None,
+) -> str:
+    total_questions = config["participant_question_total"]
+    language = normalize_language(language)
+    if language == "zh":
+        return f"""
+<div class="hero-card">
+  <div class="instruction-shell">
+    <div class="instruction-top">
+      <div class="instruction-copy">
+        <div class="block-title">
+          <h1>{tr(language, "study_title")}</h1>
+        </div>
+        <p class="lead-text">
+          本研究用于评估人体动作重演结果的主观感知质量。每一道题中，你将观看
+          一个<strong>参考视频</strong>和两个<strong>匿名结果</strong>，它们在页面上显示为
+          <strong>结果 A</strong> 和 <strong>结果 B</strong>。你需要围绕
+          <strong>动作相似性</strong>、<strong>动作质量</strong> 和 <strong>整体偏好</strong>
+          三个指标完成判断。
+        </p>
+        <ul class="instruction-list">
+          <li>每位参与者需要完成 <strong>{total_questions}</strong> 个成对对比样本。</li>
+          <li>每次比较都会同时展示一个参考视频，以及并排显示的结果 A 和结果 B。</li>
+          <li>结果 A 和结果 B 的时长可能不完全相同，但它们都对应对整段参考视频中角色运动的重演；请忽略这种长度差异。</li>
+          <li>请在进入下一页之前回答完当前题目的三个问题。</li>
+        </ul>
+        {judging_instruction_html}
+      </div>
+      <div class="instruction-top-right">
+        <div class="diagram-card">
+          {case_walkthrough_html}
+        </div>
+        <div class="walkthrough-note accent-note">
+          <strong>如何理解本任务</strong>
+          <p>
+            本研究关注的是<strong>人去模仿参考视频中角色的运动</strong>。
+            一个优秀的结果应当既忠实保留参考运动，又能呈现自然、平稳、符合人体运动规律的动作。
+          </p>
+          <p>
+            当原始角色和人体构造不完全一致时，可以接受使用人体其他肢体去模拟缺失的功能部位，
+            例如用手臂对应翅膀，只要整体动作意图和动态仍然合理并接近参考动作。
+          </p>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+""".strip()
+
+    return f"""
+<div class="hero-card">
+  <div class="instruction-shell">
+    <div class="instruction-top">
+      <div class="instruction-copy">
+        <div class="block-title">
+          <h1>Human Motion Reenactment User Study</h1>
+        </div>
+        <p class="lead-text">
+          This study evaluates perceptual quality in human motion reenactment. In each question, you will watch
+          one <strong>reference video</strong> and two <strong>anonymous results</strong>, displayed on the page as
+          <strong>Result A</strong> and <strong>Result B</strong>. You will answer three evaluation questions covering
+          <strong>Motion Similarity</strong>, <strong>Motion Quality</strong>, and <strong>Overall Preference</strong>.
+        </p>
+        <ul class="instruction-list">
+          <li>Each participant completes <strong>{total_questions}</strong> pairwise comparison samples.</li>
+          <li>Each comparison presents one reference clip together with Result A and Result B shown side by side.</li>
+          <li>Result A and Result B may have different durations, but both are reenactments of the character motion over the full reference clip; please ignore this length difference.</li>
+          <li>Please answer all three questions before moving to the next page.</li>
+        </ul>
+        {judging_instruction_html}
+      </div>
+      <div class="instruction-top-right">
+        <div class="diagram-card">
+          {case_walkthrough_html}
+        </div>
+        <div class="walkthrough-note accent-note">
+          <strong>How to interpret the task</strong>
+          <p>
+            The goal is to assess how well a human reenactment imitates the motion of the character in the reference video.
+            A strong result should preserve the reference motion while still looking smooth, stable, and physically natural as human movement.
+          </p>
+          <p>
+            When the source character does not map directly to a human body, it is acceptable to use other human limbs
+            to simulate the missing functional parts, such as using arms to mimic wings, as long as the motion intent
+            and dynamics remain plausible and close to the reference.
+          </p>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+""".strip()
+
+
+def build_example_caption(language: str | None) -> str:
+    language = normalize_language(language)
+    if language == "zh":
+        return """
+<div class="example-caption-note">
+  下方展示的是同一个示例案例在正式问卷中的实际观看布局。参与者需要将参考视频与结果 A、结果 B 进行比较，并回答三个评价问题。
+</div>
+""".strip()
+
+    return """
+<div class="example-caption-note">
+  Below is the same example case shown in the actual questionnaire layout. Participants compare the reference clip
+  against Result A and Result B and answer the three evaluation questions.
+</div>
+""".strip()
+
+
+def resolve_browser_participant_id(browser_participant_id: str | None) -> str:
+    sanitized = sanitize_participant_id(browser_participant_id)
+    return sanitized or generate_participant_id()
+
+
+def build_intro_component_updates(
+    config: dict[str, Any],
+    intro_case: dict[str, Any],
+    language: str | None,
+) -> tuple[Any, ...]:
+    language = normalize_language(language)
+    case_walkthrough_html = build_instruction_case_html(intro_case, language)
+    judging_instruction_html = build_judging_instruction_html(language)
+    return (
+        gr.update(value=build_instruction_html(config, case_walkthrough_html, judging_instruction_html, language)),
+        gr.update(value=build_example_caption(language), visible=False),
+        gr.update(label=tr(language, "reference_video")),
+        gr.update(value=video_caption_html(tr(language, "reference_caption"))),
+        gr.update(label=tr(language, "candidate_a")),
+        gr.update(value=video_caption_html(tr(language, "result_a_caption"))),
+        gr.update(label=tr(language, "candidate_b")),
+        gr.update(value=video_caption_html(tr(language, "result_b_caption"))),
+        gr.update(value=build_participant_setup_markdown(language)),
+        gr.update(value=tr(language, "generate_fresh_id")),
+        gr.update(value=tr(language, "start_continue")),
+    )
+
+
+def build_study_component_updates(
+    language: str | None,
+    similarity_value: str | None,
+    quality_value: str | None,
+    preference_value: str | None,
+    show_previous: bool,
+    show_next: bool,
+    show_submit: bool,
+) -> tuple[Any, ...]:
+    language = normalize_language(language)
+    return (
+        gr.update(label=tr(language, "reference_video")),
+        gr.update(label=tr(language, "result_a_left")),
+        gr.update(label=tr(language, "result_b_right")),
+        gr.update(
+            choices=choice_options_for_language(language),
+            label=tr(language, "question_similarity"),
+            value=similarity_value,
+        ),
+        gr.update(
+            choices=choice_options_for_language(language),
+            label=tr(language, "question_quality"),
+            value=quality_value,
+        ),
+        gr.update(
+            choices=choice_options_for_language(language),
+            label=tr(language, "question_preference"),
+            value=preference_value,
+        ),
+        gr.update(value=tr(language, "previous"), visible=show_previous),
+        gr.update(value=tr(language, "next"), visible=show_next),
+        gr.update(value=tr(language, "submit_study"), visible=show_submit),
+        gr.update(value=video_caption_html(tr(language, "reference_caption"))),
+        gr.update(value=video_caption_html(tr(language, "result_a_caption"))),
+        gr.update(value=video_caption_html(tr(language, "result_b_caption"))),
+    )
+
+
+def render_intro_view(
+    config: dict[str, Any],
+    intro_case: dict[str, Any],
+    language: str | None,
+    participant_id: str | None = None,
+    browser_participant_id: str | None = None,
+    start_message: str = "",
+) -> Tuple[Any, ...]:
+    language = normalize_language(language)
+    resolved_participant_id = resolve_browser_participant_id(browser_participant_id or participant_id)
+    intro_updates = build_intro_component_updates(config, intro_case, language)
+    study_updates = build_study_component_updates(
+        language,
+        similarity_value=None,
+        quality_value=None,
+        preference_value=None,
+        show_previous=False,
+        show_next=True,
+        show_submit=False,
+    )
+    return (
+        gr.update(visible=True),
+        gr.update(visible=False),
+        gr.update(visible=False),
+        {},
+        "",
+        "",
+        tr(language, "study_instruction"),
+        None,
+        None,
+        None,
+        study_updates[3],
+        study_updates[4],
+        study_updates[5],
+        "",
+        study_updates[6],
+        study_updates[7],
+        study_updates[8],
+        start_message,
+        "",
+        gr.update(value=resolved_participant_id, label=tr(language, "participant_id_label")),
+        resolved_participant_id,
+        language,
+        gr.update(value=language, label=LANGUAGE_SWITCH_LABEL),
+        *intro_updates,
+        study_updates[9],
+        study_updates[10],
+        study_updates[11],
+    )
+
+
+def render_question_view(
+    config: dict[str, Any],
+    intro_case: dict[str, Any],
+    language: str | None,
+    state: dict[str, Any],
+    study_message: str = "",
+    draft_answers: tuple[str | None, str | None, str | None] | None = None,
+) -> Tuple[Any, ...]:
+    language = normalize_language(language)
+    payload = build_question_payload(state)
+    synced_videos = ensure_synchronized_study_videos(
+        reference_video=payload["reference_video"],
+        left_video=payload["left_video"],
+        right_video=payload["right_video"],
+        project_root=PROJECT_ROOT,
+    )
+    similarity_value = draft_answers[0] if draft_answers and draft_answers[0] is not None else payload["answer_similarity"]
+    quality_value = draft_answers[1] if draft_answers and draft_answers[1] is not None else payload["answer_quality"]
+    preference_value = draft_answers[2] if draft_answers and draft_answers[2] is not None else payload["answer_preference"]
+    intro_updates = build_intro_component_updates(config, intro_case, language)
+    study_updates = build_study_component_updates(
+        language,
+        similarity_value=similarity_value,
+        quality_value=quality_value,
+        preference_value=preference_value,
+        show_previous=payload["show_previous"],
+        show_next=payload["show_next"],
+        show_submit=payload["show_submit"],
+    )
+    return (
+        gr.update(visible=False),
+        gr.update(visible=True),
+        gr.update(visible=False),
+        state,
+        payload["question_token"],
+        build_progress_markdown(state, language),
+        tr(language, "study_instruction"),
+        gr.update(value=synced_videos["reference_video"], label=tr(language, "reference_video")),
+        gr.update(value=synced_videos["left_video"], label=tr(language, "result_a_left")),
+        gr.update(value=synced_videos["right_video"], label=tr(language, "result_b_right")),
+        study_updates[3],
+        study_updates[4],
+        study_updates[5],
+        study_message,
+        study_updates[6],
+        study_updates[7],
+        study_updates[8],
+        "",
+        "",
+        gr.update(value=state["participant_id"], label=tr(language, "participant_id_label")),
+        state["participant_id"],
+        language,
+        gr.update(value=language, label=LANGUAGE_SWITCH_LABEL),
+        *intro_updates,
+        study_updates[9],
+        study_updates[10],
+        study_updates[11],
+    )
+
+
+def render_thank_you_view(
+    config: dict[str, Any],
+    intro_case: dict[str, Any],
+    language: str | None,
+    state: dict[str, Any],
+) -> Tuple[Any, ...]:
+    language = normalize_language(language)
+    intro_updates = build_intro_component_updates(config, intro_case, language)
+    study_updates = build_study_component_updates(
+        language,
+        similarity_value=None,
+        quality_value=None,
+        preference_value=None,
+        show_previous=False,
+        show_next=False,
+        show_submit=False,
+    )
+    return (
+        gr.update(visible=False),
+        gr.update(visible=False),
+        gr.update(visible=True),
+        state,
+        "",
+        "",
+        tr(language, "study_instruction"),
+        gr.update(value=None),
+        gr.update(value=None),
+        gr.update(value=None),
+        study_updates[3],
+        study_updates[4],
+        study_updates[5],
+        "",
+        study_updates[6],
+        study_updates[7],
+        study_updates[8],
+        "",
+        build_completion_markdown_local(state, language),
+        gr.update(value=state["participant_id"], label=tr(language, "participant_id_label")),
+        state["participant_id"],
+        language,
+        gr.update(value=language, label=LANGUAGE_SWITCH_LABEL),
+        *intro_updates,
+        study_updates[9],
+        study_updates[10],
+        study_updates[11],
+    )
+
+
+def _drop_language_selector_update(payload: Tuple[Any, ...]) -> Tuple[Any, ...]:
+    language_selector_index = 22
+    return payload[:language_selector_index] + payload[language_selector_index + 1 :]
+
+
+def build_demo(config_path: Path) -> gr.Blocks:
+    ensure_local_ffmpeg()
+    patch_gradio_video_probe()
+    config = load_study_config(config_path)
+    ensure_runtime_dirs(PROJECT_ROOT)
+    config = prepare_reference_videos_for_web(config, PROJECT_ROOT)
+    upgrade_existing_results_schema(PROJECT_ROOT, config)
+    default_language = "en"
+    choice_options = choice_options_for_language(default_language)
+
+    intro_case = get_instruction_case(config)
+    example_left_path = intro_case["method_videos"]["anyact"]
+    example_right_path = intro_case["method_videos"]["vlm_hy_motion"]
+
+    with gr.Blocks(
+        title=config["study_title"],
+        css=CUSTOM_CSS,
+        head=CUSTOM_HEAD,
+        theme=gr.themes.Soft(
+            primary_hue="blue",
+            secondary_hue="sky",
+            neutral_hue="slate",
+        ),
+    ) as demo:
+        participant_state = gr.State({})
+        question_token = gr.State("")
+        browser_participant_id = gr.BrowserState(
+            "",
+            storage_key=f"{config['study_id']}_participant_id",
+        )
+        browser_language = gr.BrowserState(
+            default_language,
+            storage_key=f"{config['study_id']}_language",
+        )
+
+        with gr.Row(elem_classes=["language-switch-row"]):
+            language_selector = gr.Radio(
+                choices=LANGUAGE_CHOICES,
+                value=default_language,
+                label=LANGUAGE_SWITCH_LABEL,
+                interactive=True,
+                show_label=False,
+                elem_classes=["language-switch"],
+            )
+
+        with gr.Column(visible=True) as intro_panel:
+            intro_instruction_html = gr.HTML(
+                build_instruction_html(
+                    config=config,
+                    case_walkthrough_html=build_instruction_case_html(intro_case, default_language),
+                    judging_instruction_html=build_judging_instruction_html(default_language),
+                    language=default_language,
+                )
+            )
+            example_caption_md = gr.Markdown(build_example_caption(default_language), visible=False)
+            with gr.Row(visible=False):
+                with gr.Column(scale=5):
+                    intro_reference_video = gr.Video(
+                        value=intro_case["reference_video"],
+                        label=tr(default_language, "reference_video"),
+                        autoplay=True,
+                        loop=True,
+                        elem_classes=["panel-card", "video-panel", "reference-panel"],
+                    )
+                    intro_reference_caption = gr.Markdown(video_caption_html(tr(default_language, "reference_caption")))
+                with gr.Column(scale=4):
+                    intro_left_video = gr.Video(
+                        value=example_left_path,
+                        label=tr(default_language, "candidate_a"),
+                        autoplay=True,
+                        loop=True,
+                        elem_classes=["panel-card", "video-panel", "candidate-panel"],
+                    )
+                    intro_left_caption = gr.Markdown(video_caption_html(tr(default_language, "result_a_caption")))
+                with gr.Column(scale=4):
+                    intro_right_video = gr.Video(
+                        value=example_right_path,
+                        label=tr(default_language, "candidate_b"),
+                        autoplay=True,
+                        loop=True,
+                        elem_classes=["panel-card", "video-panel", "candidate-panel"],
+                    )
+                    intro_right_caption = gr.Markdown(video_caption_html(tr(default_language, "result_b_caption")))
+
+            with gr.Group(elem_classes=["form-card"]):
+                participant_setup_md = gr.Markdown(build_participant_setup_markdown(default_language))
+                participant_id_box = gr.Textbox(
+                    label=tr(default_language, "participant_id_label"),
+                    interactive=False,
+                )
+                regenerate_button = gr.Button(tr(default_language, "generate_fresh_id"))
+                start_message = gr.Markdown()
+                start_button = gr.Button(tr(default_language, "start_continue"), variant="primary")
+
+        with gr.Column(visible=False, elem_classes=["study-shell"]) as study_panel:
+            progress_html = gr.HTML()
+            study_notice = gr.Markdown(tr(default_language, "study_instruction"))
+            with gr.Row():
+                with gr.Column(scale=5):
+                    reference_video = gr.Video(
+                        label=tr(default_language, "reference_video"),
+                        autoplay=True,
+                        loop=True,
+                        elem_id="study-reference-video",
+                        elem_classes=["panel-card", "video-panel", "reference-panel"],
+                    )
+                    study_reference_caption = gr.Markdown(video_caption_html(tr(default_language, "reference_caption")))
+                with gr.Column(scale=4):
+                    left_video = gr.Video(
+                        label=tr(default_language, "result_a_left"),
+                        autoplay=True,
+                        loop=True,
+                        elem_id="study-left-video",
+                        elem_classes=["panel-card", "video-panel", "candidate-panel"],
+                    )
+                    study_left_caption = gr.Markdown(video_caption_html(tr(default_language, "result_a_caption")))
+                with gr.Column(scale=4):
+                    right_video = gr.Video(
+                        label=tr(default_language, "result_b_right"),
+                        autoplay=True,
+                        loop=True,
+                        elem_id="study-right-video",
+                        elem_classes=["panel-card", "video-panel", "candidate-panel"],
+                    )
+                    study_right_caption = gr.Markdown(video_caption_html(tr(default_language, "result_b_caption")))
+
+            with gr.Group(elem_classes=["question-card"]):
+                similarity_radio = gr.Radio(
+                    choices=choice_options,
+                    label=tr(default_language, "question_similarity"),
+                    elem_classes=["choice-input"],
+                )
+                quality_radio = gr.Radio(
+                    choices=choice_options,
+                    label=tr(default_language, "question_quality"),
+                    elem_classes=["choice-input"],
+                )
+                preference_radio = gr.Radio(
+                    choices=choice_options,
+                    label=tr(default_language, "question_preference"),
+                    elem_classes=["choice-input"],
+                )
+                study_message = gr.Markdown()
+
+            with gr.Row():
+                previous_button = gr.Button(tr(default_language, "previous"))
+                next_button = gr.Button(tr(default_language, "next"), variant="primary")
+                submit_button = gr.Button(tr(default_language, "submit_study"), variant="primary", visible=False)
+
+        with gr.Column(visible=False) as thank_panel:
+            with gr.Group(elem_classes=["hero-card", "thank-card"]):
+                thank_you_markdown = gr.Markdown()
+
+        outputs = [
+            intro_panel,
+            study_panel,
+            thank_panel,
+            participant_state,
+            question_token,
+            progress_html,
+            study_notice,
+            reference_video,
+            left_video,
+            right_video,
+            similarity_radio,
+            quality_radio,
+            preference_radio,
+            study_message,
+            previous_button,
+            next_button,
+            submit_button,
+            start_message,
+            thank_you_markdown,
+            participant_id_box,
+            browser_participant_id,
+            browser_language,
+            language_selector,
+            intro_instruction_html,
+            example_caption_md,
+            intro_reference_video,
+            intro_reference_caption,
+            intro_left_video,
+            intro_left_caption,
+            intro_right_video,
+            intro_right_caption,
+            participant_setup_md,
+            regenerate_button,
+            start_button,
+            study_reference_caption,
+            study_left_caption,
+            study_right_caption,
+        ]
+        outputs_without_language_selector = outputs[:22] + outputs[23:]
+
+        def initialize_page(saved_participant_id: str, saved_language: str) -> Tuple[Any, ...]:
+            language = normalize_language(saved_language)
+            resolved_participant_id = resolve_browser_participant_id(saved_participant_id)
+            start_message = ""
+            if sanitize_participant_id(saved_participant_id):
+                start_message = tr(language, "browser_saved_id_notice")
+            return render_intro_view(
+                config=config,
+                intro_case=intro_case,
+                language=language,
+                participant_id=resolved_participant_id,
+                browser_participant_id=resolved_participant_id,
+                start_message=start_message,
+            )
+
+        def handle_generate_new_id(current_language: str) -> Tuple[Any, str, str]:
+            language = normalize_language(current_language)
+            new_participant_id = generate_participant_id()
+            return (
+                gr.update(value=new_participant_id, label=tr(language, "participant_id_label")),
+                new_participant_id,
+                tr(language, "fresh_id_notice"),
+            )
+
+        def handle_start(
+            participant_id: str,
+            current_language: str,
+            request: gr.Request,
+        ) -> Tuple[Any, ...]:
+            language = normalize_language(current_language)
+            state, status = create_or_resume_participant(
+                project_root=PROJECT_ROOT,
+                config=config,
+                participant_id=participant_id,
+                request=request,
+            )
+
+            if status == "completed":
+                return render_intro_view(
+                    config=config,
+                    intro_case=intro_case,
+                    language=language,
+                    participant_id=state["participant_id"],
+                    browser_participant_id=state["participant_id"],
+                    start_message=tr(language, "completed_id_notice"),
+                )
+
+            study_message_text = tr(language, "saved_progress_restored") if status == "resumed" else ""
+            return render_question_view(
+                config=config,
+                intro_case=intro_case,
+                language=language,
+                state=state,
+                study_message=study_message_text,
+            )
+
+        def handle_previous(
+            state: dict[str, Any],
+            current_token: str,
+            current_browser_participant_id: str,
+            current_language: str,
+        ) -> Tuple[Any, ...]:
+            language = normalize_language(current_language)
+            if not state:
+                resolved_participant_id = resolve_browser_participant_id(current_browser_participant_id)
+                return render_intro_view(
+                    config=config,
+                    intro_case=intro_case,
+                    language=language,
+                    participant_id=resolved_participant_id,
+                    browser_participant_id=resolved_participant_id,
+                    start_message=tr(language, "session_empty"),
+                )
+
+            updated_state, message = move_question_pointer(
+                project_root=PROJECT_ROOT,
+                participant_id=state["participant_id"],
+                question_token=current_token,
+                direction="previous",
+            )
+            return render_question_view(
+                config=config,
+                intro_case=intro_case,
+                language=language,
+                state=updated_state,
+                study_message=message,
+            )
+
+        def handle_next_or_submit(
+            state: dict[str, Any],
+            current_token: str,
+            answer_similarity: str,
+            answer_quality: str,
+            answer_preference: str,
+            action: str,
+            current_browser_participant_id: str,
+            current_language: str,
+        ) -> Tuple[Any, ...]:
+            language = normalize_language(current_language)
+            if not state:
+                resolved_participant_id = resolve_browser_participant_id(current_browser_participant_id)
+                return render_intro_view(
+                    config=config,
+                    intro_case=intro_case,
+                    language=language,
+                    participant_id=resolved_participant_id,
+                    browser_participant_id=resolved_participant_id,
+                    start_message=tr(language, "session_empty"),
+                )
+
+            if not answer_similarity or not answer_quality or not answer_preference:
+                return render_question_view(
+                    config=config,
+                    intro_case=intro_case,
+                    language=language,
+                    state=state,
+                    study_message=tr(language, "answer_all_required"),
+                    draft_answers=(answer_similarity, answer_quality, answer_preference),
+                )
+
+            updated_state, message, status = save_current_answer(
+                project_root=PROJECT_ROOT,
+                participant_id=state["participant_id"],
+                question_token=current_token,
+                answer_similarity=answer_similarity,
+                answer_quality=answer_quality,
+                answer_preference=answer_preference,
+                action=action,
+            )
+            if status == "completed":
+                return render_thank_you_view(
+                    config=config,
+                    intro_case=intro_case,
+                    language=language,
+                    state=updated_state,
+                )
+            return render_question_view(
+                config=config,
+                intro_case=intro_case,
+                language=language,
+                state=updated_state,
+                study_message=message,
+            )
+
+        def handle_language_change(
+            selected_language: str,
+            state: dict[str, Any],
+            current_browser_participant_id: str,
+            current_token: str,
+            answer_similarity: str | None,
+            answer_quality: str | None,
+            answer_preference: str | None,
+            current_start_message: str,
+            current_study_message: str,
+        ) -> Tuple[Any, ...]:
+            language = normalize_language(selected_language)
+            if state:
+                if state.get("completed_at"):
+                    return _drop_language_selector_update(
+                        render_thank_you_view(
+                            config=config,
+                            intro_case=intro_case,
+                            language=language,
+                            state=state,
+                        )
+                    )
+                return _drop_language_selector_update(
+                    render_question_view(
+                        config=config,
+                        intro_case=intro_case,
+                        language=language,
+                        state=state,
+                        study_message=current_study_message,
+                        draft_answers=(answer_similarity, answer_quality, answer_preference),
+                    )
+                )
+
+            resolved_participant_id = resolve_browser_participant_id(current_browser_participant_id)
+            return _drop_language_selector_update(
+                render_intro_view(
+                    config=config,
+                    intro_case=intro_case,
+                    language=language,
+                    participant_id=resolved_participant_id,
+                    browser_participant_id=resolved_participant_id,
+                    start_message=current_start_message,
+                )
+            )
+
+        demo.load(initialize_page, inputs=[browser_participant_id, browser_language], outputs=outputs)
+        regenerate_button.click(
+            handle_generate_new_id,
+            inputs=[browser_language],
+            outputs=[participant_id_box, browser_participant_id, start_message],
+        )
+        start_button.click(handle_start, inputs=[browser_participant_id, browser_language], outputs=outputs)
+        previous_button.click(
+            handle_previous,
+            inputs=[participant_state, question_token, browser_participant_id, browser_language],
+            outputs=outputs,
+        )
+        next_button.click(
+            lambda state, token, similarity, quality, preference, browser_pid, current_language: handle_next_or_submit(
+                state, token, similarity, quality, preference, "next", browser_pid, current_language
+            ),
+            inputs=[
+                participant_state,
+                question_token,
+                similarity_radio,
+                quality_radio,
+                preference_radio,
+                browser_participant_id,
+                browser_language,
+            ],
+            outputs=outputs,
+        )
+        submit_button.click(
+            lambda state, token, similarity, quality, preference, browser_pid, current_language: handle_next_or_submit(
+                state, token, similarity, quality, preference, "submit", browser_pid, current_language
+            ),
+            inputs=[
+                participant_state,
+                question_token,
+                similarity_radio,
+                quality_radio,
+                preference_radio,
+                browser_participant_id,
+                browser_language,
+            ],
+            outputs=outputs,
+        )
+        language_selector.change(
+            handle_language_change,
+            inputs=[
+                language_selector,
+                participant_state,
+                browser_participant_id,
+                question_token,
+                similarity_radio,
+                quality_radio,
+                preference_radio,
+                start_message,
+                study_message,
+            ],
+            outputs=outputs_without_language_selector,
+        )
+
+    return demo
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Launch the Gradio user study application.")
+    parser.add_argument(
+        "--config",
+        type=Path,
+        default=PROJECT_ROOT / "data" / "study_config.json",
+        help="Path to the study configuration JSON file.",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=int(os.environ.get("PORT", "7860")),
+        help="Server port for Gradio.",
+    )
+    parser.add_argument(
+        "--server-name",
+        type=str,
+        default=os.environ.get("GRADIO_SERVER_NAME", default_server_name()),
+        help="Server bind address for Gradio.",
+    )
+    parser.add_argument(
+        "--share",
+        action="store_true",
+        help="Enable Gradio's temporary public share link.",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    demo = build_demo(args.config)
+    demo.queue()
+    demo.launch(
+        server_name=args.server_name,
+        server_port=args.port,
+        share=args.share,
+        allowed_paths=[str(PROJECT_ROOT)],
+    )
+
+
+if __name__ == "__main__":
+    main()

data/study_config.json

@@ -0,0 +1,69 @@
+{
+  "study_id": "anyact_human_motion_user_study_30sample_v3",
+  "study_title": "Human Motion Reenactment User Study",
+  "question_order": "shuffle_per_participant",
+  "allow_tie_option": false,
+  "disjoint_case_sampling": true,
+  "per_participant_pair_limits": {
+    "anyact_vs_vlm_hy_motion": 15,
+    "anyact_vs_echomotion": 15
+  },
+  "instruction_case_id": "case_003",
+  "reference": {
+    "directory": "../videos/reference",
+    "glob": "{source_key}_crop.mp4"
+  },
+  "methods": {
+    "anyact": {
+      "display_name": "AnyAct (ours)",
+      "directory": "../videos/anyact",
+      "glob": "{source_key}#0#*_gen.mp4"
+    },
+    "vlm_hy_motion": {
+      "display_name": "VLM+HY-Motion",
+      "directory": "../videos/vlm_hy_motion",
+      "glob": "{source_key}#0#*_gen_joints.mp4"
+    },
+    "echomotion": {
+      "display_name": "EchoMotion",
+      "directory": "../videos/echomotion",
+      "glob": "{source_key}_crop.mp4"
+    }
+  },
+  "pair_order": [
+    ["anyact", "vlm_hy_motion"],
+    ["anyact", "echomotion"]
+  ],
+  "cases": [
+    {"case_id": "case_001", "source_key": "animal_dance2_776p"},
+    {"case_id": "case_002", "source_key": "bear_flap1_720p"},
+    {"case_id": "case_003", "source_key": "bear_jump1_540p"},
+    {"case_id": "case_004", "source_key": "bird_fly1_720p"},
+    {"case_id": "case_005", "source_key": "butterfly_fly3_720p"},
+    {"case_id": "case_006", "source_key": "cartoonhuman_dance1_istock"},
+    {"case_id": "case_007", "source_key": "chicken_walk1_istock"},
+    {"case_id": "case_008", "source_key": "crab_walk2_istock"},
+    {"case_id": "case_009", "source_key": "dear_walk1_istock"},
+    {"case_id": "case_010", "source_key": "dinosaur_walk2_720p"},
+    {"case_id": "case_011", "source_key": "dinosaur_walk7_istock"},
+    {"case_id": "case_012", "source_key": "frog_swim3_istock"},
+    {"case_id": "case_013", "source_key": "ghost_dance1_istock"},
+    {"case_id": "case_014", "source_key": "gorilla_walk1_720p"},
+    {"case_id": "case_015", "source_key": "human_jump1_istock"},
+    {"case_id": "case_016", "source_key": "kangeroo_jump4_istock"},
+    {"case_id": "case_017", "source_key": "kangeroo_jump5_1080p"},
+    {"case_id": "case_018", "source_key": "labubu_jump1_1080p"},
+    {"case_id": "case_019", "source_key": "luckycat_wave5_istock"},
+    {"case_id": "case_020", "source_key": "monkey_swing3_istock"},
+    {"case_id": "case_021", "source_key": "monkey_walk3_720p"},
+    {"case_id": "case_022", "source_key": "monster_fly2_720p"},
+    {"case_id": "case_023", "source_key": "monster_jump1_720p"},
+    {"case_id": "case_024", "source_key": "penguin_walk4_istock"},
+    {"case_id": "case_025", "source_key": "penguin_walk5_istock"},
+    {"case_id": "case_026", "source_key": "plane_fly1_720p"},
+    {"case_id": "case_027", "source_key": "rabit_jump1_720p"},
+    {"case_id": "case_028", "source_key": "seal_walk1_istock"},
+    {"case_id": "case_029", "source_key": "squirrel_eat1_720p"},
+    {"case_id": "case_030", "source_key": "turtle_swim3_istock"}
+  ]
+}

deploy_to_hf_space.bat

@@ -0,0 +1,35 @@
+@echo off
+setlocal
+cd /d %~dp0
+
+if "%~1"=="" (
+    echo Usage: deploy_to_hf_space.bat username/space-name
+    echo Example: deploy_to_hf_space.bat yourname/anyact-user-study
+    exit /b 1
+)
+
+set "SPACE_REPO=%~1"
+
+echo [1/3] Checking Hugging Face authentication...
+hf auth whoami >nul 2>nul
+if errorlevel 1 (
+    echo [ERROR] Hugging Face CLI is not logged in.
+    echo Please run: hf auth login
+    exit /b 1
+)
+
+echo [2/3] Creating the Space if needed...
+hf repos create %SPACE_REPO% --type space --space-sdk gradio --public --exist-ok
+if errorlevel 1 (
+    echo [ERROR] Failed to create or access the target Space.
+    exit /b 1
+)
+
+echo [3/3] Uploading the project...
+hf upload-large-folder %SPACE_REPO% . --repo-type space --exclude ".venv/**" --exclude ".gradio/**" --exclude "__pycache__/**" --exclude "results/**"
+if errorlevel 1 (
+    echo [ERROR] Upload failed.
+    exit /b 1
+)
+
+echo [DONE] Space uploaded successfully: https://huggingface.co/spaces/%SPACE_REPO%

requirements.txt

@@ -0,0 +1,5 @@
+gradio>=5.0.0,<6.0.0
+pandas>=2.2.0
+matplotlib>=3.8.0
+filelock>=3.16.0
+imageio-ffmpeg>=0.6.0

study_utils.py

@@ -0,0 +1,1353 @@
+from __future__ import annotations
+
+import csv
+import copy
+import hashlib
+import json
+import os
+import random
+import re
+import subprocess
+import time
+import uuid
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+from filelock import FileLock
+
+try:
+    import imageio_ffmpeg
+except ImportError:  # pragma: no cover - optional runtime dependency
+    imageio_ffmpeg = None
+
+METHOD_FALLBACK_LABELS = {
+    "anyact": "AnyAct (ours)",
+    "vlm_hy_motion": "VLM+HY-Motion",
+    "echomotion": "EchoMotion",
+}
+
+PAIRWISE_METHOD_PAIRS: List[Tuple[str, str]] = [
+    ("anyact", "vlm_hy_motion"),
+    ("anyact", "echomotion"),
+]
+
+CHOICE_OPTIONS = ["ResultA", "ResultB"]
+
+CHOICE_RESULT_A = "ResultA"
+CHOICE_RESULT_B = "ResultB"
+CHOICE_TIE = "Tie"
+
+CSV_COLUMNS = [
+    "participant_id",
+    "consent",
+    "study_id",
+    "study_title",
+    "question_id",
+    "question_position",
+    "total_questions",
+    "case_id",
+    "case_title",
+    "source_key",
+    "pair_id",
+    "result_a_method",
+    "result_b_method",
+    "left_method",
+    "right_method",
+    "reference_video",
+    "result_a_video",
+    "result_b_video",
+    "left_video",
+    "right_video",
+    "answer_similarity",
+    "answer_similarity_method",
+    "answer_similarity_video",
+    "answer_quality",
+    "answer_quality_method",
+    "answer_quality_video",
+    "answer_preference",
+    "answer_preference_method",
+    "answer_preference_video",
+    "answered_at",
+    "duration_seconds",
+    "session_hash",
+    "user_agent",
+    "started_at",
+    "updated_at",
+]
+
+
+def now_iso() -> str:
+    return datetime.now().astimezone().isoformat(timespec="seconds")
+
+
+def get_results_dir(project_root: Path) -> Path:
+    explicit_dir = os.environ.get("USER_STUDY_RESULTS_DIR", "").strip()
+    if explicit_dir:
+        return Path(explicit_dir).expanduser().resolve()
+
+    if os.environ.get("SPACE_ID"):
+        space_data_dir = Path("/data")
+        if space_data_dir.exists():
+            return (space_data_dir / "user_study_results").resolve()
+
+    return (project_root / "results").resolve()
+
+
+def ensure_runtime_dirs(project_root: Path) -> None:
+    results_dir = get_results_dir(project_root)
+    for path in [
+        results_dir,
+        results_dir / "participants",
+        results_dir / "participants_archive",
+        results_dir / "plots",
+        results_dir / "locks",
+    ]:
+        path.mkdir(parents=True, exist_ok=True)
+
+    responses_csv = results_dir / "responses.csv"
+    if not responses_csv.exists():
+        with responses_csv.open("w", newline="", encoding="utf-8") as handle:
+            writer = csv.DictWriter(handle, fieldnames=CSV_COLUMNS)
+            writer.writeheader()
+
+    responses_jsonl = results_dir / "responses.jsonl"
+    responses_jsonl.touch(exist_ok=True)
+
+
+def generate_participant_id() -> str:
+    return str(uuid.uuid4())
+
+
+def sanitize_participant_id(raw_value: str | None) -> str:
+    cleaned = re.sub(r"[^A-Za-z0-9_-]", "_", (raw_value or "").strip())
+    return cleaned[:80]
+
+def humanize_source_key(source_key: str) -> str:
+    return source_key.replace("_", " ").strip().title()
+
+
+def stable_int_seed(text: str) -> int:
+    digest = hashlib.sha256(text.encode("utf-8")).hexdigest()
+    return int(digest[:16], 16)
+
+
+def build_pair_id(method_a: str, method_b: str) -> str:
+    return f"{method_a}_vs_{method_b}"
+
+
+def normalize_choice_value(raw_value: Any) -> str:
+    if raw_value is None:
+        return ""
+
+    cleaned = str(raw_value).strip()
+    if not cleaned:
+        return ""
+
+    compact = re.sub(r"[\s_-]+", "", cleaned).lower()
+    if compact in {"left", "resulta", "a"}:
+        return CHOICE_RESULT_A
+    if compact in {"right", "resultb", "b"}:
+        return CHOICE_RESULT_B
+    if compact in {"tie", "equal", "same"}:
+        return CHOICE_TIE
+    return cleaned
+
+
+def _sync_result_slot_fields(row: Dict[str, Any], case: Dict[str, Any] | None = None) -> Dict[str, Any]:
+    result_a_method = str(row.get("result_a_method") or row.get("left_method") or "").strip()
+    result_b_method = str(row.get("result_b_method") or row.get("right_method") or "").strip()
+
+    result_a_video = str(row.get("result_a_video") or row.get("left_video") or "").strip()
+    result_b_video = str(row.get("result_b_video") or row.get("right_video") or "").strip()
+
+    if case is not None:
+        method_videos = case.get("method_videos", {})
+        if result_a_method in method_videos:
+            result_a_video = str(method_videos[result_a_method])
+        if result_b_method in method_videos:
+            result_b_video = str(method_videos[result_b_method])
+        if case.get("reference_video"):
+            row["reference_video"] = case["reference_video"]
+
+    row["result_a_method"] = result_a_method
+    row["result_b_method"] = result_b_method
+    row["left_method"] = result_a_method
+    row["right_method"] = result_b_method
+    row["result_a_video"] = result_a_video
+    row["result_b_video"] = result_b_video
+    row["left_video"] = result_a_video
+    row["right_video"] = result_b_video
+    return row
+
+
+def _resolve_choice_targets(row: Dict[str, Any], raw_choice: Any) -> tuple[str, str]:
+    normalized_choice = normalize_choice_value(raw_choice)
+    if normalized_choice == CHOICE_RESULT_A:
+        return (
+            str(row.get("result_a_method") or row.get("left_method") or "").strip(),
+            str(row.get("result_a_video") or row.get("left_video") or "").strip(),
+        )
+    if normalized_choice == CHOICE_RESULT_B:
+        return (
+            str(row.get("result_b_method") or row.get("right_method") or "").strip(),
+            str(row.get("result_b_video") or row.get("right_video") or "").strip(),
+        )
+    return "", ""
+
+
+def upgrade_response_row_schema(row: Dict[str, Any], case: Dict[str, Any] | None = None) -> Dict[str, Any]:
+    upgraded = row
+    _sync_result_slot_fields(upgraded, case=case)
+
+    for metric_key in ["answer_similarity", "answer_quality", "answer_preference"]:
+        normalized_choice = normalize_choice_value(upgraded.get(metric_key))
+        if normalized_choice:
+            upgraded[metric_key] = normalized_choice
+        elif metric_key not in upgraded:
+            upgraded[metric_key] = ""
+
+        selected_method, selected_video = _resolve_choice_targets(upgraded, upgraded.get(metric_key))
+        upgraded[f"{metric_key}_method"] = selected_method
+        upgraded[f"{metric_key}_video"] = selected_video
+
+    return upgraded
+
+
+def _web_video_cache_dir(project_root: Path) -> Path:
+    cache_dir = get_results_dir(project_root) / "web_video_cache"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    return cache_dir
+
+
+def _thumbnail_cache_dir(project_root: Path) -> Path:
+    cache_dir = get_results_dir(project_root) / "thumbnail_cache"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    return cache_dir
+
+
+def _synced_video_cache_dir(project_root: Path) -> Path:
+    cache_dir = get_results_dir(project_root) / "synced_video_cache"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    return cache_dir
+
+
+def _probe_video_stream(video_path: Path) -> Dict[str, str]:
+    if imageio_ffmpeg is None:
+        return {}
+
+    ffmpeg_exe = imageio_ffmpeg.get_ffmpeg_exe()
+    result = subprocess.run(
+        [ffmpeg_exe, "-i", str(video_path)],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="ignore",
+    )
+    stderr_text = result.stderr or ""
+    match = re.search(r"Video:\s*([^\s,(]+).*?(yuv[a-zA-Z0-9]+)?", stderr_text)
+    if not match:
+        return {}
+
+    codec_name = (match.group(1) or "").strip().lower()
+    pixel_format = (match.group(2) or "").strip().lower()
+    return {
+        "codec_name": codec_name,
+        "pixel_format": pixel_format,
+    }
+
+
+def _parse_duration_to_seconds(duration_text: str) -> float:
+    hours, minutes, seconds = duration_text.split(":")
+    return int(hours) * 3600 + int(minutes) * 60 + float(seconds)
+
+
+def _probe_video_timing(video_path: Path) -> Dict[str, float]:
+    if imageio_ffmpeg is None:
+        return {}
+
+    ffmpeg_exe = imageio_ffmpeg.get_ffmpeg_exe()
+    result = subprocess.run(
+        [ffmpeg_exe, "-i", str(video_path)],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="ignore",
+    )
+    stderr_text = result.stderr or ""
+
+    duration_match = re.search(r"Duration:\s*(\d+:\d+:\d+(?:\.\d+)?)", stderr_text)
+    fps_match = re.search(r"(\d+(?:\.\d+)?)\s+fps", stderr_text)
+    if fps_match is None:
+        fps_match = re.search(r"(\d+(?:\.\d+)?)\s+tbr", stderr_text)
+
+    metadata: Dict[str, float] = {}
+    if duration_match:
+        metadata["duration_seconds"] = _parse_duration_to_seconds(duration_match.group(1))
+    if fps_match:
+        metadata["fps"] = float(fps_match.group(1))
+    return metadata
+
+
+def _format_ffmpeg_fps(value: float) -> str:
+    rounded = round(value)
+    if abs(value - rounded) < 1e-6:
+        return str(int(rounded))
+    return f"{value:.3f}".rstrip("0").rstrip(".")
+
+
+def _sync_single_video_to_duration(
+    source_path: Path,
+    target_path: Path,
+    target_duration: float,
+    target_fps: float,
+) -> None:
+    ffmpeg_exe = imageio_ffmpeg.get_ffmpeg_exe()
+    source_timing = _probe_video_timing(source_path)
+    source_duration = float(source_timing.get("duration_seconds", 0.0) or 0.0)
+    pad_duration = max(0.0, target_duration - source_duration)
+    fps_literal = _format_ffmpeg_fps(target_fps)
+    filter_graph = (
+        f"fps={fps_literal},"
+        f"tpad=stop_mode=clone:stop_duration={pad_duration:.6f},"
+        f"trim=duration={target_duration:.6f},"
+        "setpts=PTS-STARTPTS"
+    )
+    command = [
+        ffmpeg_exe,
+        "-y",
+        "-i",
+        str(source_path),
+        "-an",
+        "-vf",
+        filter_graph,
+        "-c:v",
+        "libx264",
+        "-preset",
+        "veryfast",
+        "-pix_fmt",
+        "yuv420p",
+        "-movflags",
+        "+faststart",
+        str(target_path),
+    ]
+    result = subprocess.run(
+        command,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="ignore",
+    )
+    if result.returncode != 0 or not target_path.exists():
+        raise RuntimeError(
+            f"Failed to create synchronized study video: {source_path}\n{result.stderr}"
+        )
+
+
+def ensure_synchronized_study_videos(
+    reference_video: str,
+    left_video: str,
+    right_video: str,
+    project_root: Path,
+    target_fps: float = 30.0,
+) -> Dict[str, str]:
+    """
+    Create browser-playable synchronized copies for the three study videos.
+
+    The shorter videos are padded by cloning their last frame so that all three
+    outputs share the same fps and total duration. If synchronization fails for
+    any reason, the original paths are returned to keep the study app usable.
+    """
+    raw_paths = {
+        "reference_video": Path(reference_video).resolve(),
+        "left_video": Path(left_video).resolve(),
+        "right_video": Path(right_video).resolve(),
+    }
+    if imageio_ffmpeg is None or not all(path.exists() for path in raw_paths.values()):
+        return {key: str(path) for key, path in raw_paths.items()}
+
+    try:
+        durations = []
+        for path in raw_paths.values():
+            timing = _probe_video_timing(path)
+            durations.append(float(timing.get("duration_seconds", 0.0) or 0.0))
+
+        target_duration = max(durations)
+        if target_duration <= 0:
+            return {key: str(path) for key, path in raw_paths.items()}
+
+        cache_dir = _synced_video_cache_dir(project_root)
+        signature = hashlib.sha1(
+            "::".join(
+                [
+                    "sync_v1",
+                    f"fps={_format_ffmpeg_fps(target_fps)}",
+                    *(
+                        f"{path.as_posix()}::{path.stat().st_mtime_ns}::{path.stat().st_size}"
+                        for path in raw_paths.values()
+                    ),
+                ]
+            ).encode("utf-8")
+        ).hexdigest()[:16]
+        trio_dir = cache_dir / signature
+        lock_path = trio_dir.with_suffix(".lock")
+
+        with FileLock(str(lock_path)):
+            trio_dir.mkdir(parents=True, exist_ok=True)
+            output_paths = {
+                "reference_video": trio_dir / "reference.mp4",
+                "left_video": trio_dir / "left.mp4",
+                "right_video": trio_dir / "right.mp4",
+            }
+            ready = all(path.exists() and path.stat().st_size > 0 for path in output_paths.values())
+            if not ready:
+                for key, source_path in raw_paths.items():
+                    _sync_single_video_to_duration(
+                        source_path=source_path,
+                        target_path=output_paths[key],
+                        target_duration=target_duration,
+                        target_fps=target_fps,
+                    )
+            return {key: str(path) for key, path in output_paths.items()}
+    except Exception as exc:
+        print(f"[warn] Falling back to original study videos because sync generation failed: {exc}")
+        return {key: str(path) for key, path in raw_paths.items()}
+
+
+def ensure_web_playable_video(video_path: str, project_root: Path) -> str:
+    source_path = Path(video_path).resolve()
+    if not source_path.exists() or imageio_ffmpeg is None:
+        return str(source_path)
+
+    stream_info = _probe_video_stream(source_path)
+    if (
+        source_path.suffix.lower() == ".mp4"
+        and stream_info.get("codec_name") == "h264"
+        and (not stream_info.get("pixel_format") or stream_info.get("pixel_format") == "yuv420p")
+    ):
+        return str(source_path)
+
+    cache_dir = _web_video_cache_dir(project_root)
+    signature = hashlib.sha1(
+        f"{source_path.as_posix()}::{source_path.stat().st_mtime_ns}::{source_path.stat().st_size}".encode("utf-8")
+    ).hexdigest()[:12]
+    target_path = cache_dir / f"{source_path.stem}_{signature}.mp4"
+    lock_path = target_path.with_suffix(".lock")
+
+    with FileLock(str(lock_path)):
+        if target_path.exists() and target_path.stat().st_size > 0:
+            return str(target_path)
+
+        ffmpeg_exe = imageio_ffmpeg.get_ffmpeg_exe()
+        command = [
+            ffmpeg_exe,
+            "-y",
+            "-i",
+            str(source_path),
+            "-an",
+            "-c:v",
+            "libx264",
+            "-pix_fmt",
+            "yuv420p",
+            "-movflags",
+            "+faststart",
+            str(target_path),
+        ]
+        result = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="ignore",
+        )
+        if result.returncode != 0 or not target_path.exists():
+            raise RuntimeError(
+                f"Failed to convert video for browser playback: {source_path}\n{result.stderr}"
+            )
+
+    return str(target_path)
+
+
+def prepare_reference_videos_for_web(config: Dict[str, Any], project_root: Path) -> Dict[str, Any]:
+    for case in config.get("cases", []):
+        case["reference_video"] = ensure_web_playable_video(case["reference_video"], project_root)
+    return config
+
+
+def ensure_video_thumbnail(
+    video_path: str,
+    project_root: Path,
+    time_seconds: float = 0.8,
+    width: int = 480,
+) -> str:
+    source_path = Path(video_path).resolve()
+    if not source_path.exists() or imageio_ffmpeg is None:
+        return ""
+
+    cache_dir = _thumbnail_cache_dir(project_root)
+    signature = hashlib.sha1(
+        f"{source_path.as_posix()}::{source_path.stat().st_mtime_ns}::{source_path.stat().st_size}::{time_seconds}::{width}".encode(
+            "utf-8"
+        )
+    ).hexdigest()[:12]
+    target_path = cache_dir / f"{source_path.stem}_{signature}.jpg"
+    lock_path = target_path.with_suffix(".lock")
+
+    with FileLock(str(lock_path)):
+        if target_path.exists() and target_path.stat().st_size > 0:
+            return str(target_path)
+
+        ffmpeg_exe = imageio_ffmpeg.get_ffmpeg_exe()
+        command = [
+            ffmpeg_exe,
+            "-y",
+            "-ss",
+            str(time_seconds),
+            "-i",
+            str(source_path),
+            "-frames:v",
+            "1",
+            "-vf",
+            f"scale={width}:-1",
+            "-q:v",
+            "2",
+            str(target_path),
+        ]
+        result = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="ignore",
+        )
+        if result.returncode != 0 or not target_path.exists():
+            raise RuntimeError(
+                f"Failed to extract thumbnail from video: {source_path}\n{result.stderr}"
+            )
+
+    return str(target_path)
+
+
+def _resolve_path(config_dir: Path, raw_path: str) -> Path:
+    path = Path(raw_path)
+    if path.is_absolute():
+        return path
+    return (config_dir / path).resolve()
+
+
+def _resolve_single_match(config_dir: Path, directory: str, pattern: str, source_key: str) -> Path:
+    base_dir = _resolve_path(config_dir, directory)
+    if not base_dir.exists():
+        raise FileNotFoundError(f"Configured directory does not exist: {base_dir}")
+
+    resolved_pattern = pattern.format(source_key=source_key)
+    matches = sorted(base_dir.glob(resolved_pattern))
+    if not matches:
+        raise FileNotFoundError(
+            f"No video matched pattern '{resolved_pattern}' inside '{base_dir}' for source_key='{source_key}'."
+        )
+    if len(matches) > 1:
+        match_str = ", ".join(str(match) for match in matches)
+        raise ValueError(
+            f"Pattern '{resolved_pattern}' for source_key='{source_key}' matched multiple files: {match_str}"
+        )
+    return matches[0].resolve()
+
+
+def _normalize_case(
+    raw_case: Dict[str, Any],
+    raw_config: Dict[str, Any],
+    config_dir: Path,
+    method_ids: List[str],
+) -> Dict[str, Any]:
+    case_id = raw_case["case_id"]
+    source_key = raw_case.get("source_key", case_id)
+    case_title = raw_case.get("title") or humanize_source_key(source_key)
+
+    if raw_case.get("reference_video") and raw_case.get("method_videos"):
+        reference_video = _resolve_path(config_dir, raw_case["reference_video"]).resolve()
+        method_videos = {
+            method_id: _resolve_path(config_dir, raw_case["method_videos"][method_id]).resolve()
+            for method_id in method_ids
+        }
+    else:
+        reference_cfg = raw_config["reference"]
+        reference_video = _resolve_single_match(
+            config_dir=config_dir,
+            directory=reference_cfg["directory"],
+            pattern=reference_cfg["glob"],
+            source_key=source_key,
+        )
+        method_videos = {}
+        for method_id in method_ids:
+            method_cfg = raw_config["methods"][method_id]
+            method_videos[method_id] = _resolve_single_match(
+                config_dir=config_dir,
+                directory=method_cfg["directory"],
+                pattern=method_cfg["glob"],
+                source_key=source_key,
+            )
+
+    missing_files = [reference_video, *method_videos.values()]
+    for path in missing_files:
+        if not path.exists():
+            raise FileNotFoundError(f"Missing video file for case '{case_id}': {path}")
+
+    return {
+        "case_id": case_id,
+        "source_key": source_key,
+        "case_title": case_title,
+        "reference_video": str(reference_video),
+        "method_videos": {method_id: str(path) for method_id, path in method_videos.items()},
+    }
+
+
+def load_study_config(config_path: str | Path) -> Dict[str, Any]:
+    config_path = Path(config_path).resolve()
+    config_dir = config_path.parent
+
+    with config_path.open("r", encoding="utf-8") as handle:
+        raw_config = json.load(handle)
+
+    if "methods" not in raw_config or "cases" not in raw_config:
+        raise ValueError("study_config.json must define both 'methods' and 'cases'.")
+
+    method_ids = list(raw_config["methods"].keys())
+    if set(method_ids) != set(METHOD_FALLBACK_LABELS.keys()):
+        raise ValueError(
+            "This sample project expects exactly three methods: anyact, vlm_hy_motion, echomotion."
+        )
+
+    pair_order = raw_config.get("pair_order", [list(pair) for pair in PAIRWISE_METHOD_PAIRS])
+    normalized_pairs: List[Tuple[str, str]] = []
+    for raw_pair in pair_order:
+        if len(raw_pair) != 2:
+            raise ValueError(f"Each pair_order entry must contain exactly two methods: {raw_pair}")
+        left, right = raw_pair
+        if left not in method_ids or right not in method_ids:
+            raise ValueError(f"Unknown method in pair_order: {raw_pair}")
+        normalized_pairs.append((left, right))
+
+    methods = {}
+    for method_id, method_cfg in raw_config["methods"].items():
+        methods[method_id] = {
+            "display_name": method_cfg.get("display_name", METHOD_FALLBACK_LABELS[method_id]),
+            "directory": method_cfg.get("directory", ""),
+            "glob": method_cfg.get("glob", ""),
+        }
+
+    cases = [
+        _normalize_case(
+            raw_case=raw_case,
+            raw_config=raw_config,
+            config_dir=config_dir,
+            method_ids=method_ids,
+        )
+        for raw_case in raw_config["cases"]
+    ]
+
+    raw_pair_limits = raw_config.get("per_participant_pair_limits", {})
+    pair_sample_limits: Dict[str, int] = {}
+    for method_a, method_b in normalized_pairs:
+        pair_id = build_pair_id(method_a, method_b)
+        raw_limit = raw_pair_limits.get(pair_id, len(cases))
+        try:
+            limit_value = int(raw_limit)
+        except (TypeError, ValueError) as exc:
+            raise ValueError(f"Invalid per_participant_pair_limits value for '{pair_id}': {raw_limit}") from exc
+        if limit_value <= 0 or limit_value > len(cases):
+            raise ValueError(
+                f"per_participant_pair_limits['{pair_id}'] must be within [1, {len(cases)}], got {limit_value}."
+            )
+        pair_sample_limits[pair_id] = limit_value
+
+    disjoint_case_sampling = bool(raw_config.get("disjoint_case_sampling", False))
+    if disjoint_case_sampling and sum(pair_sample_limits.values()) > len(cases):
+        raise ValueError(
+            "disjoint_case_sampling=True requires the sum of per-participant pair limits "
+            f"to be <= number of cases ({len(cases)})."
+        )
+
+    case_ids = {case["case_id"] for case in cases}
+    instruction_case_id = raw_config.get("instruction_case_id")
+    if instruction_case_id and instruction_case_id not in case_ids:
+        raise ValueError(f"instruction_case_id='{instruction_case_id}' is not present in cases.")
+    if not instruction_case_id:
+        instruction_case_id = cases[0]["case_id"]
+
+    return {
+        "study_id": raw_config.get("study_id", "anyact_user_study"),
+        "study_title": raw_config.get("study_title", "Human Motion Reenactment User Study"),
+        "question_order": raw_config.get("question_order", "shuffle_per_participant"),
+        "allow_tie_option": raw_config.get("allow_tie_option", True),
+        "pair_order": normalized_pairs,
+        "pair_sample_limits": pair_sample_limits,
+        "disjoint_case_sampling": disjoint_case_sampling,
+        "question_bank_total": len(cases) * len(normalized_pairs),
+        "participant_question_total": sum(pair_sample_limits.values()),
+        "methods": methods,
+        "cases": cases,
+        "instruction_case_id": instruction_case_id,
+        "config_path": str(config_path),
+    }
+
+
+def get_instruction_case(config: Dict[str, Any]) -> Dict[str, Any]:
+    target_case_id = config["instruction_case_id"]
+    for case in config["cases"]:
+        if case["case_id"] == target_case_id:
+            return case
+    raise KeyError(f"Instruction case '{target_case_id}' was not found.")
+
+
+def build_questions(config: Dict[str, Any], participant_id: str) -> List[Dict[str, Any]]:
+    questions: List[Dict[str, Any]] = []
+    cases = list(config["cases"])
+    pair_case_assignments: Dict[str, List[Dict[str, Any]]] = {}
+
+    if config.get("disjoint_case_sampling"):
+        shuffled_cases = list(cases)
+        assignment_rng = random.Random(stable_int_seed(f"{config['study_id']}::{participant_id}::case_assignment"))
+        assignment_rng.shuffle(shuffled_cases)
+
+        cursor = 0
+        for method_a, method_b in config["pair_order"]:
+            pair_id = build_pair_id(method_a, method_b)
+            sample_size = config["pair_sample_limits"][pair_id]
+            selected_cases = shuffled_cases[cursor : cursor + sample_size]
+            if len(selected_cases) != sample_size:
+                raise ValueError(
+                    f"Not enough unique cases to assign pair '{pair_id}'. Requested {sample_size}, got {len(selected_cases)}."
+                )
+            pair_case_assignments[pair_id] = selected_cases
+            cursor += sample_size
+    else:
+        for method_a, method_b in config["pair_order"]:
+            pair_id = build_pair_id(method_a, method_b)
+            sample_size = config["pair_sample_limits"][pair_id]
+            pair_rng = random.Random(stable_int_seed(f"{config['study_id']}::{participant_id}::{pair_id}::sample"))
+            pair_case_assignments[pair_id] = pair_rng.sample(cases, sample_size)
+
+    for method_a, method_b in config["pair_order"]:
+        pair_id = build_pair_id(method_a, method_b)
+        for case in pair_case_assignments[pair_id]:
+            order_rng = random.Random(
+                stable_int_seed(f"{config['study_id']}::{participant_id}::{case['case_id']}::{method_a}::{method_b}")
+            )
+            result_a_method, result_b_method = (method_a, method_b)
+            if order_rng.random() < 0.5:
+                result_a_method, result_b_method = result_b_method, result_a_method
+
+            questions.append(
+                {
+                    "case_id": case["case_id"],
+                    "case_title": case["case_title"],
+                    "source_key": case["source_key"],
+                    "pair_id": pair_id,
+                    "reference_video": case["reference_video"],
+                    "result_a_method": result_a_method,
+                    "result_b_method": result_b_method,
+                    "left_method": result_a_method,
+                    "right_method": result_b_method,
+                    "result_a_video": case["method_videos"][result_a_method],
+                    "result_b_video": case["method_videos"][result_b_method],
+                    "left_video": case["method_videos"][result_a_method],
+                    "right_video": case["method_videos"][result_b_method],
+                }
+            )
+
+    if config["question_order"] == "shuffle_per_participant":
+        shuffle_rng = random.Random(stable_int_seed(f"{config['study_id']}::{participant_id}::question_order"))
+        shuffle_rng.shuffle(questions)
+
+    total_questions = len(questions)
+    for index, question in enumerate(questions, start=1):
+        question["question_number"] = index
+        question["question_id"] = f"Q{index:03d}_{question['case_id']}_{question['pair_id']}"
+        question["total_questions"] = total_questions
+
+    return questions
+
+
+def _state_path(project_root: Path, participant_id: str) -> Path:
+    return get_results_dir(project_root) / "participants" / f"{participant_id}.json"
+
+
+def _archive_dir(project_root: Path) -> Path:
+    return get_results_dir(project_root) / "participants_archive"
+
+
+def _lock_path(project_root: Path) -> Path:
+    return get_results_dir(project_root) / "locks" / "results.lock"
+
+
+def _responses_jsonl_path(project_root: Path) -> Path:
+    return get_results_dir(project_root) / "responses.jsonl"
+
+
+def _responses_csv_path(project_root: Path) -> Path:
+    return get_results_dir(project_root) / "responses.csv"
+
+
+def _read_state_unlocked(project_root: Path, participant_id: str) -> Dict[str, Any] | None:
+    path = _state_path(project_root, participant_id)
+    if not path.exists():
+        return None
+    with path.open("r", encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def _atomic_write_json(path: Path, data: Dict[str, Any]) -> None:
+    temp_path = path.with_suffix(path.suffix + ".tmp")
+    with temp_path.open("w", encoding="utf-8") as handle:
+        json.dump(data, handle, ensure_ascii=False, indent=2)
+    os.replace(temp_path, path)
+
+
+def _write_state_unlocked(project_root: Path, state: Dict[str, Any]) -> None:
+    _atomic_write_json(_state_path(project_root, state["participant_id"]), state)
+
+
+def _archive_state_unlocked(project_root: Path, state: Dict[str, Any]) -> None:
+    archive_dir = _archive_dir(project_root)
+    timestamp = re.sub(r"[^0-9A-Za-z_-]", "-", now_iso())
+    filename = f"{state.get('participant_id', 'participant')}__{state.get('study_id', 'study')}__{timestamp}.json"
+    _atomic_write_json(archive_dir / filename, state)
+
+
+def _append_jsonl_unlocked(project_root: Path, payload: Dict[str, Any]) -> None:
+    jsonl_path = _responses_jsonl_path(project_root)
+    with jsonl_path.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(payload, ensure_ascii=False) + "\n")
+
+
+def _normalize_canonical_row(row: Dict[str, Any]) -> Dict[str, Any]:
+    upgraded_row = upgrade_response_row_schema(row)
+    return {column: upgraded_row.get(column, "") for column in CSV_COLUMNS}
+
+
+def _canonical_row_key(row: Dict[str, Any]) -> Tuple[str, str, str] | None:
+    participant_id = str(row.get("participant_id", "")).strip()
+    question_id = str(row.get("question_id", "")).strip()
+    if not participant_id or not question_id:
+        return None
+    study_id = str(row.get("study_id", "")).strip()
+    return study_id, participant_id, question_id
+
+
+def _canonical_row_sort_key(row: Dict[str, Any]) -> Tuple[str, str, str]:
+    return (
+        str(row.get("event_saved_at") or row.get("answered_at") or ""),
+        str(row.get("updated_at") or ""),
+        str(row.get("answered_at") or ""),
+    )
+
+
+def _merge_canonical_rows(*row_groups: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    merged_rows: Dict[Tuple[str, str, str], Tuple[Tuple[str, str, str], Dict[str, Any]]] = {}
+    for rows in row_groups:
+        for row in rows:
+            row_key = _canonical_row_key(row)
+            if row_key is None:
+                continue
+            sort_key = _canonical_row_sort_key(row)
+            previous = merged_rows.get(row_key)
+            if previous is None or sort_key >= previous[0]:
+                merged_rows[row_key] = (sort_key, _normalize_canonical_row(row))
+
+    canonical_rows = [payload for _, payload in merged_rows.values()]
+    canonical_rows.sort(
+        key=lambda row: (row.get("answered_at", ""), row.get("participant_id", ""), row.get("question_id", ""))
+    )
+    return canonical_rows
+
+
+def _load_canonical_rows_from_jsonl_unlocked(project_root: Path) -> List[Dict[str, Any]]:
+    jsonl_path = _responses_jsonl_path(project_root)
+    if not jsonl_path.exists() or jsonl_path.stat().st_size <= 0:
+        return []
+
+    latest_rows: Dict[Tuple[str, str, str], Tuple[Tuple[str, str, str], Dict[str, Any]]] = {}
+    with jsonl_path.open("r", encoding="utf-8") as handle:
+        for line in handle:
+            if not line.strip():
+                continue
+            try:
+                record = json.loads(line)
+            except json.JSONDecodeError:
+                # A truncated trailing line should not make the whole study unreadable.
+                continue
+
+            row_key = _canonical_row_key(record)
+            if row_key is None:
+                continue
+
+            sort_key = _canonical_row_sort_key(record)
+            previous = latest_rows.get(row_key)
+            if previous is None or sort_key >= previous[0]:
+                latest_rows[row_key] = (sort_key, _normalize_canonical_row(record))
+
+    rows = [payload for _, payload in latest_rows.values()]
+    rows.sort(key=lambda row: (row.get("answered_at", ""), row.get("participant_id", ""), row.get("question_id", "")))
+    return rows
+
+
+def _load_canonical_rows_from_state_files_unlocked(project_root: Path) -> List[Dict[str, Any]]:
+    rows: List[Dict[str, Any]] = []
+    state_dirs = [
+        get_results_dir(project_root) / "participants",
+        _archive_dir(project_root),
+    ]
+    for state_dir in state_dirs:
+        for state_path in sorted(state_dir.glob("*.json")):
+            with state_path.open("r", encoding="utf-8") as handle:
+                state = json.load(handle)
+            for row in state.get("answers", {}).values():
+                rows.append(_normalize_canonical_row(row))
+    rows.sort(key=lambda row: (row.get("answered_at", ""), row.get("participant_id", ""), row.get("question_id", "")))
+    return rows
+
+
+def _all_canonical_rows_unlocked(project_root: Path) -> List[Dict[str, Any]]:
+    state_rows = _load_canonical_rows_from_state_files_unlocked(project_root)
+    jsonl_rows = _load_canonical_rows_from_jsonl_unlocked(project_root)
+    merged_rows = _merge_canonical_rows(state_rows, jsonl_rows)
+    if merged_rows:
+        return merged_rows
+    return []
+
+
+def _export_csv_unlocked(project_root: Path) -> None:
+    csv_path = _responses_csv_path(project_root)
+    temp_path = csv_path.with_suffix(".tmp")
+    rows = _all_canonical_rows_unlocked(project_root)
+    with temp_path.open("w", newline="", encoding="utf-8") as handle:
+        writer = csv.DictWriter(handle, fieldnames=CSV_COLUMNS)
+        writer.writeheader()
+        for row in rows:
+            writer.writerow(row)
+    os.replace(temp_path, csv_path)
+
+
+def get_current_question(state: Dict[str, Any]) -> Dict[str, Any]:
+    return state["questions"][state["current_index"]]
+
+
+def question_stable_key(question: Dict[str, Any]) -> str:
+    return f"{question['case_id']}::{question['pair_id']}"
+
+
+def refresh_state_video_paths(state: Dict[str, Any], config: Dict[str, Any]) -> Dict[str, Any]:
+    case_lookup = {case["case_id"]: case for case in config["cases"]}
+
+    for question in state.get("questions", []):
+        case = case_lookup.get(question.get("case_id"))
+        if not case:
+            continue
+        upgrade_response_row_schema(question, case=case)
+
+    for answer in state.get("answers", {}).values():
+        case = case_lookup.get(answer.get("case_id"))
+        if not case:
+            continue
+        upgrade_response_row_schema(answer, case=case)
+
+    return state
+
+
+def sync_state_with_config(state: Dict[str, Any], config: Dict[str, Any]) -> Dict[str, Any]:
+    new_questions = build_questions(config=config, participant_id=state["participant_id"])
+    old_questions = state.get("questions", [])
+    old_answers = state.get("answers", {})
+    case_lookup = {case["case_id"]: case for case in config["cases"]}
+
+    old_current_key = None
+    if old_questions:
+        old_index = min(max(int(state.get("current_index", 0)), 0), len(old_questions) - 1)
+        old_current_key = question_stable_key(old_questions[old_index])
+
+    old_questions_by_key = {
+        question_stable_key(question): question
+        for question in old_questions
+        if question.get("case_id") and question.get("pair_id")
+    }
+
+    old_rows_by_key = {
+        question_stable_key(answer_row): answer_row
+        for answer_row in old_answers.values()
+        if answer_row.get("case_id") and answer_row.get("pair_id")
+    }
+
+    synced_answers: Dict[str, Dict[str, Any]] = {}
+    for question in new_questions:
+        stable_key = question_stable_key(question)
+        case = case_lookup.get(question["case_id"])
+        previous_question = old_questions_by_key.get(stable_key)
+        if previous_question:
+            question["result_a_method"] = previous_question.get("result_a_method") or previous_question.get("left_method")
+            question["result_b_method"] = previous_question.get("result_b_method") or previous_question.get("right_method")
+        _sync_result_slot_fields(question, case=case)
+
+        previous_row = old_rows_by_key.get(stable_key)
+        if not previous_row:
+            continue
+
+        upgraded_row = {
+            **previous_row,
+            "study_id": config["study_id"],
+            "study_title": config["study_title"],
+            "question_id": question["question_id"],
+            "question_position": question["question_number"],
+            "total_questions": question["total_questions"],
+            "case_id": question["case_id"],
+            "case_title": question["case_title"],
+            "source_key": question["source_key"],
+            "pair_id": question["pair_id"],
+            "result_a_method": question["result_a_method"],
+            "result_b_method": question["result_b_method"],
+            "left_method": question["left_method"],
+            "right_method": question["right_method"],
+            "reference_video": question["reference_video"],
+            "result_a_video": question["result_a_video"],
+            "result_b_video": question["result_b_video"],
+            "left_video": question["left_video"],
+            "right_video": question["right_video"],
+        }
+        synced_answers[question["question_id"]] = upgrade_response_row_schema(upgraded_row, case=case)
+
+    current_index = 0
+    if new_questions:
+        if old_current_key is not None:
+            matched_index = next(
+                (index for index, question in enumerate(new_questions) if question_stable_key(question) == old_current_key),
+                None,
+            )
+            if matched_index is not None:
+                current_index = matched_index
+
+        first_unanswered_index = next(
+            (
+                index
+                for index, question in enumerate(new_questions)
+                if question["question_id"] not in synced_answers
+            ),
+            None,
+        )
+        if first_unanswered_index is not None:
+            current_index = first_unanswered_index
+        else:
+            current_index = len(new_questions) - 1
+
+    state["study_id"] = config["study_id"]
+    state["study_title"] = config["study_title"]
+    state["questions"] = new_questions
+    state["answers"] = synced_answers
+    state["current_index"] = current_index
+
+    if new_questions and len(synced_answers) == len(new_questions):
+        state["completed_at"] = state.get("completed_at") or now_iso()
+        state["status"] = "completed"
+        state["current_question_started_at"] = None
+    else:
+        state["completed_at"] = None
+        state["status"] = "in_progress"
+        state["current_question_started_at"] = time.time()
+
+    return refresh_state_video_paths(state, config)
+
+
+def _upgrade_state_schema(state: Dict[str, Any], config: Dict[str, Any]) -> Dict[str, Any]:
+    upgraded_state = copy.deepcopy(state)
+    upgraded_state["study_title"] = config["study_title"]
+    return refresh_state_video_paths(upgraded_state, config)
+
+
+def upgrade_existing_results_schema(project_root: Path, config: Dict[str, Any]) -> None:
+    ensure_runtime_dirs(project_root)
+    state_dirs = [
+        get_results_dir(project_root) / "participants",
+        _archive_dir(project_root),
+    ]
+
+    with FileLock(str(_lock_path(project_root))):
+        for state_dir in state_dirs:
+            for state_path in sorted(state_dir.glob("*.json")):
+                try:
+                    with state_path.open("r", encoding="utf-8") as handle:
+                        state = json.load(handle)
+                except json.JSONDecodeError:
+                    continue
+
+                upgraded_state = _upgrade_state_schema(state, config)
+                if upgraded_state != state:
+                    _atomic_write_json(state_path, upgraded_state)
+
+        _export_csv_unlocked(project_root)
+
+
+def create_or_resume_participant(
+    project_root: Path,
+    config: Dict[str, Any],
+    participant_id: str | None,
+    request: Any = None,
+) -> Tuple[Dict[str, Any], str]:
+    ensure_runtime_dirs(project_root)
+
+    participant_id = sanitize_participant_id(participant_id)
+    if not participant_id:
+        participant_id = generate_participant_id()
+
+    session_hash = getattr(request, "session_hash", "") if request is not None else ""
+    user_agent = request.headers.get("user-agent", "") if request is not None and getattr(request, "headers", None) else ""
+
+    with FileLock(str(_lock_path(project_root))):
+        existing_state = _read_state_unlocked(project_root, participant_id)
+        if existing_state:
+            if existing_state.get("study_id") != config["study_id"]:
+                if existing_state.get("answers"):
+                    _archive_state_unlocked(project_root, existing_state)
+                timestamp = now_iso()
+                fresh_state = {
+                    "participant_id": participant_id,
+                    "consent": True,
+                    "study_id": config["study_id"],
+                    "study_title": config["study_title"],
+                    "created_at": timestamp,
+                    "started_at": timestamp,
+                    "updated_at": timestamp,
+                    "completed_at": None,
+                    "status": "in_progress",
+                    "session_hash": session_hash,
+                    "user_agent": user_agent,
+                    "current_index": 0,
+                    "current_question_started_at": time.time(),
+                    "questions": build_questions(config=config, participant_id=participant_id),
+                    "answers": {},
+                }
+                _write_state_unlocked(project_root, fresh_state)
+                return fresh_state, "started"
+
+            existing_state = sync_state_with_config(existing_state, config)
+            if existing_state.get("completed_at"):
+                existing_state["session_hash"] = session_hash or existing_state.get("session_hash", "")
+                existing_state["user_agent"] = user_agent or existing_state.get("user_agent", "")
+                existing_state["updated_at"] = now_iso()
+                _write_state_unlocked(project_root, existing_state)
+                return existing_state, "completed"
+
+            existing_state["session_hash"] = session_hash or existing_state.get("session_hash", "")
+            existing_state["user_agent"] = user_agent or existing_state.get("user_agent", "")
+            existing_state["study_title"] = config["study_title"]
+            existing_state["updated_at"] = now_iso()
+            existing_state["current_question_started_at"] = time.time()
+            _write_state_unlocked(project_root, existing_state)
+            return existing_state, "resumed"
+
+        timestamp = now_iso()
+        state = {
+            "participant_id": participant_id,
+            "consent": True,
+            "study_id": config["study_id"],
+            "study_title": config["study_title"],
+            "created_at": timestamp,
+            "started_at": timestamp,
+            "updated_at": timestamp,
+            "completed_at": None,
+            "status": "in_progress",
+            "session_hash": session_hash,
+            "user_agent": user_agent,
+            "current_index": 0,
+            "current_question_started_at": time.time(),
+            "questions": build_questions(config=config, participant_id=participant_id),
+            "answers": {},
+        }
+        _write_state_unlocked(project_root, state)
+        return state, "started"
+
+
+def move_question_pointer(
+    project_root: Path,
+    participant_id: str,
+    question_token: str | None,
+    direction: str,
+) -> Tuple[Dict[str, Any], str]:
+    with FileLock(str(_lock_path(project_root))):
+        state = _read_state_unlocked(project_root, participant_id)
+        if state is None:
+            raise ValueError("Participant session could not be found.")
+
+        if state.get("completed_at"):
+            return state, "This study session has already been submitted."
+
+        current_question = get_current_question(state)
+        if question_token and current_question["question_id"] != question_token:
+            return state, "A newer page state was already loaded. Restored the latest progress."
+
+        if direction == "previous" and state["current_index"] > 0:
+            state["current_index"] -= 1
+            state["current_question_started_at"] = time.time()
+            state["updated_at"] = now_iso()
+            _write_state_unlocked(project_root, state)
+
+        return state, ""
+
+
+def _build_response_row(
+    state: Dict[str, Any],
+    question: Dict[str, Any],
+    answer_similarity: str,
+    answer_quality: str,
+    answer_preference: str,
+    duration_seconds: float,
+) -> Dict[str, Any]:
+    timestamp = now_iso()
+    response_row = {
+        "participant_id": state["participant_id"],
+        "consent": state.get("consent", True),
+        "study_id": state["study_id"],
+        "study_title": state["study_title"],
+        "question_id": question["question_id"],
+        "question_position": question["question_number"],
+        "total_questions": question["total_questions"],
+        "case_id": question["case_id"],
+        "case_title": question["case_title"],
+        "source_key": question["source_key"],
+        "pair_id": question["pair_id"],
+        "result_a_method": question.get("result_a_method") or question.get("left_method"),
+        "result_b_method": question.get("result_b_method") or question.get("right_method"),
+        "left_method": question["left_method"],
+        "right_method": question["right_method"],
+        "reference_video": question["reference_video"],
+        "result_a_video": question.get("result_a_video") or question.get("left_video"),
+        "result_b_video": question.get("result_b_video") or question.get("right_video"),
+        "left_video": question["left_video"],
+        "right_video": question["right_video"],
+        "answer_similarity": normalize_choice_value(answer_similarity),
+        "answer_quality": normalize_choice_value(answer_quality),
+        "answer_preference": normalize_choice_value(answer_preference),
+        "answered_at": timestamp,
+        "duration_seconds": round(duration_seconds, 3),
+        "session_hash": state.get("session_hash", ""),
+        "user_agent": state.get("user_agent", ""),
+        "started_at": state.get("started_at", ""),
+        "updated_at": timestamp,
+    }
+    return upgrade_response_row_schema(response_row)
+
+
+def save_current_answer(
+    project_root: Path,
+    participant_id: str,
+    question_token: str,
+    answer_similarity: str,
+    answer_quality: str,
+    answer_preference: str,
+    action: str,
+) -> Tuple[Dict[str, Any], str, str]:
+    if action not in {"next", "submit"}:
+        raise ValueError(f"Unsupported action: {action}")
+
+    with FileLock(str(_lock_path(project_root))):
+        state = _read_state_unlocked(project_root, participant_id)
+        if state is None:
+            raise ValueError("Participant session could not be found.")
+
+        if state.get("completed_at"):
+            return state, "This study session has already been submitted.", "completed"
+
+        current_question = get_current_question(state)
+        if current_question["question_id"] != question_token:
+            return state, "A newer page state was already loaded. Restored the latest progress.", "stale"
+
+        elapsed = max(0.0, time.time() - float(state.get("current_question_started_at") or time.time()))
+        previous_row = state["answers"].get(question_token)
+        response_row = _build_response_row(
+            state=state,
+            question=current_question,
+            answer_similarity=answer_similarity,
+            answer_quality=answer_quality,
+            answer_preference=answer_preference,
+            duration_seconds=elapsed,
+        )
+
+        state["answers"][question_token] = response_row
+        state["updated_at"] = response_row["answered_at"]
+        event_type = "answer_updated" if previous_row else "answer_saved"
+
+        if action == "next":
+            if state["current_index"] < len(state["questions"]) - 1:
+                state["current_index"] += 1
+                state["current_question_started_at"] = time.time()
+                status = "advanced"
+                message = "Response saved."
+            else:
+                state["completed_at"] = response_row["answered_at"]
+                state["status"] = "completed"
+                state["current_question_started_at"] = None
+                status = "completed"
+                message = "All responses have been submitted."
+        else:
+            state["completed_at"] = response_row["answered_at"]
+            state["status"] = "completed"
+            state["current_question_started_at"] = None
+            status = "completed"
+            message = "All responses have been submitted."
+
+        _write_state_unlocked(project_root, state)
+        _append_jsonl_unlocked(
+            project_root,
+            {
+                "event_type": event_type,
+                "event_saved_at": response_row["answered_at"],
+                **response_row,
+            },
+        )
+        _export_csv_unlocked(project_root)
+
+        return state, message, status
+
+
+def build_question_payload(state: Dict[str, Any]) -> Dict[str, Any]:
+    question = get_current_question(state)
+    saved_answers = state.get("answers", {}).get(question["question_id"], {})
+    answered_count = len(state.get("answers", {}))
+
+    return {
+        "question_token": question["question_id"],
+        "progress_markdown": (
+            f"<div class='progress-chip'>Question {question['question_number']} / {question['total_questions']}</div>"
+            f"<div class='meta-line'>Participant ID: <code>{state['participant_id']}</code></div>"
+            f"<div class='meta-line'>Saved responses: {answered_count} / {question['total_questions']}</div>"
+        ),
+        "instruction_markdown": (
+            "Watch the reference clip and both anonymous candidates before answering all three questions."
+        ),
+        "reference_video": question["reference_video"],
+        "result_a_video": question.get("result_a_video") or question["left_video"],
+        "result_b_video": question.get("result_b_video") or question["right_video"],
+        "left_video": question["left_video"],
+        "right_video": question["right_video"],
+        "answer_similarity": normalize_choice_value(saved_answers.get("answer_similarity")),
+        "answer_quality": normalize_choice_value(saved_answers.get("answer_quality")),
+        "answer_preference": normalize_choice_value(saved_answers.get("answer_preference")),
+        "show_previous": question["question_number"] > 1,
+        "show_next": question["question_number"] < question["total_questions"],
+        "show_submit": question["question_number"] == question["total_questions"],
+    }
+
+
+def build_completion_markdown(state: Dict[str, Any]) -> str:
+    completed_at = state.get("completed_at") or now_iso()
+    total_questions = len(state.get("questions", []))
+    answered_count = len(state.get("answers", {}))
+    return f"""
+## Thank you for completing the study.
+
+Your responses have been saved successfully.
+
+- Participant ID: `{state["participant_id"]}`
+- Saved answers: `{answered_count} / {total_questions}`
+- Completed at: `{completed_at}`
+
+You may now close this page.
+""".strip()