@glandais/vcyclist-engine 2.0.0 → 3.1.0

package/README.md

@@ -3,6 +3,7 @@
 [![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)
@@ -40,14 +41,33 @@ 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 |
-| **`: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, Wasm browser |
-| **`:engine`** | Physics (4 resistive `PowerProvider`s + cyclist input + `MaxSpeedComputer` + `VirtualizeService`), `Enhancer` pipeline, JVM CLI, JS/Wasm 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, Wasm browser |
-| **`:fit`** | Garmin FIT encoding. `FitCourse` model + unit conversions in commonMain; `expect object FitEncoder` with a JVM `actual` on `com.garmin:fit` and JS/Wasm `actual`s on `@garmin/fitsdk`. | 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, WASI |
+| **`: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, 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 |
 
+### Running it without a JVM or a JavaScript host
+
+`: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.
+
+```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.
+
 ### Migrating from gpx2web
 
 vcyclist replaces the `gpx` and `gpxtools-cli` modules of
@@ -58,13 +78,11 @@ 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)
@@ -72,13 +90,13 @@ 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.
 
@@ -106,16 +124,14 @@ already have. Elevation correction is off unless you pass `--fix-elevation`, so
 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
@@ -134,13 +150,68 @@ 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
 
@@ -191,7 +262,7 @@ 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; the -wasm build returns a Uint8Array. Both are the same file.
+// 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
@@ -205,7 +276,7 @@ several `<trk>` or several `<trkseg>` :
 ```js
 const { parseGpxTracks, parseGpxSegments, writeGpxTracks } = engine;
 
-const tracks = parseGpxTracks(gpxXml);       // one path per <trk>, segments concatenated
+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
 ```
@@ -213,6 +284,20 @@ 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
@@ -237,7 +322,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
@@ -254,7 +339,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)
@@ -273,11 +358,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
@@ -288,7 +373,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`).