@glandais/vcyclist-engine 4.2.1 → 5.0.0

package/README.md

@@ -8,11 +8,10 @@
 [![Maven Central fit](https://img.shields.io/maven-central/v/io.github.glandais/vcyclist-fit?label=io.github.glandais%3Avcyclist-fit)](https://central.sonatype.com/artifact/io.github.glandais/vcyclist-fit)
 [![Maven Central map](https://img.shields.io/maven-central/v/io.github.glandais/vcyclist-map?label=io.github.glandais%3Avcyclist-map)](https://central.sonatype.com/artifact/io.github.glandais/vcyclist-map)
 
-Kotlin Multiplatform port of [`@glandais/virtual-cyclist`](https://github.com/glandais/virtual-cyclist):
-physics-based cycling simulator that turns a static GPS trace into a virtualized ride with
-realistic speeds, times and power estimates. Inspired by [gpx2web](https://github.com/glandais/gpx2web)
-(Java) for the physics model and the [`@glandais/elevation`](https://github.com/glandais/elevation)
-TypeScript library for elevation data.
+Kotlin Multiplatform physics-based cycling simulator: it turns a static GPS trace into a
+virtualized ride with realistic speeds, times and power estimates. Elevation data comes from
+Terrarium-encoded DEM tiles — mapterhorn by default — fetched and decoded by the `:elevation`
+module.
 
 ```
                         ┌──────────────┐
@@ -31,7 +30,8 @@ TypeScript library for elevation data.
             │  ├─ VirtualizeService (1 Hz physics)    │
             │  ├─ PointPerSecond (uniform sampling)   │
             │  ├─ W′bal (Critical Power annotation)   │
-            │  └─ PathSimplifier (Douglas-Peucker 3D) │
+            │  ├─ PathSimplifier (Douglas-Peucker 3D) │
+            │  └─ ElevationGain (D+/D− dead band)     │
             └──────────────────┬──────────────────────┘
                                ▼
                         ┌──────────────┐
@@ -40,358 +40,223 @@ TypeScript library for elevation data.
             (*) optional — needs an ElevationProvider
 ```
 
-## Modules
+## What it can do
 
-| Module | Purpose | Targets |
-|---|---|---|
-| **`:elevation`** | Terrarium tile fetch + DEM lookup + Haversine + Douglas-Peucker 3D + triangular smoother. See [`elevation/README.md`](elevation/README.md). | JVM, JS Node, JS browser, WASI |
-| **`:gpx`** | Path model (38 fields × `DoubleArray`), resamplers, Douglas-Peucker simplifier, elevation steps, GPX I/O. Published to Maven Central; **not** published to npm — its JS output ships inside `@glandais/vcyclist-engine`. | JVM, JS Node, JS browser, WASI |
-| **`:engine`** | Physics (4 resistive `PowerProvider`s + cyclist input + `MaxSpeedComputer` + `VirtualizeService`), `Enhancer` pipeline, JVM CLI, JS façades. Re-exports `:gpx` via `api`, so `io.github.glandais.engine.path.*` and `…engine.gpx.*` stay importable from `:engine`. Also the module that links the standalone `.wasm` — see [`docs/wasm-wasi-abi.md`](docs/wasm-wasi-abi.md). | JVM, JS Node, JS browser, WASI |
-| **`:fit`** | Garmin FIT encoding. `FitCourse` model, unit conversions and `FitEncoder` itself, all in commonMain over [`fit-kotlin-sdk`](https://github.com/glandais/fit-kotlin-sdk) — a multiplatform SDK generated from the FIT profile. One encoder, byte-identical output on every target, and no vendor SDK for consumers to install. | JVM, JS Node, JS browser, WASI |
-| **`:map`** | Static map rendering: Web Mercator projection, image framing, tile download + cache, PNG output (`java.awt` / `ImageIO`). **JVM-only.** No default tile source — see [`map/README.md`](map/README.md) for the usage-policy obligations. | JVM only |
-| **`:cli`** | Command-line tool (picocli). **JVM-only, not published as a library** — distributed as an executable jar. Replaces gpx2web's `gpxtools-cli`. | JVM only |
-| **`:codegen`** | Tiny build-time helper that regenerates `GeneratedPath.kt` + `PointFieldAccessors.kt` from `PointField` (run only when the field list changes). | JVM only |
+**In**: GPX tracks, routes (`<rte>`), segments and waypoints.
 
-### Running it without a JVM or a JavaScript host
+**Physics**: elevation correction from DEM tiles, curvature estimation or an optimal racing line,
+cornering and braking sharing one friction-ellipse budget, a configurable rider and bike, and a
+1 Hz time-stepping simulation that produces speed, time and power at every point.
 
-`:engine` also links a standalone **WASI module**, so the whole pipeline runs inside wasmtime,
-WasmEdge, wazero, or an embedding in Go, Rust, Python or the JVM — no JavaScript involved.
+**Out**: GPX, Garmin FIT courses, CSV, column-oriented JSON, static PNG maps — plus climb
+detection, a racing-line report and worst-case wind analysis.
 
-```bash
-./gradlew :engine:wasmModule       # -> engine/build/wasm/vcyclist-engine.wasm + .sha256
-```
-
-```python
-handle = exports["vcParseGpx"](store, len(gpx_bytes))       # after wiring three imports
-print(exports["vcPathTotalDistance"](store, handle), "m")
-```
-
-The host provides `read_input`, `write_output` and `fetch_tile` (the last one may simply answer
-"no tile"); everything else is numeric exports and integer handles.
-[`docs/wasm-wasi-abi.md`](docs/wasm-wasi-abi.md) is the full contract, and
-[`tools/wasi`](tools/wasi/README.md) is a working host that CI runs on every pull request.
+Four doors reach the same engine, and a capability is available from all of them unless noted:
 
-### Migrating from gpx2web
+| Capability | CLI | Kotlin / Java | JavaScript / TS | WASI |
+|---|---|---|---|---|
+| Run the pipeline | `enhance` | `Enhancer.enhanceCourseDefault` | `enhance` | `vcEnhance` |
+| Configure rider, bike, wind, power | `--cyclist-*`, `--bike-*`, `--wind-*` | `CoursePhysics(Course(…))` | `enhanceWithCourse` | `vcEnhanceWithCourse` |
+| Power models `constant` · `durability` · `critical-power` · `from_data` | `--cyclist-model` | `CyclistPowerSpec` | `power.type` | `power.type` |
+| Terrain pacing, power slew limit | `--cyclist-pacing`, `--cyclist-slew` | provider decorators | `power.pacing`, `power.maxSlewWPerS` | idem |
+| Road condition, dry or wet | `--road-condition` | `Cyclist.withRoadCondition` | `cyclist.roadCondition` | idem |
+| Pedal-strike clearance | `--bike-max-pedal-angle` | `Bike.maxPedalingLeanAngleDeg` | `bike.maxPedalingLeanAngleDeg` | idem |
+| Racing line + corridor mode | `--racing-line`, `--corridor` | `RacingLineOptions` | `racingLineEnabled` | idem |
+| DEM elevation correction | `--fix-elevation` | `ElevationProvider` | `fixElevation: true` | host serves tiles |
+| Climb detection | — | `ClimbDetector.detect` | `detectClimbs` | `vcDetectClimbsJson` |
+| Racing-line report | `--racing-line-report` | `RacingLine.analyze` | `analyzeRacingLine` | `vcAnalyzeRacingLineJson` |
+| Write GPX / CSV / JSON | `--gpx --csv --json` | `GpxWriter`, `CsvWriter`, `JsonWriter` | `writeGpx`, `pathToCsv`, `pathToJson` | `vcWriteGpx`, `vcPathToCsv/Json` |
+| Write FIT course | `--fit` | `Path.toFitBytes` | `pathToFit`, `pathsToFit` | `vcPathToFit`, `vcPathsToFit` |
+| Static map PNG | `export --map` | `MapFactoriesJvm` | — | — |
 
-vcyclist replaces the `gpx` and `gpxtools-cli` modules of
-[gpx2web](https://github.com/glandais/gpx2web).
-[`docs/gpx2web-coverage.md`](docs/gpx2web-coverage.md) has one row per Java class — ported,
-replaced, or not ported with the reason — plus the deliberate behavioural differences. For the
-command-line options specifically, see [`cli/README.md`](cli/README.md).
+Static maps are JVM-only by construction — `:map` draws on `java.awt`.
+[`docs/ledgers/surface-coverage.md`](docs/ledgers/surface-coverage.md) tracks this matrix as
+capabilities land, so that a feature cannot reach one door and quietly miss the others.
 
 ## Install
 
-### npm (Kotlin/JS consumers)
+### npm — browser, Node.js and Bun
 
 ```bash
-npm install @glandais/vcyclist-engine          # Kotlin/JS bundle
-npm install @glandais/vcyclist-elevation       # Kotlin/JS bundle
+npm install @glandais/vcyclist-engine          # physics, GPX, FIT, CSV/JSON, climbs, racing line
+npm install @glandais/vcyclist-elevation       # DEM lookups on their own
 ```
 
-### Gradle / Maven (JVM or KMP consumers)
+The engine bundle already carries the elevation façade; install the second package only if you
+want DEM lookups without the physics.
+
+### Gradle — JVM or Kotlin Multiplatform
 
 ```kotlin
-// Gradle Kotlin DSL
 dependencies {
-    implementation("io.github.glandais:vcyclist-engine:1.0.0")    // pulls -jvm / -js per target
-    implementation("io.github.glandais:vcyclist-elevation:1.0.0")
+    implementation("io.github.glandais:vcyclist-engine:4.2.1")     // pulls -jvm / -js per target
+    implementation("io.github.glandais:vcyclist-elevation:4.2.1")
 }
 ```
 
-Replace `1.0.0` by the latest version shown in the badges above. KMP consumers automatically
-get the platform-specific variant (`-jvm`, `-js`) for their target.
-`vcyclist-gpx` (the `Path` model + GPX I/O) comes in transitively via `vcyclist-engine`, and
-can also be depended on alone if you only need parsing and resampling.
+### Maven
 
-See [`docs/publishing.md`](docs/publishing.md) for the release process.
+```xml
+<dependency>
+  <groupId>io.github.glandais</groupId>
+  <artifactId>vcyclist-engine-jvm</artifactId>
+  <version>4.2.1</version>
+</dependency>
+```
 
-## Quick start
+The badges above are the source of truth for the current version. KMP consumers get the
+platform-specific variant automatically; from plain Maven, name the `-jvm` artifact yourself.
 
-### Run the CLI
+`vcyclist-gpx` (the `Path` model + GPX I/O) comes in transitively via `vcyclist-engine`, and can be
+depended on alone if you only need parsing and resampling. `vcyclist-fit` and `vcyclist-map` are
+published separately.
 
-The CLI is **not** on Maven Central — it is an application, distributed as a self-contained jar
-attached to each [GitHub release](https://github.com/glandais/vcyclist/releases). Download
-`vcyclist-cli-<version>-all.jar` and run it with Java 21+, or build it yourself:
+### CLI and `.wasm`
 
-```bash
-# Build a self-contained jar, then run it from anywhere:
-./gradlew :cli:executableJar
-java -jar cli/build/libs/vcyclist-cli-*-all.jar enhance route.gpx --gpx out.gpx --csv out.csv
+The CLI is an application, not a library, so it is **not** on Maven Central: download
+`vcyclist-cli-<version>-all.jar` from a [GitHub release](https://github.com/glandais/vcyclist/releases).
+The WASI module is built from source (below) rather than published to a registry.
 
-# Or, during development:
-./gradlew :cli:run -Pargs="enhance route.gpx --gpx /tmp/out.gpx"
-```
+**Requirements**: Java 21+ for the JVM and CLI; Node ≥ 18 (22+ recommended) or Bun for JavaScript;
+a WASI runtime with the `function-references`, `gc` and `exceptions` proposals — wasmtime 46+ is
+known good.
 
-`enhance` runs the physics pipeline; `export` produces maps, FIT, CSV and JSON from a file you
-already have. Elevation correction is off unless you pass `--fix-elevation`, so nothing touches
-the network by default. Full usage, exit codes and the migration table from gpx2web's
-`gpxtools-cli` are in [`cli/README.md`](cli/README.md).
+## Quick start
 
-### Try the browser demo (elevation only)
+### Command line
 
 ```bash
-# Kotlin/JS demo
-./gradlew :elevation:jsBrowserDevelopmentRun
+java -jar vcyclist-cli-*-all.jar enhance route.gpx --gpx out.gpx --csv out.csv
 ```
 
-The demo shares the [original TS demo](https://github.com/glandais/elevation) UI (Leaflet +
-Chart.js + GPX upload). See [`elevation/README.md`](elevation/README.md) for details.
+`enhance` runs the physics pipeline; `export` produces maps, FIT, CSV and JSON from a file you
+already have. Elevation correction is off unless you pass `--fix-elevation`, so nothing touches the
+network by default.
+
+Full option reference, the rider models and what each is measured to be worth, and exit codes:
+[`cli/README.md`](cli/README.md).
 
-### Use from Kotlin
+### Kotlin
 
 ```kotlin
 import io.github.glandais.engine.Enhancer
 import io.github.glandais.engine.gpx.GpxParser
+import io.github.glandais.engine.gpx.GpxWriter
 import io.github.glandais.engine.gpx.firstTrackAsPath
+import io.github.glandais.engine.gpx.toGpxDocument
 
 suspend fun virtualize(xml: String): String {
     val path = GpxParser.parse(xml).firstTrackAsPath()
-    val out = Enhancer.enhanceCourseDefault(path)  // pure physics, no HTTP
-    return io.github.glandais.engine.gpx.GpxWriter.write(
-        out.toGpxDocument(trackName = "virtualized")
-    )
+    val out = Enhancer.enhanceCourseDefault(path)   // pure physics, no HTTP
+    return GpxWriter.write(out.toGpxDocument(trackName = "virtualized"))
 }
 ```
 
-### Use from Java
+Pass an `ElevationProvider` as the second argument to correct elevations from DEM tiles, and an
+`EnhanceOptions` as the third to configure the pipeline. For a configured rider, build a
+`CoursePhysics(Course(path, cyclist, bike), …)` and call `Enhancer.enhanceCourse`.
 
-The library is Kotlin-first, so its asynchronous entry points — elevation lookups and the
-`Enhancer` pipeline that may call them — are `suspend` functions. From Java that would mean
-hand-writing a `Continuation`, so each of them has a JVM bridge in two shapes:
-
-| Shape | Suffix | Returns | For |
-|---|---|---|---|
-| Blocking | `…Blocking` | the value | batch jobs, CLIs, tests |
-| Asynchronous | `…Async` | `CompletableFuture<T>` | servers, UIs |
+### Java
 
 ```java
-import io.github.glandais.elevation.ElevationProvider;
-import io.github.glandais.elevation.ElevationProviderJvm;
-import io.github.glandais.engine.EnhancerJvm;
-import io.github.glandais.engine.gpx.GpxParserJvm;
-import io.github.glandais.engine.gpx.GpxToPathKt;
-import io.github.glandais.engine.gpx.GpxWriterJvm;
-import io.github.glandais.engine.path.Path;
-
-String xml = Files.readString(java.nio.file.Path.of("route.gpx"));
-Path input = GpxToPathKt.firstTrackAsPath(GpxParserJvm.parse(xml));
-
-// Physics only, nothing touches the network:
+Path input = GpxToPathJvm.firstTrackAsPath(GpxParserJvm.parse(xml));
 Path enhanced = EnhancerJvm.enhanceCourseDefaultBlocking(input);
-
-// Or with elevation correction, off the calling thread:
-ElevationProvider provider = ElevationProviderJvm.newElevationProvider();
-CompletableFuture<Path> future = EnhancerJvm.enhanceCourseDefaultAsync(input, provider);
-
 String out = GpxWriterJvm.write(enhanced);
 ```
 
-**Every entry point has a `…Jvm` twin**, in the same package as the Kotlin original:
-`GpxParserJvm`, `GpxWriterJvm`, `GpxFromPathJvm`, `GpxModelJvm`, `PathSimplifierJvm`,
-`ElevationStepJvm`, `TabularWritersJvm` (`:gpx`), `ElevationProviderJvm`, `TileFetcherJvm`
-(`:elevation`), `EnhancerJvm`, `EngineModelJvm`, `ClimbDetectorJvm` (`:engine`), `PathToFitJvm`
-(`:fit`), `MapFactoriesJvm` (`:map`). They exist for two reasons: Kotlin default arguments are
-invisible to Java, and `@JvmOverloads` cannot be used on the common source sets where the API
-lives. Call them and every optional parameter becomes optional again.
-
-- `…Blocking` parks the calling thread. **Never call it from a UI thread, from inside a
-  coroutine, or from a thread of the executor you passed** — the first two freeze the caller,
-  the third can deadlock the pool. Exceptions propagate unchanged.
-- `…Async` takes an optional `java.util.concurrent.Executor` (default: the coroutines IO
-  dispatcher, the right pool for network-bound work). Cancelling the returned future cancels the
-  work underneath; failures arrive as a `CompletionException`, so unwrap with `getCause()`.
-- Everything else in the library is already synchronous and needs no bridge: `GpxParser`,
-  `GpxWriter`, `ElevationStep.smoothElevation`, `PathSimplifier`, the resamplers, FIT and the
-  CSV / JSON writers.
-- `ElevationProviderJvm.newElevationProvider(config, fetcher)` takes a
-  `Function<String, RawTile>`, so a disk cache — or any other tile transport — plugs in from Java.
-  The fetcher may block (it runs on the IO dispatcher) but must be thread-safe: up to ten tiles
-  are fetched at once. See [`elevation/README.md`](elevation/README.md) for a complete example.
-
-### Use from JavaScript / TypeScript
-
-`generateTypeScriptDefinitions()` is enabled on `js(IR)`, so you get a `.d.ts` next to the
-bundle in `build/dist/js/productionExecutable/vcyclist-engine.d.{ts,mts}`.
-
-The Kotlin/JS variant (`@glandais/vcyclist-engine`, `@glandais/vcyclist-elevation`) runs
-**in both browser and Node.js / Bun**.
-
-#### Getting at the exports
-
-Kotlin/JS emits a **UMD bundle that preserves the package namespace**, so the module has
-exactly one top-level export, `io`. Named imports do not work — `import { parseGpx } from
-'@glandais/vcyclist-engine'` fails under Node ESM with *"Named export 'parseGpx' not found"*.
-Unwrap the namespace once and destructure from it :
-
-```js
-import * as engineRaw from '@glandais/vcyclist-engine';   // or: require('@glandais/vcyclist-engine')
-
-const engine = engineRaw.io.github.glandais.engine;
-```
+Every entry point has a `…Jvm` twin that restores Kotlin's default arguments, and every `suspend`
+function has both a `…Blocking` and a `…Async` (`CompletableFuture`) bridge.
+**[`docs/guides/using-from-java.md`](docs/guides/using-from-java.md)** has the calling rules — some
+of them matter, `…Blocking` on a UI thread being the obvious one.
 
-Every snippet below assumes that `engine`. `demo/src/engine-shim.ts` does the same unwrap and
-adds TypeScript types for the DTOs, which Kotlin/JS emits as referenced names only.
+### JavaScript / TypeScript
 
-#### Browser
+Kotlin/JS emits a UMD bundle that preserves the package namespace, so there is exactly one
+top-level export. Named imports do not work — unwrap it once:
 
 ```js
-const { parseGpx, enhance, writeGpx, pathSize, pathTotalDistance } = engine;
-
-const handle = parseGpx(gpxXml);
-console.log('input points:', pathSize(handle));
-const out = await enhance(handle, null);                    // physics only, no HTTP
-console.log('output:', pathSize(out), pathTotalDistance(out), 'm');
-const xml = writeGpx(out);
-```
-
-#### Node.js / Bun (with elevation correction)
-
-```js
-const { parseGpx, enhance, writeGpx } = engine;
-
-const handle = parseGpx(gpxXml);
-const out = await enhance(handle, { fixElevation: true });  // fetches DEM tiles, decodes WebP
-const xml = writeGpx(out);
-```
-
-`enhance(..., { fixElevation: true })` auto-instantiates a default `ElevationProvider`
-(mapterhorn Terrarium tiles) and runs the full pipeline (densify → fix elevation → smooth →
-max speeds → virtualize → resample → simplify).
+import * as engineRaw from '@glandais/vcyclist-engine';
+const engine = engineRaw.io.github.glandais.engine;
 
-#### FIT export
+const { parseGpx, enhance, writeGpx, pathSize, pathTotalDistance } = engine;
 
-```js
-const { parseGpx, enhance, pathToFit } = engine;
+const path = parseGpx(gpxXml);
+const out  = await enhance(path, null);          // physics only; { fixElevation: true } for DEM
+console.log(pathSize(out), pathTotalDistance(out), 'm');
 
-const out = await enhance(parseGpx(gpxXml), null);
-const fit = pathToFit(out, 'My route', Date.parse('2026-08-01T08:00:00Z'));
-// Kotlin/JS returns an Int8Array containing the FIT file.
+// `<power>` carries the SOURCE file's power by default — writing simulated data into a format the
+// ecosystem reads as a recording is the caller's call. Ask for the simulation explicitly:
+const xml  = writeGpx(out, true, 'computed-or-input', 'my route');
 ```
 
-FIT has no relative clock, so the start instant is mandatory. The output is a **Course** file
-(a route to follow), which is what a virtualized trace should be — not an Activity.
-
-#### Multi-track GPX
+**[`docs/guides/using-from-javascript.md`](docs/guides/using-from-javascript.md)** covers the whole
+façade — `enhanceWithCourse` and its five DTOs, FIT and CSV/JSON export, climbs, the racing-line
+report, the standalone elevation API, and the Node/Bun specifics.
 
-`parseGpx` returns the **first** track, which is what most files contain. For documents with
-several `<trk>` or several `<trkseg>` :
+### WASI — no JVM, no JavaScript
 
-```js
-const { parseGpxTracks, parseGpxSegments, writeGpxTracks } = engine;
+`:engine` links a standalone WASI module, so the whole pipeline runs inside wasmtime, WasmEdge,
+wazero, or an embedding in Go, Rust, Python or the JVM.
 
-const tracks = parseGpxTracks(gpxXml);       // one path per <trk> *and* per <rte>
-const segments = parseGpxSegments(gpxXml);   // one path per <trkseg>, always continuous
-const xml = writeGpxTracks(tracks);          // one <trk> per path
+```bash
+./gradlew :engine:wasmModule       # -> engine/build/wasm/vcyclist-engine.wasm + .sha256
 ```
 
-Concatenating segments folds the pause between them into `totalDistance` — a `<trkseg>`
-boundary is a physical discontinuity. Use `parseGpxSegments` when that artefact matters.
-
-`parseGpxTracks` also returns `<rte>` routes, which many planners emit and which used to be
-dropped silently. `parseGpxTracksOnly` and `parseGpxRoutesOnly` select one container or the other.
+The host implements three imports — `read_input`, `write_output` and `fetch_tile` (which may simply
+answer "no tile") — and everything else is numeric exports over integer handles:
 
-#### Options on the writers
+```python
+staged["bytes"] = open("ride.gpx", "rb").read()
+handle = exports["vcParseGpx"](store, len(staged["bytes"]))
 
-```js
-const bare = engine.writeGpx(path, false);   // no <extensions>: no power, heart rate, cadence
-const fit = engine.pathsToFit([a, b], 'Two days', Date.parse('2026-08-01T08:00:00Z'));
+staged["bytes"] = b'{"computeOnePointPerSecond": true}'
+out = exports["vcEnhance"](store, handle, len(staged["bytes"]))
+print(exports["vcPathDurationMs"](store, out) / 1000, "s")
 ```
 
-`writeGpx`, `writeGpxAt` and `writeGpxTracks` take a trailing `writeExtensions` flag (default
-`true`). `pathsToFit` encodes several paths into one FIT course — a lap and a timer event pair
-each — where `pathToFit` takes a single one.
+This is not a reduced surface: `vcEnhanceWithCourse`, `vcPathToFit`, `vcPathToCsv`,
+`vcDetectClimbsJson` and `vcAnalyzeRacingLineJson` are all there, and §10 of the guide is a
+function-by-function parity table against the JavaScript façade.
+**[`docs/guides/wasm-wasi-abi.md`](docs/guides/wasm-wasi-abi.md)** is the full contract;
+[`tools/wasi`](tools/wasi/README.md) is a working host that CI runs on every pull request.
 
-On Node.js / Bun, tile decoding uses [`@jsquash/webp`](https://www.npmjs.com/package/@jsquash/webp)
-(a pure-WASM WebP decoder, ~50 KB, listed as a runtime `dependency` of
-`@glandais/vcyclist-engine` and `@glandais/vcyclist-elevation`). It is loaded lazily via
-`eval('require')`, so browser bundlers do not pull it into the browser build. Requires
-Node ≥ 18 (`globalThis.fetch` is built-in since Node 18 / Bun) ; Node 22+ recommended for
-ESM `require()` support.
+## Try the demo
 
-## Try the interactive demo
+**<https://glandais.github.io/vcyclist>** — no install, runs the real engine in your browser.
 
-The [`demo/`](demo/) module is a Vue 3 + Vite frontend that exercises the
-Kotlin/JS engine end-to-end in a browser (GPX upload, configurable cyclist /
-bike / wind / power, chart + map, hover sync).
+A Vue 3 + Leaflet + Chart.js app with two routes, both on the same Kotlin/JS bundle:
 
-```bash
-./gradlew :demo:assemble
-python -m http.server -d demo/dist 8000  # or any static file server
-```
-
-See [`demo/README.md`](demo/README.md) for the dev workflow and architecture.
-
-## Build & test
+- `#/` — **GPX analysis**: upload a route, run the physics pipeline, inspect every field on a
+  synchronized chart and map, with climb detection and the racing line, then download the result
+  as GPX or as a Garmin FIT course.
+- `#/elevation` — **elevation explorer**: query DEM tiles at a point or along a path, with
+  smoothing, Douglas-Peucker simplification and hillshade/slope relief.
 
 ```bash
-./gradlew check                         # full build + all tests on all targets
-./gradlew :engine:allTests              # engine tests across JVM / JS Node / JS browser
-./gradlew :elevation:allTests           # elevation tests
-./gradlew :elevation:jvmTest --tests '*Integration*' \
-          -PINTEGRATION=1               # live HTTP tests against tiles.mapterhorn.com
-./gradlew ktlintCheck                   # lint
-```
-
-## Layout
-
+cd demo && npm run dev        # http://localhost:3000, against a locally built engine
 ```
-vcyclist/
-├── settings.gradle.kts          # multi-module Gradle KMP project
-├── gradle/libs.versions.toml    # version catalog (Kotlin 2.3.21, coroutines 1.11, xmlutil 0.91, …)
-├── docs/
-│   ├── PLAN.md                  # task-by-task progress (Phases 1-2bis)
-│   ├── elevation-integration.md # how to run live HTTP integration tests
-│   ├── kotlin-js-jvm-webp.md    # Kotlin/JS ↔ JS interop guide
-│   └── tasks/                   # one Markdown per implementation task (00-31, + bonus demos)
-├── elevation/                   # :elevation KMP module
-├── engine/                      # :engine KMP module (depends on :elevation)
-└── codegen/                     # :codegen JVM helper for Path accessor generation
-```
-
-## Status
 
-- ✅ **Phase 1** — `:elevation` module port (tasks 00-09) : Terrarium tiles, Haversine, ECEF,
-  Douglas-Peucker 3D, smoother, LRU cache + TileManager, `ElevationProvider`, live HTTP integration.
-- ✅ **Phase 2** — `:engine` module port (tasks 10-28) : Path model, Cyclist/Bike/Course,
-  GPX I/O, full physics, simulation, post-processing, `Enhancer`, CLI, `@JsExport` façades.
-- ✅ **Phase 2bis** — pipeline fidelity fixes (tasks 29-31) : `VirtualizeService` last-point
-  timestamp, `PointPerDistance` port, integration into `Enhancer`.
-- ✅ **Phase 3** — Node.js / Bun support (tasks 32-33) : runtime-detection in
-  `TileFetcher.js.kt` (browser path unchanged, Node path uses `globalThis.fetch` +
-  `@jsquash/webp` WASM decoder loaded via lazy `eval('require')`), webpack externals to keep
-  the browser bundle free of `@jsquash/webp`, `ElevationProvider` auto-instantiation in
-  `EngineJsApi.enhance` when `opts.fixElevation` is true (JS façade), 6 jsTest classes
-  gated by `INTEGRATION=1`.
-
-Total `:engine` test coverage : 32 test classes / ~326 commonTest cases / 3 targets =
-~1000 green executions, plus JVM-only smoke tests for the CLI and the full pipeline.
-
-End-to-end smoke (after Phase 2bis) : sample.gpx (3569 source points, 130 km, ~4550 m gain)
-runs through the complete `Enhancer` pipeline in ~1.7 s on JVM, producing ~1000 simplified
-output points covering ~128.6 km / ~5.3 h of simulated ride.
+See [`demo/README.md`](demo/README.md) for the architecture and the static-site build.
 
 ## Documentation
 
-- [`docs/PLAN.md`](docs/PLAN.md) — task-by-task plan with commit hashes for every step.
-- [`docs/tasks/`](docs/tasks/) — detailed Markdown spec for each task (00-31 + bonus demos).
-- [`docs/kotlin-js-jvm-webp.md`](docs/kotlin-js-jvm-webp.md) — Kotlin/JS ↔ JS interop
-  guide that underpins the `@JsExport` façades and the WebP tile decoding.
-- [`docs/publishing.md`](docs/publishing.md) — release flow (Maven Central + npm via
-  semantic-release on push to `develop`).
-- [`elevation/README.md`](elevation/README.md) — `:elevation` module details + browser demos.
+[`docs/README.md`](docs/README.md) is the index and says which documents are current and which are
+frozen history. The short version:
+
+- [`docs/guides/`](docs/README.md#guides) — how to use and extend the project: Java, JavaScript, the
+  WASI ABI, the racing line, the release flow
+- [`docs/ledgers/`](docs/README.md#ledgers) — living state: research improvements, build warnings,
+  surface coverage
+- [`docs/research/`](docs/research/README.md) — the solo-rider simulation research report
+- Module documentation lives next to its module: [`cli/`](cli/README.md),
+  [`elevation/`](elevation/README.md), [`map/`](map/README.md), [`demo/`](demo/README.md)
 
 ## Contributing
 
-`develop` is the **default and only long-lived branch** — there is no `main`. Open PRs
-against `develop` using [Conventional Commits](https://www.conventionalcommits.org/) :
-`feat:` triggers a minor release, `fix:` a patch, anything else is a no-op release-wise.
-Every push to `develop` runs the full multi-target test suite via
-`.github/workflows/release.yml` and, if green, lets semantic-release tag a new version,
-publish to Maven Central + npm, and commit the version bump back to `develop` with
-`[skip ci]`. See [`docs/publishing.md`](docs/publishing.md) for the full flow.
+Open PRs against `develop` — the default and only long-lived branch — using
+[Conventional Commits](https://www.conventionalcommits.org/). Build commands, module layout,
+testing conventions and the release flow are in [`CONTRIBUTING.md`](CONTRIBUTING.md).
 
 ## License
 
-Apache License 2.0, aligned with the upstream `gpx2web` project. See the Maven Central POM
-metadata in `engine/build.gradle.kts` and `elevation/build.gradle.kts`. A top-level `LICENSE`
-file will be added before the first public release.
+[Apache License 2.0](LICENSE).

package/index.cjs

@@ -0,0 +1,70 @@
+// GENERATED by `./gradlew :codegen:generateTsFacade` — do not edit.
+//
+// The CommonJS half of the same unwrapping. Both spellings ship because the bundle is UMD
+// and Node resolves a bare `.js` as CommonJS — an ESM-only wrapper breaks `require()`.
+const root = require('./vcyclist-engine.js');
+
+const ns = root.io?.github?.glandais?.engine ?? root;
+
+const climbDefaults = Object.freeze({
+    minMinClimbElevationM: 10,
+    maxMinClimbElevationM: 35,
+    minClimbElevationRatio: 100,
+    minGradePercent: 3,
+    maxDiffRealGrade: 1.3,
+    booster: 1.3,
+    maxAnalysisPoints: 3000,
+});
+
+const csvDefaults = Object.freeze({
+    separator: ',',
+    unitsInHeader: true,
+    decimals: null,
+    lineSeparator: '\n',
+});
+
+const jsonDefaults = Object.freeze({
+    pretty: false,
+    decimals: null,
+    includeMeta: true,
+});
+
+module.exports = {
+    parseGpxWaypoints: ns.parseGpxWaypoints,
+    parseGpx: ns.parseGpx,
+    parseGpxTracks: ns.parseGpxTracks,
+    parseGpxSegments: ns.parseGpxSegments,
+    parseGpxTracksOnly: ns.parseGpxTracksOnly,
+    parseGpxRoutesOnly: ns.parseGpxRoutesOnly,
+    writeGpxTracks: ns.writeGpxTracks,
+    pathSize: ns.pathSize,
+    pathTotalDistance: ns.pathTotalDistance,
+    pathDurationMs: ns.pathDurationMs,
+    pathElevationGain: ns.pathElevationGain,
+    pathElevationLoss: ns.pathElevationLoss,
+    pathElevationGainFiltered: ns.pathElevationGainFiltered,
+    pathElevationLossFiltered: ns.pathElevationLossFiltered,
+    pathReportedElevationGain: ns.pathReportedElevationGain,
+    pathReportedElevationLoss: ns.pathReportedElevationLoss,
+    pointAt: ns.pointAt,
+    writeGpx: ns.writeGpx,
+    writeGpxAt: ns.writeGpxAt,
+    enhance: ns.enhance,
+    enhanceWithCourse: ns.enhanceWithCourse,
+    getField: ns.getField,
+    fieldDefinitions: ns.fieldDefinitions,
+    pathLatitudeDeg: ns.pathLatitudeDeg,
+    pathLongitudeDeg: ns.pathLongitudeDeg,
+    pathToCsv: ns.pathToCsv,
+    pathToJson: ns.pathToJson,
+    pathToFit: ns.pathToFit,
+    pathsToFit: ns.pathsToFit,
+    dominantHeadwindAzimuth: ns.dominantHeadwindAzimuth,
+    dominantHeadwindAzimuthOfTracks: ns.dominantHeadwindAzimuthOfTracks,
+    detectClimbs: ns.detectClimbs,
+    detectClimbsWithOptions: ns.detectClimbsWithOptions,
+    analyzeRacingLine: ns.analyzeRacingLine,
+    climbDefaults,
+    csvDefaults,
+    jsonDefaults,
+};