@math.gl/geospatial 5.0.0-alpha.9 → 5.0.0-beta.1

package/src/geoarrow/types.ts

@@ -0,0 +1,259 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {SpatialReference} from '../crs/index';
+import type {TypedArray} from '@math.gl/core';
+/** Minimal tagged geometry shape used only by compatibility builders.
+ *
+ * The physical GeoArrow APIs never create these values. Keeping the structural type here avoids
+ * making the descriptor package depend on the WKB format package.
+ */
+export type GeoArrowGeometryValue =
+  | {type: 'Point'; coordinates: readonly number[]}
+  | {type: 'LineString'; coordinates: readonly (readonly number[])[]}
+  | {type: 'Polygon'; coordinates: readonly (readonly (readonly number[])[])[]}
+  | {type: 'MultiPoint'; coordinates: readonly (readonly number[])[]}
+  | {type: 'MultiLineString'; coordinates: readonly (readonly (readonly number[])[])[]}
+  | {type: 'MultiPolygon'; coordinates: readonly (readonly (readonly (readonly number[])[])[])[]}
+  | {type: 'GeometryCollection'; geometries: readonly GeoArrowGeometryValue[]};
+
+/** GeoArrow concrete, mixed, bounding-box, and serialized encodings. */
+export type GeoArrowEncoding =
+  | 'geoarrow.point'
+  | 'geoarrow.linestring'
+  | 'geoarrow.polygon'
+  | 'geoarrow.multipoint'
+  | 'geoarrow.multilinestring'
+  | 'geoarrow.multipolygon'
+  | 'geoarrow.geometry'
+  | 'geoarrow.geometrycollection'
+  | 'geoarrow.box'
+  | 'geoarrow.wkb'
+  | 'geoarrow.wkt';
+
+/** Semantic coordinate dimensions. M is never interpreted as Z. */
+export type GeoArrowDimension = 'xy' | 'xyz' | 'xym' | 'xyzm';
+
+/** Physical coordinate organization for native geometries. */
+export type GeoArrowCoordinateLayout = 'interleaved' | 'separated';
+
+/** Supported list-offset buffers. */
+export type GeoArrowOffsets = Int32Array | BigInt64Array;
+
+/** Numeric physical storage accepted by GeoArrow descriptors. */
+export type GeoArrowNumericArray = TypedArray | BigInt64Array | BigUint64Array;
+
+/** Borrowed validity bitmap. Set bits are valid rows. */
+export type GeoArrowValidity = Readonly<{
+  values: Uint8Array;
+  /** Bit position corresponding to logical row zero. */
+  bitOffset?: number;
+}>;
+
+/** Properties shared by all physical arrays. */
+export type GeoArrowArrayBase = Readonly<{
+  /** Number of logical values represented by this array. */
+  length: number;
+  /** Optional borrowed validity bitmap for this nesting level. */
+  validity?: GeoArrowValidity;
+}>;
+
+/** Primitive scalar storage, optionally strided within a typed array. */
+export type GeoArrowPrimitive = GeoArrowArrayBase &
+  Readonly<{
+    kind: 'primitive';
+    values: GeoArrowNumericArray;
+    /** Scalar offset of logical value zero. */
+    offset?: number;
+    /** Scalars between consecutive logical values. Defaults to one. */
+    stride?: number;
+  }>;
+
+/** Fixed-size list storage, used for interleaved coordinate tuples. */
+export type GeoArrowFixedSizeList = GeoArrowArrayBase &
+  Readonly<{
+    kind: 'fixed-size-list';
+    size: number;
+    child: GeoArrowArray;
+    /** Logical list offset into the child. */
+    offset?: number;
+  }>;
+
+/** Variable-size list storage. */
+export type GeoArrowList = GeoArrowArrayBase &
+  Readonly<{
+    kind: 'list';
+    offsets: GeoArrowOffsets;
+    /** Index of logical row zero in `offsets`. */
+    offset?: number;
+    /** Value subtracted from offsets before indexing the supplied child view. */
+    offsetBase?: number | bigint;
+    child: GeoArrowArray;
+  }>;
+
+/** Named separated children, used for separated coordinates and boxes. */
+export type GeoArrowStruct = GeoArrowArrayBase &
+  Readonly<{
+    kind: 'struct';
+    children: Readonly<Record<string, GeoArrowArray>>;
+    /** Logical struct offset applied to every child. */
+    offset?: number;
+  }>;
+
+/** Struct storage used by `geoarrow.box` minimum/maximum ordinate columns. */
+export type GeoArrowBox = GeoArrowStruct;
+
+/** One dense-union child and its stable type ID. */
+export type GeoArrowDenseUnionChild = Readonly<{
+  name: string;
+  typeId: number;
+  /** Child-specific physical encoding (required for mixed-dimensional unions). */
+  encoding?: GeoArrowEncoding;
+  /** Child-specific semantic dimension. Falls back to the column dimension for legacy data. */
+  dimension?: GeoArrowDimension;
+  /** Child-specific coordinate layout. Falls back to the column layout for legacy data. */
+  coordinateLayout?: GeoArrowCoordinateLayout | null;
+  data: GeoArrowArray;
+}>;
+
+/** Dense-union storage for mixed geometry families. */
+export type GeoArrowDenseUnion = GeoArrowArrayBase &
+  Readonly<{
+    kind: 'dense-union';
+    typeIds: Int8Array | Uint8Array;
+    valueOffsets: Int32Array;
+    children: readonly GeoArrowDenseUnionChild[];
+    /** Logical row offset into typeIds and valueOffsets. */
+    offset?: number;
+  }>;
+
+/** Variable-width binary or UTF-8 storage for WKB and WKT. */
+export type GeoArrowSerialized = GeoArrowArrayBase &
+  Readonly<{
+    kind: 'serialized';
+    encoding: 'binary' | 'utf8';
+    offsets: GeoArrowOffsets;
+    values: Uint8Array;
+    /** Optional Arrow BinaryView-style records (four uint32 words per row). */
+    views?: Uint32Array;
+    /** Borrowed out-of-line buffers referenced by BinaryView records. */
+    dataBuffers?: readonly Uint8Array[];
+    /** Index of logical row zero in `offsets`. */
+    offset?: number;
+    /** Value subtracted from offsets before indexing `values`. */
+    offsetBase?: number | bigint;
+  }>;
+
+/** Arrow-compatible physical array tree without Arrow runtime classes. */
+export type GeoArrowArray =
+  | GeoArrowPrimitive
+  | GeoArrowFixedSizeList
+  | GeoArrowList
+  | GeoArrowStruct
+  | GeoArrowDenseUnion
+  | GeoArrowSerialized;
+
+/** One logical GeoArrow geometry column backed by borrowed chunks. */
+export type GeoArrowColumn = Readonly<{
+  encoding: GeoArrowEncoding;
+  dimension: GeoArrowDimension;
+  coordinateLayout: GeoArrowCoordinateLayout | null;
+  chunks: readonly GeoArrowArray[];
+  spatialReference?: SpatialReference | null;
+  edges?: 'planar' | 'spherical';
+  metadata?: Readonly<Record<string, unknown>>;
+}>;
+
+/** Coordinate callback used by mapping kernels. */
+export type GeoArrowCoordinateMapper = (
+  coordinate: readonly number[],
+  rowIndex: number
+) => readonly number[];
+
+/** Four-value XY bounds. */
+export type GeoArrowBounds = readonly [number, number, number, number];
+
+/** Returns the number of coordinate components for a semantic dimension. */
+export function getGeoArrowDimensionSize(dimension: GeoArrowDimension): 2 | 3 | 4 {
+  switch (dimension) {
+    case 'xy':
+      return 2;
+    case 'xyz':
+    case 'xym':
+      return 3;
+    case 'xyzm':
+      return 4;
+  }
+}
+
+/** Combines semantic dimensions without confusing a measure ordinate with elevation. */
+export function mergeGeoArrowDimensions(
+  left: GeoArrowDimension,
+  right: GeoArrowDimension
+): GeoArrowDimension {
+  const hasZ = left === 'xyz' || left === 'xyzm' || right === 'xyz' || right === 'xyzm';
+  const hasM = left === 'xym' || left === 'xyzm' || right === 'xym' || right === 'xyzm';
+  return hasZ && hasM ? 'xyzm' : hasZ ? 'xyz' : hasM ? 'xym' : 'xy';
+}
+
+/**
+ * Infers the dimensions present in coordinate arrays of a tagged geometry value.
+ * Three ordinates are interpreted as XYZ; callers with XYM data should supply that semantic
+ * dimension explicitly instead of inferring it from tuple length.
+ */
+export function inferGeoArrowGeometryDimension(geometry: GeoArrowGeometryValue): GeoArrowDimension {
+  if (geometry.type === 'GeometryCollection') {
+    return geometry.geometries.reduce(
+      (dimension, child) =>
+        mergeGeoArrowDimensions(dimension, inferGeoArrowGeometryDimension(child)),
+      'xy' as GeoArrowDimension
+    );
+  }
+  return inferCoordinateDimensions(geometry.coordinates);
+}
+
+/** Infers the combined dimensions of nested coordinate tuples. */
+function inferCoordinateDimensions(coordinates: readonly unknown[]): GeoArrowDimension {
+  if (typeof coordinates[0] === 'number') {
+    return coordinates.length >= 4 ? 'xyzm' : coordinates.length === 3 ? 'xyz' : 'xy';
+  }
+  let dimension: GeoArrowDimension = 'xy';
+  for (const child of coordinates) {
+    if (Array.isArray(child)) {
+      dimension = mergeGeoArrowDimensions(dimension, inferCoordinateDimensions(child));
+    }
+  }
+  return dimension;
+}
+
+/** Returns the concrete geometry family associated with an encoding. */
+export function getGeoArrowGeometryType(
+  encoding: GeoArrowEncoding
+): Exclude<GeoArrowGeometryValue['type'], 'GeometryCollection'> | 'GeometryCollection' | null {
+  switch (encoding) {
+    case 'geoarrow.point':
+      return 'Point';
+    case 'geoarrow.linestring':
+      return 'LineString';
+    case 'geoarrow.polygon':
+      return 'Polygon';
+    case 'geoarrow.multipoint':
+      return 'MultiPoint';
+    case 'geoarrow.multilinestring':
+      return 'MultiLineString';
+    case 'geoarrow.multipolygon':
+      return 'MultiPolygon';
+    case 'geoarrow.geometrycollection':
+      return 'GeometryCollection';
+    default:
+      return null;
+  }
+}
+
+/** Returns the canonical concrete encoding for a materialized geometry family. */
+export function getGeoArrowEncodingForGeometry(
+  type: GeoArrowGeometryValue['type']
+): GeoArrowEncoding {
+  return `geoarrow.${type.toLowerCase()}` as GeoArrowEncoding;
+}

package/src/geoarrow/views.ts

@@ -0,0 +1,150 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {GeoArrowArray, GeoArrowColumn} from './types';
+import {getEncodingFromChildName, isGeoArrowValueValid, sliceGeoArrowArray} from './layout';
+
+/** One physical batch borrowed from a native geometry column. */
+export type GeoArrowBatchView = Readonly<{
+  /** Single-chunk column retaining the source semantics and typed arrays. */
+  column: GeoArrowColumn;
+  /** Index of the physical chunk in the source column, including empty chunks. */
+  chunkIndex: number;
+  /** First logical row in the source column; not a feature ID or byte cursor. */
+  rowOffset: number;
+}>;
+
+/** One logical row, with top-level union dispatch resolved without decoding coordinates. */
+export type GeoArrowRowView = Readonly<{
+  /** One-row column, preserving nulls, collections, and exact single/multi identity. */
+  column: GeoArrowColumn;
+  /** Logical row index relative to the input column, including null rows. */
+  rowIndex: number;
+  /** Physical chunk index in the input column. */
+  chunkIndex: number;
+  /** Logical row index within that chunk, before union dispatch. */
+  chunkRowIndex: number;
+}>;
+
+/**
+ * Iterates native physical chunks lazily, including empty chunks, without new typed arrays.
+ * This is not a loader record-batch protocol: one loader batch may contain several chunks.
+ * Views borrow storage; callers must not mutate, recycle, or detach it while views are in use.
+ * Assumes valid physical descriptors; use validateGeoArrowColumn for untrusted input.
+ */
+export function* iterateGeoArrowBatches(
+  column: GeoArrowColumn
+): IterableIterator<GeoArrowBatchView> {
+  assertNativeGeometryColumn(column);
+  let rowOffset = 0;
+  for (let chunkIndex = 0; chunkIndex < column.chunks.length; chunkIndex++) {
+    const chunk = column.chunks[chunkIndex];
+    yield {column: {...column, chunks: [chunk]}, chunkIndex, rowOffset};
+    rowOffset += chunk.length;
+  }
+}
+
+/**
+ * Borrows one native geometry row, allocating descriptors but no typed arrays or coordinates.
+ * Resolves the top-level union by type ID and retains collection grouping inside the row.
+ * Indices are relative to the supplied column (including when it is already sliced).
+ * Throws for an invalid row index, serialized/box encoding, or invalid union dispatch.
+ * Assumes valid physical descriptors beyond the selected union dispatch.
+ */
+export function getGeoArrowRowView(column: GeoArrowColumn, rowIndex: number): GeoArrowRowView {
+  assertNativeGeometryColumn(column);
+  if (!Number.isSafeInteger(rowIndex) || rowIndex < 0) {
+    throw new RangeError('GeoArrow row index must be a nonnegative safe integer');
+  }
+  let chunkRowIndex = rowIndex;
+  for (let chunkIndex = 0; chunkIndex < column.chunks.length; chunkIndex++) {
+    const chunk = column.chunks[chunkIndex];
+    if (chunkRowIndex >= chunk.length) {
+      chunkRowIndex -= chunk.length;
+      continue;
+    }
+    let rowColumn = {
+      ...column,
+      chunks: [sliceGeoArrowArray(chunk, chunkRowIndex, chunkRowIndex + 1)]
+    };
+    // A parent-masked union row has no child value to resolve; dispatch may be unused.
+    if (
+      column.encoding === 'geoarrow.geometry' &&
+      isGeoArrowValueValid(chunk.validity, chunkRowIndex)
+    ) {
+      if (chunk.kind !== 'dense-union') {
+        throw new Error('Mixed GeoArrow geometry requires dense-union storage');
+      }
+      const physicalIndex = (chunk.offset || 0) + chunkRowIndex;
+      const child = chunk.children.find(
+        candidate => candidate.typeId === chunk.typeIds[physicalIndex]
+      );
+      const valueOffset = chunk.valueOffsets[physicalIndex];
+      if (
+        !child ||
+        !Number.isInteger(valueOffset) ||
+        valueOffset < 0 ||
+        valueOffset >= child.data.length
+      ) {
+        throw new Error('Invalid GeoArrow union row dispatch');
+      }
+      const encoding = child.encoding || getEncodingFromChildName(child.name);
+      if (encoding === 'geoarrow.geometry') {
+        throw new Error('GeoArrow geometry union children must be concrete geometries');
+      }
+      const data = sliceGeoArrowArray(child.data, valueOffset, valueOffset + 1);
+      rowColumn = {
+        ...column,
+        encoding,
+        dimension: child.dimension ?? column.dimension,
+        coordinateLayout: child.coordinateLayout ?? column.coordinateLayout,
+        chunks: [data]
+      };
+      assertNativeGeometryColumn(rowColumn);
+    }
+    return {column: rowColumn, rowIndex, chunkIndex, chunkRowIndex};
+  }
+  throw new RangeError('GeoArrow row index exceeds column length');
+}
+
+/**
+ * Assembles a nonempty iterable of compatible native columns without merging physical chunks.
+ * Encodings, dimensions, and layouts must match. CRS and opaque metadata must be the same
+ * references (or both absent); no semantic equivalence, metadata merging, or reprojection is
+ * attempted. Missing edges mean planar. Empty columns/chunks are permitted and retained.
+ * Returns a new envelope and chunk-reference list, never new typed arrays.
+ */
+export function concatenateGeoArrowColumns(columns: Iterable<GeoArrowColumn>): GeoArrowColumn {
+  let firstColumn: GeoArrowColumn | undefined;
+  const chunks: GeoArrowArray[] = [];
+  for (const column of columns) {
+    assertNativeGeometryColumn(column);
+    if (!firstColumn) {
+      firstColumn = column;
+    } else if (
+      column.encoding !== firstColumn.encoding ||
+      column.dimension !== firstColumn.dimension ||
+      column.coordinateLayout !== firstColumn.coordinateLayout ||
+      (column.edges ?? 'planar') !== (firstColumn.edges ?? 'planar') ||
+      column.spatialReference !== firstColumn.spatialReference ||
+      column.metadata !== firstColumn.metadata
+    ) {
+      throw new Error('Cannot concatenate GeoArrow columns with different semantic envelopes');
+    }
+    for (const chunk of column.chunks) chunks.push(chunk);
+  }
+  if (!firstColumn) throw new Error('At least one GeoArrow column is required');
+  return {...firstColumn, chunks};
+}
+
+/** Keeps borrowed geometry access distinct from decoding serialized data or interpreting boxes. */
+function assertNativeGeometryColumn(column: GeoArrowColumn): void {
+  if (
+    column.encoding === 'geoarrow.wkb' ||
+    column.encoding === 'geoarrow.wkt' ||
+    column.encoding === 'geoarrow.box'
+  ) {
+    throw new Error('GeoArrow geometry views require native geometry; decode WKB/WKT first');
+  }
+}

package/src/geoarrow/wkb-entry.ts

@@ -0,0 +1,13 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+/** Optional serialized-format bridge. The parser implementation lives in @math.gl/geospatial/wkb. */
+export {
+  decodeGeoArrowWKB,
+  decodeGeoArrowWKT,
+  encodeGeoArrowWKB,
+  encodeGeoArrowWKT,
+  getGeoArrowWKBVertexCount
+} from './codecs';
+export type {DecodeGeoArrowWKBOptions} from './codecs';

package/src/geoarrow/worker.ts

@@ -0,0 +1,20 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {GeoArrowColumn} from './types';
+import {getGeoArrowTransferList} from './layout';
+
+export {getGeoArrowTransferList} from './layout';
+export type {GeoArrowColumn} from './types';
+
+/** A column and the unique borrowed buffers that may be transferred with it. */
+export type GeoArrowTransfer = Readonly<{
+  column: GeoArrowColumn;
+  transferList: ArrayBuffer[];
+}>;
+
+/** Prepares an explicit structured-clone transfer payload without detaching any buffers. */
+export function prepareGeoArrowTransfer(column: GeoArrowColumn): GeoArrowTransfer {
+  return {column, transferList: getGeoArrowTransferList(column)};
+}

package/src/geodesic-buffer.ts

@@ -0,0 +1,120 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+import type {NumericArray} from '@math.gl/core';
+import type {GeodesicLine} from './ellipsoid-geodesic';
+import type {RhumbLine} from './ellipsoid-rhumb';
+export const GEODESIC_BUFFER_FIELDS = Object.freeze([
+  'lat2',
+  'lon2',
+  'azi2',
+  's12',
+  'a12',
+  'm12',
+  'M12',
+  'M21'
+] as const);
+export const RHUMB_BUFFER_FIELDS = Object.freeze(['lat2', 'lon2', 'azi12', 's12'] as const);
+type Result = {[key: string]: number | undefined};
+function shared(value: unknown): boolean {
+  return (
+    ArrayBuffer.isView(value) &&
+    typeof SharedArrayBuffer !== 'undefined' &&
+    value.buffer instanceof SharedArrayBuffer
+  );
+}
+class LineBuffer {
+  readonly capacity: number;
+  readonly fields: readonly string[];
+  readonly stride: number;
+  private readonly stage: Float64Array;
+  private readonly scratch: Result = {};
+  private readonly control = {busy: false};
+  constructor(
+    private readonly evaluate: (distance: number, output: Result) => Result,
+    capacity: number,
+    fields: readonly string[]
+  ) {
+    if (!Number.isSafeInteger(capacity) || capacity < 0 || capacity > 1e6)
+      throw new RangeError('Buffer capacity must be in [0,1000000]');
+    this.capacity = capacity;
+    this.fields = Object.freeze([...fields]);
+    this.stride = fields.length;
+    this.stage = new Float64Array(capacity * this.stride);
+    Object.freeze(this);
+  }
+  /** Atomically write interleaved rows; input/output aliasing is supported. */
+  positions(distances: Readonly<NumericArray>, output: Float64Array): Float64Array {
+    if (this.control.busy) throw new RangeError('Packed line samplers are not reentrant');
+    this.control.busy = true;
+    try {
+      return this.write(distances, output);
+    } finally {
+      this.control.busy = false;
+    }
+  }
+  private write(distances: Readonly<NumericArray>, output: Float64Array): Float64Array {
+    const count = distances.length;
+    if (
+      !Number.isSafeInteger(count) ||
+      count < 0 ||
+      count > this.capacity ||
+      !(output instanceof Float64Array) ||
+      output.length < count * this.stride ||
+      shared(distances) ||
+      shared(output)
+    )
+      throw new RangeError('Invalid packed line storage');
+    for (let i = 0; i < count; i++)
+      if (!Number.isFinite(distances[i])) throw new RangeError('Expected finite distances');
+    for (let i = 0; i < count; i++) {
+      const result = this.evaluate(distances[i], this.scratch);
+      for (let field = 0; field < this.stride; field++) {
+        const value = result[this.fields[field]];
+        if (!Number.isFinite(value))
+          throw new RangeError('Line result or requested field is not representable');
+        this.stage[i * this.stride + field] = value!;
+      }
+    }
+    for (let i = 0; i < count * this.stride; i++) output[i] = this.stage[i];
+    return output;
+  }
+}
+/** Fixed-capacity sampler; prepares staging once and reuses scalar result sinks when available. */
+export class GeodesicLineBuffer extends LineBuffer {
+  constructor(
+    line: Pick<GeodesicLine, 'position'>,
+    capacity: number,
+    options: {area?: boolean} = {}
+  ) {
+    if (!line || typeof line.position !== 'function')
+      throw new RangeError('Expected a geodesic line');
+    const position = line.position.bind(line) as (
+      distance: number,
+      index?: undefined,
+      array?: undefined,
+      output?: Result
+    ) => Result;
+    super(
+      (distance, result) => position(distance, undefined, undefined, result),
+      capacity,
+      options.area ? [...GEODESIC_BUFFER_FIELDS, 'S12'] : GEODESIC_BUFFER_FIELDS
+    );
+  }
+}
+export class RhumbLineBuffer extends LineBuffer {
+  constructor(line: RhumbLine, capacity: number, options: {area?: boolean} = {}) {
+    if (!line || typeof line.position !== 'function') throw new RangeError('Expected a rhumb line');
+    const position = line.position.bind(line) as (
+      distance: number,
+      index?: undefined,
+      array?: undefined,
+      output?: Result
+    ) => Result;
+    super(
+      (distance, result) => position(distance, undefined, undefined, result),
+      capacity,
+      options.area ? [...RHUMB_BUFFER_FIELDS, 'S12'] : RHUMB_BUFFER_FIELDS
+    );
+  }
+}

package/src/geodesic-exact/area.ts

@@ -0,0 +1,70 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) Charles Karney (2012-2025)
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Area decomposition and I4 integrand adapted from GeographicLib 2.7 GeodesicExact/GeodesicLineExact (MIT). Original derivative-integral divided difference avoids cancellation. See ../../GEOGRAPHICLIB-LICENSE.txt.
+import {integrate} from './quadrature';
+/** Derivative of t(x) = x + sqrt(1+x) asinh(sqrt(x))/sqrt(x) - 1,
+ * analytically continued to negative x. Taylor evaluation avoids subtraction at 0.
+ */
+function derivative(x: number): number {
+  if (Math.abs(x) < 0.125) {
+    let coefficient = 1 / 3,
+      power = 1,
+      sum = 1;
+    for (let n = 1; n <= 24; n++) {
+      sum += n * coefficient * power;
+      coefficient *= (-2 * n) / (2 * n + 3);
+      power *= x;
+    }
+    return sum;
+  }
+  const root = Math.sqrt(Math.abs(x));
+  const ratio = (x > 0 ? Math.asinh(root) : Math.asin(root)) / root;
+  return 1 + (1 - ratio / Math.sqrt(1 + x)) / (2 * x);
+}
+/** Stable t value for a well-separated divided difference. */
+function value(x: number): number {
+  if (Math.abs(x) < 0.125) {
+    let term = x / 3,
+      sum = x;
+    for (let n = 1; n <= 24; n++) {
+      const next = sum + term;
+      if (next === sum) break;
+      sum = next;
+      term *= (-2 * n * x) / (2 * n + 3);
+    }
+    return sum;
+  }
+  const root = Math.sqrt(Math.abs(x));
+  return x + ((Math.sqrt(1 + x) * (x > 0 ? Math.asinh(root) : Math.asin(root))) / root - 1);
+}
+/** Integrate the smooth correction, evaluating t's divided difference as an
+ * integral of its derivative rather than subtracting nearly equal t values.
+ */
+export function areaCorrection(
+  ep2: number,
+  k2: number,
+  s1: number,
+  c1: number,
+  delta: number
+): number {
+  // I4 is anti-periodic after pi and has zero integral over a full circuit.
+  const remainder = delta % (2 * Math.PI),
+    tX = value(ep2);
+  return integrate(
+    theta => {
+      const s = s1 * Math.cos(theta) + c1 * Math.sin(theta),
+        y = k2 * s * s;
+      const divided =
+        ep2 === y
+          ? derivative(y)
+          : Math.abs(y) <= 1e-8 * Math.abs(ep2)
+            ? (tX - value(y)) / (ep2 - y)
+            : integrate(u => derivative(y + (ep2 - y) * u), 0, 1);
+      return (-s * divided) / 2;
+    },
+    0,
+    remainder
+  );
+}