Add JSBSim service backend

service/README.md

@@ -0,0 +1,98 @@
+# Local Flight Simulation Service
+
+Offline mock service for the first milestone.
+
+## Run
+
+```powershell
+npm run service
+```
+
+The default URL is:
+
+```text
+http://127.0.0.1:4317
+```
+
+## Endpoints
+
+- `GET /health`
+- `GET /aircraft`
+- `POST /trim`
+- `POST /simulate`
+- `POST /cancel`
+
+## Coordinate and Heading Conventions
+
+- Local position is `[east, up, north]` in meters.
+- True heading `0 deg` points north.
+- Clockwise heading is positive.
+- Counter-clockwise heading is negative.
+
+## Rates
+
+- `sampleRateHz` controls the output sample frequency returned to the web client.
+- `integrationRateHz` controls the internal JSBSim integration frequency and defaults to `120`.
+- The web client currently requests `sampleRateHz: 30` and `integrationRateHz: 120`.
+- `trim: false` skips pre-simulation trim. This is useful for F-22 maneuver research because the bundled F-22 model can run from initial conditions even when longitudinal trim fails.
+
+The mock service currently supports:
+
+- `straight`
+- `climb`
+- `descent`
+- `level-turn`
+- `control-script`
+- `cobra`
+
+## Maneuver Research Path
+
+This project treats special maneuvers as reusable control-input studies:
+
+1. Use `control-script` for raw elevator/aileron/rudder/throttle timelines.
+2. Build named maneuver templates, such as `cobra`, on top of those timelines.
+3. Compare mock output against the JSBSim backend.
+4. Improve or replace aircraft XML models when high-alpha/post-stall data is not credible.
+
+`control-script` parameters:
+
+```json
+{
+  "timeline": [
+    { "t": 0.0, "elevator": 0, "aileron": 0, "rudder": 0, "throttle": 0.85 },
+    { "t": 0.5, "elevator": 0.8, "aileron": 0, "rudder": 0, "throttle": 1.0 },
+    { "t": 1.6, "elevator": 0, "aileron": 0, "rudder": 0, "throttle": 1.0 }
+  ]
+}
+```
+
+`cobra` is currently an experimental template. It is useful for plumbing and visualization, but physical credibility depends on the selected JSBSim aircraft model having high-alpha and post-stall aerodynamic tables.
+
+The default F-22 research path uses `f22cobra-jsbsim`, a project-local copy of the bundled F-22 model with manual TVC command support. The current stable near-cobra baseline uses the closed-loop Cobra controller:
+
+```json
+{
+  "aircraftId": "f22cobra-jsbsim",
+  "durationSec": 5,
+  "initialState": { "position": [0, 3000, 0], "velocityMps": 120, "headingDeg": 0 },
+  "trim": false,
+  "maneuver": {
+    "type": "cobra",
+    "parameters": {
+      "controlMode": "closed-loop",
+      "pullDurationSec": 0.7,
+      "recoveryDurationSec": 2.0,
+      "targetAlphaDeg": 80,
+      "pitchRateLimitDegS": 80,
+      "maxElevatorCmd": -0.45,
+      "recoveryElevatorCmd": 0.65,
+      "pullTvcCmd": -0.05,
+      "recoveryTvcCmd": 0.85,
+      "throttleCmd": 1,
+      "speedbrakeCmd": 0
+    }
+  }
+}
+```
+
+This baseline reaches roughly 70-72 degrees alpha in the current model, keeps peak pitch rate around 120-125 deg/s, and recovers to low alpha by the end of the run. Higher-alpha open-loop settings can still be tested with `"controlMode": "open-loop"`, but they tend to deep-stall or over-rotate with the current F-22 aerodynamic tables.