combo_engine.py

import logging
import sys
import threading
import time
from pathlib import Path
from typing import Any, Callable

from Game_Wuthering_Waves import (
    WW_DEFAULT_COMBO_ENDERS,
    WW_DEFAULT_COMBO_ENDERS_SOFT,
    WW_DEFAULT_TRANSCRIBE_KEYS,
    WutheringWavesGame,
    set_active_ww_team,
    save_or_update_ww_team,
    delete_ww_team,
    select_team_stateless,
    save_ww_character_cmd,
    delete_ww_character_cmd,
    update_ww_dash_cmd,
    save_ww_character_note_cmd,
)
import combo_analytics
import combo_engine_ui as ui
from combo_engine_ui import Status
from persistence import load_engine_state, save_engine_state
from state_store import JsonStateStore, StateStore

import _combo_commands as combo_commands
from parser import expanded_ast_from_tokens, runtime_source_token_indices_from_tokens, split_inputs
import format_utils
import stats_recording
import step_introspection
from combo_engine_ui_adapter import UIAdapter
from states import (
    AcceptResult,
    CompleteResult,
    FailResult,
    GroupState,
    HoldState,
    HoldWithBodyState,
    IgnoreResult,
    PressState,
    SequenceState,
    SpamState,
    WaitState,
    build_runtime_state,
)

logger = logging.getLogger(__name__)


class ComboTrackerEngine:
    """
    Headless combo tracker:
    - Owns combos + stats persistence
    - Owns state machine (press/hold/wait + ender cooldown)
    - Emits UI events via a callback (WebSocket, etc.)
    """

    def __init__(
        self,
        *,
        state_store: StateStore | None = None,
        monotonic_now: Callable[[], float] | None = None,
    ):
        # Engine is mutated from multiple threads:
        # - pynput keyboard/mouse callbacks
        # - ui_server tick thread (wait completion without input)
        self._lock = threading.RLock()
        self._now: Callable[[], float] = monotonic_now or time.perf_counter
        # --- Data & State ---
        self.combos: dict[str, list[str]] = {}
        self.active_combo_name: str | None = None
        self.active_combo_tokens: list[str] = []
        self.runtime_steps: list[Any] = []  # list[StepState]

        self.current_index = 0

        # Shortcuts to active step when it's a hold or wait (updated on advance)
        self.hold: HoldState | None = None
        self.wait: WaitState | None = None
        self.start_time = 0.0
        self.last_input_time = 0.0
        # Boundary-based timing: finalize previous step when next boundary is reached.
        self.pending_step_label: str | None = None
        self.pending_step_started_at = 0.0
        # Wall-clock anchor for macro-style row deltas (replay + hold_with_body manual)
        self._attempt_hit_clock: float | None = None
        self.attempt_counter = 0
        # Replay owns time-based advancement while active. The normal 50 Hz tick
        # must not race confirmed macro markers for holds and nested waits.
        self._replay_active = False

        self.hold_in_progress = False
        self.hold_expected_input: str | None = None
        self.hold_started_at = 0.0
        self.hold_required_ms: int | None = None
        # Max hold duration observed this step (for drop message: "but held for Xms")
        self._hold_max_held_ms: float = 0.0

        self.wait_in_progress = False
        self.wait_started_at = 0.0
        self.wait_required_ms: int | None = None

        self.currently_pressed: set[str] = set()

        # Per-attempt visual annotations for the timeline UI.
        # step_index -> mark string (e.g. "ok", "early", "missed", "wrong")
        self.step_marks: dict[int, str] = {}
        # For soft waits: track if the *next expected input* was pressed during the wait window.
        # So we only send wait_begin once per group mandatory wait (UI animates progress).
        self.ui_adapter = UIAdapter()

        # Generalized hold buffer: after any advance, if the next step is a hold and that key
        # is already in currently_pressed, we start the hold immediately (no separate buffer state).

        # Combo enders: key -> cooldown_ms (0 = no cooldown; wrong press drops immediately)
        self.combo_enders: dict[str, int] = dict(WW_DEFAULT_COMBO_ENDERS)
        # Soft enders: keys that do not drop the combo when pressed during a hold step (~key:2s)
        self.combo_enders_soft: set[str] = set(WW_DEFAULT_COMBO_ENDERS_SOFT)
        # Auto-transcribe: comma-separated valid keys (persisted like combo_enders)
        self.transcribe_valid_keys: str = WW_DEFAULT_TRANSCRIBE_KEYS
        # Key that begins a transcription when auto-transcribe is on (normalized token, e.g. f, space, lmb)
        self.transcribe_start_key: str = "f"
        # When enabled and transcribe_strip_wait_under_ms is non-empty, omit wait: below that many ms.
        self.transcribe_strip_wait_under_enabled: bool = False
        self.transcribe_strip_wait_under_ms: str = "0"
        # Per-ender cooldown: key -> monotonic time when that key's cooldown ends.
        # When the user correctly presses an ender key, we set cooldown for that key so
        # re-pressing it during a wait/hold doesn't drop the combo until cooldown expires.
        self._ender_cooldown_until: dict[str, float] = {}

        # UI helper: after a successful completion we reset current_index back to 0 (ready for next attempt),
        # but we still want the timeline to stay fully "completed" (green) until the next attempt begins.
        self._ui_last_success_combo: str | None = None
        self._ui_last_success_steps_len: int = 0

        # No-fail (practice) mode: on failure, mark step red and advance instead of resetting combo.
        self.no_fail_mode: bool = False

        # Macro replay settings (persisted)
        self.macro_start_key: str = "f8"
        self.macro_stop_key: str = "f9"
        self.macro_spam_interval_ms: int | None = 100

        # Stats
        self.combo_stats: dict[str, dict[str, Any]] = {}
        # Per-combo metadata (kept minimal on purpose)
        # - expected_ms: user-entered typical execution time (used for Practical APM / difficulty)
        self.combo_expected_ms: dict[str, int] = {}
        # - user_difficulty: user-entered difficulty rating (0..10)
        self.combo_user_difficulty: dict[str, float] = {}

        # Optional: per-combo step display configuration
        # - combo_step_display_mode: "icons" (default) or "images"
        self.combo_step_display_mode: dict[str, str] = {}
        # - combo_key_images: combo_name -> { key -> image_url }
        self.combo_key_images: dict[str, dict[str, str]] = {}
        # - combo_demo_video: combo_name -> video URL (e.g. YouTube link for embedded demo)
        self.combo_demo_video: dict[str, str] = {}

        # Game-specific state (kept out of the core combo engine logic)
        self.ww = WutheringWavesGame()

        # Emission
        self._emit: Callable[[dict[str, Any]], None] | None = None

        # Persistence
        self.data_dir = self._get_data_dir()
        self.save_path = self.data_dir / "combos.json"
        self.state_store: StateStore = state_store or JsonStateStore(
            self.save_path, seed_path=self.data_dir / "combos.example.json"
        )

        # Load persisted state
        self.load_combos()

    # -------------------------
    # Backwards-compatible accessors (WW fields used throughout the engine)
    # -------------------------
    # These properties keep older code paths working while the WW logic is moved into
    # `Game_Wuthering_Waves.py`.

    @property
    def ww_teams(self) -> dict[str, dict[str, Any]]:
        return self.ww.ww_teams

    @ww_teams.setter
    def ww_teams(self, value: dict[str, dict[str, Any]]):
        self.ww.ww_teams = value

    @property
    def ww_active_team_id(self) -> str | None:
        return self.ww.ww_active_team_id

    @ww_active_team_id.setter
    def ww_active_team_id(self, value: str | None):
        self.ww.ww_active_team_id = value

    @property
    def combo_ww_team(self) -> dict[str, str]:
        return self.ww.combo_ww_team

    @combo_ww_team.setter
    def combo_ww_team(self, value: dict[str, str]):
        self.ww.combo_ww_team = value

    @property
    def ww_active_character(self) -> str | None:
        return self.ww.ww_active_character

    # -------------------------
    # Emission helpers
    # -------------------------

    def set_emitter(self, emit_func: Callable[[dict[str, Any]], None] | None):
        """Set an event emitter callback. It must be thread-safe."""
        self._emit = emit_func

    def _send(self, msg: dict[str, Any]):
        if self._emit:
            try:
                self._emit(msg)
            except Exception:
                # Never let UI plumbing crash input processing
                logger.debug("Emitter raised while sending message", exc_info=True)

    def _emit_stats_and_fail(self):
        self._send({"type": "stat_update", "stats": ui.stats_text(self)})
        self._send({"type": "fail_update", "fail_by_step": ui.failures_by_step(self)})

    # -------------------------
    # Normalization helpers (delegate to input_normalization)
    # -------------------------

    def _mark_step(self, step_index: int, mark: str):
        """
        Set a per-attempt mark for a step (for UI coloring).
        Later marks overwrite earlier ones (e.g. wait can go from "early" -> "ok").
        """
        try:
            idx = int(step_index)
        except Exception:
            return
        if idx < 0:
            return
        m = str(mark or "").strip().lower()
        if not m:
            return
        self.step_marks[idx] = m

    def _reset_attempt_marks(self):
        self.step_marks = {}

    def _next_non_wait_step_index(self, *, start_index: int) -> int | None:
        """Return the next step index >= start_index that is not a wait step."""
        try:
            for j in range(max(0, int(start_index)), len(self.runtime_steps)):
                if not isinstance(self.runtime_steps[j], WaitState):
                    return j
        except Exception:
            return None
        return None

    def _maybe_complete_combo_if_trailing_wait(self, *, now: float, total_ms: float) -> bool:
        """
        If the next expected step is a wait gate *and there are no further non-wait steps after it*,
        then the wait is effectively a no-op. In that case, complete the combo immediately.

        This avoids "hanging" on a trailing wait like: e, q, wait(r, 3.65s)
        (there's nothing left to time-gate).
        """
        try:
            step = self._active_runtime_step()
            if not isinstance(step, WaitState):
                return False
            # If there is any real action after this wait, it is not trailing.
            if self._next_non_wait_step_index(start_index=int(self.current_index) + 1) is not None:
                return False
        except Exception:
            return False

        self._on_combo_completed(total_ms)
        return True

    # -------------------------
    # Persistence
    # -------------------------

    def _get_data_dir(self) -> Path:
        if getattr(sys, "frozen", False):
            return Path(sys.executable).resolve().parent
        return Path(__file__).resolve().parent

    def load_combos(self):
        load_engine_state(self)

    def save_combos(self) -> bool:
        return save_engine_state(self)

    # -------------------------
    # Stats helpers
    # -------------------------

    # -------------------------
    # UI state snapshots
    # -------------------------

    def get_editor_payload(self) -> dict[str, Any]:
        return ui.get_editor_payload(self)

    def get_status(self) -> Status:
        return ui.get_status(self)

    def timeline_steps(self) -> list[dict[str, Any]]:
        return ui.timeline_steps(self, self._now())

    def init_payload(self) -> dict[str, Any]:
        return ui.init_payload(self)

    # -------------------------
    # Combo ender logic
    # -------------------------

    def _is_combo_ender(self, input_name: str) -> bool:
        return input_name in self.combo_enders

    def _ender_cooldown_ms(self, input_name: str) -> int:
        """Cooldown duration in ms for this ender key (0 = no cooldown)."""
        try:
            return int(self.combo_enders.get(input_name, 0))
        except Exception:
            return 0

    def _start_ender_cooldown(self, input_name: str, now: float) -> None:
        """When the user correctly presses an ender key, start that key's cooldown."""
        if not (input_name or "").strip() or not self._is_combo_ender(input_name):
            return
        ms = self._ender_cooldown_ms(input_name)
        if ms <= 0:
            return
        self._ender_cooldown_until[(input_name or "").strip().lower()] = now + (ms / 1000.0)

    def _ender_on_cooldown(self, input_name: str, *, now: float | None = None) -> bool:
        """True if this ender key was recently used correctly and is still on cooldown (ignore press)."""
        if not (input_name or "").strip() or not self._is_combo_ender(input_name):
            return False
        now = self._now() if now is None else float(now)
        until = self._ender_cooldown_until.get((input_name or "").strip().lower(), 0.0)
        return now <= until

    # -------------------------
    # Commands from UI
    # -------------------------

    def apply_enders_from_text(self, raw: str) -> tuple[bool, str | None]:
        with self._lock:
            return combo_commands.apply_enders_from_text(self, raw)

    def save_or_update_combo(
        self,
        *,
        name: str,
        inputs: str,
        enders: str | None,
        expected_time: str | None = None,
        user_difficulty: str | None = None,
        step_display_mode: str | None = None,
        key_images: Any | None = None,
        demo_video: str | None = None,
        ww_team_id: str | None = None,
        as_new: bool = False,
    ) -> tuple[bool, str | None]:
        with self._lock:
            return combo_commands.save_or_update_combo(
                self,
                name=name,
                inputs=inputs,
                enders=enders,
                expected_time=expected_time,
                user_difficulty=user_difficulty,
                step_display_mode=step_display_mode,
                key_images=key_images,
                demo_video=demo_video,
                ww_team_id=ww_team_id,
                as_new=as_new,
            )

    def delete_combo(self, name: str) -> tuple[bool, str | None]:
        with self._lock:
            return combo_commands.delete_combo(self, name)

    # -------------------------
    # Wuthering Waves teams (presets) - delegate to Game_Wuthering_Waves
    # -------------------------

    def set_active_ww_team(self, team_id: str):
        with self._lock:
            set_active_ww_team(self, team_id)

    def save_or_update_ww_team(
        self,
        *,
        team_id: str | None,
        team_name: str | None,
        slot1: str,
        slot2: str,
        slot3: str,
    ) -> tuple[bool, str | None]:
        with self._lock:
            return save_or_update_ww_team(
                self,
                team_id=team_id,
                team_name=team_name,
                slot1=slot1,
                slot2=slot2,
                slot3=slot3,
            )

    def save_ww_character(
        self,
        *,
        name: str,
        swap_image: str,
        lmb_image: str,
        ability_images: Any,
    ) -> tuple[bool, str | None]:
        with self._lock:
            return save_ww_character_cmd(
                self,
                name=name,
                swap_image=swap_image,
                lmb_image=lmb_image,
                ability_images=ability_images,
            )

    def delete_ww_character(self, name: str) -> tuple[bool, str | None]:
        with self._lock:
            return delete_ww_character_cmd(self, name=name)

    def save_ww_character_note(self, char_id: str, text: str) -> tuple[bool, str | None]:
        with self._lock:
            return save_ww_character_note_cmd(self, char_id=char_id, text=text)

    def update_ww_dash(self, dash_image: str) -> tuple[bool, str | None]:
        with self._lock:
            return update_ww_dash_cmd(self, dash_image=dash_image)

    def delete_ww_team(self, team_id: str) -> tuple[bool, str | None]:
        with self._lock:
            return delete_ww_team(self, team_id)

    def select_team_stateless(self, team_id: str):
        with self._lock:
            select_team_stateless(self, team_id)

    def new_combo(self):
        with self._lock:
            combo_commands.new_combo(self)

    def reorder_timeline_step(self, from_runtime_idx: int, before_runtime_idx: int | None) -> tuple[bool, str | None]:
        """Move a timeline tile (identified by its runtime index) to a new position.

        If before_runtime_idx is None the tile is appended to the end.
        Both indices refer to runtime steps produced by expanded_ast_from_tokens.
        Multi-token groups (e.g. press+wait:0.2s) are moved as a whole.
        """
        with self._lock:
            name = (self.active_combo_name or "").strip()
            if not name or name not in self.combos:
                return False, "No active combo selected."

            tokens = list(self.combos.get(name) or [])
            if not tokens:
                return False, "Active combo has no inputs."

            runtime_to_source = runtime_source_token_indices_from_tokens(tokens)
            if not runtime_to_source:
                return False, "Could not map timeline steps to input tokens."

            try:
                from_idx = int(from_runtime_idx)
            except Exception:
                return False, "Invalid from_step_index."

            if not (0 <= from_idx < len(runtime_to_source)):
                return False, "from_step_index out of range."

            src_group = runtime_to_source[from_idx]

            # Resolve the before target — first source token index of the drop target.
            before_src: int | None = None
            if before_runtime_idx is not None:
                try:
                    b_idx = int(before_runtime_idx)
                except Exception:
                    return False, "Invalid before_step_index."
                if not (0 <= b_idx < len(runtime_to_source)):
                    return False, "before_step_index out of range."
                before_src = runtime_to_source[b_idx][0]

            # Build ordered source groups: collapse all tokens into their logical tile groups.
            seen: set[int] = set()
            ordered_groups: list[list[int]] = []
            for group in runtime_to_source:
                key = tuple(group)
                if key not in seen:
                    seen.add(key)
                    ordered_groups.append(group)

            # Pull out the moving group and re-insert.
            moving = list(src_group)
            others = [g for g in ordered_groups if g != moving]

            if before_src is None:
                new_order = others + [moving]
            else:
                new_order = []
                inserted = False
                for g in others:
                    if not inserted and before_src in g:
                        new_order.append(moving)
                        inserted = True
                    new_order.append(g)
                if not inserted:
                    new_order.append(moving)

            # Reconstruct flat token list in the new order.
            new_tokens = [tokens[src_i] for g in new_order for src_i in g]

            if new_tokens == tokens:
                return True, None

            self.combos[name] = new_tokens
            self.save_combos()
            self.set_active_combo(name, emit=True)
            return True, None

    def delete_timeline_steps(self, step_indices: list[int]) -> tuple[bool, str | None]:
        with self._lock:
            name = (self.active_combo_name or "").strip()
            if not name or name not in self.combos:
                return False, "No active combo selected."

            tokens = list(self.combos.get(name) or [])
            if not tokens:
                return False, "Active combo has no inputs."

            runtime_to_source = runtime_source_token_indices_from_tokens(tokens)
            if not runtime_to_source:
                return False, "Could not map timeline steps to input tokens."

            src_to_remove: set[int] = set()
            for raw_idx in step_indices or []:
                try:
                    idx = int(raw_idx)
                except Exception:
                    continue
                if 0 <= idx < len(runtime_to_source):
                    src_to_remove.update(runtime_to_source[idx])

            if not src_to_remove:
                return False, "Nothing to delete for selected step."
            if len(src_to_remove) >= len(tokens):
                return False, "Combo must contain at least one input."

            new_tokens = [tok for i, tok in enumerate(tokens) if i not in src_to_remove]
            self.combos[name] = new_tokens
            self.save_combos()
            self.set_active_combo(name, emit=True)
            return True, None

    def send_transcription_result(self, transcript: str) -> None:
        """Push transcript to client: inputs field + parsed steps / timeline (used for live updates and when recording stops)."""
        with self._lock:
            self._send({"type": "transcription_result", "inputs": transcript or ""})
            tokens = [k.strip().lower() for k in split_inputs(transcript or "") if k.strip()]
            ast_list = expanded_ast_from_tokens(tokens)
            self.active_combo_tokens = tokens
            self.runtime_steps = [build_runtime_state(node) for node in ast_list]
            self.reset_tracking()
            self._send(
                {
                    "type": "timeline_update",
                    "steps": self.timeline_steps(),
                    "focus_latest": True,
                }
            )

    def clear_history_and_stats(self):
        with self._lock:
            combo_commands.clear_history_and_stats(self)

    def clear_all_history_and_stats(self):
        with self._lock:
            combo_commands.clear_all_history_and_stats(self)

    def set_active_combo(self, name: str, *, emit: bool = True):
        with self._lock:
            name = (name or "").strip()
            if name not in self.combos:
                self.active_combo_name = None
                self.active_combo_tokens = []
                self.runtime_steps = []
                self.reset_tracking()
                if emit:
                    self._send({"type": "init", **self.init_payload()})
                return

            self.active_combo_name = name
            self.active_combo_tokens = self.combos[name]
            # Build runtime state objects from AST (expanded: wait(r,t) -> press + wait)
            ast_list = expanded_ast_from_tokens(self.active_combo_tokens)
            self.runtime_steps = [build_runtime_state(node) for node in ast_list]
            stats_recording.ensure_combo_stats(self, name)
            
            # Restore saved WW active team when selecting a combo
            self.ww.ww_active_team_id = self.ww.combo_ww_team.get(name)

            self.reset_tracking()
            self.save_combos()

            if emit:
                st = self.get_status()
                self._send({"type": "combo_data", **self.get_editor_payload()})
                self._send({"type": "min_time", "text": ui.min_time_text(self)})
                self._send(
                    {
                        "type": "difficulty_update",
                        "text": ui.difficulty_text(self),
                        "value": combo_analytics.difficulty_score_10(self),
                    }
                )
                self._send(
                    {
                        "type": "user_difficulty_update",
                        "text": ui.user_difficulty_text(self),
                        "value": ui.user_difficulty_value(self),
                    }
                )
                self._send({"type": "apm_update", "text": ui.apm_text(self)})
                self._send({"type": "apm_max_update", "text": ui.apm_max_text(self)})
                self._emit_stats_and_fail()
                self._send({"type": "timeline_update", "steps": self.timeline_steps()})
                self._send({"type": "status", "text": st.text, "color": st.color})
                self._send({
                    "type": "combo_list",
                    "combos": sorted(self.combos.keys()),
                    "active": self.active_combo_name,
                    "overview": ui.combo_overview(self),
                })

    # -------------------------
    # Core state machine
    # -------------------------

    def reset_tracking(self):
        self.current_index = 0
        self.start_time = 0.0
        self.last_input_time = 0.0
        self.pending_step_label = None
        self.pending_step_started_at = 0.0
        self._attempt_hit_clock = None
        self._replay_active = False
        self.attempt_counter = 0
        self._ender_cooldown_until.clear()
        self.ww.ww_active_character = None
        self._ui_last_success_combo = None
        self._ui_last_success_steps_len = 0
        self._reset_attempt_marks()
        self._reset_hold_state()
        self._reset_wait_state()
        self._reset_group_state()

    def _active_runtime_step(self):
        """Current step as StepState (for new match dispatch)."""
        if 0 <= self.current_index < len(self.runtime_steps):
            return self.runtime_steps[self.current_index]
        return None

    def _insert_attempt_separator(self):
        self.attempt_counter += 1
        name = self.active_combo_name or "Combo"
        # New attempt → clear any per-step failure coloring from the previous attempt.
        self._reset_attempt_marks()
        # New attempt → stop showing the previous "success snapshot" (fully green timeline).
        self._ui_last_success_combo = None
        self._ui_last_success_steps_len = 0
        self._send({"type": "attempt_start", "name": name, "attempt": self.attempt_counter})

    def record_hit(
        self,
        label: str,
        step_ms: float | str,
        total_ms: float | str,
        *,
        at_time: float | None = None,
    ):
        # Keep formatting consistent with HTML table
        if isinstance(step_ms, (float, int)):
            step_s = f"{float(step_ms):.1f}"
        else:
            step_s = str(step_ms)
        if isinstance(total_ms, (float, int)):
            total = f"{float(total_ms):.1f}"
        else:
            total = str(total_ms)
        # Keep split_ms temporarily for compatibility with older clients.
        self._send({"type": "hit", "input": label, "step_ms": step_s, "split_ms": step_s, "total_ms": total})
        self._attempt_hit_clock = self._now() if at_time is None else float(at_time)

    def _attempt_hit_delta_ms(self, now: float) -> float:
        """Milliseconds since last attempt-log row (matches macro replay karaoke deltas)."""
        if self._attempt_hit_clock is None:
            if self.start_time and self.start_time > 0:
                return max(0.0, (now - self.start_time) * 1000.0)
            return 0.0
        return max(0.0, (now - self._attempt_hit_clock) * 1000.0)

    def _emit_pending_attempt_row(self, now: float) -> None:
        """Emit pending boundary row only (does not queue a new pending label)."""
        if self.pending_step_label is None or self.pending_step_started_at <= 0:
            return
        step_ms = max(0.0, (now - self.pending_step_started_at) * 1000.0)
        total_ms = (now - self.start_time) * 1000.0 if self.start_time else 0.0
        self.record_hit(self.pending_step_label, step_ms, total_ms, at_time=now)
        self.pending_step_label = None
        self.pending_step_started_at = 0.0

    def _record_attempt_hit_delta(self, label: str, now: float) -> None:
        """Log one attempt row with split = wall time since last hit (replay-compatible)."""
        total_ms = (now - self.start_time) * 1000.0 if self.start_time else 0.0
        step_ms = self._attempt_hit_delta_ms(now)
        self.record_hit(label, step_ms, total_ms, at_time=now)

    def _record_step_timing(self, label: str, now: float) -> None:
        """Finalize previous step timing and queue current accepted step."""
        if self.pending_step_label is not None and self.pending_step_started_at > 0:
            step_ms = max(0.0, (now - self.pending_step_started_at) * 1000.0)
            total_ms = (now - self.start_time) * 1000.0 if self.start_time else 0.0
            self.record_hit(self.pending_step_label, step_ms, total_ms, at_time=now)
        self.pending_step_label = str(label or "")
        self.pending_step_started_at = float(now)

    def _flush_pending_step_timing(self, now: float) -> None:
        """Flush pending step timing at attempt boundary (complete/fail)."""
        if self.pending_step_label is None or self.pending_step_started_at <= 0:
            return
        step_ms = max(0.0, (now - self.pending_step_started_at) * 1000.0)
        total_ms = (now - self.start_time) * 1000.0 if self.start_time else 0.0
        self.record_hit(self.pending_step_label, step_ms, total_ms, at_time=now)
        self.pending_step_label = None
        self.pending_step_started_at = 0.0

    def _reset_hold_state(self):
        # If we were showing a hold indicator in the UI, clear it.
        if self.hold_in_progress:
            self._send({"type": "hold_end"})
        self.hold_in_progress = False
        self.hold_expected_input = None
        self.hold_started_at = 0.0
        self.hold_required_ms = None
        # _hold_max_held_ms is NOT cleared here so release-too-early keeps the max for the drop message

    def _reset_wait_state(self):
        # If we were showing a wait indicator in the UI, clear it.
        if self.wait_in_progress:
            self._send({"type": "wait_end"})
        self.wait_in_progress = False
        self.wait_started_at = 0.0
        self.wait_required_ms = None

    def _reset_group_state(self):
        """Clear per-attempt progress: reset all runtime steps and update shortcuts."""
        try:
            if self.hold or self.wait:
                if self.wait:
                    self._send({"type": "wait_end"})
                if self.hold:
                    self._send({"type": "hold_end"})
            for step in self.runtime_steps:
                step.reset()
            self._update_shortcuts()
        except Exception:
            pass

    def _update_shortcuts(self) -> None:
        """Set self.hold and self.wait from current runtime step."""
        step = self._active_runtime_step()
        self.hold = step if isinstance(step, (HoldState, HoldWithBodyState)) else None
        self.wait = step if isinstance(step, WaitState) else None

    def _reset_to_start(self) -> None:
        """Reset index and step state after a combo completion (ready for next attempt)."""
        self.current_index = 0
        # Stop the ~50Hz tick loop from continuously emitting timeline frames while idle.
        # (A new attempt will re-initialize timing on the first accepted input.)
        self.start_time = 0.0
        self.last_input_time = 0.0
        self.pending_step_label = None
        self.pending_step_started_at = 0.0
        self._attempt_hit_clock = None
        self._replay_active = False
        try:
            self.currently_pressed.clear()
        except Exception:
            pass
        self._ender_cooldown_until.clear()
        self.ww.ww_active_character = None
        self._reset_hold_state()
        self._reset_wait_state()
        self._reset_group_state()
        self.ui_adapter.reset(emit=self._send)

    def _on_combo_completed(self, total_ms: float) -> None:
        """Record success, reset to start, and notify UI. Single place for combo completion."""
        flush_now = (self.start_time + (float(total_ms) / 1000.0)) if self.start_time else self._now()
        self._flush_pending_step_timing(flush_now)
        self.record_combo_success(total_ms)
        # Snapshot timeline while steps are still in completed state; after _reset_to_start()
        # all step state is cleared, so the UI would lose the "completed" styling.
        steps_snapshot = self.timeline_steps()
        self._reset_to_start()
        total_s = total_ms / 1000.0
        self._send({"type": "status", "text": f"Combo '{self.active_combo_name}' Complete! Completed in {total_s:.2f} seconds", "color": "success"})
        self._send({"type": "timeline_update", "steps": steps_snapshot})

    def cancel_attempt(self) -> None:
        """Cancel current attempt and reset to beginning (e.g. on Esc). No fail recorded."""
        with self._lock:
            if not self.runtime_steps:
                return
            # Clear success snapshot + marks so the timeline is not stuck all-green (same as a new attempt).
            self._ui_last_success_combo = None
            self._ui_last_success_steps_len = 0
            self._reset_attempt_marks()
            self._reset_to_start()
            st = self.get_status()
            self._send({"type": "status", "text": st.text, "color": st.color})
            self._send({"type": "timeline_update", "steps": self.timeline_steps()})

    def _reset_after_fail(self) -> None:
        """Full reset after a combo failure: clear index, time, step state, and notify UI."""
        # Snapshot timeline while the failed step is still marked (step_marks), so the UI
        # can show the red outline on the failed step before we clear everything.
        steps_snapshot = self.timeline_steps()
        self.current_index = 0
        self.start_time = 0.0
        self.last_input_time = 0.0
        self.pending_step_label = None
        self.pending_step_started_at = 0.0
        self._attempt_hit_clock = None
        self._replay_active = False
        self._ender_cooldown_until.clear()
        self.ww.ww_active_character = None
        self._hold_max_held_ms = 0.0
        self.ui_adapter.reset(emit=self._send)
        for s in self.runtime_steps:
            s.reset()
        self._reset_hold_state()
        self._reset_wait_state()
        self._reset_group_state()
        self._reset_attempt_marks()
        self._update_shortcuts()
        self._send({"type": "timeline_update", "steps": steps_snapshot})

    def _active_nested_mandatory_wait(self) -> WaitState | None:
        """
        Return an in-progress mandatory WaitState if the current step contains one (including nested).
        """
        try:
            step = self._active_runtime_step()
            ws = ui.find_active_in_progress_wait(step)
            if isinstance(ws, WaitState) and ws.in_progress and not ws.completed and (ws.mode == "mandatory"):
                return ws
        except Exception:
            return None
        return None

    def _get_expected_hold_key(self) -> str | None:
        """
        If the current step is (or starts with) a hold, return that hold's expected key.
        Used by generalized hold buffer: after any advance, we can start a hold immediately
        if that key is already in currently_pressed.
        """
        try:
            step = self._active_runtime_step()
            if step is None:
                return None
            if isinstance(step, (HoldState, HoldWithBodyState)):
                return (step.expected or "").strip().lower() or None
            if isinstance(step, SequenceState) and getattr(step, "steps", None):
                idx = getattr(step, "current_index", 0) or 0
                if 0 <= idx < len(step.steps):
                    inner = step.steps[idx]
                    if isinstance(inner, (HoldState, HoldWithBodyState)):
                        return (inner.expected or "").strip().lower() or None
                if step.steps and isinstance(step.steps[0], (HoldState, HoldWithBodyState)):
                    return (step.steps[0].expected or "").strip().lower() or None
            if isinstance(step, GroupState):
                for item in getattr(step, "items", []) or []:
                    if getattr(item, "completed_count", 0) >= getattr(item, "required_count", 1):
                        continue
                    if item.kind == "hold" and isinstance(item.state, HoldState):
                        key = (item.state.expected or "").strip().lower()
                        if key and key in self.currently_pressed:
                            return key
        except Exception:
            pass
        return None

    def _apply_buffered_hold_if_possible(self, now: float) -> None:
        """
        Generalized hold buffer: after any advance, if the next step is a hold and that key
        is already held (in currently_pressed), start the hold immediately.
        Works for top-level holds and for holds that are the first/current action in a sequence.
        """
        try:
            expected = self._get_expected_hold_key()
            if not expected or expected not in self.currently_pressed:
                return
            self._process_press_unlocked(expected, now, allow_repeat=True)
        except Exception:
            return

    def _ensure_attempt_started(self, now: float) -> None:
        """On first accepted input of an attempt, start timing and send Recording status."""
        if not self.last_input_time and self.current_index == 0:
            self._insert_attempt_separator()
            self.start_time = now
            self.last_input_time = now
            self._send({"type": "status", "text": "Recording...", "color": "recording"})

    def _advance_step(self, now: float) -> None:
        """Advance to next step; update shortcuts, maybe start wait, send timeline."""
        self.current_index += 1
        self._update_shortcuts()
        self._maybe_start_wait_step(now)
        self._send({"type": "timeline_update", "steps": self.timeline_steps()})
        self.ui_adapter.set_active_step_signature(self)

    def _mark_current_and_skip(self, now: float, mark: str | None = None) -> None:
        """No-fail mode: mark current step as failed and advance without ending the combo."""
        idx = int(self.current_index)
        if idx not in self.step_marks:
            self._mark_step(idx, mark if mark else "wrong")
        step = self._active_runtime_step()
        if step is None:
            self._send({"type": "timeline_update", "steps": self.timeline_steps()})
            return
        if step.skip_and_advance(now):
            self._advance_step(now)
            self._sync_wait_animation_ui(now)
            self._send({"type": "status", "text": "Missed - continuing", "color": "fail"})
            self._send({"type": "timeline_update", "steps": self.timeline_steps()})
            if self.current_index >= len(self.runtime_steps):
                self._send({"type": "status", "text": "Practice run finished", "color": "fail"})
                self._reset_to_start()
                self._send({"type": "timeline_update", "steps": self.timeline_steps()})
            else:
                self._apply_buffered_hold_if_possible(now)
        else:
            self._send({"type": "status", "text": "Missed - continuing", "color": "fail"})
            self._send({"type": "timeline_update", "steps": self.timeline_steps()})

    def set_no_fail_mode(self, enabled: bool) -> None:
        """Enable or disable no-fail (practice) mode."""
        self.no_fail_mode = bool(enabled)

    def _send_combo_dropped(self, full_status_text: str, now: float) -> None:
        """Send one message for both status display and attempt log (single source of truth).
        Uses same row shape as 'hit' (input, step_ms, total_ms) so the frontend can treat
        both as attempt-log rows; combo_dropped also updates the status line.
        Timings are computed from engine state before reset (same format as success rows)."""
        self._flush_pending_step_timing(now)
        total_ms = (now - self.start_time) * 1000.0 if self.start_time else 0.0
        total_s = f"{float(total_ms):.1f}" if isinstance(total_ms, (float, int)) else str(total_ms)
        self._send({
            "type": "combo_dropped",
            "input": full_status_text,
            "step_ms": "FAIL",
            "split_ms": "FAIL",
            "total_ms": total_s,
            "color": "fail",
            "fail": True,
        })

    def _fail_combo(self, reason: str, now: float, *, expected_label: str | None = None, actual: str | None = None, waited_ms: float | None = None) -> None:
        """Record failure, reset all steps, send status and timeline."""
        # Mark the failed step so the timeline snapshot (sent in _reset_after_fail) shows red outline.
        if int(self.current_index) not in self.step_marks:
            self._mark_step(int(self.current_index), "wrong")
        msg_reason = reason or "fail"
        if "hold" in msg_reason.lower():
            if self.hold_in_progress:
                held_ms = (now - self.hold_started_at) * 1000
                self._hold_max_held_ms = max(self._hold_max_held_ms, held_ms)
            if self._hold_max_held_ms > 0:
                msg_reason += f" but held for {int(self._hold_max_held_ms)}ms"
        if actual is not None:
            msg_reason += f" but got {actual}"
            if waited_ms is not None:
                msg_reason += f" after {int(waited_ms)}ms"
            elif getattr(self, "wait_started_at", 0) and self.wait_started_at > 0:
                msg_reason += f" after {int((now - self.wait_started_at) * 1000)}ms"
        full_text = "Combo Dropped (" + msg_reason + ")"
        self._send_combo_dropped(full_text, now)
        elapsed_ms = (now - self.start_time) * 1000.0 if self.start_time else None
        self.record_combo_fail(
            actual=actual or reason,
            expected_step_index=int(self.current_index),
            expected_label=expected_label or step_introspection.expected_label_for_step(self._active_runtime_step()),
            reason=reason,
            elapsed_ms=elapsed_ms,
        )
        self._reset_after_fail()

    def _only_ender_can_drop(self, input_name: str, *, now: float | None = None) -> bool:
        return self.ww.can_ender_drop_combo(self, input_name, now=now)

    def _is_soft_ender(self, input_name: str) -> bool:
        """True if this key is a soft ender (~key:2s); does not drop combo when pressed during hold."""
        return (input_name or "").strip().lower() in getattr(self, "combo_enders_soft", set())

    def _ender_can_drop_now(self, input_name: str, *, now: float | None = None) -> bool:
        """True if this key can drop the combo in the current context. Soft enders do not drop during hold."""
        if not self._only_ender_can_drop(input_name, now=now):
            return False
        if self.hold_in_progress and self._is_soft_ender(input_name):
            return False
        return True

    def _check_ender_fail(self, input_name: str, now: float) -> None:
        """If key is a combo ender (and not on cooldown), drop the combo."""
        if not self._ender_can_drop_now(input_name, now=now):
            return
        self._mark_step(int(self.current_index), "missed")
        expected = str(step_introspection.expected_label_for_step(self._active_runtime_step()) or "").strip().lower()
        actual = str(input_name or "").strip().lower()
        if self.no_fail_mode:
            self._mark_current_and_skip(now, mark="missed")
            return
        if self.wait_in_progress and self.wait_started_at:
            waited_s = (now - self.wait_started_at)
            reason = f"only waited for {waited_s:.2f}s, combo ended by {actual}"
        else:
            reason = f"combo ended by {actual}"
        self._fail_combo(reason, now, actual=actual, expected_label=expected)

    def _start_hold(self, input_name: str, required_ms: int, now: float):
        self.hold_in_progress = True
        self.hold_expected_input = input_name
        self.hold_started_at = now
        self.hold_required_ms = required_ms
        # Keep _hold_max_held_ms across retries (multiple short releases) so drop message shows max
        self._send({"type": "hold_begin", "input": str(input_name or ""), "required_ms": int(required_ms)})
        st = self.get_status()
        self._send({"type": "status", "text": st.text, "color": st.color})
        self._send({"type": "timeline_update", "steps": self.timeline_steps()})

    def _start_wait(self, required_ms: int, *, started_at: float):
        self.wait_in_progress = True
        self.wait_started_at = float(started_at)
        self.wait_required_ms = required_ms
        # Tell the UI to animate a visible wait progress bar (similar to holds).
        # Mode may be soft|hard|mandatory (mandatory = animation lock; inputs ignored).
        try:
            step = self._active_runtime_step()
            mode = "soft"
            wait_for = ""
            if isinstance(step, WaitState):
                mode = str(step.mode or "soft").strip().lower() or "soft"
                wait_for = str(step.wait_for or "")
            self._send({"type": "wait_begin", "required_ms": int(required_ms), "mode": mode, "wait_for": wait_for})
        except Exception:
            self._send({"type": "wait_begin", "required_ms": int(required_ms), "mode": "soft", "wait_for": ""})
        st = self.get_status()
        self._send({"type": "status", "text": st.text, "color": st.color})
        self._send({"type": "timeline_update", "steps": self.timeline_steps()})

    def _complete_wait(self, now: float, *, fail: bool, reason: str | None = None):
        required_ms = int(self.wait_required_ms or 0)
        waited_ms = max(0.0, (now - self.wait_started_at) * 1000)
        req_s = format_utils.format_hold_requirement(required_ms) if required_ms else "?"
        # For display, include mode when relevant
        mode = "soft"
        step = self._active_runtime_step()
        try:
            if isinstance(step, WaitState):
                mode = str(step.mode or "soft").strip().lower() or "soft"
        except Exception:
            mode = "soft"
        prefix = "wait-hard" if mode == "hard" else "wait"
        if mode == "mandatory":
            prefix = "anim-wait"
        label = f"{prefix} (≥ {req_s}, {waited_ms:.0f}ms)"
        total_ms = (now - self.start_time) * 1000 if self.start_time else 0.0

        if fail:
            if reason:
                label += f" [{reason}]"
            self._send_combo_dropped("Combo Dropped (Too Early)", now)
            elapsed_ms = (now - self.start_time) * 1000.0 if self.start_time else None
            self.record_combo_fail(
                actual=str(reason or ""),
                expected_step_index=int(self.current_index),
                expected_label=step_introspection.expected_label_for_step(self._active_runtime_step()),
                reason="too early",
                elapsed_ms=elapsed_ms,
            )
            self._reset_after_fail()
            return False

        self._record_step_timing(label, now)
        self.last_input_time = now
        self.current_index += 1
        self._reset_wait_state()
        self._update_shortcuts()
        self.ui_adapter.set_active_step_signature(self)
        self._send({"type": "timeline_update", "steps": self.timeline_steps()})
        # If a mandatory wait (possibly nested) just ended and the user was already holding
        # the next hold key, start the hold immediately (game-like input buffer).
        self._apply_buffered_hold_if_possible(now)

        # If a wait step was (accidentally) the last step, don't get stuck past the end.
        if self.current_index >= len(self.runtime_steps):
            self._on_combo_completed(total_ms)
        return True

    def _maybe_start_wait_step(self, now: float):
        step = self._active_runtime_step()
        if not step or not isinstance(step, WaitState):
            return
        if not self.wait_in_progress:
            step.start(now)
            self._start_wait(int(step.required_ms), started_at=now)

    def _sync_wait_animation_ui(self, now: float) -> None:
        """UI hook: nested wait begin/end (delegated to UI adapter)."""
        try:
            self.ui_adapter.sync_wait_animation(self, emit=self._send)
        except Exception:
            return

    def _complete_hold(self, now: float, *, auto: bool):
        step = self._active_runtime_step()
        if not isinstance(step, (HoldState, HoldWithBodyState)):
            return False

        target_input = str(step.expected or "")
        target_hold_ms = int(step.required_ms or 0)

        held_ms = (now - self.hold_started_at) * 1000
        self._hold_max_held_ms = max(self._hold_max_held_ms, held_ms)
        ok = held_ms >= float(target_hold_ms)

        req_s = format_utils.format_hold_requirement(target_hold_ms)
        total_ms = (now - self.start_time) * 1000 if self.start_time else 0.0

        label = f"{target_input} (hold ≥ {req_s}, {held_ms:.0f}ms)"
        if auto:
            label += " [auto]"

        if ok:
            if isinstance(step, HoldWithBodyState):
                self._record_attempt_hit_delta(label, now)
            else:
                self._record_step_timing(label, now)
            self.last_input_time = now
            self._start_ender_cooldown(target_input, now)
            self.ww.on_accepted_key(self, target_input)
            step.complete()

            # If this hold was gated by a wait right before it, mark that wait green (timing satisfied).
            if self.current_index > 0:
                prev = self.runtime_steps[self.current_index - 1]
                if isinstance(prev, WaitState):
                    self._mark_step(self.current_index - 1, "ok")

            # Advance using the standard path so shortcuts update correctly.
            self._hold_max_held_ms = 0.0
            self._advance_step(now)
            if self._maybe_complete_combo_if_trailing_wait(now=now, total_ms=total_ms):
                return True
            if self.current_index >= len(self.runtime_steps):
                self._on_combo_completed(total_ms)
        else:
            drop_text = "Combo Dropped (Hold Incomplete)"
            if self._hold_max_held_ms > 0:
                drop_text += f" but held for {int(self._hold_max_held_ms)}ms"
            self._send_combo_dropped(drop_text, now)
            elapsed_ms = (now - self.start_time) * 1000.0 if self.start_time else None
            self.record_combo_fail(
                actual=f"released @ {held_ms:.0f}ms",
                expected_step_index=int(self.current_index),
                expected_label=step_introspection.expected_label_for_step(step),
                reason="hold incomplete",
                elapsed_ms=elapsed_ms,
            )
            self._reset_after_fail()
            return False

        self._reset_hold_state()
        return ok

    def record_combo_success(self, completion_ms: float | int | None = None) -> None:
        stats_recording.record_combo_success(self, completion_ms)

    def record_combo_fail(
        self,
        *,
        actual: str | None = None,
        expected_step_index: int | None = None,
        expected_label: str | None = None,
        reason: str | None = None,
        elapsed_ms: float | None = None,
    ) -> None:
        stats_recording.record_combo_fail(
            self,
            actual=actual,
            expected_step_index=expected_step_index,
            expected_label=expected_label,
            reason=reason,
            elapsed_ms=elapsed_ms,
        )

    # -------------------------
    # Karaoke replay (called from MacroPlayer.on_step)
    # -------------------------

    def _replay_clear_blocking_waits(self, now: float) -> None:
        """Force-complete any waits that block the current replay position.

        The MacroPlayer sleeps through waits without firing replay events, so by the
        time the *next* replay event arrives the wait is already done.  We mark it
        complete unconditionally — no elapsed-time check — so a few-millisecond
        rounding difference in the macro sleep can never leave the display stuck.

        Handles these shapes:
        - Top-level standalone WaitState  (e.g. `wait:1.4s` compiled to its own runtime step)
        - SequenceState where the inner cursor is sitting on a WaitState
          (e.g. `e, wait:1.4s` merged into one SequenceState; press fired, wait in progress)
        - GroupState animation waits and active sequences containing waits
        """
        for _ in range(len(self.runtime_steps) + 1):
            step = self._active_runtime_step()
            if step is None:
                break

            # Top-level standalone wait — macro just slept through it.
            if isinstance(step, WaitState):
                if self.wait_in_progress:
                    self._reset_wait_state()
                else:
                    self._send({"type": "wait_end"})
                step.in_progress = False
                step.completed = True
                self.current_index += 1
                self._update_shortcuts()
                continue

            # SequenceState (e.g. press+wait) where the inner step is a pending wait.
            if isinstance(step, SequenceState) and step.started:
                inner_idx = step.current_index
                if 0 <= inner_idx < len(step.steps):
                    inner = step.steps[inner_idx]
                    if isinstance(inner, WaitState) and not inner.completed:
                        inner.in_progress = False
                        inner.completed = True
                        step.current_index += 1
                        if step.current_index >= len(step.steps):
                            # Sequence is now fully done — advance the top-level index.
                            self._advance_step(now)
                            self._sync_wait_animation_ui(now)
                            # Loop: the next top-level step might also be a wait.
                            continue
                        # Sequence has more inner steps; the incoming key will be
                        # dispatched to them normally below.
                        self._sync_wait_animation_ui(now)
            # Group replay can be blocked by either an animation-lock wait or a
            # wait inside its active sequence. The macro plan has already elapsed
            # that deadline before delivering the incoming key, so finish the wait
            # without consuming the key.
            if isinstance(step, GroupState):
                if step.wait_active:
                    wait_item = next(
                        (
                            item
                            for item in step.items
                            if item.kind == "anim_wait"
                            and isinstance(item.state, WaitState)
                            and item.state.in_progress
                        ),
                        None,
                    )
                    if wait_item is not None:
                        wait_item.state.in_progress = False
                        wait_item.state.completed = True
                        wait_item.completed_count = wait_item.required_count
                        step.wait_active = False
                        self._sync_wait_animation_ui(now)
                        if step._is_complete():
                            self._advance_step(now)
                            continue
                    break

                active_item = step.active_item
                if active_item is not None and isinstance(active_item.state, SequenceState):
                    sequence = active_item.state
                    inner_idx = sequence.current_index
                    if 0 <= inner_idx < len(sequence.steps):
                        inner = sequence.steps[inner_idx]
                        if isinstance(inner, WaitState) and not inner.completed:
                            inner.in_progress = False
                            inner.completed = True
                            sequence_finished = sequence._advance_inner(now)
                            self._sync_wait_animation_ui(now)
                            if sequence_finished:
                                active_item.completed_count += 1
                                step.active_item = None
                                if step._is_complete():
                                    self._advance_step(now)
                                    continue
                    break

            break

    def replay_accept(
        self,
        key: str,
        step_ms: float,
        total_ms: float,
        pressed: bool = True,
    ) -> None:
        """Advance the visual combo state for one replayed step.

        Called by MacroPlayer's on_step callback; completely bypasses the
        detection state machine so synthetic keystrokes never cause false drops.
        The visual timeline and attempt log are driven directly by the macro's
        own wall-clock timing.
        """
        with self._lock:
            self._replay_accept_unlocked(key, step_ms, total_ms, pressed=pressed)

    def _replay_accept_unlocked(
        self,
        key: str,
        step_ms: float,
        total_ms: float,
        *,
        pressed: bool,
    ) -> None:
        if not self.runtime_steps:
            return

        key = (key or "").strip().lower()
        wall_now = self._now()

        # Start the attempt on the first replayed step.
        if not self.last_input_time and self.current_index == 0:
            self._insert_attempt_separator()
            # Anchor start_time so total_ms from the macro aligns with engine timing.
            self.start_time = wall_now - (total_ms / 1000.0)
            self.last_input_time = wall_now
            self._replay_active = True
            self._send({"type": "status", "text": "Macro replaying\u2026", "color": "recording"})

        # Use the macro plan's clock for deterministic transitions even when the
        # replay delivery queue runs slightly late.
        now = self.start_time + (total_ms / 1000.0) if self.start_time else wall_now

        # The MacroPlayer sleeps through every wait before firing the next event.
        # Force-complete any wait blocking the current position so the incoming key
        # always lands on the right step — no timing checks required.
        self._replay_clear_blocking_waits(now)

        # Planned releases occur on an inclusive duration deadline. Account for
        # floating-point subtraction once here so every nested hold shape observes
        # the same rule without mutating individual state start timestamps.
        if not pressed:
            now += 0.000001

        step = self._active_runtime_step()
        if step is None:
            return

        # Merged press + soft/hard wait (e.g. `e, wait:1.4s`) is one SequenceState — must run inner
        # process_press like normal play. Naively bumping current_index skips the wait phase entirely
        # (press_wait tile jumps to completed with no loading bar).
        if isinstance(step, SequenceState):
            result = (
                step.process_press(key, now)
                if pressed
                else step.process_release(key, now)
            )
            if isinstance(result, IgnoreResult):
                return
            if isinstance(result, FailResult):
                return
            if isinstance(result, CompleteResult):
                self.record_hit(key, step_ms, total_ms, at_time=now)
                self.last_input_time = now
                self._advance_step(now)
                self._sync_wait_animation_ui(now)
                if self.current_index >= len(self.runtime_steps):
                    self._on_combo_completed(total_ms)
                return
            if isinstance(result, AcceptResult):
                if getattr(result, "record_hit", True):
                    self.record_hit(key, step_ms, total_ms, at_time=now)
                self.last_input_time = now
                self._update_shortcuts()
                self._sync_wait_animation_ui(now)
                if result.advance:
                    self._advance_step(now)
                    self._sync_wait_animation_ui(now)
                    if self.current_index >= len(self.runtime_steps):
                        self._on_combo_completed(total_ms)
                else:
                    self._send({"type": "timeline_update", "steps": self.timeline_steps()})
                return

        # Groups contain their own progress cursor. Replay must drive that cursor
        # item-by-item instead of advancing the whole top-level group on its first key.
        if isinstance(step, GroupState):
            active_item = step.active_item
            releasing_hold = bool(
                not pressed
                and active_item is not None
                and isinstance(active_item.state, HoldState)
                and key == active_item.state.expected
            )
            result = (
                step.process_release(key, now)
                if not pressed
                else step.process_press(key, now)
            )

            if isinstance(result, (IgnoreResult, FailResult)):
                return
            if isinstance(result, CompleteResult):
                self._advance_step(now)
                self._sync_wait_animation_ui(now)
                if self.current_index >= len(self.runtime_steps):
                    self._on_combo_completed(total_ms)
                    return
                return self._replay_accept_unlocked(
                    key, step_ms, total_ms, pressed=pressed
                )
            if isinstance(result, AcceptResult):
                if result.record_hit:
                    self.record_hit(key, step_ms, total_ms, at_time=now)
                self.last_input_time = now

                if releasing_hold:
                    self._reset_hold_state()
                else:
                    started_item = step.active_item
                    if (
                        started_item is not None
                        and isinstance(started_item.state, HoldState)
                        and started_item.state.in_progress
                    ):
                        self._start_hold(
                            started_item.state.expected,
                            started_item.state.required_ms,
                            now,
                        )

                self._sync_wait_animation_ui(now)
                if result.advance:
                    self._advance_step(now)
                    self._sync_wait_animation_ui(now)
                    if self.current_index >= len(self.runtime_steps):
                        self._on_combo_completed(total_ms)
                    elif self._maybe_complete_combo_if_trailing_wait(
                        now=now, total_ms=total_ms
                    ):
                        return
                else:
                    self._send({"type": "timeline_update", "steps": self.timeline_steps()})
                return

        # Plain hold: replay fires holder key-down before sleep and key-up after (macro_player HoldNode).
        if isinstance(step, HoldState):
            holder = str(step.expected or "").strip().lower()
            if not holder:
                return

            if pressed and (not step.in_progress) and (not step.completed):
                if key != holder:
                    return
                result = step.process_press(key, now)
                if isinstance(result, AcceptResult):
                    self.record_hit(key, step_ms, total_ms, at_time=now)
                    self.last_input_time = now
                    self._start_hold(holder, step.required_ms, now)
                    self._send({"type": "timeline_update", "steps": self.timeline_steps()})
                return

            if not pressed and key == holder and step.in_progress:
                result = step.process_release(key, now)
                if isinstance(result, AcceptResult) and result.advance:
                    held_ms = (now - step.started_at) * 1000.0 if step.started_at else float(step.required_ms or 0)
                    req_s = format_utils.format_hold_requirement(int(step.required_ms or 0))
                    label = f"{holder} (hold ≥ {req_s}, {held_ms:.0f}ms) [auto]"
                    self.record_hit(label, step_ms, total_ms, at_time=now)
                    self.last_input_time = now
                    self._start_ender_cooldown(holder, now)
                    self.ww.on_accepted_key(self, holder)
                    self._hold_max_held_ms = 0.0
                    self._reset_hold_state()
                    self.current_index += 1
                    self._update_shortcuts()
                    self._send({"type": "timeline_update", "steps": self.timeline_steps()})
                    if self.current_index >= len(self.runtime_steps):
                        self._on_combo_completed(total_ms)
                return

            return

        # Special handling for hold_with_body in replay mode:
        # consume inner body keys for timeline/log fidelity, and only advance the
        # top-level step on the holder key release marker.
        if isinstance(step, HoldWithBodyState):
            holder = str(step.expected or "").strip().lower()
            if not holder:
                return

            # Start marker (holder key-down).
            if pressed and (not step.in_progress) and (not step.completed):
                if key != holder:
                    return
                result = step.process_press(key, now)
                if isinstance(result, AcceptResult):
                    self.record_hit(key, step_ms, total_ms, at_time=now)
                    self.last_input_time = now
                    self._start_hold(holder, step.required_ms, now)
                    self._send({"type": "timeline_update", "steps": self.timeline_steps()})
                return

            # Inner body key while holder is down.
            if pressed and step.in_progress and key != holder:
                result = step.process_press(key, now)
                if isinstance(result, AcceptResult):
                    self.record_hit(key, step_ms, total_ms, at_time=now)
                    self.last_input_time = now
                    self._start_ender_cooldown(key, now)
                    self.ww.on_accepted_key(self, key)
                    self._send({"type": "timeline_update", "steps": self.timeline_steps()})
                return

            # Completion marker (holder key-up callback from macro player).
            if not pressed and key == holder:
                held_ms = (now - self.hold_started_at) * 1000.0 if self.hold_started_at else float(step.required_ms or 0)
                req_s = format_utils.format_hold_requirement(int(step.required_ms or 0))
                label = f"{holder} (hold ≥ {req_s}, {held_ms:.0f}ms) [auto]"
                self.record_hit(label, step_ms, total_ms, at_time=now)
                self.last_input_time = now
                self._start_ender_cooldown(holder, now)
                self.ww.on_accepted_key(self, holder)
                step.complete()
                self._hold_max_held_ms = 0.0
                self._reset_hold_state()
                self.current_index += 1
                self._update_shortcuts()
                self._send({"type": "timeline_update", "steps": self.timeline_steps()})
                if self.current_index >= len(self.runtime_steps):
                    self._on_combo_completed(total_ms)
                return

        # Plain replayed presses use the same runtime-state interface and engine
        # advancement path as live input. This keeps the state's completed flag,
        # shortcuts, and timeline projection consistent between both adapters.
        if not pressed:
            return
        result = step.process_press(key, now)
        if isinstance(result, AcceptResult) and not result.advance:
            if result.record_hit:
                self.record_hit(key, step_ms, total_ms, at_time=now)
                self.last_input_time = now
                self._sync_wait_animation_ui(now)
                self._send({"type": "timeline_update", "steps": self.timeline_steps()})
            return
        if not isinstance(result, AcceptResult) or not result.advance:
            return

        # Record the step in the attempt log with macro-accurate timing.
        self.record_hit(key, step_ms, total_ms, at_time=now)
        self.last_input_time = now

        self._advance_step(now)
        self._sync_wait_animation_ui(now)

        if self.current_index >= len(self.runtime_steps):
            self._on_combo_completed(total_ms)
        else:
            self._maybe_complete_combo_if_trailing_wait(now=now, total_ms=total_ms)

    # -------------------------
    # Input processing (called from pynput)
    # -------------------------

    def process_press(self, input_name: str, *, event_time: float | None = None):
        # Thread-safe wrapper
        with self._lock:
            return self._process_press_unlocked(input_name, event_time)

    def _process_press_unlocked(
        self,
        input_name: str,
        now: float | None = None,
        *,
        allow_repeat: bool = False,
    ):
        input_name = (input_name or "").strip().lower()
        if not input_name:
            return

        # Only a genuine key-down can advance detection. OS repeat-down events are
        # coalesced until release; allow_repeat is reserved for re-processing the
        # same physical event after a wait/optional transition and buffered holds.
        press_is_repeat = input_name in self.currently_pressed
        self.currently_pressed.add(input_name)
        if press_is_repeat and not allow_repeat:
            return
        if not self.runtime_steps:
            return

        now = self._now() if now is None else float(now)

        # During a nested mandatory wait (animation lock), ignore the key for progression.
        # currently_pressed already has it; when the wait ends and we advance,
        # _apply_buffered_hold_if_possible will start the hold if the next step is that key.
        if self._active_nested_mandatory_wait() is not None:
            return

        # 1) Active wait
        if self.wait and self.wait.in_progress:
            result = self.wait.process_press(input_name, now)
            if isinstance(result, CompleteResult):
                self._complete_wait(now, fail=False)
                return self._process_press_unlocked(input_name, now, allow_repeat=True)
            if isinstance(result, FailResult):
                if self.no_fail_mode:
                    self._mark_step(int(self.current_index), "early")
                    self._reset_wait_state()
                    step = self._active_runtime_step()
                    if step is not None and step.skip_and_advance(now):
                        self._advance_step(now)
                        self._sync_wait_animation_ui(now)
                    self._send({"type": "status", "text": "Missed - continuing", "color": "fail"})
                    self._send({"type": "timeline_update", "steps": self.timeline_steps()})
                    if self.current_index >= len(self.runtime_steps):
                        self._send({"type": "status", "text": "Practice run finished", "color": "fail"})
                        self._reset_to_start()
                        self._send({"type": "timeline_update", "steps": self.timeline_steps()})
                    else:
                        self._apply_buffered_hold_if_possible(now)
                else:
                    # Only enders can end combos; early press with non-ender is ignored.
                    # Key repeat (already held) does not end the combo.
                    if not press_is_repeat and self._ender_can_drop_now(input_name, now=now):
                        self._check_ender_fail(input_name, now)
                return
            # Ender during wait: use same gate as everywhere else. Key repeat does not end combo.
            if not press_is_repeat and self.wait.mode in ("soft", "hard") and self._ender_can_drop_now(input_name, now=now):
                if self.no_fail_mode:
                    self._mark_step(int(self.current_index), "wrong")
                    self._reset_wait_state()
                    step = self._active_runtime_step()
                    if step is not None and step.skip_and_advance(now):
                        self._advance_step(now)
                        self._sync_wait_animation_ui(now)
                    self._send({"type": "status", "text": "Missed - continuing", "color": "fail"})
                    self._send({"type": "timeline_update", "steps": self.timeline_steps()})
                    if self.current_index >= len(self.runtime_steps):
                        self._send({"type": "status", "text": "Practice run finished", "color": "fail"})
                        self._reset_to_start()
                        self._send({"type": "timeline_update", "steps": self.timeline_steps()})
                    else:
                        self._apply_buffered_hold_if_possible(now)
                else:
                    self._check_ender_fail(input_name, now)
            return

        # 2) Active hold
        if self.hold and self.hold.in_progress:
            if input_name == self.hold.expected:
                return
            if self.hold.check_complete(now):
                self._complete_hold(now, auto=False)
                return self._process_press_unlocked(input_name, now, allow_repeat=True)

            if isinstance(self.hold, HoldWithBodyState):
                # Route the press to the body sequence; no forgiving-hold ignore here.
                step = self._active_runtime_step()
                result = step.process_press(input_name, now)
                if isinstance(result, AcceptResult) and result.advance:
                    # Both body and hold time satisfied; complete the whole step.
                    self._ensure_attempt_started(now)
                    if result.record_hit:
                        self._record_attempt_hit_delta(str(input_name), now)
                    self._complete_hold(now, auto=False)
                    return
                if isinstance(result, AcceptResult):
                    # Body advanced but not fully done (or hold time not yet met).
                    self._ensure_attempt_started(now)
                    if result.record_hit:
                        self._record_attempt_hit_delta(str(input_name), now)
                    self.last_input_time = now
                    self._start_ender_cooldown(input_name, now)
                    self.ww.on_accepted_key(self, input_name)
                    self._send({"type": "timeline_update", "steps": self.timeline_steps()})
                    return
                if isinstance(result, FailResult):
                    if self.no_fail_mode:
                        self._mark_current_and_skip(now)
                        return
                    self._fail_combo(result.reason, now)
                    return
                # IgnoreResult: body didn't accept this key yet (e.g. timing gate not elapsed).
                # Do NOT fire the ender gate — body keys pressed slightly early must not drop
                # the combo while the hold-with-body step is still active.
                return

            # Only enders can end combos (same gate as everywhere). Key repeat does not end combo.
            if not press_is_repeat and self._ender_can_drop_now(input_name, now=now):
                self._check_ender_fail(input_name, now)
                return

            # Forgiving hold: only drop if they pressed the next step's key AND it's an ender (new press only).
            next_step = self.runtime_steps[int(self.current_index) + 1] if (int(self.current_index) + 1) < len(self.runtime_steps) else None
            next_keys = step_introspection.start_keys_for_step(next_step)
            if not press_is_repeat and next_keys and (input_name in next_keys) and self._ender_can_drop_now(input_name, now=now):
                if self.no_fail_mode:
                    self._mark_current_and_skip(now)
                    self._sync_wait_animation_ui(now)
                    return
                self._fail_combo("hold incomplete", now, actual=f"pressed {input_name}")
            # Otherwise ignore (random keys or next key that isn't an ender).
            return

        # 3) Dispatch to current step (polymorphic: GroupState, SequenceState, PressState, HoldState, WaitState all implement process_press)
        step = self._active_runtime_step()
        if step is None:
            return

        result = step.process_press(input_name, now)

        if isinstance(result, AcceptResult):
            self._ensure_attempt_started(now)
            if result.record_hit:
                if isinstance(step, HoldWithBodyState):
                    self._emit_pending_attempt_row(now)
                    self._record_attempt_hit_delta(str(input_name), now)
                else:
                    self._record_step_timing(input_name, now)
            self.last_input_time = now
            self._start_ender_cooldown(input_name, now)
            self.ww.on_accepted_key(self, input_name)
            # If this press started a nested wait (e.g. press_wait inside a group/sequence),
            # kick off the client-side wait animation immediately.
            self._sync_wait_animation_ui(now)
            if result.advance:
                self._advance_step(now)
                self._sync_wait_animation_ui(now)
                # If a mandatory wait ended and we advanced into a hold step that is already held,
                # apply the buffered hold immediately.
                self._apply_buffered_hold_if_possible(now)
                if self.current_index >= len(self.runtime_steps):
                    self._on_combo_completed((now - self.start_time) * 1000.0 if self.start_time else 0.0)
                    return
                if self._maybe_complete_combo_if_trailing_wait(now=now, total_ms=(now - self.start_time) * 1000.0 if self.start_time else 0.0):
                    return
                # Important: do NOT re-process the same input against the next step.
                # The input was already consumed by the current step; re-processing can
                # incorrectly treat it as an "ender during wait" (e.g., `e, wait:0.4`).
                return
            if isinstance(step, (HoldState, HoldWithBodyState)):
                self._start_hold(step.expected, step.required_ms, now)
            elif isinstance(step, GroupState):
                self._send({"type": "timeline_update", "steps": self.timeline_steps()})
            elif isinstance(step, SpamState) and result.record_hit:
                self._send({"type": "timeline_update", "steps": self.timeline_steps()})
            return
        if isinstance(result, FailResult):
            if self.no_fail_mode:
                mark = "early" if "early" in (result.reason or "").lower() else "wrong"
                self._mark_current_and_skip(now, mark=mark)
                self._sync_wait_animation_ui(now)
                return
            # Only enders can end combos; wrong/early key that isn't an ender is ignored. Key repeat does not end combo.
            if not press_is_repeat and self._ender_can_drop_now(input_name, now=now):
                self._check_ender_fail(input_name, now)
            return
        if isinstance(result, CompleteResult):
            self._advance_step(now)
            self._sync_wait_animation_ui(now)
            if self.current_index >= len(self.runtime_steps):
                self._on_combo_completed((now - self.start_time) * 1000.0 if self.start_time else 0.0)
                return
            if self._maybe_complete_combo_if_trailing_wait(now=now, total_ms=(now - self.start_time) * 1000.0 if self.start_time else 0.0):
                return
            return self._process_press_unlocked(input_name, now, allow_repeat=True)
        # During group mandatory wait (animation lock), ignore all keys including enders.
        if isinstance(step, GroupState) and step.wait_active:
            return
        # Input didn't match current step (IgnoreResult). Only enders can end combos. Key repeat does not end combo.
        if isinstance(result, IgnoreResult):
            if not self.last_input_time and self.current_index == 0:
                return
            # Optional press step: pressing the next step's key skips the optional without dropping.
            if isinstance(step, PressState) and getattr(step, "optional", False):
                next_idx = int(self.current_index) + 1
                if next_idx < len(self.runtime_steps):
                    next_step = self.runtime_steps[next_idx]
                    next_keys = step_introspection.start_keys_for_step(next_step)
                    if next_keys and input_name in next_keys:
                        step.was_skipped = True
                        step.completed = True
                        self._advance_step(now)
                        self._sync_wait_animation_ui(now)
                        return self._process_press_unlocked(input_name, now, allow_repeat=True)
            # Optional sequence step (e.g. -e, wait:0.80s): pressing next step's key skips the whole sequence.
            if isinstance(step, SequenceState) and getattr(step, "optional", False):
                next_idx = int(self.current_index) + 1
                if next_idx < len(self.runtime_steps):
                    next_step = self.runtime_steps[next_idx]
                    next_keys = step_introspection.start_keys_for_step(next_step)
                    if next_keys and input_name in next_keys:
                        step.was_skipped = True
                        self._advance_step(now)
                        self._sync_wait_animation_ui(now)
                        return self._process_press_unlocked(input_name, now, allow_repeat=True)
            # Optional-key grace: optional key is valid in its own slot and through the entire next step.
            # If we're 1 or 2 steps past a skipped optional and user presses that optional's key, accept it (don't drop).
            for prev_idx in (self.current_index - 1, self.current_index - 2):
                if prev_idx < 0:
                    continue
                prev_step = self.runtime_steps[prev_idx]
                opt_key = step_introspection.optional_step_key(prev_step)
                if opt_key is None or not getattr(prev_step, "was_skipped", False) or input_name != opt_key:
                    continue
                prev_step.was_skipped = False
                return
            if not press_is_repeat and self._ender_can_drop_now(input_name, now=now):
                expected = step_introspection.expected_label_for_step(step) or "?"
                self._mark_step(int(self.current_index), "missed")
                if self.no_fail_mode:
                    self._mark_current_and_skip(now, mark="missed")
                    self._sync_wait_animation_ui(now)
                    return
                # If current step is a sequence with an active inner wait, pass how long they waited
                waited_ms_val: float | None = None
                if isinstance(step, SequenceState) and 0 <= step.current_index < len(step.steps):
                    inner = step.steps[step.current_index]
                    if isinstance(inner, WaitState) and inner.started_at > 0:
                        waited_ms_val = (now - inner.started_at) * 1000
                self._fail_combo(f"expected {expected}", now, actual=input_name, expected_label=expected, waited_ms=waited_ms_val)
            return
        return


    def process_release(self, input_name: str, *, event_time: float | None = None):
        # Thread-safe wrapper
        with self._lock:
            return self._process_release_unlocked(input_name, event_time)

    def _process_release_unlocked(self, input_name: str, now: float | None = None):
        input_name = (input_name or "").strip().lower()
        if not input_name:
            return

        self.currently_pressed.discard(input_name)

        if not self.runtime_steps:
            return

        step = self._active_runtime_step()
        if step is None:
            return

        now = self._now() if now is None else float(now)
        result = step.process_release(input_name, now)

        # Track max hold duration when release was too short (for drop message later)
        if isinstance(step, HoldState) and input_name == str(step.expected or "") and self.hold_in_progress:
            if isinstance(result, IgnoreResult):
                held_ms = (now - self.hold_started_at) * 1000
                self._hold_max_held_ms = max(self._hold_max_held_ms, held_ms)

        # Forgiving holds: releasing too early should end the UI "hold" indicator,
        # but should NOT drop the combo.
        if isinstance(step, HoldState) and input_name == str(step.expected or ""):
            try:
                if self.hold_in_progress and (not bool(getattr(step, "in_progress", False))) and (not bool(getattr(step, "completed", False))):
                    self._reset_hold_state()
                    self._send({"type": "timeline_update", "steps": self.timeline_steps()})
            except Exception:
                pass

        if isinstance(result, AcceptResult):
            if result.advance:
                if isinstance(step, (HoldState, HoldWithBodyState)):
                    self._complete_hold(now, auto=False)
                else:
                    self._advance_step(now)
                    self._sync_wait_animation_ui(now)
                    if self.current_index >= len(self.runtime_steps):
                        total_ms = (now - self.start_time) * 1000.0 if self.start_time else 0.0
                        self._on_combo_completed(total_ms)
                    elif self._maybe_complete_combo_if_trailing_wait(now=now, total_ms=(now - self.start_time) * 1000.0 if self.start_time else 0.0):
                        pass
                    else:
                        st = self.get_status()
                        self._send({"type": "status", "text": st.text, "color": st.color})
            else:
                # Group-internal hold completed; notify UI
                if isinstance(step, GroupState):
                    self._send({"type": "hold_end"})
                    self._send({"type": "timeline_update", "steps": self.timeline_steps()})
            return
        if isinstance(result, FailResult):
            if self.no_fail_mode:
                self._mark_current_and_skip(now)
                self._sync_wait_animation_ui(now)
                return
            if isinstance(step, HoldWithBodyState):
                # Hold-with-body: early release always fails (no ender gate).
                self._fail_combo(result.reason, now, actual="released hold early")
            elif self._ender_can_drop_now(input_name, now=now):
                # Plain HoldState: releasing too early drops only if that key is a combo ender.
                self._fail_combo(result.reason, now, actual="released (hold too short)")
            self._sync_wait_animation_ui(now)
            return

    def tick(self):
        # Thread-safe wrapper
        with self._lock:
            return self._tick_unlocked()

    def _tick_unlocked(self):
        """
        Advance time-based steps (waits / group internal waits) without requiring another input event.
        This allows wait tiles to complete/turn green automatically when the timer elapses.

        Why this exists:
        - `process_press()` only runs when the player presses something.
        - But we want waits to "finish" in the UI even if the player pauses and does not press the next key.
        - `ui_server.py` runs a lightweight tick loop (~50Hz) that calls `engine.tick()`.
        - During macro replay this also handles trailing waits at the end of the combo.

        This method intentionally does **not** start a combo; it only advances timers for an already-started attempt.
        The engine lock serialises this with replay_accept; they cannot conflict.
        """
        try:
            if not self.runtime_steps:
                return
            if not self.start_time or not self.last_input_time:
                return

            now = self._now()
            self._maybe_start_wait_step(now)
            self._sync_wait_animation_ui(now)

            step = self._active_runtime_step()
            if step is None:
                return

            # Hold duration satisfied without release: auto-complete and advance.
            if (
                not self._replay_active
                and isinstance(step, HoldState)
                and self.hold_in_progress
                and self.hold
                and self.hold.check_complete(now)
            ):
                self._complete_hold(now, auto=True)
                self._sync_wait_animation_ui(now)
                return

            if self._replay_active and isinstance(step, HoldWithBodyState):
                return

            result = step.tick(now)

            if isinstance(result, CompleteResult) or (
                isinstance(result, AcceptResult) and result.advance
            ):
                if isinstance(step, WaitState):
                    self._complete_wait(now, fail=False)
                    st = self.get_status()
                    self._send({"type": "status", "text": st.text, "color": st.color})
                elif isinstance(step, HoldWithBodyState):
                    self._complete_hold(now, auto=False)
                    self._sync_wait_animation_ui(now)
                else:
                    self._advance_step(now)
                    self._sync_wait_animation_ui(now)
                    if self.current_index >= len(self.runtime_steps):
                        total_ms = (now - self.start_time) * 1000.0 if self.start_time else 0.0
                        self._on_combo_completed(total_ms)
                    elif self._maybe_complete_combo_if_trailing_wait(
                        now=now, total_ms=(now - self.start_time) * 1000.0 if self.start_time else 0.0
                    ):
                        pass
                    else:
                        st = self.get_status()
                        self._send({"type": "status", "text": st.text, "color": st.color})
                return

            self.ui_adapter.maybe_emit_timeline_update_on_change(self, emit=self._send)
            self._apply_buffered_hold_if_possible(now)
        except Exception as exc:
            # The UI loop owns rate-limited error reporting. Propagate invariant
            # failures so they are observable instead of silently disabling tick.
            raise RuntimeError("Engine tick transition failed") from exc