# lane-progress

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

Projects a vessel position onto a shipping lane and reports how much of
the lane has been traversed, how much remains, and which waypoint is
nearest. Used by `estimateETA` to derive the remaining-distance figure
that feeds the ETA computation, and exposed publicly so downstream UIs
can render lane-progress bars without re-implementing the geometry.

## Features

- Finds the nearest waypoint by great-circle distance.
- Estimates fractional progress within the nearest waypoint's adjacent
  segment (prev or next, whichever is closer).
- Returns `{ progress, remainingDistanceNm, distanceTravelledNm,
  nearestWaypointIndex }` with `progress` clamped to `[0, 1]` and
  rounded to four decimals; distances clamped to `>= 0` and rounded to
  two decimals.
- Throws `PortsInsufficientWaypointsError` for lanes with fewer than
  two waypoints.
- Handles degenerate zero-length lanes (every waypoint identical) by
  returning zero progress.

## Usage: Basic

```ts
import { findPositionOnLane, getShippingLaneStrict } from "@suaveplan/ports";

const lane = getShippingLaneStrict("asia-europe-suez");
const progress = findPositionOnLane(
    { latitude: 12.5, longitude: 43.3 },
    lane
);
```

## Usage: Advanced

```ts
import { findPositionOnLane, type ShippingLane } from "@suaveplan/ports";

function eta(
    coord: { latitude: number; longitude: number },
    lane: ShippingLane,
    knots: number,
    departure: Date
): Date {
    const { remainingDistanceNm } = findPositionOnLane(coord, lane);
    const hours = remainingDistanceNm / knots;
    return new Date(departure.getTime() + hours * 3_600_000);
}
```

## API Reference

- `findPositionOnLane(coord, lane): LaneProgress`.

## Implementation Notes

The "nearest waypoint" pass is a linear scan. The adjacent-segment
projection uses a 1D ratio (distance-to-nearest / segment-length)
clamped to `[0, 1]`; this is an approximation that works well when the
coord is reasonably close to the lane and degrades gracefully when the
coord is far off-lane (the ETA `confidence` band downgrades to
`medium`/`low`). The function never throws on out-of-lane coords —
callers receive a clamped progress fraction and a non-negative
remaining distance regardless of how far off-lane the vessel is.