@glandais/vcyclist-engine 4.3.0 → 5.0.0

package/index.d.ts

@@ -0,0 +1,725 @@
+// GENERATED by `./gradlew :codegen:generateTsFacade` — do not edit.
+// Mirrors src/jsMain/kotlin/io/github/glandais/engine/EngineJsApi.kt.
+
+/**
+ * An opaque Kotlin/JS `Path` instance. It is a real JS object, but it is not
+ * `@JsExport`ed and has no TypeScript surface — reach into it through the
+ * accessor functions below, never by property.
+ *
+ * Branded rather than `object` or `any` so two handle kinds cannot be swapped,
+ * and so a typo dereferencing one is a compile error.
+ */
+declare const PathBrand: unique symbol;
+export type Path = { readonly [PathBrand]: 'Path' };
+
+/** The spellings every door parses, derived from the `CorridorMode` catalogue in `commonMain`. */
+export type CorridorMode =
+    | 'lane'
+    | 'lane-left'
+    | 'full-road';
+
+/** The spellings every door parses, derived from the `ElevationGainPreset` catalogue in `commonMain`. */
+export type ElevationGainPreset =
+    | 'raw'
+    | 'barometric'
+    | 'dem'
+    | 'gps';
+
+/** The spellings every door parses, derived from the `RoadCondition` catalogue in `commonMain`. */
+export type RoadCondition =
+    | 'dry'
+    | 'wet';
+
+/** The spellings every door parses, derived from the `PowerModel` catalogue in `commonMain`. */
+export type PowerModel =
+    | 'constant'
+    | 'durability'
+    | 'critical-power'
+    | 'from_data';
+
+/** The spellings every door parses, derived from the `PointField` catalogue in `commonMain`. */
+export type PointFieldProp =
+    | 'latitude'
+    | 'longitude'
+    | 'distance'
+    | 'dx'
+    | 'time'
+    | 'elapsed'
+    | 'dt'
+    | 'bearing'
+    | 'elevation'
+    | 'grade'
+    | 'radius'
+    | 'aeroCoef'
+    | 'windBearing'
+    | 'windAlpha'
+    | 'pAero'
+    | 'pGravity'
+    | 'pRollingResistance'
+    | 'pWheelBearings'
+    | 'pInputPower'
+    | 'pCyclistProvidedOptimalPower'
+    | 'pCyclistProvidedOptimalPowerWithHarmonics'
+    | 'pCyclistPowerNeeded'
+    | 'pCyclistProvidedMuscular'
+    | 'pCyclistProvidedWheel'
+    | 'pComputedTotalPower'
+    | 'pComputedWheelPower'
+    | 'pComputedPower'
+    | 'speed'
+    | 'speedMax'
+    | 'speedMaxIncline'
+    | 'virtSpeedCurrent'
+    | 'temperature'
+    | 'windSpeed'
+    | 'windDirection'
+    | 'heartRate'
+    | 'cadence'
+    | 'wPrimeBalance'
+    | 'pBrake'
+    | 'trajectoryCurvature'
+    | 'roadWidth'
+    | 'lateralOffset'
+    | 'sourceLatitude'
+    | 'sourceLongitude'
+    | 'sourceElevation';
+
+/** The spellings every door parses, derived from the `CornerKind` catalogue in `commonMain`. */
+export type CornerKind =
+    | 'GENTLE'
+    | 'CORNER'
+    | 'HAIRPIN';
+
+/** The spellings every door parses, derived from the `GpxPowerSource` catalogue in `commonMain`. */
+export type GpxPowerSource =
+    | 'input'
+    | 'computed'
+    | 'computed-or-input';
+
+/**
+ * JS-facing snapshot of a single path point. Read-only ; built lazily by `pointAt`. Field units
+ * are degrees, meters, m/s, watts, epoch ms, slope ratio.
+ */
+export interface PointDto {
+    readonly latitudeDeg: number;
+    readonly longitudeDeg: number;
+    readonly elevation: number;
+    readonly timeMs: number;
+    readonly speed: number;
+    readonly pComputedPower: number;
+    readonly distance: number;
+    readonly grade: number;
+}
+
+/**
+ * JS-facing snapshot of a `<wpt>` waypoint (see `GpxWaypoint`).
+ * Flat DTO ; built by `parseGpxWaypoints`. `timeEpochMs` is `null` when `<time>` is absent, same
+ * as the Kotlin model.
+ */
+export interface WaypointDto {
+    readonly latitudeDeg: number;
+    readonly longitudeDeg: number;
+    readonly elevationM?: number | null;
+    readonly name?: string | null;
+    readonly description?: string | null;
+    readonly symbol?: string | null;
+    readonly type?: string | null;
+    readonly timeEpochMs?: number | null;
+}
+
+/**
+ * JS-side mirror of `EnhanceOptions` / `SimplifyPathOptions`. Every flag is optional ; when a
+ * caller leaves a field `undefined`, `defaultJsOptions` picks the JS-safe default (skip elevation
+ * fetch, skip 1 Hz resample, skip simplify — see task 27 for the timestamp pitfall).
+ */
+export interface EnhanceOptionsDto {
+    readonly fixElevation?: boolean | null;
+    readonly computeMaxSpeeds?: boolean | null;
+    readonly virtualizeTrack?: boolean | null;
+    readonly computeOnePointPerSecond?: boolean | null;
+    readonly simplifyEnabled?: boolean | null;
+    readonly simplifyToleranceM?: number | null;
+    readonly simplifyZExaggeration?: number | null;
+    /**
+     * W′ balance annotation pass (ledger R15). Defaults to `true`, which is what JS callers have
+     * been getting all along — `WPrimeBalanceOptions` is enabled by default and nothing here ever
+     * overrode it, so the `wPrimeBalance` field was already being written, at CP 250 W / W′ 20 kJ.
+     * These three fields make it *calibrable*, they do not turn it on.
+     */
+    readonly wPrimeBalanceEnabled?: boolean | null;
+    /**
+     * CP (W) for the W′ balance **field**.
+     *
+     * This is **not** automatically `criticalPower`. The two are independent by
+     * design (see `WPrimeBalanceOptions` for why CP/W′ live on the options rather than on
+     * `Cyclist`), so passing different values here and on the power provider yields a W′bal trace
+     * that does not describe the rider being simulated. Legitimate — reporting one rider's effort
+     * against another's physiology — but rarely intended.
+     */
+    readonly wPrimeBalanceCriticalPower?: number | null;
+    /**
+     * W′ (J) for the W′ balance field. Same independence caveat as `wPrimeBalanceCriticalPower`.
+     */
+    readonly wPrimeBalanceWPrime?: number | null;
+    /**
+     * Curvature estimation. Defaults to on — it corrects `radius` and `speedMax`, so turning it
+     * off restores the historical windowed estimate rather than saving work worth saving.
+     */
+    readonly curvatureEnabled?: boolean | null;
+    /**
+     * Optimal-trajectory ("racing line") stage. Off by default: enabling it **moves every
+     * coordinate** of the result. The original positions are preserved in `sourceLatitude` /
+     * `sourceLongitude`.
+     */
+    readonly racingLineEnabled?: boolean | null;
+    /**
+     * `"lane"` (default), `"lane-left"`, or `"full-road"` — closed roads and time trials only.
+     */
+    readonly racingLineCorridor?: CorridorMode | null;
+    /**
+     * Road width assumed where the GPX supplies none, in metres.
+     */
+    readonly racingLineRoadWidthM?: number | null;
+    /**
+     * Scale the reported climbing is measured at: `"raw"`, `"barometric"`, `"dem"`, `"gps"`.
+     * See `docs/guides/elevation.md`.
+     */
+    readonly elevationGainPreset?: ElevationGainPreset | null;
+    /**
+     * Override the preset's hysteresis dead band, in metres. `0` disables it.
+     */
+    readonly elevationGainThresholdM?: number | null;
+    /**
+     * Whether to measure the dead-banded climbing at all. Defaults to `true`.
+     */
+    readonly elevationGainEnabled?: boolean | null;
+    /**
+     * Triangular-kernel half-width for the elevation smoother, in metres.
+     *
+     * The single largest determinant of both the reported climbing and the gradients the
+     * simulation rides — it costs a clean route ~1.5 % and a noisy GPS trace ~48 %.
+     */
+    readonly elevationSmoothWindowM?: number | null;
+    /**
+     * Web-Mercator zoom for the DEM lookup, `0..15`, used only when `fixElevation` is on.
+     *
+     * Not part of `EnhanceOptions` — it configures the provider, not the pipeline — so it is read
+     * where the provider is built rather than in `toEnhanceOptions`.
+     */
+    readonly demZoom?: number | null;
+}
+
+/**
+ * JS-side mirror of `Cyclist`. All fields required when the DTO is passed (Kotlin/JS does not
+ * gracefully tolerate optional fields on `external interface` without `?`). Callers can pass
+ * `null` for the whole DTO to fall back to engine defaults (80 kg / 0.7 Cd / 0.5 m² / 35° / 100
+ * km/h / 0.4 g brake).
+ *
+ * Passing a key this interface does not declare is an **error** since task 43 — see
+ * `requireOnlyKeys`.
+ */
+export interface CyclistDto {
+    readonly massKg: number;
+    readonly cd: number;
+    readonly frontalAreaM2: number;
+    readonly maxLeanAngleDeg: number;
+    readonly maxBrakeG: number;
+    readonly maxSpeedKmH: number;
+    /**
+     * Road surface preset (ledger R9) : `"dry"` (the default) or `"wet"`, case-insensitive. Sets
+     * cornering grip and braking together — wet cuts cornering speed by 1.58× and braking to
+     * 0.23 g. Any other value throws.
+     *
+     * **The preset wins over `maxLeanAngleDeg` and `maxBrakeG` when present**, which is the
+     * opposite of the CLI, where an explicit `--cyclist-max-angle` overrides `--road-condition`.
+     * The CLI can tell "not given" from "given" because its fields are nullable ; here they are
+     * not, so a JS caller always supplies all six and "explicit wins" would make the preset
+     * unreachable. Omit `roadCondition` to keep the raw values — that is the pre-R9 behaviour, and
+     * `"dry"` reproduces the shipped defaults bit-for-bit anyway.
+     */
+    readonly roadCondition?: RoadCondition | null;
+}
+
+/**
+ * JS-side mirror of `Bike`. Pass `null` to use defaults (Crr 0.004, road-bike inertias,
+ * 0.7 m wheel radius, 0.95 drivetrain efficiency).
+ */
+export interface BikeDto {
+    readonly crr: number;
+    readonly inertiaFront: number;
+    readonly inertiaRear: number;
+    readonly wheelRadiusM: number;
+    readonly efficiency: number;
+    /**
+     * Lean angle (°) past which the rider stops pedalling; `90` disables the cut-off.
+     */
+    readonly maxPedalingLeanAngleDeg?: number | null;
+}
+
+/**
+ * JS-side mirror of constant-wind input. `windDirection` is in **degrees**, `0` = north,
+ * `90` = east — `toWindProvider` converts to the radians the engine uses internally.
+ *
+ * The angle names the direction the wind blows **toward**, not the meteorological "from" it was
+ * long documented as. Task g31 established this by simulation; see
+ * `PathWind.dominantHeadwindAzimuthDeg`, whose output goes into this field unchanged.
+ */
+export interface WindDto {
+    readonly windSpeed: number;
+    readonly windDirection: number;
+}
+
+/**
+ * JS-side description of which `CyclistPowerProvider` to instantiate.
+ *
+ * `type` takes any `PowerModel` wire name — `"constant"`, `"durability"`, `"critical-power"` or
+ * `"from_data"` — and the catalog is the single source of that list, so a model added to the
+ * engine is reachable here without editing this file.
+ *
+ * `pacing` and `maxSlewWPerS` are **decorators**, not types : they compose over whichever `type`
+ * was chosen, in the order `toProvider` defines.
+ */
+export interface PowerProviderDto {
+    readonly type: PowerModel;
+    readonly power?: number | null;
+    readonly useHarmonics?: boolean | null;
+    /**
+     * CP (W) for `"durability"` and `"critical-power"`. Defaults to 250 W.
+     */
+    readonly criticalPower?: number | null;
+    /**
+     * W′ (J) for `"critical-power"` — the reserve spendable above CP. Defaults to 20 kJ.
+     */
+    readonly wPrime?: number | null;
+    /**
+     * Terrain pacing (ledger R19) : harder uphill and into headwind, easier downhill, with a causal
+     * energy account so the effort is redistributed rather than added. Off by default.
+     *
+     * A heuristic with **no lookahead** — the rider reacts to the road it is on. Its magnitudes
+     * (gradient gain, the ~300 m ramp, the energy-budget window) are the project's own rather than
+     * sourced, so they are not exposed here ; use `PowerProviderTerrainPacing` directly from Kotlin
+     * to change them.
+     */
+    readonly pacing?: boolean | null;
+    /**
+     * Power slew-rate limit (ledger R18) in W/s ; `0` or omitted disables it. 50 is the value
+     * Zignoli & Biral use. Same semantics as the CLI's `--cyclist-slew`.
+     *
+     * Applied **outermost**, so it smooths whatever `type` and `pacing` produced.
+     */
+    readonly maxSlewWPerS?: number | null;
+}
+
+/**
+ * Catalog entry for a `PointField`. Exposed to JS
+ * via `fieldDefinitions` so consumers can render generic field-pickers without hard-coding
+ * the 43-entry list.
+ */
+export interface FieldDefinitionDto {
+    readonly prop: PointFieldProp;
+    readonly unit: string;
+    readonly shortDescription: string;
+    readonly categoryId: string;
+    readonly categoryName: string;
+    readonly notSelectable: boolean;
+    readonly anglesInRadians: boolean;
+}
+
+/**
+ * A homogeneous-grade segment of a climb. Distances are absolute along the path, in meters;
+ * `grade` is dimensionless (`0.08` = 8 %), matching `averageGrade`.
+ */
+export interface ClimbPartDto {
+    readonly startDistanceM: number;
+    readonly endDistanceM: number;
+    readonly startElevationM: number;
+    readonly endElevationM: number;
+    readonly lengthM: number;
+    readonly elevationGainM: number;
+    readonly grade: number;
+}
+
+/**
+ * A detected climb, flattened for the JS boundary.
+ */
+export interface ClimbDto {
+    readonly startIndex: number;
+    readonly endIndex: number;
+    readonly startDistanceM: number;
+    readonly endDistanceM: number;
+    readonly startElevationM: number;
+    readonly endElevationM: number;
+    readonly lengthM: number;
+    readonly elevationGainM: number;
+    /**
+     * Dimensionless: `0.08` = 8 %.
+     */
+    readonly averageGrade: number;
+    /**
+     * Dimensionless, counting only the rising sections.
+     */
+    readonly climbingGrade: number;
+    readonly positiveElevationM: number;
+    readonly negativeElevationM: number;
+    readonly parts: ClimbPartDto[];
+}
+
+/**
+ * One detected bend, as the racing-line analysis sees it.
+ *
+ * @see analyzeRacingLine
+ */
+export interface CornerDto {
+    readonly fromIndex: number;
+    readonly untilIndex: number;
+    readonly apexIndex: number;
+    /**
+     * `"GENTLE"`, `"CORNER"` or `"HAIRPIN"`.
+     */
+    readonly kind: CornerKind;
+    readonly turnRad: number;
+    /**
+     * `+1` turning left, `-1` turning right.
+     */
+    readonly direction: number;
+    /**
+     * 20th percentile of `1/|κ|` over the span — robust to the clothoid ends a mean is biased by.
+     */
+    readonly radiusQ20M: number;
+    readonly radiusMinM: number;
+    readonly lengthM: number;
+}
+
+/**
+ * What the racing-line stage decided, without applying it.
+ *
+ * Every array has one entry per path station. `corridorLo`/`corridorHi` bound the lateral offset in
+ * metres, positive to the left; `lateralOffsetM` is the line that was solved for inside them.
+ */
+export interface RacingLineReportDto {
+    readonly size: number;
+    readonly corners: CornerDto[];
+    /**
+     * Curvature of the road itself, m⁻¹, positive turning left.
+     */
+    readonly centerlineCurvature: Float64Array;
+    /**
+     * Curvature of the solved line, same convention.
+     */
+    readonly trajectoryCurvature: Float64Array;
+    readonly corridorLo: Float64Array;
+    readonly corridorHi: Float64Array;
+    readonly roadHalfWidthM: Float64Array;
+    readonly lateralOffsetM: Float64Array;
+    /**
+     * Widest the corridor gets anywhere, `hi − lo`, in metres.
+     */
+    readonly maxCorridorWidthM: number;
+    readonly newtonIterations: number;
+    /**
+     * Final residual relative to the initial gradient — scale-free, so comparable across routes.
+     */
+    readonly relativeGradient: number;
+    readonly converged: boolean;
+    readonly activeConstraints: number;
+}
+
+/**
+ * Parse `xml` and return every `<wpt>` in document order, as flat `WaypointDto` objects.
+ */
+export declare function parseGpxWaypoints(xml: string): WaypointDto[];
+
+export declare function parseGpx(xml: string): Path;
+
+/**
+ * Parse `xml` and return **one Path per `<trk>`**, in document order. Tracks with no point are
+ * skipped. Segments of a same track are concatenated — distance jumps across a segment
+ * boundary ; use `parseGpxSegments` if that artefact matters.
+ *
+ * **Since task g24 this includes `<rte>` routes**, which used to be dropped silently. Use
+ * `parseGpxTracksOnly` for the pre-g24 selection.
+ */
+export declare function parseGpxTracks(xml: string): Path[];
+
+/**
+ * Parse `xml` and return **one Path per `<trkseg>`**, across all tracks, in document order.
+ * Empty segments are skipped. Every returned Path is continuous.
+ */
+export declare function parseGpxSegments(xml: string): Path[];
+
+/**
+ * Like `parseGpxTracks` but **`<trk>` only** — routes are left out (task g29).
+ *
+ * `GpxPathKind` is deliberately not exported: an enum crosses to JavaScript as an object nobody
+ * wants to import just to filter a list. Two named functions say the same thing at the call site.
+ */
+export declare function parseGpxTracksOnly(xml: string): Path[];
+
+/**
+ * Like `parseGpxTracks` but **`<rte>` only** — recorded tracks are left out (task g29).
+ */
+export declare function parseGpxRoutesOnly(xml: string): Path[];
+
+/**
+ * Serialise `paths` as a multi-track GPX document — one `<trk>` per Path. `waypoints`, if given,
+ * is written as `<wpt>` entries before the tracks (typically the source document's
+ * `waypoints`, forwarded so a parse → enhance → write
+ * round-trip does not silently drop points of interest — see g03).
+ *
+ * `trackNames` names the tracks positionally; a shorter list — or `null` — leaves the remaining
+ * tracks unnamed, which is `pathsToGpxDocument`'s own contract and **not** the
+ * `DEFAULT_TRACK_NAME` that `writeGpx` applies to its single track. Extra names are ignored.
+ *
+ * `startTimeEpochMs` is what `writeGpxAt` does, applied to every track at once: `<time>` =
+ * `startTimeEpochMs + time(i)`. `null` (the default) writes the times as they stand. It is a
+ * `Double` for the reason `writeGpxAt` gives.
+ *
+ * Both arrived late — the WASI door had accepted `trackName` and `startTimeEpochMs` since w09 and
+ * this façade had no way to say either, so a multi-track export was the one GPX a JS caller could
+ * not date or name.
+ */
+export declare function writeGpxTracks(paths: Path[], waypoints?: WaypointDto[], writeExtensions?: boolean, powerSource?: GpxPowerSource | null, trackNames?: string[] | null, startTimeEpochMs?: number | null): string;
+
+export declare function pathSize(path: Path): number;
+
+export declare function pathTotalDistance(path: Path): number;
+
+export declare function pathDurationMs(path: Path): number;
+
+export declare function pathElevationGain(path: Path): number;
+
+export declare function pathElevationLoss(path: Path): number;
+
+/**
+ * Cumulative ascent with the dead band applied, or `NaN` if the stage did not run.
+ *
+ * `NaN` rather than `null` so the export stays a plain `Double` on the JS side; use
+ * `pathReportedElevationGain` to get the raw sum as a fallback instead.
+ */
+export declare function pathElevationGainFiltered(path: Path): number;
+
+/**
+ * Counterpart of `pathElevationGainFiltered`. NEGATIVE by convention, or `NaN`.
+ */
+export declare function pathElevationLossFiltered(path: Path): number;
+
+/**
+ * The figure to show a human: dead-banded when measured, the raw sum otherwise.
+ */
+export declare function pathReportedElevationGain(path: Path): number;
+
+/**
+ * Counterpart of `pathReportedElevationGain`. NEGATIVE by convention.
+ */
+export declare function pathReportedElevationLoss(path: Path): number;
+
+export declare function pointAt(path: Path, i: number): PointDto;
+
+/**
+ * Serialise `path` as a single-track GPX.
+ *
+ * `writeExtensions` `false` drops `<extensions>` — no power, heart rate, cadence or temperature,
+ * and no `gpxtpx` namespace (task g23). `<ele>` and `<time>` are standard GPX and stay. Useful in
+ * a browser for a download meant for a platform with a strict schema.
+ *
+ * `powerSource` selects which of the path's two power fields lands in `<power>`: `"input"`,
+ * `"computed"` or `"computed-or-input"` — the CLI's `--gpx-power-source` values, parsed through
+ * the one catalogue in `GpxPowerSource`. `null` keeps the default, which writes the *input*
+ * power: emitting simulated data into a format the ecosystem reads as a recording is the caller's
+ * decision, not a default's.
+ *
+ * `trackName` names the `<trk><name>`; `null` keeps `"virtualized"`.
+ */
+export declare function writeGpx(path: Path, writeExtensions?: boolean, powerSource?: GpxPowerSource | null, trackName?: string | null): string;
+
+/**
+ * Serialise `path` with an absolute `<time>` on every point : `<time> = startTimeEpochMs +
+ * time(i)` milliseconds (see `startTime` / task g05).
+ *
+ * `startTimeEpochMs` is a `Double`, not a `Long` : on Kotlin/JS `Long` crosses the boundary as a
+ * `BigInt`, which is awkward for callers building it from `Date.now()` or `new Date(...).getTime()`
+ * (both already `number`/`Double`). Epoch milliseconds fit exactly in a `Double` until the year
+ * 287396 — the same reasoning already used by `pathDurationMs`.
+ */
+export declare function writeGpxAt(path: Path, startTimeEpochMs: number, writeExtensions?: boolean, powerSource?: GpxPowerSource | null, trackName?: string | null): string;
+
+export declare function enhance(path: Path, options: EnhanceOptionsDto | null): Promise<Path>;
+
+/**
+ * Enhance `path` using a fully custom `CoursePhysics` (cyclist + bike + wind + power provider).
+ *
+ * Any DTO parameter may be `null` ; defaults are picked from the engine
+ * (see `CyclistDto`, `BikeDto`, `WindDto`, `PowerProviderDto` KDoc for specifics).
+ *
+ * Like `enhance`, when `options.fixElevation == true` a default `ElevationProvider` is
+ * auto-instantiated (Terrarium tiles via HTTP).
+ */
+export declare function enhanceWithCourse(path: Path, cyclist: CyclistDto | null, bike: BikeDto | null, wind: WindDto | null, power: PowerProviderDto | null, options: EnhanceOptionsDto | null): Promise<Path>;
+
+/**
+ * Read field `fieldProp` (camelCase, e.g. `"elevation"` / `"speed"`) at point `i`. Throws if
+ * the field name is unknown.
+ */
+export declare function getField(path: Path, i: number, fieldProp: PointFieldProp): number;
+
+/**
+ * Enumerate the 43-entry `PointField` catalog as JS-friendly `FieldDefinitionDto` objects.
+ * UIs use this to render generic field-pickers without hard-coding the list.
+ */
+export declare function fieldDefinitions(): FieldDefinitionDto[];
+
+/**
+ * Latitude of point `i` in degrees (convenience wrapper around `latitudeDeg`).
+ */
+export declare function pathLatitudeDeg(path: Path, i: number): number;
+
+/**
+ * Longitude of point `i` in degrees (convenience wrapper around `longitudeDeg`).
+ */
+export declare function pathLongitudeDeg(path: Path, i: number): number;
+
+/**
+ * Serialise `path` to CSV (all 36 `PointField`s, one row per point) — see `CsvWriter` / task g06.
+ * Lets a browser demo offer an "Export CSV" button without a server round-trip : the caller
+ * wraps the returned `String` in a `Blob` and triggers a download via
+ * `URL.createObjectURL`.
+ *
+ * `separator` takes only its first character (JS has no `Char` type at the interop boundary) ;
+ * an empty string falls back to `,`.
+ *
+ * `decimals` and `lineSeparator` arrived in S4 of the surface-alignment work. The WASI door had
+ * accepted `decimals` since w09 while this signature had three parameters, so the same core writer
+ * was configurable from one wire door and not the other. `null` on either keeps the `CsvOptions`
+ * default rather than a literal restated here.
+ */
+export declare function pathToCsv(path: Path, separator: string, unitsInHeader: boolean, decimals?: number | null, lineSeparator?: string | null): string;
+
+/**
+ * Serialise `path` to JSON, column-oriented (one array per `PointField`) — see `JsonWriter` /
+ * task g07. Lets a browser demo hand the result straight to `JSON.parse` and feed a chart
+ * library (e.g. Chart.js) without a server round-trip.
+ *
+ * `decimals` rounds every value; `includeMeta` drops the `size` / `fields` preamble when `false`.
+ * Both were reachable from the WASI door and not from here until S4 — `null` keeps the
+ * `JsonOptions` default, which is where the default lives.
+ */
+export declare function pathToJson(path: Path, pretty: boolean, decimals?: number | null, includeMeta?: boolean | null): string;
+
+/**
+ * Encode `path` as a Garmin FIT Course file.
+ *
+ * @param startTimeEpochMs absolute start instant in Unix epoch milliseconds. FIT has no relative
+ *   clock, so this is mandatory — `Double` rather than `Long` to avoid a BigInt at the JS
+ *   boundary, matching the convention `pathDurationMs` and `writeGpxAt` already use.
+ * @return the complete FIT file. On Kotlin/JS a `ByteArray` surfaces as a JS `Int8Array`.
+ */
+export declare function pathToFit(path: Path, name: string, startTimeEpochMs: number): Int8Array;
+
+/**
+ * Encode **several** paths into one FIT course — one lap and one `TIMER`/`START`…`STOP` event
+ * pair per path (task g25, exported here by g29).
+ *
+ * A separate function rather than a parameter on `pathToFit`: the shape of the first argument
+ * changes, and Kotlin/JS has no overloading to lean on.
+ *
+ * `interPathGapMs` shifts each path after the first by that many milliseconds; `0` (the default)
+ * runs them straight on from one another. It is **not** a pause — FIT expresses those with
+ * `TIMER`/`PAUSE` events, which this port does not emit.
+ */
+export declare function pathsToFit(paths: Path[], name: string, startTimeEpochMs: number, interPathGapMs?: number): Int8Array;
+
+/**
+ * Azimuth in degrees of the constant wind that makes `path` hardest on average — the opposite of
+ * the course's dominant orientation (task g26, exported by g31).
+ *
+ * The value goes **straight into** a `WindDto.directionDeg` or `Wind(speedMS, directionRad)`: no
+ * 180° flip, no unit conversion beyond degrees → radians. The engine's angle convention is not the
+ * meteorological one it claims to be, which is why this is exposed as a ready-to-use number rather
+ * than as a vector the caller would have to interpret.
+ *
+ * This function says nothing about wind **speed** — only about the direction that hurts most.
+ *
+ * @return `NaN` when the question has no answer: fewer than 4 points, or a course whose mean
+ *   direction cancels out (a perfectly symmetric loop). `0` is a valid answer, so check with
+ *   `Number.isNaN`.
+ */
+export declare function dominantHeadwindAzimuth(path: Path): number;
+
+/**
+ * Multi-path form of `dominantHeadwindAzimuth` — the tracks of one file weigh equally.
+ */
+export declare function dominantHeadwindAzimuthOfTracks(paths: Path[]): number;
+
+/**
+ * Detect climbs on `path` with the default options — see `ClimbOptions`.
+ */
+export declare function detectClimbs(path: Path): ClimbDto[];
+
+/**
+ * Detect climbs with explicit parameters. Flat scalars rather than an options DTO to keep the
+ * JS boundary simple.
+ */
+export declare function detectClimbsWithOptions(path: Path, minMinClimbElevationM: number, maxMinClimbElevationM: number, minClimbElevationRatio: number, minGradePercent: number, maxDiffRealGrade: number, booster: number, maxAnalysisPoints?: number | null): ClimbDto[];
+
+/**
+ * Analyse what the racing line *would* do to `path`, without touching it.
+ *
+ * Read-only by construction — it takes a `Path` and returns numbers, so asking the question can
+ * never move a coordinate. That is the point: the stage rewrites every position it is applied to,
+ * and being able to inspect the corridor it assumed and the offset it chose is what makes that
+ * inspectable rather than merely optional.
+ *
+ * Returns `null` for a path too short or too degenerate to analyse, matching the Kotlin API's
+ * contract of declining rather than guessing.
+ *
+ * The `options` are the same `racingLine*` keys `enhance` accepts; `enabled` is ignored here, since
+ * calling this *is* the request.
+ */
+export declare function analyzeRacingLine(path: Path, options?: EnhanceOptionsDto | null): RacingLineReportDto | null;
+
+/**
+ * The engine's own defaults for `detectClimbsWithOptions`, read off `ClimbOptions`.
+ *
+ * `detectClimbsWithOptions` takes its options **positionally**, so changing the last one means
+ * naming all the others and there is no field to omit. These are those values, generated
+ * from the same catalogue the CLI and WASI doors resolve their defaults through — never
+ * transcribed. Spread it and override what you need.
+ */
+export declare const climbDefaults: {
+    readonly minMinClimbElevationM: number;
+    readonly maxMinClimbElevationM: number;
+    readonly minClimbElevationRatio: number;
+    readonly minGradePercent: number;
+    readonly maxDiffRealGrade: number;
+    readonly booster: number;
+    readonly maxAnalysisPoints: number;
+};
+
+/**
+ * The engine's own defaults for `pathToCsv`, read off `CsvOptions`.
+ *
+ * `pathToCsv` takes its options **positionally**, so changing the last one means
+ * naming all the others and there is no field to omit. These are those values, generated
+ * from the same catalogue the CLI and WASI doors resolve their defaults through — never
+ * transcribed. Spread it and override what you need.
+ */
+export declare const csvDefaults: {
+    readonly separator: ',';
+    readonly unitsInHeader: boolean;
+    readonly decimals: null;
+    readonly lineSeparator: '\n';
+};
+
+/**
+ * The engine's own defaults for `pathToJson`, read off `JsonOptions`.
+ *
+ * `pathToJson` takes its options **positionally**, so changing the last one means
+ * naming all the others and there is no field to omit. These are those values, generated
+ * from the same catalogue the CLI and WASI doors resolve their defaults through — never
+ * transcribed. Spread it and override what you need.
+ */
+export declare const jsonDefaults: {
+    readonly pretty: boolean;
+    readonly decimals: null;
+    readonly includeMeta: boolean;
+};