app.py

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
KeyAxis - turn a Hall-effect keyboard into analog pedals + a live travel monitor.

Backend for a pywebview desktop app. This module owns ALL hardware:
  * Raw HID access to the keyboard's vendor interface (via the `hid` / hidapi package).
  * A virtual Xbox 360 gamepad (via the optional `vgamepad` / ViGEmBus package).

The UI is a single embedded HTML page (ui.html, a sibling file) rendered in a native
WebView2 window. The JS side talks to this file exclusively through
`window.pywebview.api.METHOD(...)`, which resolves to the JSON returned by the matching
method on the `Api` class below.

Design notes
------------
* A single background daemon thread ("the reader") owns every byte of HID I/O once the
  stream is armed. It reads the ~1000 Hz event-driven travel stream, keeps a
  lock-protected snapshot of per-key depth for the UI to poll, and - when pedals are
  active - maps configured keys onto virtual-gamepad axes and pushes them immediately.
  The UI never sits in the input path; it only polls light-weight state every ~50 ms.
* All HID reads/writes happen on that one thread to avoid cross-thread use of a single
  hidapi handle. The main (API) thread only opens/closes the handle while the reader is
  stopped, and flips flags the reader observes.
* vgamepad is optional. If it (or ViGEmBus) is missing, the monitor still works fully;
  only the pedal-output feature is disabled, with a clear message.

Verified M68 protocol (Redragon M68 / E-YOOSO HZ-68, VID 0x0416 PID 0x7372):
  * Use the vendor interface: the hid.enumerate() entry with usage_page == 0xff1b.
  * Every write is: h.write(bytes([0x01]) + payload_padded_to_63)  -> 64 bytes total.
  * ARM (start stream) / DISARM (stop stream) payloads are defined per-profile below.
  * A travel frame from h.read(64) (hidapi prepends the report id) looks like:
        d[0]=0x01 report id, d[1]=0x21, d[5]=0x03 (travel frame; 0x01 = idle/ack),
        d[7]=row, d[8]=col, d[9]=depth in 0..40  (0.1 mm/unit -> 0.0..4.0 mm)
  * Always DISARM on stop / disconnect / app close.
"""

import os
import sys
import json
import math
import threading
import time
import traceback

# --- Make stdout UTF-8 safe on Windows even when launched without a real console. ---
try:
    sys.stdout.reconfigure(encoding="utf-8")  # Python 3.7+
except Exception:
    pass
try:
    sys.stderr.reconfigure(encoding="utf-8")
except Exception:
    pass


# =============================================================================
# Optional / required third-party imports (fail soft where the contract allows).
# =============================================================================

# pywebview is required to actually run the app, but importing app.py for tests
# or tooling should not hard-crash if it is absent.
try:
    import webview  # pywebview
    WEBVIEW_OK = True
except Exception:
    webview = None
    WEBVIEW_OK = False

# hidapi is required for any real hardware work.
try:
    import hid
    HID_OK = True
except Exception:
    hid = None
    HID_OK = False

# vgamepad is OPTIONAL. Importing it does NOT prove ViGEmBus is installed - that is only
# discovered when we actually instantiate a virtual pad, so we probe lazily.
try:
    import vgamepad as vg
    VGAMEPAD_IMPORT_OK = True
except Exception:
    vg = None
    VGAMEPAD_IMPORT_OK = False

# keysuppress is our own optional module (Windows low-level key blocking, so a
# pedal key doesn't also type its letter). Guard it: the app runs fine without it.
try:
    import keysuppress
except Exception:
    keysuppress = None


# =============================================================================
# Device protocol layer - structured so more boards can be added later.
# Only the M68 / HZ-68 is implemented for now.
# =============================================================================

class DeviceProfile:
    """Static description of a supported Hall-effect board and its wire protocol."""

    def __init__(self, key, name, vid, pid, usage_page,
                 arm_payload, disarm_payload, max_depth=40):
        self.key = key                      # short internal id, e.g. "m68"
        self.name = name                    # display name
        self.vid = vid
        self.pid = pid
        self.usage_page = usage_page        # vendor interface selector
        self.arm_payload = bytes(arm_payload)
        self.disarm_payload = bytes(disarm_payload)
        self.max_depth = max_depth          # depth units at full travel (40 -> 4.0 mm)


# Redragon M68 / E-YOOSO HZ-68. All bytes below are the tested-working sequences.
M68_ARM = [
    0x21, 0x00, 0x00, 0x00, 0x18, 0x02,
    0x3e, 0x26, 0x3e, 0x1e, 0x1e, 0x1e, 0x3e, 0x1e, 0x1e,
    0x3e, 0x1e, 0x3e, 0x2e, 0x10, 0x2e, 0x30, 0x3e,
]
M68_DISARM = [0x21, 0x00, 0x00, 0x00, 0x18, 0x03]

M68_PROFILE = DeviceProfile(
    key="m68",
    name="Redragon M68 / E-YOOSO HZ-68",
    vid=0x0416,
    pid=0x7372,
    usage_page=0xff1b,
    arm_payload=M68_ARM,
    disarm_payload=M68_DISARM,
    max_depth=40,
)

# Registry of supported boards. Add new DeviceProfile entries here later.
SUPPORTED_PROFILES = [M68_PROFILE]


# =============================================================================
# Paths.
#
# Two different roots, and mixing them up breaks the installed build:
#
#   resource_path()  - READ-ONLY files shipped with the app (ui.html). When
#                      frozen by PyInstaller these live in the unpacked bundle
#                      dir (sys._MEIPASS), which is DELETED when the app exits.
#   user_data_path() - files we WRITE (calibration, settings, crash log). These
#                      must survive restarts and must not need admin rights, so
#                      once installed they go to %LOCALAPPDATA%\KeyAxis.
#
# Running from source keeps writing next to app.py (handy during development);
# the moment we're frozen, or the app directory isn't writable (Program Files),
# we switch to LOCALAPPDATA and migrate any existing files across once.
# =============================================================================

APP_NAME = "KeyAxis"


def _frozen():
    return getattr(sys, "frozen", False)


def resource_path(rel):
    """Absolute path to a read-only file shipped with the app."""
    base = getattr(sys, "_MEIPASS", None) \
        or os.path.dirname(os.path.abspath(__file__))
    return os.path.join(base, rel)


def _app_dir():
    """Directory the app itself lives in (the .exe's folder when frozen)."""
    if _frozen():
        return os.path.dirname(os.path.abspath(sys.executable))
    return os.path.dirname(os.path.abspath(__file__))


def _dir_writable(path):
    try:
        probe = os.path.join(path, ".keyaxis_write_test")
        with open(probe, "w") as f:
            f.write("")
        os.remove(probe)
        return True
    except Exception:
        return False


_DATA_DIR = None


def user_data_dir():
    """
    Where we store files we write. Cached after the first call.
    Frozen (or unwritable app dir) -> %LOCALAPPDATA%\\KeyAxis, else next to app.py.
    """
    global _DATA_DIR
    if _DATA_DIR is not None:
        return _DATA_DIR
    here = _app_dir()
    if not _frozen() and _dir_writable(here):
        _DATA_DIR = here
        return _DATA_DIR
    base = os.environ.get("LOCALAPPDATA") or os.path.expanduser("~")
    d = os.path.join(base, APP_NAME)
    try:
        os.makedirs(d, exist_ok=True)
    except Exception:
        d = here                      # last resort; better than crashing
    _DATA_DIR = d
    _migrate_legacy_data(here, d)
    return _DATA_DIR


def _migrate_legacy_data(old_dir, new_dir):
    """
    First run of an installed build: copy any calibration/settings that were
    written by a from-source run so the user doesn't have to calibrate again.
    Never overwrites files already in the new location.
    """
    if os.path.abspath(old_dir) == os.path.abspath(new_dir):
        return
    for fn in ("calibration.json", "settings.json"):
        src, dst = os.path.join(old_dir, fn), os.path.join(new_dir, fn)
        try:
            if os.path.exists(src) and not os.path.exists(dst):
                with open(src, "rb") as a, open(dst, "wb") as b:
                    b.write(a.read())
        except Exception:
            pass


def user_data_path(filename):
    """Absolute path to one of our writable files."""
    return os.path.join(user_data_dir(), filename)


# =============================================================================
# Calibration - learns the true (row,col) + peak depth per physical key NAME.
# =============================================================================

CALIBRATION_FILENAME = "calibration.json"


def _calibration_path():
    return user_data_path(CALIBRATION_FILENAME)


def _sanitize_calibration(data, default_max=40):
    """
    Coerce an arbitrary calibration payload into a clean
    { name: {"row": int, "col": int, "max": int} } dict.

    Accepts either the full { "keys": {...} } envelope or a bare keys dict.
    Tolerates junk: skips any entry missing a usable row/col. Returns {} on
    anything unusable so the app simply reads as "uncalibrated".
    """
    if isinstance(data, dict) and "keys" in data:
        raw = data.get("keys")
    else:
        raw = data
    out = {}
    if not isinstance(raw, dict):
        return out
    for name, v in raw.items():
        if not isinstance(v, dict):
            continue
        try:
            row = int(v.get("row"))
            col = int(v.get("col"))
        except (TypeError, ValueError):
            continue
        try:
            mx = int(round(float(v.get("max", default_max))))
        except (TypeError, ValueError):
            mx = default_max
        # Keep max within a sane device range; a 0 or negative max would make a
        # pedal divide-to-zero, so floor it at 1 and cap at the device ceiling.
        if mx < 1:
            mx = default_max
        if mx > default_max:
            mx = default_max
        key = str(name)
        if not key:
            continue
        out[key] = {"row": row, "col": col, "max": mx}
    return out


# =============================================================================
# Persistent app settings (window size, last profile, key-suppress toggle) and
# the key-name -> Windows virtual-key map used for key-suppression.
# =============================================================================

SETTINGS_FILENAME = "settings.json"
# suppress defaults OFF: keeping a pedal key multi-function (e.g. W = throttle AND
# a game action) is the better default; suppression is an opt-in toggle.
DEFAULT_SETTINGS = {"window": {"w": 1100, "h": 760},
                    "suppress": False, "last_profile": None}


def _settings_path():
    return user_data_path(SETTINGS_FILENAME)


# Windows virtual-key codes for the UI template key names, so a bound pedal key's
# keystroke can be swallowed. Fn is a hardware key with no VK (never types anyway).
NAME_TO_VK = {}
for _ch in "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789":
    NAME_TO_VK[_ch] = ord(_ch)
NAME_TO_VK.update({
    "Esc": 0x1B, "Tab": 0x09, "Caps": 0x14, "Enter": 0x0D, "Back": 0x08,
    "Space": 0x20, "Del": 0x2E, "PgUp": 0x21, "PgDn": 0x22,
    "LShift": 0xA0, "RShift": 0xA1, "LCtrl": 0xA2, "RCtrl": 0xA3,
    "LAlt": 0xA4, "RAlt": 0xA5, "LWin": 0x5B,
    "Left": 0x25, "Up": 0x26, "Right": 0x27, "Down": 0x28,
    "-": 0xBD, "=": 0xBB, "[": 0xDB, "]": 0xDD, "\\": 0xDC,
    ";": 0xBA, "'": 0xDE, ",": 0xBC, ".": 0xBE, "/": 0xBF, "`": 0xC0,
})


class HidBoard:
    """
    Thin wrapper around one open hidapi handle to a board's vendor interface.

    All I/O methods are intended to be called from a single thread at a time
    (the reader thread once streaming; the API thread only while stopped).
    """

    def __init__(self, profile):
        self.profile = profile
        self._h = None
        self._path = None

    # -- discovery / lifecycle ------------------------------------------------

    @staticmethod
    def find_path(profile):
        """Return the bytes path of the vendor interface, or None if not present."""
        if not HID_OK:
            return None
        try:
            for d in hid.enumerate(profile.vid, profile.pid):
                if d.get("usage_page", 0) == profile.usage_page:
                    return d.get("path")
        except Exception:
            return None
        return None

    def open(self):
        """Open the vendor interface in non-blocking mode. Raises on failure."""
        if not HID_OK:
            raise RuntimeError("hidapi (the 'hid' package) is not installed.")
        path = self.find_path(self.profile)
        if not path:
            raise RuntimeError("Device not found (vendor interface missing).")
        h = hid.device()
        h.open_path(path)
        h.set_nonblocking(1)
        self._h = h
        self._path = path

    def is_open(self):
        return self._h is not None

    def reopen(self):
        """
        Close and re-open the SAME interface in place (recover from a transient
        USB drop). Keeps this HidBoard object valid so the reader's reference and
        self._board stay pointed at it. Returns True on success.
        """
        try:
            if self._h is not None:
                try:
                    self._h.close()
                except Exception:
                    pass
            self._h = None
            # Prefer the path we already had; if that no longer resolves, re-scan.
            path = self._path or self.find_path(self.profile)
            h = hid.device()
            try:
                h.open_path(path)
            except Exception:
                path = self.find_path(self.profile)
                if not path:
                    return False
                h = hid.device()
                h.open_path(path)
            h.set_nonblocking(1)
            self._h = h
            self._path = path
            return True
        except Exception:
            self._h = None
            return False

    def close(self):
        h, self._h = self._h, None
        self._path = None
        if h is not None:
            try:
                h.close()
            except Exception:
                pass

    # -- framing helpers ------------------------------------------------------

    def _send(self, payload):
        """
        Prepend report id 0x01, pad payload to 63 bytes -> 64 total, and write.
        Returns the number of bytes written (64 on success).
        """
        if self._h is None:
            raise RuntimeError("Board is not open.")
        body = bytes(payload[:63]).ljust(63, b"\x00")
        return self._h.write(bytes([0x01]) + body)

    def arm(self):
        """Start the travel stream."""
        return self._send(self.profile.arm_payload)

    def disarm(self):
        """Stop the travel stream."""
        return self._send(self.profile.disarm_payload)

    def read(self):
        """
        Non-blocking read of one 64-byte report. Returns a list of ints
        (possibly empty when nothing is pending). Raises on HID error
        (e.g. device unplugged).
        """
        if self._h is None:
            raise RuntimeError("Board is not open.")
        return self._h.read(64)

    def parse_frame(self, d):
        """
        Parse a raw report into (row, col, depth) for a travel frame, else None.
        depth is clamped to 0..max_depth.
        """
        if not d or len(d) < 10:
            return None
        if d[0] != 0x01 or d[1] != 0x21:
            return None
        if d[5] != 0x03:            # 0x03 = travel-data frame; 0x01 = idle/ack
            return None
        row, col, depth = d[7], d[8], d[9]
        if depth < 0:
            depth = 0
        if depth > self.profile.max_depth:
            depth = self.profile.max_depth
        return row, col, depth


# =============================================================================
# Pedal math (pure function - trivially testable).
# =============================================================================

def pedal_value(depth, max_depth, deadzone, curve, invert):
    """
    Map a raw travel depth to a 0..1 axis value.

      norm = clamp(depth / max_depth, 0, 1)
      if norm < deadzone: 0
      else rescale (norm - deadzone) / (1 - deadzone)
      then norm ** curve   (1.0 = linear, >1 = softer initial bite)
      then optional invert (1 - norm)
    """
    try:
        norm = float(depth) / float(max_depth) if max_depth else 0.0
    except Exception:
        norm = 0.0
    if norm < 0.0:
        norm = 0.0
    elif norm > 1.0:
        norm = 1.0

    dz = 0.0
    try:
        dz = float(deadzone)
    except Exception:
        dz = 0.0
    if dz < 0.0:
        dz = 0.0
    elif dz > 0.999:
        dz = 0.999

    if norm < dz:
        norm = 0.0
    else:
        norm = (norm - dz) / (1.0 - dz)

    try:
        c = float(curve)
    except Exception:
        c = 1.0
    if c > 0 and c != 1.0:
        norm = norm ** c

    if invert:
        norm = 1.0 - norm

    # Defense in depth: NaN survives every < / > comparison above (all False),
    # so an explicit finiteness check is the only thing that stops a NaN from
    # ever reaching vgamepad.
    if not math.isfinite(norm):
        return 0.0
    if norm < 0.0:
        norm = 0.0
    elif norm > 1.0:
        norm = 1.0
    return norm


# =============================================================================
# The Api class - the JS<->Python bridge. Every method returns a JSON-able dict.
# =============================================================================

class Api:
    """
    All hardware state and the reader thread live here. Every public method is
    callable from JS as window.pywebview.api.<method>(...). Methods are written to
    be robust and thread-safe: shared state is guarded by locks and no method blocks
    the caller for longer than a short thread join.
    """

    #: axes we can drive on the virtual pad
    VALID_AXES = ("RT", "LT", "LSY", "LSX", "RSY", "RSX")

    def __init__(self):
        # The active device profile (only M68 for now).
        self._profile = M68_PROFILE
        self._board = None                      # HidBoard or None

        # Calibration map: physical key NAME -> {"row","col","max"}. Loaded from
        # calibration.json next to app.py; empty dict means "uncalibrated".
        self._calibration = self._load_calibration()

        # Persistent settings (window size, last-used profile, key-suppress toggle).
        self._settings = self._load_settings()

        # Reader-thread control.
        self._thread = None
        self._running = False                   # reader loop should keep going
        self._recovering = False                # mid self-heal of a transient USB drop

        # Feature flags.
        self._monitoring = False                # travel stream wanted for display
        self._pedals_active = False             # gamepad output wanted

        # Live snapshot for the MONITOR tab. Guarded by _lock.
        self._live = {}                         # "row,col" -> depth 0..40
        self._last = {"row": None, "col": None, "depth": 0}

        # Pedal configuration + computed values. Guarded by _lock.
        self._pedals = []                       # list of normalized pedal dicts
        self._pedal_values = {}                 # name -> 0..1
        self._axis_values = {a: 0.0 for a in self.VALID_AXES}

        # Active key-suppression reasons (see _push_suppression).
        self._suppress_pedals = set()
        self._suppress_guard = set()

        # Virtual gamepad (created lazily when pedals start).
        self._gamepad = None

        # ViGEmBus probe result, cached after the first real probe so we never
        # spawn a throwaway pad twice (each one flickers a connect/disconnect).
        # None = not probed yet; otherwise (ok: bool, msg: str).
        self._vigem_probe = None

        # Locks: _lock guards shared state dicts; _gp_lock serialises gamepad calls;
        # _op_lock serialises start/stop/connect operations so flags stay coherent.
        self._lock = threading.Lock()
        self._gp_lock = threading.Lock()
        self._op_lock = threading.Lock()

        # pywebview window (set by main() once created) for native file dialogs.
        # NOTE: this MUST stay underscore-prefixed. pywebview builds the JS bridge
        # by walking dir(api) and recursing into any non-callable attribute; the
        # Window object contains .NET/WinForms members, and comparing one of those
        # (System.Drawing.Rectangle) against this Api instance raises, which kills
        # the whole bridge ("Backend bridge unavailable"). Names starting with "_"
        # are skipped by that walk, so keep the underscore.
        self._window = None

    # ------------------------------------------------------------------ status

    def status(self):
        """Overall snapshot for the header/status strip."""
        connected = (self._board is not None and self._board.is_open()) \
            or self._recovering
        # ViGEm usability must match vigem_available(): a live pad proves it; a
        # recorded probe failure denies it; otherwise it's usable if vgamepad is
        # importable (the definitive test is deferred to start_pedals). Do NOT
        # gate on a pad being live here or the header falsely reads "missing".
        if self._gamepad is not None:
            vigem = True
        elif not VGAMEPAD_IMPORT_OK:
            vigem = False
        elif self._vigem_probe is not None:
            vigem = bool(self._vigem_probe[0])
        else:
            vigem = True
        return {
            "connected": connected,
            "device": self._profile.name if connected else None,
            "vigem": vigem,
            "monitoring": self._monitoring,
            "pedals_active": self._pedals_active,
        }

    def vigem_available(self):
        """
        Report whether virtual-gamepad output is usable.

        We deliberately do NOT instantiate a throwaway pad to probe. Creating a
        pad spawns a virtual controller (Windows Game Bar popup), and destroying
        it would double-free the ViGEm target and crash the process. So we report
        based on the library being importable, plus any pad that is already live.
        The definitive test happens exactly ONCE in start_pedals(), which creates
        the single persistent pad and reports any failure cleanly. This means a
        virtual controller only ever appears when the user actually starts pedals.
        """
        if not VGAMEPAD_IMPORT_OK:
            return {
                "ok": False,
                "msg": "vgamepad is not installed. Pedal output is disabled. "
                       "Install with: pip install vgamepad",
            }
        if self._gamepad is not None:
            return {"ok": True, "msg": "ViGEmBus ready (virtual pad active)."}
        if self._vigem_probe is not None:
            ok, msg = self._vigem_probe
            return {"ok": ok, "msg": msg}
        return {
            "ok": True,
            "msg": "vgamepad ready. ViGEmBus is verified when you start pedals.",
        }

    # -------------------------------------------------------------- connection

    def connect(self):
        """Find and open the vendor interface. Idempotent-ish."""
        with self._op_lock:
            if not HID_OK:
                return {"ok": False, "msg": "hidapi is not installed (pip install hid).",
                        "device": None}
            if self._board is not None and self._board.is_open():
                return {"ok": True, "msg": "Already connected.",
                        "device": self._profile.name}
            board = HidBoard(self._profile)
            try:
                board.open()
            except Exception as e:
                return {"ok": False, "msg": str(e), "device": None}
            self._board = board
            return {"ok": True, "msg": "Connected.", "device": self._profile.name}

    def disconnect(self):
        """Stop the stream and close the handle. Always DISARMs on the way out."""
        with self._op_lock:
            self._monitoring = False
            # Flip under _gp_lock so an in-flight reader push (during the join
            # window below) sees the cleared flag and won't leave an axis set.
            with self._gp_lock:
                self._pedals_active = False
            self._stop_stream_locked()          # joins reader -> reader DISARMs
            if self._board is not None:
                self._board.close()
                self._board = None
            self._release_gamepad()             # resets to neutral as last write
            with self._lock:
                self._live.clear()
                self._last = {"row": None, "col": None, "depth": 0}
                self._pedal_values.clear()
                self._axis_values = {a: 0.0 for a in self.VALID_AXES}
            return {"ok": True}

    # ------------------------------------------------------------- monitor tab

    def start_monitor(self):
        """ARM the stream so the reader fills the live depth map for display."""
        with self._op_lock:
            if self._board is None or not self._board.is_open():
                r = self._connect_locked()
                if not r["ok"]:
                    return {"ok": False, "msg": r["msg"]}
            self._monitoring = True
            ok, msg = self._ensure_stream_locked()
            if not ok:
                self._monitoring = False
                return {"ok": False, "msg": msg}
            return {"ok": True, "msg": "Monitoring travel stream."}

    def stop_monitor(self):
        """
        Stop display monitoring. The travel stream is LEFT RUNNING while the board
        stays connected - tearing it down and re-arming on every tab switch is what
        upset this flaky board and caused the random disconnects. The stream is only
        stopped on disconnect()/shutdown().
        """
        with self._op_lock:
            self._monitoring = False
            return {"ok": True}

    def live(self):
        """Light-weight poll target for the MONITOR tab (~50 ms)."""
        with self._lock:
            return {
                "active": self._running and self._monitoring,
                "keys": dict(self._live),
                "last": dict(self._last),
            }

    # -------------------------------------------------------------- pedals tab

    # -------------------------------------------------------------- settings

    def _load_settings(self):
        try:
            with open(_settings_path(), "r", encoding="utf-8") as f:
                data = json.load(f)
            if isinstance(data, dict):
                out = dict(DEFAULT_SETTINGS)
                out.update({k: data[k] for k in data if k in DEFAULT_SETTINGS})
                if not isinstance(out.get("window"), dict):
                    out["window"] = dict(DEFAULT_SETTINGS["window"])
                return out
        except Exception:
            pass
        return dict(DEFAULT_SETTINGS)

    def _save_settings(self):
        try:
            with open(_settings_path(), "w", encoding="utf-8") as f:
                json.dump(self._settings, f, indent=2)
            return True
        except Exception:
            return False

    def get_settings(self):
        """Return the persisted settings (window size, suppress flag, last profile)."""
        with self._lock:
            return json.loads(json.dumps(self._settings))   # deep copy

    def save_settings(self, data):
        """Merge & persist a partial settings update from the UI."""
        if not isinstance(data, dict):
            return {"ok": False}
        with self._lock:
            for k in ("suppress", "last_profile", "window"):
                if k in data:
                    self._settings[k] = data[k]
            ok = self._save_settings()
        return {"ok": bool(ok)}

    # ----------------------------------------------------- key-suppression

    # There are TWO independent reasons we might swallow a key, and the hook
    # takes one flat set - so track them separately and always push the union.
    # Otherwise whichever one updates last wipes the other's keys.
    #   _suppress_pedals - opt-in, the bound pedal keys while pedals are driving
    #   _suppress_guard  - the Windows keys while the calibration wizard is open

    VK_LWIN, VK_RWIN = 0x5B, 0x5C

    def _push_suppression(self):
        """Apply the union of every active suppression reason."""
        if keysuppress is None or not keysuppress.available():
            return
        vks = set(self._suppress_pedals) | set(self._suppress_guard)
        if vks:
            keysuppress.ensure_started()
        keysuppress.set_suppressed(vks)

    def _apply_suppression(self, pedals):
        """If enabled, swallow the bound pedal keys' OS keystrokes while driving."""
        vks = set()
        if self._settings.get("suppress", False):
            for p in pedals:
                name = p.get("key")
                vk = NAME_TO_VK.get(name) if name else None
                if vk:
                    vks.add(vk)
        self._suppress_pedals = vks
        self._push_suppression()

    def _clear_suppression(self):
        self._suppress_pedals = set()
        self._push_suppression()

    def calibration_guard(self, on=True):
        """
        Swallow the Windows keys while the calibration wizard is open.

        Pressing Win during calibration pops the Start menu over the app and
        steals focus mid-wizard. The wizard has to see the key press to learn
        it, and it still does - KeyAxis reads travel over HID, which the hook
        never touches. We only stop Windows acting on the keystroke.

        Always released when the wizard closes, and again on shutdown().
        """
        self._suppress_guard = {self.VK_LWIN, self.VK_RWIN} if on else set()
        self._push_suppression()
        return {"ok": True, "guarded": bool(self._suppress_guard)}

    def start_pedals(self, cfg):
        """
        Begin driving the virtual gamepad from the configured pedals.

        cfg = { "pedals": [ {name, axis, row, col, deadzone, curve, invert}, ... ] }
        """
        with self._op_lock:
            pedals, err = self._normalize_pedals(cfg)
            if err:
                return {"ok": False, "msg": err}
            if not pedals:
                return {"ok": False, "msg": "No pedals configured."}

            # Ensure device.
            if self._board is None or not self._board.is_open():
                r = self._connect_locked()
                if not r["ok"]:
                    return {"ok": False, "msg": r["msg"]}

            # Ensure a virtual gamepad exists. Do NOT probe with
            # vigem_available() first - that would spawn an extra throwaway pad
            # (and its flicker). Just try to create the ONE real pad we keep;
            # a creation failure here IS the "ViGEmBus missing" signal.
            if self._gamepad is None:
                if not VGAMEPAD_IMPORT_OK:
                    return {
                        "ok": False,
                        "msg": "vgamepad is not installed. Pedal output is "
                               "disabled. Install with: pip install vgamepad",
                    }
                try:
                    self._gamepad = vg.VX360Gamepad()
                except Exception as e:
                    self._gamepad = None
                    # Cache the negative result so later vigem_available()
                    # calls don't re-probe and flicker again.
                    self._vigem_probe = (
                        False,
                        "vgamepad is installed but ViGEmBus was not found. "
                        "Install the ViGEmBus driver, then reconnect. (%s)" % e,
                    )
                    return {"ok": False,
                            "msg": "Could not create virtual gamepad - ViGEmBus "
                                   "missing or not running. (%s)" % e}

            # Install config + reset axis state to neutral.
            with self._lock:
                self._pedals = pedals
                self._pedal_values = {p["name"]: 0.0 for p in pedals}
                self._axis_values = {a: 0.0 for a in self.VALID_AXES}
            self._reset_gamepad()

            self._pedals_active = True
            ok, msg = self._ensure_stream_locked()
            if not ok:
                self._pedals_active = False
                return {"ok": False, "msg": msg}
            # Optionally swallow the bound keys' typing while driving.
            self._apply_suppression(pedals)
            return {"ok": True,
                    "msg": "Pedals active: %s" % ", ".join(p["name"] for p in pedals)}

    def stop_pedals(self):
        """Stop gamepad output and centre all axes. Keeps monitoring if requested."""
        with self._op_lock:
            # Flip the flag, zero the cached values, and push the neutral reset
            # all under _gp_lock. Because the reader also pushes under _gp_lock
            # and re-checks _pedals_active there, it cannot interleave a non-zero
            # axis after this reset - the reset is guaranteed to be the LAST
            # gamepad write, so no axis can be left stuck.
            with self._gp_lock:
                self._pedals_active = False
                with self._lock:
                    self._pedal_values = {p["name"]: 0.0 for p in self._pedals}
                    self._axis_values = {a: 0.0 for a in self.VALID_AXES}
                self._reset_gamepad_locked()
            self._clear_suppression()
            # Leave the stream running while connected (see stop_monitor). It stops
            # only on disconnect()/shutdown(), so tab/mode switches never re-arm.
            return {"ok": True}

    def pedal_state(self):
        """Poll target for the live pedal gauges (~50 ms)."""
        with self._lock:
            return {
                "active": self._pedals_active and self._running,
                "values": dict(self._pedal_values),
            }

    # ---------------------------------------------------------- profile I/O

    def save_profile(self, cfg):
        """Write the pedal config to a user-chosen file via the native save dialog."""
        try:
            pedals, err = self._normalize_pedals(cfg)
            if err:
                return {"ok": False, "msg": err}
            payload = {
                "app": "KeyAxis",
                "version": 1,
                "device": self._profile.key,
                "pedals": pedals,
            }
            path = self._save_dialog("keyaxis-profile.json")
            if not path:
                return {"ok": False, "msg": "Save cancelled."}
            with open(path, "w", encoding="utf-8") as f:
                json.dump(payload, f, indent=2)
            return {"ok": True, "path": path}
        except Exception as e:
            return {"ok": False, "msg": "Save failed: %s" % e}

    def load_profile(self):
        """Read a pedal config from a user-chosen file via the native open dialog."""
        try:
            path = self._open_dialog()
            if not path:
                return {"ok": False, "msg": "Load cancelled."}
            with open(path, "r", encoding="utf-8") as f:
                data = json.load(f)
            pedals, err = self._normalize_pedals(data)
            if err:
                return {"ok": False, "msg": err}
            return {"ok": True, "cfg": {"pedals": pedals}}
        except Exception as e:
            return {"ok": False, "msg": "Load failed: %s" % e}

    # ---------------------------------------------------------- calibration

    def get_calibration(self):
        """
        Return the learned key map for the UI.

          { "done": bool, "keys": { name: {"row","col","max"} } }

        'done' is True once at least one key has been calibrated. The UI uses the
        map to label the board, light the correct cell, drive binding, and scale
        pedals; when 'done' is False it should guide the user to calibrate.
        """
        with self._lock:
            keys = {k: dict(v) for k, v in self._calibration.items()}
        return {"done": bool(keys), "keys": keys}

    def save_calibration(self, data):
        """
        Persist a calibration map to calibration.json and update it in memory.

        'data' may be the full { "keys": {...} } envelope or a bare keys dict;
        each entry needs a usable row/col and (optionally) a peak 'max'. Junk
        entries are skipped rather than rejecting the whole save.
        """
        try:
            clean = _sanitize_calibration(data, self._profile.max_depth)
            payload = {
                "app": "KeyAxis",
                "version": 1,
                "device": self._profile.key,
                "keys": clean,
            }
            with open(_calibration_path(), "w", encoding="utf-8") as f:
                json.dump(payload, f, indent=2)
            with self._lock:
                self._calibration = clean
            return {"ok": True, "keys": clean}
        except Exception as e:
            return {"ok": False, "msg": "Save failed: %s" % e}

    def last_key(self):
        """
        Convenience accessor for the most recent travel frame, for the
        calibration wizard's capture loop: { "row","col","depth" }.
        """
        with self._lock:
            return dict(self._last)

    # =========================================================================
    # Internal helpers (not part of the JS contract).
    # =========================================================================

    def _load_calibration(self):
        """Read calibration.json next to app.py. Missing/corrupt -> {} (uncalibrated)."""
        try:
            with open(_calibration_path(), "r", encoding="utf-8") as f:
                data = json.load(f)
        except Exception:
            return {}
        try:
            return _sanitize_calibration(data, self._profile.max_depth)
        except Exception:
            return {}

    def _connect_locked(self):
        """connect() body assuming _op_lock is already held."""
        if not HID_OK:
            return {"ok": False, "msg": "hidapi is not installed.", "device": None}
        if self._board is not None and self._board.is_open():
            return {"ok": True, "msg": "Already connected.", "device": self._profile.name}
        board = HidBoard(self._profile)
        try:
            board.open()
        except Exception as e:
            return {"ok": False, "msg": str(e), "device": None}
        self._board = board
        return {"ok": True, "msg": "Connected.", "device": self._profile.name}

    def _normalize_pedals(self, cfg):
        """
        Validate + coerce a raw cfg dict into a clean list of pedal dicts.
        Returns (pedals, error_message). error_message is "" on success.
        """
        if not isinstance(cfg, dict):
            return [], "Invalid config."
        raw = cfg.get("pedals")
        if raw is None:
            return [], "Config has no 'pedals'."
        if not isinstance(raw, list):
            return [], "'pedals' must be a list."
        out = []
        for i, p in enumerate(raw):
            if not isinstance(p, dict):
                return [], "Pedal #%d is not an object." % (i + 1)
            axis = str(p.get("axis", "")).upper()
            if axis not in self.VALID_AXES:
                return [], "Pedal '%s' has invalid axis '%s'." % (
                    p.get("name", i + 1), axis)
            try:
                row = int(p.get("row"))
                col = int(p.get("col"))
            except Exception:
                return [], "Pedal '%s' has invalid row/col." % p.get("name", i + 1)
            name = str(p.get("name") or ("Pedal %d" % (i + 1)))
            try:
                deadzone = float(p.get("deadzone", 0.0))
            except Exception:
                deadzone = 0.0
            try:
                curve = float(p.get("curve", 1.0))
            except Exception:
                curve = 1.0
            invert = bool(p.get("invert", False))
            # Optional per-pedal peak depth (from calibration). Full press = this
            # value, not a fixed 40, so a switch that tops out at ~39 still hits
            # 100%. Absent -> fall back to the device ceiling (profile.max_depth).
            mx = p.get("max", None)
            if mx is None:
                mx = self._profile.max_depth
            try:
                mx = float(mx)
            except Exception:
                mx = float(self._profile.max_depth)
            # Reject NaN/inf BEFORE clamping: min()/max() do not sanitise a NaN
            # (comparisons against it are all False), so it would slip through.
            if not math.isfinite(deadzone):
                deadzone = 0.0
            if not math.isfinite(curve):
                curve = 1.0
            if not math.isfinite(mx) or mx < 1.0:
                mx = float(self._profile.max_depth)
            if mx > float(self._profile.max_depth):
                mx = float(self._profile.max_depth)
            # Clamp to sane ranges.
            deadzone = min(max(deadzone, 0.0), 0.95)
            curve = min(max(curve, 0.2), 5.0)
            # Store max as an int (device depth is integer units).
            mx = int(round(mx))
            # Bound-safe key name for optional calibration lookup (display only).
            keyname = p.get("key")
            keyname = str(keyname) if keyname else None
            out.append({
                "name": name,
                "axis": axis,
                "row": row,
                "col": col,
                "deadzone": deadzone,
                "curve": curve,
                "invert": invert,
                "max": mx,
                "key": keyname,
            })
        return out, ""

    # ---- reader-thread lifecycle -------------------------------------------

    def _ensure_stream_locked(self):
        """
        Make sure the reader thread is running (assumes _op_lock held).
        The reader ARMs on entry and DISARMs on exit, so all HID I/O stays on it.
        """
        if self._thread is not None and self._thread.is_alive():
            return True, "Stream already running."
        if self._board is None or not self._board.is_open():
            return False, "Not connected."
        self._running = True
        self._thread = threading.Thread(
            target=self._reader_loop, name="keyaxis-reader", daemon=True)
        self._thread.start()
        return True, "Stream started."

    def _stop_stream_locked(self):
        """Signal the reader to stop and join it (assumes _op_lock held)."""
        self._running = False
        t = self._thread
        self._thread = None
        if t is not None and t.is_alive() and t is not threading.current_thread():
            t.join(timeout=2.0)

    def _reader_loop(self):
        """
        The single HID I/O thread. Arms the stream, reads travel frames until asked
        to stop or the device errors, updates shared state, drives the gamepad when
        pedals are active, then always disarms on the way out.
        """
        board = self._board
        if board is None:
            self._running = False
            return

        # ARM (with a heal attempt if the very first arm fails).
        if not self._arm_board(board):
            if not self._recover_stream(board):
                self._running = False
                self._on_hid_error()
                return

        try:
            while self._running:
                try:
                    d = board.read()
                except Exception:
                    # This board is known to drop the USB pipe momentarily and
                    # come straight back ("bizarre lock state, still detecting").
                    # Try to heal in place rather than dropping the connection.
                    if not self._running:
                        break
                    if self._recover_stream(board):
                        continue
                    self._on_hid_error()
                    break
                if not d:
                    # Event-driven stream: nothing pending. Idle briefly when a
                    # consumer needs low latency (pedals/monitor); back right off
                    # when merely connected-and-idle so we don't busy-poll the CPU.
                    if self._pedals_active or self._monitoring:
                        time.sleep(0.0008)
                    else:
                        time.sleep(0.01)
                    continue
                frame = board.parse_frame(d)
                if frame is None:
                    continue
                row, col, depth = frame
                self._process_frame(row, col, depth)
        finally:
            # Always try to DISARM, even on error (harmless if the handle is dead).
            try:
                board.disarm()
            except Exception:
                pass

    def _arm_board(self, board):
        """Arm the travel stream; return False on failure instead of raising."""
        try:
            board.arm()
            return True
        except Exception:
            return False

    def _recover_stream(self, board):
        """
        Heal a transient USB drop from inside the reader thread: reopen the handle
        and re-arm, a few tries with a short backoff. Bails immediately if a stop
        was requested (disconnect/stop_pedals clears self._running). While healing
        we set self._recovering so status() still reports 'connected' and the UI
        doesn't flicker for a sub-second hiccup.
        """
        self._recovering = True
        try:
            for _ in range(6):
                if not self._running:
                    return False
                time.sleep(0.15)
                if not self._running:
                    return False
                if board.reopen() and self._arm_board(board):
                    return True
            return False
        finally:
            self._recovering = False

    def _on_hid_error(self):
        """Mark the device gone after an HID failure inside the reader thread."""
        self._running = False
        self._monitoring = False
        self._pedals_active = False
        b, self._board = self._board, None
        if b is not None:
            try:
                b.close()
            except Exception:
                pass

    # ---- per-frame processing ----------------------------------------------

    # A key at rest can emit tiny magnetic-noise frames (depth 1-3). For the
    # BOARD DISPLAY we drop anything below this floor so resting keys don't light
    # up or "stick". Pedals always get the RAW depth, so full-scale/zero-deadzone
    # is unaffected - the floor is display-only.
    LIVE_FLOOR = 4  # 0.4 mm

    def _process_frame(self, row, col, depth):
        """Update the live snapshot and, if pedals are active, drive the gamepad."""
        key = "%d,%d" % (row, col)
        with self._lock:
            if depth >= self.LIVE_FLOOR:
                self._live[key] = depth
            else:
                # Below the noise floor: drop it so the board view clears cleanly.
                self._live.pop(key, None)
            if depth >= self.LIVE_FLOOR or self._last.get("row") == row and \
               self._last.get("col") == col:
                self._last = {"row": row, "col": col, "depth": depth}
        # Guard the gamepad path: monitor-only use (no vgamepad / no pad created)
        # must never reach a gamepad call, or the reader thread would crash.
        # Pedals get the RAW depth (no floor) so zero-deadzone stays true 0->100%.
        if self._pedals_active and self._gamepad is not None:
            self._drive_pedals(row, col, depth)

    def _drive_pedals(self, row, col, depth):
        """Recompute any pedals bound to (row,col) and push the gamepad if changed."""
        changed = False
        with self._lock:
            pedals = self._pedals
            for p in pedals:
                if p["row"] == row and p["col"] == col:
                    # Scale against the pedal's calibrated peak depth (falls back
                    # to the device ceiling), so a real full press = 100%.
                    pmax = p.get("max") or self._profile.max_depth
                    v = pedal_value(depth, pmax,
                                    p["deadzone"], p["curve"], p["invert"])
                    self._pedal_values[p["name"]] = v
                    self._axis_values[p["axis"]] = v
                    changed = True
            axis_snapshot = dict(self._axis_values) if changed else None
            axes_in_use = {p["axis"] for p in pedals} if changed else set()
        if changed and axis_snapshot is not None:
            self._push_gamepad(axis_snapshot, axes_in_use)

    # ---- virtual gamepad ----------------------------------------------------

    def _push_gamepad(self, axis_values, axes_in_use=None):
        """Apply the current axis values to the virtual pad and update().

        Trigger axes (RT/LT) are unipolar 0..1 (rest 0, pressed 1) - perfect for a
        single pedal, but the Xbox controller COMBINES LT+RT onto one shared Z axis
        in DirectInput, so two pedals can't both use triggers.

        Stick axes (LSX/LSY/RSX/RSY) are bipolar -1..+1 centred at 0, and are fully
        INDEPENDENT of each other - the right choice for multiple pedals. We map a
        pedal's 0..1 travel across the FULL stick axis (rest = -1 min, pressed = +1
        max) so a game sees a clean full-range 0->100% pedal axis that rests at one
        end. A stick axis with NO pedal bound to it must stay CENTRED (0), never
        jammed to -1.
        """
        gp = self._gamepad
        if gp is None:
            return
        if axes_in_use is None:
            axes_in_use = set()

        def stick(axis):
            if axis not in axes_in_use:
                return 0.0
            v = axis_values.get(axis, 0.0)
            return max(-1.0, min(1.0, v * 2.0 - 1.0))

        with self._gp_lock:
            # Re-check the flag under the SAME lock that stop/disconnect/shutdown
            # use to flip _pedals_active=False and zero the pad. If pedals were
            # stopped between the reader computing this snapshot and acquiring the
            # lock, push nothing - otherwise we would clobber the neutral reset
            # and leave an axis stuck non-zero (the stream is event-driven, so
            # nothing else would ever correct it).
            if not self._pedals_active:
                return
            try:
                gp.right_trigger_float(value_float=axis_values.get("RT", 0.0))
                gp.left_trigger_float(value_float=axis_values.get("LT", 0.0))
                gp.left_joystick_float(x_value_float=stick("LSX"),
                                       y_value_float=stick("LSY"))
                gp.right_joystick_float(x_value_float=stick("RSX"),
                                        y_value_float=stick("RSY"))
                gp.update()
            except Exception:
                # Never let a gamepad hiccup kill the reader thread.
                pass

    def _reset_gamepad(self):
        """Centre all axes and push a neutral state."""
        with self._gp_lock:
            self._reset_gamepad_locked()

    def _reset_gamepad_locked(self):
        """
        Centre all axes and push a neutral state (assumes _gp_lock is held).
        Callers that flip _pedals_active=False must call this LAST so it is the
        final gamepad write and cannot be undone by an in-flight reader push.
        """
        gp = self._gamepad
        if gp is None:
            return
        try:
            gp.reset()
            gp.update()
        except Exception:
            pass

    def _release_gamepad(self):
        """Drop the virtual pad entirely (on disconnect / close)."""
        gp, self._gamepad = self._gamepad, None
        if gp is not None:
            with self._gp_lock:
                try:
                    gp.reset()
                    gp.update()
                except Exception:
                    pass
            try:
                del gp
            except Exception:
                pass

    # ---- native file dialogs ------------------------------------------------

    def _save_dialog(self, default_name):
        """Return a chosen save path (str) or None. Handles pywebview return shapes."""
        if not WEBVIEW_OK:
            return None
        win = self._window
        try:
            res = win.create_file_dialog(
                webview.SAVE_DIALOG,
                save_filename=default_name,
                file_types=("KeyAxis profile (*.json)", "All files (*.*)"),
            )
        except Exception:
            return None
        return self._first_path(res)

    def _open_dialog(self):
        """Return a chosen open path (str) or None."""
        if not WEBVIEW_OK:
            return None
        win = self._window
        try:
            res = win.create_file_dialog(
                webview.OPEN_DIALOG,
                allow_multiple=False,
                file_types=("KeyAxis profile (*.json)", "All files (*.*)"),
            )
        except Exception:
            return None
        return self._first_path(res)

    @staticmethod
    def _first_path(res):
        """Normalize the various return shapes of create_file_dialog to a single path."""
        if not res:
            return None
        if isinstance(res, (list, tuple)):
            return res[0] if res else None
        return res

    # ---- app shutdown -------------------------------------------------------

    def shutdown(self):
        """
        Called from the window 'closing' handler: disarm, stop the reader, release the
        gamepad, and close the HID handle so nothing is left armed on exit.
        """
        try:
            with self._op_lock:
                self._monitoring = False
                # Flip under _gp_lock so an in-flight reader push cannot leave
                # an axis set before the pad is released to neutral.
                with self._gp_lock:
                    self._pedals_active = False
                self._stop_stream_locked()
                self._release_gamepad()         # resets to neutral as last write
                if self._board is not None:
                    self._board.close()
                    self._board = None
        except Exception:
            pass
        # Remove the key-suppression hook entirely on exit.
        try:
            if keysuppress is not None and keysuppress.available():
                keysuppress.shutdown()
        except Exception:
            pass


# =============================================================================
# UI loading + window bootstrap.
# =============================================================================

def _load_ui_html():
    """
    Read the sibling ui.html so backend and UI stay in separate files. If it is
    missing, fall back to a minimal self-contained page that still explains what to do.

    Uses resource_path() so this also finds ui.html inside a PyInstaller bundle.
    """
    ui_path = resource_path("ui.html")
    try:
        with open(ui_path, "r", encoding="utf-8") as f:
            return f.read()
    except Exception:
        return (
            "<!DOCTYPE html><html><head><meta charset='utf-8'>"
            "<style>html,body{margin:0;height:100%;background:#0d0f14;color:#e7e9ee;"
            "font-family:Segoe UI,system-ui,sans-serif;display:flex;align-items:center;"
            "justify-content:center;text-align:center}"
            ".c{max-width:520px;padding:32px}h1{color:#ff5a3c;margin:0 0 12px;"
            "letter-spacing:2px}code{background:#171a21;padding:2px 6px;border-radius:4px;"
            "color:#ff8a6c}</style><title>KeyAxis</title></head><body><div class='c'>"
            "<h1>KEYAXIS</h1><p>The interface file <code>ui.html</code> was not found "
            "next to <code>app.py</code>.</p><p>Place <code>ui.html</code> in the same "
            "folder and relaunch.</p></div></body></html>"
        )


def main():
    """Create the native window, expose the Api, and run the event loop."""
    if not WEBVIEW_OK:
        sys.stderr.write(
            "pywebview is not installed. Install it with: pip install pywebview\n")
        return 1

    api = Api()
    html = _load_ui_html()

    # Restore the last window size (clamped to something sane).
    _w = 1100
    _h = 760
    try:
        _win = api._settings.get("window") or {}
        _w = int(_win.get("w", 1100)); _h = int(_win.get("h", 760))
        _w = max(920, min(_w, 3840)); _h = max(620, min(_h, 2160))
    except Exception:
        _w, _h = 1100, 760

    window = webview.create_window(
        "KeyAxis",
        html=html,
        js_api=api,
        width=_w,
        height=_h,
        min_size=(920, 620),
        background_color="#0d0f14",
    )
    api._window = window

    # Remember the window size across launches.
    def _on_resized(width, height):
        try:
            api._settings["window"] = {"w": int(width), "h": int(height)}
            api._save_settings()
        except Exception:
            pass
    try:
        window.events.resized += _on_resized
    except Exception:
        pass

    # Ensure we always disarm + tear down on close.
    def _on_closing():
        api.shutdown()

    try:
        window.events.closing += _on_closing
    except Exception:
        # Older pywebview: fall back to closed event.
        try:
            window.events.closed += _on_closing
        except Exception:
            pass

    # gui=None lets pywebview pick WebView2 on Windows 11 automatically.
    try:
        webview.start()
    finally:
        # Belt-and-braces: make sure nothing is left armed if start() returns.
        api.shutdown()
    return 0


if __name__ == "__main__":
    try:
        sys.exit(main())
    except Exception:
        # Auto-capture any real crash to crash.log in the writable data dir, so a
        # failure under the windowless launcher is still diagnosable (WebView2
        # cold-start can occasionally fault). Best-effort; never mask the exit.
        try:
            import datetime
            _p = user_data_path("crash.log")
            with open(_p, "a", encoding="utf-8") as _f:
                _f.write("\n===== crash %s =====\n" % datetime.datetime.now().isoformat())
                _f.write(traceback.format_exc())
        except Exception:
            pass
        traceback.print_exc()
        sys.exit(1)