V2

README.md

@@ -109,11 +109,12 @@ The car-style virtual joystick maps only to forward/reverse and continuous
 differential turning; it never sends lateral motion. The joystick and vertical
 slider ease back to center over 400 ms after mouse/key release, so neither can
 be left commanding motion.
-Heartbeat loss, disconnect, and disarm remain immediate safety stops and are
-intentionally not eased.
+Focus loss, stale telemetry, disconnect, and disarm clear commanded inputs
+without easing. This is a neutral-command request, **not proof that motors have
+stopped** when the communication link is unavailable.
 
 In addition, transmitted pilot demands have a small 4% input deadband and a
-0.8-second full-range slew limit. This makes both acceleration and deceleration
+0.25-second full-range slew limit. This makes both acceleration and deceleration
 arrive at the flight controller as a sequence of stable intermediate values.
 Forward and yaw are normalized as a SimpleROV-3 motor pair before the output
 limit is applied, preventing their mixer contributions from adding beyond the
@@ -122,3 +123,51 @@ selected horizontal limit.
 ArduPilot may ignore manual input when `MAV_GCS_SYSID` does not match this
 application's system ID (default 255), or when `MAV_OPTIONS` does not allow
 MAVLink input. Those parameters must already be correctly configured.
+
+## Engage, confirmation, and interruption handling
+
+The compact window opens at 1100 × 650. Empty sidebar areas drag the window;
+the STL viewer, buttons, and sliders are separate interactive regions. Output
+limit and Motor setup sit below the main controls. Recent activity retains the
+last three events, oldest at the top and newest emphasized at the bottom.
+Routine hold instructions are kept in tooltips;
+pending confirmations and safety warnings still appear above the controls.
+The full-width text control displays `engage` / `disengage`; disengage sends the
+same immediate disarm request described below.
+
+- Hold **ENGAGE** for 1.4 seconds (or hold F2). Early release, leaving the
+  button, interrupted touch, and focus loss cancel the hold without sending arm.
+- **ENGAGING…** means a request is pending. A send result or accepted command
+  ACK alone does not prove that the vehicle armed: a fresh autopilot heartbeat
+  reporting the requested state is the final confirmation. A heartbeat can
+  confirm state even if the ACK packet was lost.
+- **DISARM** is one tap or F3, with no long hold. While confirmation is pending,
+  **DISARMING…** stays red and driving is disabled. Disarm can also interrupt a
+  pending Engage request. No forced-arm/disarm bypass is used.
+- Confirmation timeout: 5 seconds in the backend (6-second UI fallback).
+  Rejection and timeout remain visible. Late heartbeat updates still determine
+  the displayed state; the UI never substitutes an animation state for telemetry.
+- A heartbeat older than 3 seconds is stale. A missing bridge reply after
+  1.5 seconds shows **STATE UNKNOWN**, preserving the last-known state without
+  claiming disarm. Battery readings older than 5 seconds are marked stale.
+- The web frontend renews an input lease locally every 250 ms. If it stops for
+  1 second, the worker clears stored demands and sends neutral at its configured
+  control rate. This adds no MAVLink stream or parameter download. Focus loss
+  clears both captured touch pointers and queued input; reconnect never replays
+  the old joystick position. Normal release still eases back to center.
+- Link loss cannot deliver a stop over a broken tether. Verify the vehicle's
+  own failsafe and use independent physical power isolation for bench tests.
+
+### Regression checks (no hardware)
+
+Run from this project folder after setting up the Python environment:
+
+```powershell
+.venv\Scripts\python.exe -m unittest discover -s tests -v
+node --test tests/control_ui.test.cjs
+```
+
+Node is needed only for the frontend regression tests, not to run the app.
+The tests use mocked transport and synthetic pointer events, including independent
+joystick/vertical pointers. Validate physical multi-touch on the intended screen
+and FC failsafes on a restrained, propeller-free setup before powered operation.