@math.gl/dggs 5.0.0-alpha.5 → 5.0.0-alpha.8

package/src/geohash-decoder.ts

@@ -3,10 +3,15 @@
 // Copyright (c) vis.gl contributors
 
 import {type Bounds2D} from '@math.gl/types';
-import {type DGGSCell, type DGGSDecoder, getDGGSCellToken} from './dggs-decoder';
+import {
+  withDGGSBoundaryOptions,
+  type DGGSCell,
+  type DGGSDecoder,
+  getDGGSCellToken
+} from './dggs-decoder';
 
 /** Decoder for the geohash dggs */
-export const GeohashDecoder = {
+export const GeohashDecoder = withDGGSBoundaryOptions({
   name: 'geohash',
   hasNumericRepresentation: false,
   cellColumnNames: ['geohash', 'geohashId', 'geohash_id'],
@@ -17,7 +22,7 @@ export const GeohashDecoder = {
   cellToBoundaryFlat: (cell: DGGSCell): number[] =>
     getGeohashBoundaryFlat(getDGGSCellToken(cell, 'GeoHash')),
   cellToBounds: (cell: DGGSCell): Bounds2D => getGeohashBounds(getDGGSCellToken(cell, 'GeoHash'))
-} as const satisfies DGGSDecoder;
+} as const satisfies DGGSDecoder);
 
 const BASE32_CODES = '0123456789bcdefghjkmnpqrstuvwxyz';
 const BASE32_CODES_DICT: Record<string, number> = {};

package/src/h3-decoder.ts

@@ -4,10 +4,15 @@
 
 import {cellToBoundary, cellToLatLng} from 'h3-js';
 import {type Bounds2D} from '@math.gl/types';
-import {type DGGSCell, type DGGSDecoder, getDGGSCellBounds} from './dggs-decoder';
+import {
+  withDGGSBoundaryOptions,
+  type DGGSCell,
+  type DGGSDecoder,
+  getDGGSCellBounds
+} from './dggs-decoder';
 
 /** Lightweight cell geometry decoder for the H3 hexagonal DGGS. */
-export const H3Decoder = {
+export const H3Decoder = withDGGSBoundaryOptions({
   name: 'h3',
   hasNumericRepresentation: true,
   cellColumnNames: [
@@ -26,7 +31,7 @@ export const H3Decoder = {
   cellToBoundary: (cell: DGGSCell): [number, number][] => getH3Boundary(cell),
   cellToBoundaryFlat: (cell: DGGSCell): number[] => getH3Boundary(cell).flat(),
   cellToBounds: (cell: DGGSCell): Bounds2D => getDGGSCellBounds(getH3Boundary(cell))
-} as const satisfies DGGSDecoder;
+} as const satisfies DGGSDecoder);
 
 function getH3Token(cell: DGGSCell): string {
   return typeof cell === 'bigint' ? cell.toString(16) : removeHexPrefix(cell);

package/src/index.ts

@@ -10,14 +10,25 @@ import {PlusCodeDecoder} from './plus-code-decoder';
 import {QuadkeyDecoder} from './quadkey-decoder';
 import {S2Decoder} from './s2-decoder';
 
+export {type DGGSBoundaryOptions} from './dggs-decoder';
 export {type DGGSCell, type DGGSCellColumn, type DGGSDecoder};
+export {unwrapDGGSBoundary} from './unwrap-dggs-boundary';
 export {A5Decoder};
 export {GeohashDecoder};
 export {H3Decoder};
 export {PlusCodeDecoder};
 export {QuadkeyDecoder, quadkeyToWorldBounds} from './quadkey-decoder';
-export {S2Decoder};
-export {getS2ChildIndex} from './s2-geometry/s2-token';
+export {S2Decoder, getS2Bounds, getS2LngLat, getS2BoundaryFlat} from './s2-decoder';
+export {
+  getS2ChildIndex,
+  getS2IndexFromToken,
+  getS2Level,
+  getS2TokenFromIndex,
+  isS2IndexValid,
+  isS2TokenValid
+} from './s2-geometry/s2-token';
+export {getS2DescendantIndex, getS2IndexFromCell} from './s2-geometry/s2-geometry';
+export type {S2Cell} from './s2-geometry/s2-geometry';
 
 /** Lightweight decoders bundled with this module. */
 export const DGGS_DECODERS: readonly DGGSDecoder[] = [

package/src/plus-code-decoder.ts

@@ -4,7 +4,12 @@
 
 import OpenLocationCodePackage, {type OpenLocationCodeArea} from 'open-location-code';
 import {type Bounds2D} from '@math.gl/types';
-import {type DGGSCell, type DGGSDecoder, getDGGSCellToken} from './dggs-decoder';
+import {
+  withDGGSBoundaryOptions,
+  type DGGSCell,
+  type DGGSDecoder,
+  getDGGSCellToken
+} from './dggs-decoder';
 
 const openLocationCode = new OpenLocationCodePackage.OpenLocationCode();
 
@@ -12,7 +17,7 @@ const openLocationCode = new OpenLocationCodePackage.OpenLocationCode();
  * Lightweight geometry decoder for full Google Plus Codes (Open Location Codes).
  * Short codes require a reference location and are intentionally unsupported.
  */
-export const PlusCodeDecoder = {
+export const PlusCodeDecoder = withDGGSBoundaryOptions({
   name: 'plus-code',
   hasNumericRepresentation: false,
   cellColumnNames: ['plusCode', 'plus_code', 'openLocationCode', 'open_location_code', 'olc'],
@@ -29,7 +34,7 @@ export const PlusCodeDecoder = {
       [area.longitudeHi, area.latitudeHi]
     ];
   }
-} as const satisfies DGGSDecoder;
+} as const satisfies DGGSDecoder);
 
 function getPlusCodeLngLat(cell: DGGSCell): [number, number] {
   const area = decodePlusCode(cell);

package/src/quadkey-decoder.ts

@@ -3,12 +3,17 @@
 // Copyright (c) vis.gl contributors
 
 import {type Bounds2D} from '@math.gl/types';
-import {type DGGSCell, type DGGSDecoder, getDGGSCellToken} from './dggs-decoder';
+import {
+  withDGGSBoundaryOptions,
+  type DGGSCell,
+  type DGGSDecoder,
+  getDGGSCellToken
+} from './dggs-decoder';
 
 const TILE_SIZE = 512;
 
 /** Decoder for the quadkey DGGS */
-export const QuadkeyDecoder = {
+export const QuadkeyDecoder = withDGGSBoundaryOptions({
   name: 'quadkey',
   hasNumericRepresentation: false,
   cellColumnNames: ['quadkey', 'quadkeyId', 'quadkey_id'],
@@ -19,7 +24,7 @@ export const QuadkeyDecoder = {
   cellToBoundaryFlat: (cell: DGGSCell): number[] =>
     getQuadkeyBoundaryFlat(getDGGSCellToken(cell, 'Quadkey')),
   cellToBounds: (cell: DGGSCell): Bounds2D => getQuadkeyBounds(getDGGSCellToken(cell, 'Quadkey'))
-} as const satisfies DGGSDecoder;
+} as const satisfies DGGSDecoder);
 
 function getQuadkeyLngLat(quadkey: string): [number, number] {
   const [topLeft, bottomRight] = quadkeyToWorldBounds(quadkey);

package/src/s2-decoder.ts

@@ -3,25 +3,24 @@
 // Copyright (c) vis.gl contributors
 
 import {type Bounds2D} from '@math.gl/types';
-import {type DGGSCell, type DGGSDecoder} from './dggs-decoder';
+import {withDGGSBoundaryOptions, type DGGSCell, type DGGSDecoder} from './dggs-decoder';
 
 import {getS2IndexFromToken, getS2TokenFromIndex} from './s2-geometry/s2-token';
 import {getS2GeoBounds} from './s2-geometry/s2-to-boundary';
 import {getS2Cell, IJToST, STToUV, FaceUVToXYZ, XYZToLngLat} from './s2-geometry/s2-geometry';
 
 /** Decoder for the S2 DGGS */
-export const S2Decoder = {
+export const S2Decoder = withDGGSBoundaryOptions({
   name: 's2',
   hasNumericRepresentation: true,
   cellColumnNames: ['s2', 's2Token', 's2_token', 's2Cell', 's2_cell', 's2CellId', 's2_cell_id'],
   tokenToCell: (s2Token: string): bigint => getS2IndexFromToken(s2Token),
-  cellToToken: (cell: DGGSCell): string =>
-    typeof cell === 'string' ? cell : getS2TokenFromIndex(cell),
+  cellToToken: (cell: DGGSCell): string => getS2TokenFromIndex(getS2CellIndex(cell)),
   cellToLngLat: (cell: DGGSCell): [number, number] => getS2LngLat(cell),
   cellToBoundary: (cell: DGGSCell): [number, number][] => getS2Boundary(cell),
   cellToBoundaryFlat: (cell: DGGSCell): number[] => getS2BoundaryFlat(cell),
   cellToBounds: (cell: DGGSCell): Bounds2D => getS2Bounds(cell)
-} as const satisfies DGGSDecoder;
+} as const satisfies DGGSDecoder);
 
 /**
  * Retrieve S2 geometry center
@@ -60,28 +59,99 @@ function getS2Boundary(cell: DGGSCell): [number, number][] {
   return boundary;
 }
 
-function getS2Bounds(cell: DGGSCell): Bounds2D {
-  const flatBoundary = getS2Boundary(cell);
-
-  // We know that we have at least one point, no Infinity will be returned.
-  let xmin = Infinity;
-  let ymin = Infinity;
-  let xmax = -Infinity;
-  let ymax = -Infinity;
+/**
+ * Returns conservative longitude/latitude bounds for an S2 cell.
+ *
+ * Longitudes are unwrapped so `east >= west`; either endpoint may lie outside `[-180, 180]` for
+ * antimeridian cells. The two level-zero polar faces span a complete 360-degree longitude range.
+ *
+ * @param cell - S2 token or 64-bit cell index.
+ * @returns Bounds in `[[west, south], [east, north]]` order and degrees.
+ */
+export function getS2Bounds(cell: DGGSCell): Bounds2D {
+  const s2Cell = getS2Cell(getS2CellIndex(cell));
+  if (s2Cell.level === 0) {
+    return getS2RootBounds(s2Cell.face);
+  }
 
-  for (const [x, y] of flatBoundary) {
-    if (x < xmin) xmin = x;
-    if (x > xmax) xmax = x;
-    if (y < ymin) ymin = y;
-    if (y > ymax) ymax = y;
+  // For non-root S2 cells, latitude and longitude extrema occur at vertices. Root cells require
+  // the special cases above because their curved edges or interiors contain the extrema.
+  // https://github.com/google/s2geometry/blob/master/src/s2/s2cell.cc
+  const offsets: readonly [number, number][] = [
+    [0, 0],
+    [0, 1],
+    [1, 1],
+    [1, 0]
+  ];
+  let west = Infinity;
+  let south = Infinity;
+  let east = -Infinity;
+  let north = -Infinity;
+  let previousLongitude: number | undefined;
+  for (const offset of offsets) {
+    const st = IJToST(s2Cell.ij, s2Cell.level, offset);
+    const uv = STToUV(st);
+    const [x, y, z] = FaceUVToXYZ(s2Cell.face, uv);
+    let [longitude, latitude] = XYZToLngLat([x, y, z]);
+    if (x === 0 && y === 0 && previousLongitude !== undefined) {
+      longitude = previousLongitude;
+    }
+    if (previousLongitude !== undefined) {
+      const longitudeDelta = longitude - previousLongitude;
+      longitude += longitudeDelta > 180 ? -360 : longitudeDelta < -180 ? 360 : 0;
+    }
+    previousLongitude = longitude;
+    west = Math.min(west, longitude);
+    south = Math.min(south, latitude);
+    east = Math.max(east, longitude);
+    north = Math.max(north, latitude);
   }
 
+  const angularEpsilon = (2 * Number.EPSILON * 180) / Math.PI;
   return [
-    [xmin, ymin],
-    [xmax, ymax]
+    [west - angularEpsilon, Math.max(-90, south - angularEpsilon)],
+    [east + angularEpsilon, Math.min(90, north + angularEpsilon)]
   ];
 }
 
 function getS2CellIndex(cell: DGGSCell): bigint {
   return typeof cell === 'bigint' ? cell : getS2IndexFromToken(cell);
 }
+
+function getS2RootBounds(face: number): Bounds2D {
+  const polarLatitude = (Math.asin(Math.sqrt(1 / 3)) * 180) / Math.PI;
+  switch (face) {
+    case 0:
+      return [
+        [-45, -45],
+        [45, 45]
+      ];
+    case 1:
+      return [
+        [45, -45],
+        [135, 45]
+      ];
+    case 2:
+      return [
+        [-180, polarLatitude],
+        [180, 90]
+      ];
+    case 3:
+      return [
+        [135, -45],
+        [225, 45]
+      ];
+    case 4:
+      return [
+        [-135, -45],
+        [-45, 45]
+      ];
+    case 5:
+      return [
+        [-180, -90],
+        [180, -polarLatitude]
+      ];
+    default:
+      throw new Error(`Invalid S2 face: ${face}`);
+  }
+}

package/src/s2-geometry/s2-geometry.ts

@@ -11,6 +11,8 @@ Permission to use, copy, modify, and/or distribute this software for any purpose
 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */
 
+import {isS2IndexValid} from './s2-token';
+
 export type S2Cell = {
   face: number;
   ij: [number, number];
@@ -18,6 +20,9 @@ export type S2Cell = {
 };
 
 export function getS2Cell(s2Index: bigint): S2Cell {
+  if (!isS2IndexValid(s2Index)) {
+    throw new Error(`Invalid S2 index: ${s2Index}`);
+  }
   const key = toHilbertQuadkey(s2Index);
   const s2cell = fromHilbertQuadKey(key);
   return s2cell;
@@ -31,11 +36,46 @@ const MAX_LEVEL = 30;
 const POS_BITS = 2 * MAX_LEVEL + 1; // 61 (60 bits of data, 1 bit lsb marker)
 const RADIAN_TO_DEGREE = 180 / Math.PI;
 
+type HilbertOrientation = 'a' | 'b' | 'c' | 'd';
+
+const HILBERT_MAP: Record<
+  HilbertOrientation,
+  readonly (readonly [position: number, orientation: HilbertOrientation])[]
+> = {
+  a: [
+    [0, 'd'],
+    [1, 'a'],
+    [3, 'b'],
+    [2, 'a']
+  ],
+  b: [
+    [2, 'b'],
+    [1, 'b'],
+    [3, 'a'],
+    [0, 'c']
+  ],
+  c: [
+    [2, 'c'],
+    [3, 'd'],
+    [1, 'c'],
+    [0, 'b']
+  ],
+  d: [
+    [0, 'a'],
+    [3, 'c'],
+    [1, 'd'],
+    [2, 'd']
+  ]
+};
+
 /*
   Original function taken from deck.gl doesn't support the case of (face <= 5)
   It's fixed here.
 */
 export function fromHilbertQuadKey(hilbertQuadkey: string): S2Cell {
+  if (!/^[0-5]\/[0-3]{0,30}$/.test(hilbertQuadkey)) {
+    throw new Error(`Invalid S2 Hilbert quadkey: ${hilbertQuadkey}`);
+  }
   const parts = hilbertQuadkey.split('/');
   const face = parseInt(parts[0], 10);
   const position = parts[1] || '';
@@ -75,6 +115,9 @@ export function fromHilbertQuadKey(hilbertQuadkey: string): S2Cell {
 }
 
 export function toHilbertQuadkey(id: bigint): string {
+  if (!isS2IndexValid(id)) {
+    throw new Error(`Invalid S2 index: ${id}`);
+  }
   let bin = id.toString(2);
 
   while (bin.length < FACE_BITS + POS_BITS) {
@@ -105,6 +148,86 @@ export function toHilbertQuadkey(id: bigint): string {
   return `${faceS}/${posS}`;
 }
 
+/**
+ * Converts face-local integer coordinates into an S2 cell index.
+ *
+ * @param s2Cell - Face, `(i, j)` coordinates, and level of an S2 cell.
+ * @returns The corresponding 64-bit S2 cell index.
+ */
+export function getS2IndexFromCell(s2Cell: S2Cell): bigint {
+  const {face, ij, level} = s2Cell;
+  if (!Number.isInteger(face) || face < 0 || face > 5) {
+    throw new Error(`Invalid S2 face: ${face}`);
+  }
+  if (!Number.isInteger(level) || level < 0 || level > MAX_LEVEL) {
+    throw new Error(`Invalid S2 level: ${level}`);
+  }
+  const maximumCoordinate = 2 ** level;
+  if (
+    !Number.isInteger(ij[0]) ||
+    !Number.isInteger(ij[1]) ||
+    ij[0] < 0 ||
+    ij[1] < 0 ||
+    ij[0] >= maximumCoordinate ||
+    ij[1] >= maximumCoordinate
+  ) {
+    throw new Error(`Invalid S2 IJ coordinates: ${ij[0]}, ${ij[1]}`);
+  }
+
+  const positions = getHilbertQuadList(ij[0], ij[1], level, face);
+  let s2Index = BigInt(face) << 61n;
+  for (let positionIndex = 0; positionIndex < positions.length; positionIndex++) {
+    const bitOffset = 59 - positionIndex * 2;
+    s2Index |= BigInt(positions[positionIndex]) << BigInt(bitOffset);
+  }
+  s2Index |= 1n << BigInt(60 - level * 2);
+  return s2Index;
+}
+
+/**
+ * Returns a spatially addressed descendant of an S2 cell.
+ *
+ * Unlike {@link getS2ChildIndex}, `x` and `y` address the descendant along increasing face-local
+ * `i` and `j` axes. This accounts for Hilbert orientation changes across faces and levels.
+ *
+ * @param rootIndex - Valid S2 cell index at the root of the relative grid.
+ * @param relativeLevel - Number of subdivision levels below the root.
+ * @param x - Descendant coordinate along the root cell's increasing `i` axis.
+ * @param y - Descendant coordinate along the root cell's increasing `j` axis.
+ * @returns The descendant S2 cell index.
+ */
+export function getS2DescendantIndex(
+  rootIndex: bigint,
+  relativeLevel: number,
+  x: number,
+  y: number
+): bigint {
+  const rootCell = getS2Cell(rootIndex);
+  if (
+    !Number.isInteger(relativeLevel) ||
+    relativeLevel < 0 ||
+    rootCell.level + relativeLevel > MAX_LEVEL
+  ) {
+    throw new Error(`Invalid S2 relative level: ${relativeLevel}`);
+  }
+  const divisionCount = 2 ** relativeLevel;
+  if (
+    !Number.isInteger(x) ||
+    !Number.isInteger(y) ||
+    x < 0 ||
+    y < 0 ||
+    x >= divisionCount ||
+    y >= divisionCount
+  ) {
+    throw new Error(`Invalid S2 descendant coordinates: ${x}, ${y}`);
+  }
+  return getS2IndexFromCell({
+    face: rootCell.face,
+    ij: [rootCell.ij[0] * divisionCount + x, rootCell.ij[1] * divisionCount + y],
+    level: rootCell.level + relativeLevel
+  });
+}
+
 export function IJToST(
   ij: [number, number],
   order: number,
@@ -164,3 +287,17 @@ function rotateAndFlipQuadrant(n: number, point: [number, number], rx: number, r
     point[1] = x;
   }
 }
+
+function getHilbertQuadList(x: number, y: number, level: number, face: number): number[] {
+  let orientation: HilbertOrientation = face % 2 === 1 ? 'd' : 'a';
+  const positions: number[] = [];
+  for (let bit = level - 1; bit >= 0; bit--) {
+    const mask = 1 << bit;
+    const quadrantX = (x & mask) !== 0 ? 1 : 0;
+    const quadrantY = (y & mask) !== 0 ? 1 : 0;
+    const [position, nextOrientation] = HILBERT_MAP[orientation][quadrantX * 2 + quadrantY];
+    positions.push(position);
+    orientation = nextOrientation;
+  }
+  return positions;
+}

package/src/s2-geometry/s2-token.ts

@@ -5,7 +5,10 @@
 // s2-geometry is a pure JavaScript port of Google/Niantic's S2 Geometry library
 // which is perfect since it works in the browser.
 
-// const MAXIMUM_TOKEN_LENGTH = 16;
+const MAXIMUM_TOKEN_LENGTH = 16;
+const MAXIMUM_S2_INDEX = (1n << 64n) - 1n;
+const VALID_LOWEST_ON_BITS = 0x1555555555555555n;
+const MAXIMUM_LEVEL = 30;
 
 // INDEX CALCULATIONS
 
@@ -16,10 +19,13 @@
  */
 export function getS2IndexFromToken(token: string): bigint {
   if (token === 'X') {
-    token = '';
+    return 0n;
+  }
+  if (!isS2TokenValid(token)) {
+    throw new Error(`Invalid S2 token: ${token}`);
   }
   // pad token with zeros to make the length 16
-  const paddedToken = token.padEnd(16, '0');
+  const paddedToken = token.padEnd(MAXIMUM_TOKEN_LENGTH, '0');
   return BigInt(`0x${paddedToken}`);
 }
 
@@ -31,6 +37,9 @@ export function getS2TokenFromIndex(cellId: bigint): string {
   if (cellId === 0n) {
     return 'X';
   }
+  if (!isS2IndexValid(cellId)) {
+    throw new Error(`Invalid S2 index: ${cellId}`);
+  }
   let numZeroDigits = countTrailingZeros(cellId);
 
   const remainder = numZeroDigits % 4;
@@ -44,7 +53,67 @@ export function getS2TokenFromIndex(cellId: bigint): string {
   return zeroString + hexString;
 }
 
+/**
+ * Returns whether a value is a valid non-empty 64-bit S2 cell index.
+ *
+ * @param s2Index - Candidate S2 cell index.
+ * @returns `true` when the face and level marker encode a valid S2 cell.
+ */
+export function isS2IndexValid(s2Index: unknown): s2Index is bigint {
+  if (typeof s2Index !== 'bigint' || s2Index <= 0n || s2Index > MAXIMUM_S2_INDEX) {
+    return false;
+  }
+  const face = s2Index >> 61n;
+  const lowestOnBit = s2Index & -s2Index;
+  return face < 6n && (lowestOnBit & VALID_LOWEST_ON_BITS) !== 0n;
+}
+
+/**
+ * Returns whether a string is a canonical token for a non-empty S2 cell.
+ *
+ * The empty-cell sentinel `X` is supported by the conversion functions but is not a valid cell.
+ *
+ * @param token - Candidate hexadecimal S2 token.
+ * @returns `true` when the token canonically encodes a valid S2 cell.
+ */
+export function isS2TokenValid(token: unknown): token is string {
+  if (typeof token !== 'string' || !/^[0-9a-fA-F]{1,16}$/.test(token) || token.endsWith('0')) {
+    return false;
+  }
+  const paddedToken = token.padEnd(MAXIMUM_TOKEN_LENGTH, '0');
+  return isS2IndexValid(BigInt(`0x${paddedToken}`));
+}
+
+/**
+ * Returns the subdivision level encoded by an S2 cell index.
+ *
+ * @param s2Index - Valid non-empty S2 cell index.
+ * @returns The S2 level in the range `[0, 30]`.
+ */
+export function getS2Level(s2Index: bigint): number {
+  if (!isS2IndexValid(s2Index)) {
+    throw new Error(`Invalid S2 index: ${s2Index}`);
+  }
+  return (60 - countTrailingZeros(s2Index)) / 2;
+}
+
+/**
+ * Returns one of the four Hilbert-ordered children of an S2 cell.
+ *
+ * @param s2Index - Valid S2 cell index below level 30.
+ * @param index - Hilbert child position in the range `[0, 3]`.
+ * @returns The child S2 cell index.
+ */
 export function getS2ChildIndex(s2Index: bigint, index: number): bigint {
+  if (!isS2IndexValid(s2Index)) {
+    throw new Error(`Invalid S2 index: ${s2Index}`);
+  }
+  if (!Number.isInteger(index) || index < 0 || index > 3) {
+    throw new Error(`Invalid S2 child index: ${index}`);
+  }
+  if (getS2Level(s2Index) === MAXIMUM_LEVEL) {
+    throw new Error('Cannot subdivide an S2 leaf cell');
+  }
   // Shift sentinel bit 2 positions to the right.
   const newLsb = lsb(s2Index) >> 2n;
   // Insert child index before the sentinel bit.
@@ -57,7 +126,7 @@ export function getS2ChildIndex(s2Index: bigint, index: number): bigint {
  * @private
  */
 function lsb(cellId: bigint): bigint {
-  return cellId & (cellId + 1n); // eslint-disable-line
+  return cellId & -cellId; // eslint-disable-line
 }
 
 function countTrailingZeros(n: bigint): number {

package/src/s2.ts

@@ -2,5 +2,14 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-export {S2Decoder} from './s2-decoder';
-export {getS2ChildIndex} from './s2-geometry/s2-token';
+export {S2Decoder, getS2Bounds, getS2LngLat, getS2BoundaryFlat} from './s2-decoder';
+export {
+  getS2ChildIndex,
+  getS2IndexFromToken,
+  getS2Level,
+  getS2TokenFromIndex,
+  isS2IndexValid,
+  isS2TokenValid
+} from './s2-geometry/s2-token';
+export {getS2DescendantIndex, getS2IndexFromCell} from './s2-geometry/s2-geometry';
+export type {S2Cell} from './s2-geometry/s2-geometry';

package/src/unwrap-dggs-boundary.ts

@@ -0,0 +1,54 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/**
+ * Copy a cell boundary, unwrapping longitudes across the antimeridian.
+ * @param boundary Open or closed longitude/latitude pairs in degrees.
+ * @param referenceLongitude Optional longitude near which to place the first vertex.
+ * @returns Fresh pairs with each longitude nearest the preceding longitude. Exact
+ * 180-degree ties retain their direction. Latitudes and vertex order are preserved.
+ * @remarks Explicit boundaries spanning at least 360 degrees and closed rings with
+ * net longitude winding are copied unchanged. Polar cells need additional topology
+ * handling. This helper neither splits polygons nor calculates geodesic edges.
+ */
+export function unwrapDGGSBoundary(
+  boundary: ReadonlyArray<readonly [number, number]>,
+  referenceLongitude?: number
+): [number, number][] {
+  const result: [number, number][] = boundary.map(([longitude, latitude]) => [longitude, latitude]);
+  if (result.length === 0) {
+    return result;
+  }
+
+  let west = Infinity;
+  let east = -Infinity;
+  for (const [longitude] of boundary) {
+    west = Math.min(west, longitude);
+    east = Math.max(east, longitude);
+  }
+  if (east - west >= 360) {
+    return result;
+  }
+
+  let previous = referenceLongitude ?? result[0][0];
+  for (const point of result) {
+    const delta = point[0] - previous;
+    if (delta > 180) {
+      point[0] -= 360 * Math.ceil((delta - 180) / 360);
+    } else if (delta < -180) {
+      point[0] += 360 * Math.ceil((-delta - 180) / 360);
+    }
+    previous = point[0];
+  }
+
+  const first = boundary[0];
+  const last = boundary[boundary.length - 1];
+  if (first[0] === last[0] && first[1] === last[1]) {
+    if (Math.abs(result[result.length - 1][0] - result[0][0]) > 180) {
+      return boundary.map(([longitude, latitude]) => [longitude, latitude]);
+    }
+    result[result.length - 1] = [...result[0]];
+  }
+  return result;
+}