@glandais/vcyclist-engine 1.2.1 → 3.0.0

package/README.md

@@ -3,6 +3,10 @@
 [![npm engine](https://img.shields.io/npm/v/@glandais/vcyclist-engine?label=%40glandais%2Fvcyclist-engine)](https://www.npmjs.com/package/@glandais/vcyclist-engine)
 [![npm elevation](https://img.shields.io/npm/v/@glandais/vcyclist-elevation?label=%40glandais%2Fvcyclist-elevation)](https://www.npmjs.com/package/@glandais/vcyclist-elevation)
 [![Maven Central](https://img.shields.io/maven-central/v/io.github.glandais/vcyclist-engine?label=io.github.glandais%3Avcyclist-engine)](https://central.sonatype.com/artifact/io.github.glandais/vcyclist-engine)
+[![Maven Central elevation](https://img.shields.io/maven-central/v/io.github.glandais/vcyclist-elevation?label=io.github.glandais%3Avcyclist-elevation)](https://central.sonatype.com/artifact/io.github.glandais/vcyclist-elevation)
+[![Maven Central gpx](https://img.shields.io/maven-central/v/io.github.glandais/vcyclist-gpx?label=io.github.glandais%3Avcyclist-gpx)](https://central.sonatype.com/artifact/io.github.glandais/vcyclist-gpx)
+[![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
@@ -37,19 +41,29 @@ TypeScript library for elevation data.
 
 | 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, Wasm browser |
-| **`:engine`** | Path model (36 fields × `DoubleArray`), physics (4 resistive `PowerProvider`s + cyclist input + `MaxSpeedComputer` + `VirtualizeService`), GPX I/O, `Enhancer` pipeline, JVM CLI. | JVM, JS Node, JS browser, Wasm browser |
+| **`:elevation`** | Terrarium tile fetch + DEM lookup + Haversine + Douglas-Peucker 3D + triangular smoother. See [`elevation/README.md`](elevation/README.md). | JVM, JS Node, JS browser |
+| **`:gpx`** | Path model (36 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 |
+| **`: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`. | JVM, JS Node, JS browser |
+| **`:fit`** | Garmin FIT encoding. `FitCourse` model + unit conversions in commonMain; `expect object FitEncoder` with a JVM `actual` on `com.garmin:fit` and a JS `actual` on `@garmin/fitsdk`. | JVM, JS Node, JS browser |
+| **`: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 |
 
+### Migrating from gpx2web
+
+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).
+
 ## Install
 
-### npm (Kotlin/JS or Kotlin/Wasm consumers)
+### npm (Kotlin/JS consumers)
 
 ```bash
 npm install @glandais/vcyclist-engine          # Kotlin/JS bundle
-npm install @glandais/vcyclist-engine-wasm     # Kotlin/Wasm bundle
 npm install @glandais/vcyclist-elevation       # Kotlin/JS bundle
-npm install @glandais/vcyclist-elevation-wasm  # Kotlin/Wasm bundle
 ```
 
 ### Gradle / Maven (JVM or KMP consumers)
@@ -57,38 +71,48 @@ npm install @glandais/vcyclist-elevation-wasm  # Kotlin/Wasm bundle
 ```kotlin
 // Gradle Kotlin DSL
 dependencies {
-    implementation("io.github.glandais:vcyclist-engine:1.0.0")    // pulls -jvm / -js / -wasm-js per target
+    implementation("io.github.glandais:vcyclist-engine:1.0.0")    // pulls -jvm / -js per target
     implementation("io.github.glandais:vcyclist-elevation:1.0.0")
 }
 ```
 
 Replace `1.0.0` by the latest version shown in the badges above. KMP consumers automatically
-get the platform-specific variant (`-jvm`, `-js`, `-wasm-js`) for their target.
+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.
 
 See [`docs/publishing.md`](docs/publishing.md) for the release process.
 
 ## Quick start
 
-### Run the JVM CLI
+### Run the CLI
+
+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:
 
 ```bash
-# Enhance a GPX file with the default cyclist (80 kg / 280 W) and bike (Crr 0.004) :
-./gradlew :engine:run -Pargs="enhance path/to/input.gpx -o /tmp/output.gpx"
+# 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
+
+# Or, during development:
+./gradlew :cli:run -Pargs="enhance route.gpx --gpx /tmp/out.gpx"
 ```
 
-The CLI runs the full enhancement pipeline (no elevation correction — no HTTP) and writes the
-simulated trace back to a GPX file. See [`engine/src/jvmMain/.../EngineCli.kt`](engine/src/jvmMain/kotlin/io/github/glandais/engine/EngineCli.kt).
+`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).
 
-### Try the browser demos (elevation only)
+### Try the browser demo (elevation only)
 
 ```bash
-# Kotlin/Wasm demo
-./gradlew :elevation:wasmJsBrowserDevelopmentRun
-# Kotlin/JS demo (sibling, same UI)
+# Kotlin/JS demo
 ./gradlew :elevation:jsBrowserDevelopmentRun
 ```
 
-Both demos share the [original TS demo](https://github.com/glandais/elevation) UI (Leaflet +
+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.
 
 ### Use from Kotlin
@@ -107,18 +131,89 @@ suspend fun virtualize(xml: String): String {
 }
 ```
 
+### Use from Java
+
+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
+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 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 both `js(IR)` and `wasmJs`, so you get a
-`.d.ts` next to the bundle in `build/dist/{js,wasmJs}/productionExecutable/vcyclist-engine.d.{ts,mts}`.
+`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**. The Wasm variants (`*-wasm`) are browser-only.
+**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 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.
 
 #### Browser
 
 ```js
-import { parseGpx, enhance, writeGpx, pathSize, pathTotalDistance } from '@glandais/vcyclist-engine';
+const { parseGpx, enhance, writeGpx, pathSize, pathTotalDistance } = engine;
 
 const handle = parseGpx(gpxXml);
 console.log('input points:', pathSize(handle));
@@ -130,7 +225,7 @@ const xml = writeGpx(out);
 #### Node.js / Bun (with elevation correction)
 
 ```js
-import { parseGpx, enhance, writeGpx } from '@glandais/vcyclist-engine';
+const { parseGpx, enhance, writeGpx } = engine;
 
 const handle = parseGpx(gpxXml);
 const out = await enhance(handle, { fixElevation: true });  // fetches DEM tiles, decodes WebP
@@ -141,6 +236,49 @@ const xml = writeGpx(out);
 (mapterhorn Terrarium tiles) and runs the full pipeline (densify → fix elevation → smooth →
 max speeds → virtualize → resample → simplify).
 
+#### FIT export
+
+```js
+const { parseGpx, enhance, pathToFit } = engine;
+
+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.
+```
+
+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
+
+`parseGpx` returns the **first** track, which is what most files contain. For documents with
+several `<trk>` or several `<trkseg>` :
+
+```js
+const { parseGpxTracks, parseGpxSegments, writeGpxTracks } = engine;
+
+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
+```
+
+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.
+
+#### Options on the writers
+
+```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'));
+```
+
+`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.
+
 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
@@ -165,7 +303,7 @@ See [`demo/README.md`](demo/README.md) for the dev workflow and architecture.
 
 ```bash
 ./gradlew check                         # full build + all tests on all targets
-./gradlew :engine:allTests              # engine tests across JVM / JS Node / JS browser / Wasm browser
+./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
@@ -182,7 +320,7 @@ vcyclist/
 │   ├── PLAN.md                  # task-by-task progress (Phases 1-2bis)
 │   ├── parity.md                # parity strategy vs the TS reference
 │   ├── elevation-integration.md # how to run live HTTP integration tests
-│   ├── kotlin-wasm-jvm-webp.md  # Kotlin/Wasm ↔ JS interop guide
+│   ├── 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)
@@ -201,11 +339,11 @@ vcyclist/
   `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 + Wasm façades), 6 jsTest classes
+  `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 / 4 targets =
-~1300 green executions, plus JVM-only smoke tests for the CLI and the full pipeline.
+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
@@ -216,7 +354,7 @@ output points covering ~128.6 km / ~5.3 h of simulated ride.
 - [`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/parity.md`](docs/parity.md) — TS↔Kotlin parity approach and tolerances.
-- [`docs/kotlin-wasm-jvm-webp.md`](docs/kotlin-wasm-jvm-webp.md) — Kotlin/Wasm ↔ JS interop
+- [`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`).