t3grid 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TriGrid contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,461 @@
+# Trifold T3 — a hierarchical triangular DGGS with *exact* nesting
+
+**Triangles tile the sphere into a quadtree where every parent is *exactly*
+the union of its four children — something neither hexagons nor most
+square systems can offer — with a 6-character address for a ~110 km cell.**
+
+**[Live demo & intro site](https://jaakla.github.io/trifold/)** · globe ↔ flat ·
+7 grid systems side by side · click any cell for its address ·
+[![Technical reference](https://img.shields.io/badge/Technical%20Reference-Docs-blue?logo=github)](https://github.com/jaakla/trifold/blob/main/docs/t3-technical-reference.md)
+
+![global overview](docs/img/global_overview.png)
+
+---
+
+## 1. The idea in 30 seconds
+
+Start from the icosahedron: 20 spherical triangles covering the Earth.
+Split every triangle into 4 by connecting the great-circle midpoints of its
+edges. Repeat. Each level halves the edge length and quadruples the cell
+count (*aperture 4*):
+
+| level | mean edge | mean area | cells (global) |
+|---:|---:|---:|---:|
+| 0 | 7,054 km | 25.5M km² | 20 |
+| 3 | 882 km | 399k km² | 1,280 |
+| 6 | 110 km | 6,226 km² | 81,920 |
+| 9 | 13.8 km | 97 km² | 5.2M |
+| 12 | 1.7 km | 1.5 km² | 336M |
+| 15 | 215 m | 24 ha | 21.5B |
+
+Because children are built from the parent's own vertices plus edge
+midpoints, **a parent cell is bit-for-bit the union of its children**.
+Aggregating data up the hierarchy or drilling down loses nothing and
+double-counts nothing. That property — *exact nesting* (with limited size variation, about ±20%) — is the central property of this project and is uncommon among global grids (see [§6](#6-comparison-with-other-dggs)).
+
+The repository contains the Python library, a three-form addressing codec,
+global grid products generated against Natural Earth land, generators for
+comparison grid systems, an interactive MapLibre demo (globe and flat),
+and a Cloudflare Worker that computes cells on demand from the grid geometry.
+
+### SDK and application code
+
+Core grid behavior is exposed through two standalone SDKs:
+
+| Runtime | Public SDK | Install | Code using it |
+|---|---|---|---|
+| Python | `trifold.api` (also re-exported by `trifold`) | `pip install t3grid` | CLI and build scripts |
+| JavaScript | `js/trifold.js` | `npm install t3grid` | Cloudflare Worker and website |
+
+The distributable packages are named **`t3grid`** (the unscoped name `trifold`
+was already taken on both registries); the Python import stays `import trifold`.
+The landcheck application ships separately as `pip install landcheck` /
+`npm install landcheck`.
+
+The SDKs cover address codecs, hierarchy operations, point location, cell
+geometry, metrics, and GeoJSON. Python land classification is an optional
+extension under `trifold.land`. See the [SDK API reference](docs/sdk-api.md)
+for the supported functions and examples.
+
+---
+
+## 2. Addressing: one identity, three encodings
+
+A cell is identified by `(face, path)`: which of the 20 icosahedron faces
+it lives on, and the sequence of base-4 digits choosing a child at every
+subdivision (`0,1,2` = corner children toward the parent's vertices,
+`3` = the central, orientation-flipped child).
+
+The same identity has three interchangeable encodings, each optimized for
+a different consumer:
+
+| form | example (London, level 6) | for | size |
+|---|---|---|---|
+| **compact** | `TF6958` | humans, URLs, labels, CSV columns | 3 + ⌈2L/5⌉ chars |
+| **path** | `F15-102111` | teaching, debugging — shows the tree descent | 4 + L chars |
+| **addr64** | `8811996358392152070` | compute — sort, join, mask | 8 bytes |
+
+**Why not just digits 0–3?** A digit string spends 8 bits per character to
+carry 2 bits of information. The compact form re-encodes the *same* path
+bits in Crockford base32 (5 bits/char, no ambiguous `I L O U`), prefixed
+by face and level characters: `T` `F`(face 15) `6`(level 6) `958`(12 path
+bits in 3 chars). Level 15 — sub-kilometre cells — still fits in 9
+characters. Base64 would save little and is not URL-safe; raw binary is
+not human-readable. Base32 provides a compact, URL-safe representation.
+
+**The uint64 layout** packs face (5 bits) + up to 27 path digits (54 bits)
++ level (5 bits). The path is left-aligned and the level is the low-bit
+tie-breaker that places a parent before its descendants:
+
+```
+ 63       59                                                       5     0
+ ┌─────────┬────────────────────────────────────────────────────────┬─────┐
+ │ face:5  │ path digits, 2 bits each, left-aligned                 │ L:5 │
+ └─────────┴────────────────────────────────────────────────────────┴─────┘
+```
+
+Left-alignment and the low level field provide these properties:
+
+* numeric sort = depth-first hierarchical order within a face
+  (Z-order curve — spatially adjacent cells tend to be numerically close);
+* parent and child addresses are direct masks/shifts — no tree traversal;
+* `is_ancestor(a, b)` = one shift and compare;
+* `descendant_range(a)` returns the inclusive uint64 interval containing
+  that cell and all descendants, suitable for database range scans.
+
+**Compatibility:** this corrected field order changes numeric `addr64`
+values produced by the initial v0.1.0 code. Compact and path addresses are
+unchanged; regenerate stored numeric IDs from either string form.
+
+```python
+import trifold.api as tg
+addr = tg.encode64(*tg.locate(-0.1276, 51.5072, level=6))
+tg.to_compact(addr)        # 'TF6958'
+tg.to_path(addr)           # 'F15-102111'
+tg.to_compact(tg.parent64(addr))   # 'TF595'
+[tg.to_compact(c) for c in tg.children64(addr)]
+# ['TF7958', 'TF795A', 'TF795C', 'TF795E']
+```
+
+Same answers from the command line (`pip install -e .`):
+
+```console
+$ trifold locate -0.1276 51.5072 6
+TF6958
+$ trifold show TF6958
+compact : TF6958
+path    : F15-102111
+addr64  : 8811996358392152070 (0x7A4A800000000006)
+level   : 6
+edge_km : 116.9
+area_km2: 5864
+$ trifold geom TF6958 > london_cell.geojson
+```
+
+The same operations are available from the standalone
+[JavaScript SDK](js/trifold.js) and the [Cloudflare Worker](worker/cell-server.js)
+(`GET /locate/-0.1276,51.5072?level=6` → `TF6958`). The Worker is an HTTP
+adapter over the SDK. The Python and JavaScript implementations are cross-tested.
+
+### Derived grouping keys
+
+Every triangle can also be projected into two grouping indexes without
+changing its geometry or accounting identity:
+
+| property | role | behavior |
+|---|---|---|
+| `rhombus_id` | exact grouping | two triangles per rhombus on the complete grid |
+| `rhombus_hilbert` | sort/partition key | Hilbert order within ten nested base diamonds |
+| `hex_id` | display grouping | six triangles in face interiors; seam and vertex exceptions |
+
+Rhombi have an exact aperture-4 hierarchy: a parent rhombus is the union of
+four child rhombi. Hex groups are defined independently at each level and do
+not nest. The face-local coloring produces three- or six-triangle seam groups
+and fixed one- or five-triangle vertex groups, so `hex_id` is a visualization
+and grouping key rather than a uniform global hex grid.
+
+Land-filtered and compacted exports can contain partial groups when member
+triangles fall outside the coverage or are represented at another level.
+Grouped features include `triangle_count` to make this explicit.
+
+---
+
+## 3. Grid products
+
+Built against Natural Earth 1:50m land, base level 6 (~110 km edges):
+
+| product | cells | GeoJSON | TopoJSON |
+|---|---:|---:|---:|
+| **uncompacted** — every level-6 cell touching land | 27,614 | 14 MB | 9 MB |
+| **compacted** — interior cells merged up the quadtree as far as they stay wholly on land; coast stays at level 6 | 10,046 | 6 MB | 3.5 MB |
+
+Both cover the identical 171.1M km² (149M km² of land + the seaward
+overhang of coastal cells), verified to 0 invalid geometries. Per-cell
+properties: `id` (compact), `path`, `addr64`, `rhombus_id`,
+`rhombus_hilbert`, `hex_id`, `level`, `interior`,
+`edge_km`, `area_km2`, `pole`, `xam`.
+
+TopoJSON is the recommended interchange form for grids: every triangle
+edge is shared by two cells, so arc deduplication cuts size ~40–60%. To
+make arcs shared even between *different-sized* neighbours in the
+compacted grid, edges are densified by recursive midpoint subdivision to a
+fixed sub-lattice — a large cell's boundary passes through its small
+neighbours' vertices bit-exactly.
+
+### Special cases
+
+* **Antimeridian.** Cells crossing ±180° are written with *continuous*
+  longitudes (e.g. `176 → 184`). This intentionally deviates from RFC 7946
+  §3.1.9 ("should be split"): splitting would destroy triangle semantics
+  and TopoJSON arc sharing, and MapLibre/Leaflet/deck.gl all render
+  continuous longitudes correctly. Cells carry `xam: true` so you can
+  re-split for strict-RFC consumers if needed. Classification of these
+  cells runs against land copies translated ±360°.
+* **Poles.** A pleasing accident of the icosahedron's geometry: in this
+  orientation both poles are *lattice vertices* (the south pole is exactly
+  the normalized midpoint of an icosahedron edge), so six triangles meet
+  at each pole. They are exported as meridian wedges reaching exactly ±90°
+  — like UTM-zone tips — and flagged `pole: "vertex"`. Classification near
+  the poles runs in polar azimuthal-equidistant frames, where lon/lat
+  pathologies do not exist.
+* **No samples, no shortcuts.** Land/sea classification is exact polygon
+  containment in an appropriate frame, not point sampling.
+
+---
+
+## 4. Suitable uses and limitations
+
+* **Lossless multi-resolution aggregation.** Sum level-9 statistics into
+  level-6 cells and the numbers are *exact* — no boundary slivers, no
+  overlap weighting. This differs from non-congruent hexagonal hierarchies.
+* **Variable-resolution coverage** (the compacted mode): one dataset,
+  coarse where uniform, fine where it matters, with cells that retain
+  shared boundaries. Database range scans over `addr64` retrieve
+  any subtree as one interval.
+* **Simplicial data structures.** Triangles are *the* primitive of
+  numerical geometry: FEM/FVM meshes, terrain TINs, barycentric
+  interpolation, subdivision surfaces. A triangular DGGS plugs into that
+  machinery directly; quads and hexes need conversion.
+* **Geodesic properties.** Cells are quasi-equilateral
+  everywhere — no polar singularity, no latitude-dependent area collapse
+  (a lon/lat grid cell at 80°N has ~17% of its equatorial area; Trifold
+  cells vary ~±20% worldwide, smoothly).
+* **Sampling designs and ecology-style survey grids**, where equal-ish
+  area and hierarchical refinement matter more than neighbour traversal.
+
+### Limitations
+
+* **Neighbour-heavy algorithms.** A triangle has 3 edge-neighbours but 9
+  more vertex-neighbours, and alternating up/down orientation makes
+  "movement" semantics less uniform. Hexagonal grids provide 6 uniform
+  neighbours for diffusion, routing, cellular automata, and related
+  analyses. (Neighbour traversal across icosahedron face boundaries is
+  also unimplemented here — see roadmap.)
+* **Choropleth presentation.** Triangle boundaries can be visually
+  prominent. Hexagonal grids may be easier to read for general-audience
+  choropleths.
+* **Anisotropy-sensitive statistics.** Up- and down-pointing cells are
+  congruent but rotated 60°; kernel-based methods that assume identical
+  cell orientation need care.
+* **Local analysis.** At city scale and below, a projected CRS and planar
+  grid may be simpler than a global DGGS.
+
+---
+
+## 5. The demo
+
+`docs/index.html` (GitHub Pages-ready, https://jaakla.github.io/trifold/)
+— a single self-contained landing page: the full introduction (concept,
+addressing, comparison, use cases, serving) with the interactive viewer
+embedded as its centerpiece:
+
+* **7 systems**: Trifold T3 triangles, [A5](https://a5geo.org) pentagons,
+  H3 hexagons, S2 quads (s2sphere), rHEALPix (aperture 9,
+  near-equal-area), HTM octahedral triangles (a related astronomy grid,
+  built with T3's own machinery), and lon/lat rectangles — same land,
+  same styling and land mask;
+* **globe ↔ flat** toggle (MapLibre GL v5 native globe and Mercator
+  projections);
+* compacted ↔ uncompacted, three triangle resolutions, click-for-address.
+
+A presentation can compare the systems in this order: lon/lat in Mercator
+and globe projections, S2, H3, A5, rHEALPix, HTM, and Trifold compacted.
+This sequence shows projection effects, area variation, parent-child
+geometry, and compact addressing.
+
+---
+
+## 6. Comparison with other DGGS
+
+| | **Trifold** (this) | **A5** (pentagon) | **H3** (hex) | **S2** (square) | **rHEALPix** | **Geohash / slippy** |
+|---|---|---|---|---|---|---|
+| cell shape | spherical triangle | equilateral pentagon | hexagon (+12 pentagons) | curvilinear quad | quad (squashed at caps) | lon/lat rect |
+| aperture | 4 | 4 (logical) | 7 | 4 | 9 | 4 (slippy) / 32 (geohash) |
+| **exact parent⊃child nesting** | **yes** | no (logical only, index-exact) | **no** (≈7 children, ragged) | yes (within face) | yes | yes (but planar) |
+| equal area | ~±20%, smooth | **exactly equal** per level | ~±35% across res; pentagons differ | up to ~2× corner/centre | **exactly equal-area** | varies with latitude |
+| neighbours | 3 edge + 9 vertex, mixed | 5, two distance classes | **6 uniform** | 4 + 4 | 4 + 4 | 4 + 4 |
+| pole handling | vertex wedges | regular cells | regular cells | face vertices | polar caps | **singular / degenerate** |
+| index arithmetic | uint64, prefix = subtree | uint64, Hilbert | uint64 | uint64, Hilbert | string/int | string prefix |
+| ecosystem | this repository | introduced in 2025 | widely used (Uber, DuckDB, BigQuery…) | widely used (Google, S2geometry) | academic, OGC-adopted | widely used |
+| typical uses | lossless hierarchy, simplicial/FEM work, multi-resolution coverage | equal-area statistics and visualization | neighbour operations, visualization, analytics joins | indexing, range queries, storage | equal-area statistics | tiling and prefix lookup |
+
+Selection depends on the application: **H3 provides uniform neighbour
+traversal and a mature ecosystem; S2 focuses on spatial indexing;
+rHEALPix and [A5](https://a5geo.org) provide equal-area cells.** Trifold
+focuses on exact hierarchical aggregation, variable-resolution tilings,
+and pipelines based on triangular geometry. The demo provides a visual
+comparison of these properties.
+
+Kin and prior art: OGC DGGS Abstract Specification (Topic 21); ISEA3H /
+DGGRID (icosahedral, aperture 3/4 hex); QTM (Dutton's Quaternary
+Triangular Mesh, an octahedron-based related scheme);
+SCENZ-Grid; HTM (Hierarchical Triangular Mesh, used in astronomy — also
+triangular aperture-4 and octahedron-based; Trifold uses an icosahedron,
+compact addressing, and web tooling. The demo includes
+an octahedral HTM layer for comparison); and
+[**A5**](https://a5geo.org) (Felix Palmer, 2025) — a dodecahedron-based
+pentagonal DGGS with a different hierarchy and area trade-off. It trades
+exact geometric nesting (its aperture-4 hierarchy is logical, with exact
+*index* prefixes but only approximate parent/child geometry) for
+**exactly equal-area cells** within each level via a Snyder-derived
+equal-area projection. Both systems use 64-bit integer indexing. A5 is
+included in the demo's comparison mode (`scripts/build_a5_layer.py`, using
+the official
+[`pya5`](https://pypi.org/project/pya5/) library).
+
+---
+
+## 7. Serving at scale
+
+Embedded TopoJSON is used in the demo for datasets up to about 30k cells
+or 10 MB. Larger datasets can use either of these serverless approaches:
+
+**Pregenerated PMTiles** — `scripts/make_pmtiles.sh` converts grid products
+to single-file vector-tile archives via tippecanoe and copies them to
+`docs/data/` for GitHub Pages. `make_site.py` detects matching archives in
+`data/` and uses them instead of embedding the corresponding TopoJSON.
+Set `TRIFOLD_PMTILES_BASE_URL` when the archives are hosted separately. Level 8 (~28 km,
+~440k land cells) tiles to a few tens of MB and supports full-grid display.
+
+**Dynamic generation** — `worker/cell-server.js`, deployable free with
+`npx wrangler deploy`. No stored data: cells are regenerated from pure
+math on every request and cached at the edge (`/cell/TF6958`,
+`/locate/lon,lat?level=N`, `/children/…`, `/cells/a,b,c`). This supports
+applications that know which addresses they need, for example from a
+database join on `addr64`, and fetch geometry lazily. The two approaches
+can be combined: PMTiles for full-grid display and the Worker for
+interactive lookup.
+
+---
+
+## 8. Subproject: landcheck — offline land/sea lookup
+
+A practical demonstration of exact nesting: the level-10 land
+classification (~6.15M land-touching cells) collapses into 153,884
+run-length intervals over the canonical cell index space — a **182 KB**
+bundled dataset that answers *"is this point on land?"* in ~1–13 µs,
+offline, in Python and JavaScript with identical results and a
+calibrated confidence per answer (measured 99.82% agreement with exact
+polygon containment; all residual error confined to self-flagged
+`coast` answers). An optional second file refines coastal answers with
+OSM simplified land polygons clipped per cell. See
+[landcheck/](landcheck/) and the
+[live in-browser demo](https://jaakla.github.io/trifold/landcheck.html)
+(classify sample or your own points on a map, with measured lookup rate).
+
+---
+
+## 9. Repository layout
+
+```
+src/trifold/        library: address.py · core.py · classify.py · grid.py · cli.py
+scripts/            build_grids.py · build_comparison_dggs.py · build_a5_layer.py · build_more_dggs.py · make_site.py · make_pmtiles.sh
+worker/             cell-server.js (Cloudflare Worker, zero-data cell API)
+landcheck/          offline land/sea point lookup (Python + JS + 182 KB data)
+docs/               index.html (landing page + demo — GitHub Pages ready) ·
+                    t3-technical-reference.md · img/
+data/               generated products (gitignored; see data/README.md)
+tests/              test_address.py
+```
+
+Quickstart:
+
+```bash
+poetry install --all-extras
+poetry run pytest tests/
+poetry run python scripts/build_grids.py --levels 4 5 6
+poetry run python scripts/build_comparison_dggs.py
+poetry run python scripts/build_a5_layer.py
+poetry run python scripts/build_more_dggs.py
+poetry run python scripts/make_site.py          # → docs/index.html
+```
+
+After `eval "$(poetry env activate)"`, omit `poetry run`:
+
+```bash
+pytest tests/
+python scripts/build_grids.py --levels 4 5 6
+python scripts/build_comparison_dggs.py
+python scripts/build_a5_layer.py
+python scripts/build_more_dggs.py       # S2 + rHEALPix + HTM layers
+python scripts/make_site.py              # → docs/index.html
+```
+
+---
+
+## Development environment
+
+Poetry is the recommended development environment:
+
+```bash
+poetry install --all-extras
+eval "$(poetry env activate)"  # activate in the current zsh/bash session
+```
+
+Poetry 2.x no longer includes `poetry shell` by default. It manages this
+environment itself and may not install `pip`; do not run pip installation
+commands while the prompt starts with `(trifold)`. Use `poetry add` to add
+dependencies, or `poetry run COMMAND` without activating the environment.
+
+Alternatively, use a standard virtual environment instead of Poetry:
+
+```bash
+deactivate 2>/dev/null || true  # leave the Poetry environment first
+python -m venv .venv-pip
+source .venv-pip/bin/activate
+python -m ensurepip --upgrade
+python -m pip install -e ".[build,dev]"
+```
+
+`tippecanoe` is required for `scripts/make_pmtiles.sh` (OS-level tool):
+
+```bash
+# macOS (Homebrew)
+brew install tippecanoe
+
+# Linux: build from source or use the docker image; the script assumes `tippecanoe` is on PATH
+```
+
+PMTiles are built from generated GeoJSON files. Generate those files
+first, then run `tippecanoe` through the wrapper:
+
+```bash
+python scripts/build_grids.py --levels 6
+./scripts/make_pmtiles.sh                 # all discovered global_tri_L*; skips existing archives
+python scripts/make_site.py
+```
+
+The wrapper auto-discovers every `data/global_tri_L*_*.geojson` product —
+nothing is hardcoded. By default it skips grids whose `.pmtiles` already
+exists; pass `--force` to rebuild. Restrict to specific levels with
+`--levels` (accepts `N`, `N-M`, `N-`, or `-M`):
+
+```bash
+./scripts/make_pmtiles.sh --levels 7      # just L7
+./scripts/make_pmtiles.sh -l 4-8          # L4 through L8
+./scripts/make_pmtiles.sh -l 6- --force   # L6 and up, rebuild even if present
+./scripts/make_pmtiles.sh --help          # full usage
+```
+
+The wrapper writes archives under both `data/` and `docs/data/`. The site
+generator detects matching PMTiles in `data/` and embeds
+TopoJSON only for datasets without an archive.
+
+The grid build requires the Natural Earth checkout described in
+Natural Earth 1:50m land data. The default build downloads and verifies the
+pinned v5.1.2 GeoJSON automatically. Use `--land PATH` to supply another
+local dataset instead.
+
+## 10. Roadmap
+
+* neighbour traversal across face boundaries (edge-adjacency tables)
+* level 7–9 products + PMTiles in CI
+* vectorized `locate` DuckDB UDF for `addr64` joins
+* optional ISEA-style equal-area variant (snyder projection per face)
+* polygon→cells fill (`polyfill` equivalent)
+
+## License
+
+MIT. Land data: [Natural Earth](https://www.naturalearthdata.com/) (public
+domain). Built with shapely, pyproj, geopandas, topojson, MapLibre GL,
+topojson-client, H3 (comparison layer).

package/js/trifold.d.ts

@@ -0,0 +1,60 @@
+export type CellIdentity = { face: number; digits: number[] };
+export type AddressLike = bigint | number | string | CellIdentity | [number, number[]];
+export type PolygonFeature = {
+  type: "Feature";
+  properties: Record<string, string | number | boolean>;
+  geometry: { type: "Polygon"; coordinates: number[][][] };
+};
+export type PolygonFeatureCollection = {
+  type: "FeatureCollection";
+  features: PolygonFeature[];
+};
+
+export const EARTH_RADIUS_KM: number;
+export const MAX_LEVEL: number;
+export const EXPORT_DEPTH: number;
+
+export function icosahedron(): { vertices: number[][]; faces: number[][] };
+export function subdivide(triangle: number[][]): number[][][];
+export function containsPoint(triangle: number[][], point: number[]): boolean;
+export function encode64(face: number, digits: number[]): bigint;
+export function decode64(address: bigint | number | string): CellIdentity;
+export function parseAddress(address: AddressLike): CellIdentity;
+export function toCompact(address: AddressLike): string;
+export function toCompact(face: number, digits: number[]): string;
+export function fromCompact(address: string): bigint;
+export function toPath(address: AddressLike): string;
+export function toPath(face: number, digits: number[]): string;
+export function fromPath(address: string): bigint;
+export function parent64(address: bigint | number | string): bigint;
+export function children64(address: bigint | number | string): bigint[];
+export function isAncestor(ancestor: bigint | number | string, descendant: bigint | number | string): boolean;
+export function descendantRange(address: bigint | number | string): [bigint, bigint];
+export function latticeTriangle(address: AddressLike): number[][];
+export function latticeTriangle(face: number, digits: number[]): number[][];
+export function rhombusCoords(address: AddressLike): {
+  diamond: number; level: number; x: number; y: number; orientation: number;
+};
+export function rhombusId(address: AddressLike): string;
+export function rhombus64(address: AddressLike): bigint;
+export function decodeRhombus64(address: bigint | number | string): {
+  diamond: number; level: number; x: number; y: number;
+};
+export function hexId(address: AddressLike): string;
+export function cellTriangle(address: AddressLike): number[][];
+export function cellTriangle(face: number, digits: number[]): number[][];
+export function locate(lon: number, lat: number, level: number): CellIdentity;
+export function locateAddress(lon: number, lat: number, level: number): bigint;
+export function edgeKm(triangle: number[][]): number;
+export function areaKm2(triangle: number[][]): number;
+export function cellRing(address: AddressLike, options?: { depth?: number; precision?: number }): number[][];
+export function cellMetrics(address: AddressLike): {
+  id: string; path: string; addr64: bigint; face: number; level: number;
+  rhombusId: string; rhombusHilbert: bigint; hexId: string;
+  edgeKm: number; areaKm2: number;
+};
+export function cellFeature(address: AddressLike, options?: { precision?: number }): PolygonFeature;
+export function levelFeatureCollection(
+  level: number,
+  options?: { face?: number | null; maxLevel?: number },
+): PolygonFeatureCollection;

package/js/trifold.js

@@ -0,0 +1,650 @@
+/**
+ * Trifold JavaScript SDK.
+ *
+ * This module has no runtime dependencies and works in browsers, Node.js,
+ * service workers, and Cloudflare Workers. Addresses are represented as
+ * BigInt values in code and decimal strings in GeoJSON properties.
+ */
+
+export const EARTH_RADIUS_KM = 6371.0088;
+export const MAX_LEVEL = 27;
+export const EXPORT_DEPTH = 8;
+
+const LEVEL_BITS = 5n;
+const PATH_BITS = 2n * BigInt(MAX_LEVEL);
+const PATH_MASK = (1n << PATH_BITS) - 1n;
+const LON_ROT = 7.3 * Math.PI / 180;
+const B32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const B32_INV = Object.fromEntries([...B32].map((char, index) => [char, index]));
+Object.assign(B32_INV, { I: 1, L: 1, O: 0, U: 27 });
+
+const add = (a, b) => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+const cross = (a, b) => [
+  a[1] * b[2] - a[2] * b[1],
+  a[2] * b[0] - a[0] * b[2],
+  a[0] * b[1] - a[1] * b[0],
+];
+
+function norm(point) {
+  const length = Math.hypot(point[0], point[1], point[2]);
+  return [point[0] / length, point[1] / length, point[2] / length];
+}
+
+function validateIdentity(face, digits) {
+  if (!Number.isInteger(face) || face < 0 || face >= 20) {
+    throw new RangeError(`face ${face} is outside 0..19`);
+  }
+  if (!Array.isArray(digits) || digits.length > MAX_LEVEL) {
+    throw new RangeError(`path level must be within 0..${MAX_LEVEL}`);
+  }
+  for (const digit of digits) {
+    if (!Number.isInteger(digit) || digit < 0 || digit > 3) {
+      throw new RangeError(`path digit ${digit} is outside 0..3`);
+    }
+  }
+  return { face, digits: [...digits] };
+}
+
+/** Return the rotated unit icosahedron used by Trifold. */
+export function icosahedron() {
+  const phi = (1 + Math.sqrt(5)) / 2;
+  let vertices = [
+    [-1, phi, 0], [1, phi, 0], [-1, -phi, 0], [1, -phi, 0],
+    [0, -1, phi], [0, 1, phi], [0, -1, -phi], [0, 1, -phi],
+    [phi, 0, -1], [phi, 0, 1], [-phi, 0, -1], [-phi, 0, 1],
+  ].map(norm);
+  const cos = Math.cos(LON_ROT);
+  const sin = Math.sin(LON_ROT);
+  vertices = vertices.map(point => [
+    point[0] * cos - point[1] * sin,
+    point[0] * sin + point[1] * cos,
+    point[2],
+  ]);
+  const faces = [
+    [0, 11, 5], [0, 5, 1], [0, 1, 7], [0, 7, 10], [0, 10, 11],
+    [1, 5, 9], [5, 11, 4], [11, 10, 2], [10, 7, 6], [7, 1, 8],
+    [3, 9, 4], [3, 4, 2], [3, 2, 6], [3, 6, 8], [3, 8, 9],
+    [4, 9, 5], [2, 4, 11], [6, 2, 10], [8, 6, 7], [9, 8, 1],
+  ];
+  return { vertices, faces };
+}
+
+const ICO = icosahedron();
+const NORTH = [0, 0, 1];
+const SOUTH = [0, 0, -1];
+const DIAMONDS = [
+  [0, 1, [0, 5]], [2, 3, [0, 7]], [4, 7, [10, 11]],
+  [5, 15, [5, 9]], [6, 16, [4, 11]], [8, 17, [6, 10]],
+  [9, 18, [7, 8]], [10, 11, [3, 4]], [12, 13, [3, 6]],
+  [14, 19, [8, 9]],
+];
+const FACE_DIAMOND = Array(20);
+DIAMONDS.forEach(([faceA, faceB, edge], diamond) => {
+  FACE_DIAMOND[faceA] = { diamond, half: 0, edge };
+  FACE_DIAMOND[faceB] = { diamond, half: 1, edge };
+});
+
+/** Split a spherical triangle into its four aperture-4 children. */
+export function subdivide(triangle) {
+  const [v0, v1, v2] = triangle;
+  const m01 = norm(add(v0, v1));
+  const m12 = norm(add(v1, v2));
+  const m20 = norm(add(v2, v0));
+  return [[v0, m01, m20], [m01, v1, m12], [m20, m12, v2], [m01, m12, m20]];
+}
+
+/** Test whether a unit vector lies inside a spherical triangle. */
+export function containsPoint(triangle, point) {
+  return dot(cross(triangle[0], triangle[1]), point) >= -1e-14 &&
+    dot(cross(triangle[1], triangle[2]), point) >= -1e-14 &&
+    dot(cross(triangle[2], triangle[0]), point) >= -1e-14;
+}
+
+/** Encode a face and base-4 path as an addr64 BigInt. */
+export function encode64(face, digits) {
+  const identity = validateIdentity(face, digits);
+  let path = 0n;
+  for (const digit of identity.digits) path = (path << 2n) | BigInt(digit);
+  path <<= 2n * BigInt(MAX_LEVEL - identity.digits.length);
+  return (BigInt(identity.face) << 59n) | (path << LEVEL_BITS) |
+    BigInt(identity.digits.length);
+}
+
+/** Decode an addr64 value to `{face, digits}`. */
+export function decode64(address) {
+  if (typeof address === "number" && !Number.isSafeInteger(address)) {
+    throw new RangeError("numeric addr64 values must be safe integers; use BigInt or string");
+  }
+  const value = typeof address === "bigint" ? address : BigInt(address);
+  if (value < 0n || value >= (1n << 64n)) throw new RangeError("addr64 is outside uint64");
+  const face = Number((value >> 59n) & 31n);
+  const level = Number(value & 31n);
+  if (face >= 20 || level > MAX_LEVEL) throw new RangeError("invalid addr64 value");
+  const path = (value >> LEVEL_BITS) & PATH_MASK;
+  const digits = [];
+  for (let index = 0; index < level; index++) {
+    const shift = PATH_BITS - 2n * BigInt(index + 1);
+    digits.push(Number((path >> shift) & 3n));
+  }
+  return { face, digits };
+}
+
+/** Parse compact, path, addr64, or `{face, digits}` input. */
+export function parseAddress(address) {
+  if (typeof address === "bigint" || typeof address === "number") return decode64(address);
+  if (Array.isArray(address) && address.length === 2) {
+    return validateIdentity(Number(address[0]), [...address[1]].map(Number));
+  }
+  if (address && typeof address === "object" && "face" in address && "digits" in address) {
+    return validateIdentity(Number(address.face), [...address.digits].map(Number));
+  }
+  if (typeof address !== "string") throw new TypeError("unsupported address value");
+  const text = decodeURIComponent(address).trim().toUpperCase();
+  if (text.startsWith("F")) {
+    const [head, tail = ""] = text.split("-");
+    if (!/^F\d{1,2}$/.test(head) || !/^[0-3]*$/.test(tail)) {
+      throw new Error(`invalid path address ${address}`);
+    }
+    return validateIdentity(Number(head.slice(1)), [...tail].map(Number));
+  }
+  if (!text.startsWith("T") || text.length < 3) {
+    if (/^\d+$/.test(text)) return decode64(BigInt(text));
+    throw new Error(`invalid compact address ${address}`);
+  }
+  const face = B32_INV[text[1]];
+  const level = B32_INV[text[2]];
+  if (face === undefined || level === undefined || face >= 20 || level > MAX_LEVEL) {
+    throw new Error(`invalid compact address ${address}`);
+  }
+  const bitCount = 2 * level;
+  const charCount = Math.ceil(bitCount / 5);
+  if (text.length !== 3 + charCount) throw new Error("invalid compact address length");
+  let bits = 0n;
+  for (const char of text.slice(3)) {
+    if (B32_INV[char] === undefined) throw new Error(`invalid base32 character ${char}`);
+    bits = (bits << 5n) | BigInt(B32_INV[char]);
+  }
+  bits >>= BigInt(charCount * 5 - bitCount);
+  const digits = [];
+  for (let index = level - 1; index >= 0; index--) {
+    digits.push(Number((bits >> BigInt(2 * index)) & 3n));
+  }
+  return validateIdentity(face, digits);
+}
+
+function identityFromArgs(addressOrFace, digits) {
+  return Array.isArray(digits)
+    ? validateIdentity(addressOrFace, digits)
+    : parseAddress(addressOrFace);
+}
+
+/** Convert an address to compact Crockford base32. */
+export function toCompact(addressOrFace, digits) {
+  const identity = identityFromArgs(addressOrFace, digits);
+  const level = identity.digits.length;
+  const bitCount = 2 * level;
+  const charCount = Math.ceil(bitCount / 5);
+  let bits = 0n;
+  for (const digit of identity.digits) bits = (bits << 2n) | BigInt(digit);
+  bits <<= BigInt(charCount * 5 - bitCount);
+  let text = `T${B32[identity.face]}${B32[level]}`;
+  for (let index = charCount - 1; index >= 0; index--) {
+    text += B32[Number((bits >> BigInt(5 * index)) & 31n)];
+  }
+  return text;
+}
+
+export function fromCompact(address) {
+  if (typeof address !== "string" || !address.trim().toUpperCase().startsWith("T")) {
+    throw new Error("compact addresses start with T");
+  }
+  return encode64(...identityTuple(parseAddress(address)));
+}
+
+/** Convert an address to the `Fxx-digits` path form. */
+export function toPath(addressOrFace, digits) {
+  const identity = identityFromArgs(addressOrFace, digits);
+  return `F${String(identity.face).padStart(2, "0")}-${identity.digits.join("")}`;
+}
+
+export function fromPath(address) {
+  if (typeof address !== "string" || !address.trim().toUpperCase().startsWith("F")) {
+    throw new Error("path addresses start with F");
+  }
+  return encode64(...identityTuple(parseAddress(address)));
+}
+
+function identityTuple(identity) {
+  return [identity.face, identity.digits];
+}
+
+export function parent64(address) {
+  const { face, digits } = decode64(address);
+  if (!digits.length) throw new RangeError("level-0 cell has no parent");
+  return encode64(face, digits.slice(0, -1));
+}
+
+export function children64(address) {
+  const { face, digits } = decode64(address);
+  if (digits.length >= MAX_LEVEL) throw new RangeError("cell is at the maximum level");
+  return [0, 1, 2, 3].map(digit => encode64(face, [...digits, digit]));
+}
+
+export function isAncestor(ancestor, descendant) {
+  const a = decode64(ancestor);
+  const b = decode64(descendant);
+  return a.face === b.face && a.digits.length <= b.digits.length &&
+    a.digits.every((digit, index) => digit === b.digits[index]);
+}
+
+export function descendantRange(address) {
+  const { face, digits } = decode64(address);
+  const value = encode64(face, digits);
+  const suffixBits = PATH_BITS - 2n * BigInt(digits.length);
+  const path = (value >> LEVEL_BITS) & PATH_MASK;
+  const highPath = path | (suffixBits ? (1n << suffixBits) - 1n : 0n);
+  return [value, (BigInt(face) << 59n) | (highPath << LEVEL_BITS) | BigInt(MAX_LEVEL)];
+}
+
+/** Return exact integer barycentric vertices for one triangle. */
+export function latticeTriangle(addressOrFace, digits) {
+  const identity = identityFromArgs(addressOrFace, digits);
+  let vertices = [[1, 0, 0], [0, 1, 0], [0, 0, 1]];
+  for (const digit of identity.digits) {
+    const [v0, v1, v2] = vertices;
+    const doubled = vertices.map(vertex => vertex.map(value => 2 * value));
+    const midpoint = (a, b) => a.map((value, index) => value + b[index]);
+    const m01 = midpoint(v0, v1);
+    const m12 = midpoint(v1, v2);
+    const m20 = midpoint(v2, v0);
+    vertices = [
+      [doubled[0], m01, m20],
+      [m01, doubled[1], m12],
+      [m20, m12, doubled[2]],
+      [m01, m12, m20],
+    ][digit];
+  }
+  return vertices;
+}
+
+function hilbertXYToIndex(level, inputX, inputY) {
+  let x = inputX;
+  let y = inputY;
+  let index = 0n;
+  for (let scale = Math.floor((2 ** level) / 2); scale > 0; scale = Math.floor(scale / 2)) {
+    const rx = x & scale ? 1 : 0;
+    const ry = y & scale ? 1 : 0;
+    index += BigInt(scale) * BigInt(scale) * BigInt((3 * rx) ^ ry);
+    if (ry === 0) {
+      if (rx === 1) {
+        x = scale - 1 - x;
+        y = scale - 1 - y;
+      }
+      [x, y] = [y, x];
+    }
+  }
+  return index;
+}
+
+function hilbertIndexToXY(level, inputIndex) {
+  const size = 2 ** level;
+  let x = 0;
+  let y = 0;
+  let value = inputIndex;
+  for (let scale = 1; scale < size; scale *= 2) {
+    const rx = Number(1n & (value >> 1n));
+    const ry = Number(1n & (value ^ BigInt(rx)));
+    if (ry === 0) {
+      if (rx === 1) {
+        x = scale - 1 - x;
+        y = scale - 1 - y;
+      }
+      [x, y] = [y, x];
+    }
+    x += scale * rx;
+    y += scale * ry;
+    value >>= 2n;
+  }
+  return [x, y];
+}
+
+/** Map a triangle to `{diamond, level, x, y, orientation}`. */
+export function rhombusCoords(address) {
+  const identity = parseAddress(address);
+  const size = 2 ** identity.digits.length;
+  const { diamond, half, edge } = FACE_DIAMOND[identity.face];
+  const faceVertices = ICO.faces[identity.face];
+  const edgeIndexes = edge.map(vertex => faceVertices.indexOf(vertex));
+  const points = latticeTriangle(identity).map(barycentric => {
+    let x = barycentric[edgeIndexes[0]];
+    let y = barycentric[edgeIndexes[1]];
+    if (half) [x, y] = [size - y, size - x];
+    return [x, y];
+  });
+  const x = Math.min(...points.map(point => point[0]));
+  const y = Math.min(...points.map(point => point[1]));
+  const orientation = points.some(point => point[0] === x && point[1] === y) ? 0 : 1;
+  return { diamond, level: identity.digits.length, x, y, orientation };
+}
+
+/** Return the human-readable ID shared by an exact triangle pair. */
+export function rhombusId(address) {
+  const { diamond, level, x, y } = rhombusCoords(address);
+  return `R${String(diamond).padStart(2, "0")}-${String(level).padStart(2, "0")}-${x}-${y}`;
+}
+
+/** Return the Hilbert-linearized BigInt key shared by an exact triangle pair. */
+export function rhombus64(address) {
+  const { diamond, level, x, y } = rhombusCoords(address);
+  const hilbert = hilbertXYToIndex(level, x, y) << BigInt(2 * (MAX_LEVEL - level));
+  return (BigInt(diamond) << 59n) | (hilbert << LEVEL_BITS) | BigInt(level);
+}
+
+/** Decode a rhombus64 key to `{diamond, level, x, y}`. */
+export function decodeRhombus64(address) {
+  const value = typeof address === "bigint" ? address : BigInt(address);
+  if (value < 0n || value >= (1n << 63n)) throw new RangeError("rhombus64 is outside its 63-bit range");
+  const diamond = Number((value >> 59n) & 15n);
+  const level = Number(value & 31n);
+  if (diamond >= DIAMONDS.length || level > MAX_LEVEL) throw new RangeError("invalid rhombus64 value");
+  const hilbert = ((value >> LEVEL_BITS) & PATH_MASK) >> BigInt(2 * (MAX_LEVEL - level));
+  const [x, y] = hilbertIndexToXY(level, hilbert);
+  return { diamond, level, x, y };
+}
+
+function canonicalVertexId(face, level, barycentric) {
+  const faceVertices = ICO.faces[face];
+  const nonzero = barycentric.map((value, index) => value ? index : -1)
+    .filter(index => index >= 0);
+  if (nonzero.length === 1) {
+    return `HV${String(faceVertices[nonzero[0]]).padStart(2, "0")}-${String(level).padStart(2, "0")}`;
+  }
+  if (nonzero.length === 2) {
+    const [first, second] = nonzero;
+    const vertexA = faceVertices[first];
+    const vertexB = faceVertices[second];
+    const [low, high] = [vertexA, vertexB].sort((a, b) => a - b);
+    const highIndex = vertexA === high ? first : second;
+    return `HE${String(low).padStart(2, "0")}${String(high).padStart(2, "0")}-${String(level).padStart(2, "0")}-${barycentric[highIndex]}`;
+  }
+  return `HF${String(face).padStart(2, "0")}-${String(level).padStart(2, "0")}-${barycentric.join("-")}`;
+}
+
+/** Return a per-level display-group key with six-triangle face interiors. */
+export function hexId(address) {
+  const identity = parseAddress(address);
+  const centers = latticeTriangle(identity)
+    .filter(vertex => (vertex[1] + 2 * vertex[2]) % 3 === 0);
+  if (centers.length !== 1) throw new Error("triangle lattice coloring must select one vertex");
+  return canonicalVertexId(identity.face, identity.digits.length, centers[0]);
+}
+
+/** Return the spherical triangle for an address. */
+export function cellTriangle(addressOrFace, digits) {
+  const identity = identityFromArgs(addressOrFace, digits);
+  const [i, j, k] = ICO.faces[identity.face];
+  let triangle = [ICO.vertices[i], ICO.vertices[j], ICO.vertices[k]];
+  for (const digit of identity.digits) triangle = subdivide(triangle)[digit];
+  return triangle;
+}
+
+/** Locate a point and return `{face, digits}`. */
+export function locate(lon, lat, level) {
+  if (!Number.isFinite(lon) || lon < -180 || lon > 180) {
+    throw new RangeError("longitude must be within [-180, 180]");
+  }
+  if (!Number.isFinite(lat) || lat < -90 || lat > 90) {
+    throw new RangeError("latitude must be within [-90, 90]");
+  }
+  if (!Number.isInteger(level) || level < 0 || level > MAX_LEVEL) {
+    throw new RangeError(`level must be within 0..${MAX_LEVEL}`);
+  }
+  const lambda = lon * Math.PI / 180;
+  const phi = lat * Math.PI / 180;
+  const point = [Math.cos(phi) * Math.cos(lambda), Math.cos(phi) * Math.sin(lambda), Math.sin(phi)];
+  let face = -1;
+  let triangle = null;
+  for (let index = 0; index < 20; index++) {
+    const candidate = cellTriangle(index, []);
+    if (containsPoint(candidate, point)) {
+      face = index;
+      triangle = candidate;
+      break;
+    }
+  }
+  if (face < 0) {
+    let best = -2;
+    for (let index = 0; index < 20; index++) {
+      const [i, j, k] = ICO.faces[index];
+      const centre = norm(add(add(ICO.vertices[i], ICO.vertices[j]), ICO.vertices[k]));
+      const score = dot(centre, point);
+      if (score > best) {
+        best = score;
+        face = index;
+      }
+    }
+    triangle = cellTriangle(face, []);
+  }
+  const digits = [];
+  for (let current = 0; current < level; current++) {
+    const children = subdivide(triangle);
+    let selected = -1;
+    let bestMargin = -2;
+    for (let digit = 0; digit < 4; digit++) {
+      const child = children[digit];
+      const margin = Math.min(
+        dot(cross(child[0], child[1]), point),
+        dot(cross(child[1], child[2]), point),
+        dot(cross(child[2], child[0]), point),
+      );
+      if (margin >= -1e-14) {
+        selected = digit;
+        break;
+      }
+      if (margin > bestMargin) {
+        bestMargin = margin;
+        selected = digit;
+      }
+    }
+    digits.push(selected);
+    triangle = children[selected];
+  }
+  return { face, digits };
+}
+
+export function locateAddress(lon, lat, level) {
+  const identity = locate(lon, lat, level);
+  return encode64(identity.face, identity.digits);
+}
+
+export function edgeKm(triangle) {
+  const edges = [[triangle[0], triangle[1]], [triangle[1], triangle[2]], [triangle[2], triangle[0]]];
+  const angles = edges.map(([a, b]) => Math.acos(Math.max(-1, Math.min(1, dot(a, b)))));
+  return angles.reduce((sum, angle) => sum + angle, 0) / angles.length * EARTH_RADIUS_KM;
+}
+
+export function areaKm2(triangle) {
+  const angle = (a, b, c) => {
+    const n1 = cross(a, b);
+    const n2 = cross(a, c);
+    return Math.acos(Math.max(-1, Math.min(1,
+      dot(n1, n2) / (Math.hypot(...n1) * Math.hypot(...n2)))));
+  };
+  const excess = angle(triangle[0], triangle[1], triangle[2]) +
+    angle(triangle[1], triangle[2], triangle[0]) +
+    angle(triangle[2], triangle[0], triangle[1]) - Math.PI;
+  return excess * EARTH_RADIUS_KM ** 2;
+}
+
+function edgePoints(a, b, halvings) {
+  if (halvings <= 0) return [a];
+  const midpoint = norm(add(a, b));
+  return [...edgePoints(a, midpoint, halvings - 1), ...edgePoints(midpoint, b, halvings - 1)];
+}
+
+function toLonLat(point) {
+  return [
+    Math.atan2(point[1], point[0]) * 180 / Math.PI,
+    Math.asin(Math.max(-1, Math.min(1, point[2]))) * 180 / Math.PI,
+  ];
+}
+
+function recenter(ring) {
+  const mean = ring.reduce((sum, point) => sum + point[0], 0) / ring.length;
+  let shift = 0;
+  while (mean + shift > 180) shift -= 360;
+  while (mean + shift <= -180) shift += 360;
+  return ring.map(([lon, lat]) => [lon + shift, lat]);
+}
+
+function unwrap(points) {
+  const ring = [];
+  let previous = null;
+  let offset = 0;
+  for (const point of points) {
+    let [lon, lat] = toLonLat(point);
+    lon += offset;
+    if (previous !== null) {
+      while (lon - previous > 180) { lon -= 360; offset -= 360; }
+      while (lon - previous < -180) { lon += 360; offset += 360; }
+    }
+    ring.push([lon, lat]);
+    previous = lon;
+  }
+  return recenter(ring);
+}
+
+function exportRing(points, triangle) {
+  const poleIndexes = points.map((point, index) => Math.abs(point[2]) >= 1 - 1e-9 ? index : -1)
+    .filter(index => index >= 0);
+  if (poleIndexes.length) {
+    const poleLatitude = points[poleIndexes[0]][2] > 0 ? 90 : -90;
+    const poleSet = new Set(poleIndexes);
+    const longitudes = {};
+    let previous = null;
+    let offset = 0;
+    for (let index = 0; index < points.length; index++) {
+      if (poleSet.has(index)) continue;
+      let [lon, lat] = toLonLat(points[index]);
+      lon += offset;
+      if (previous !== null) {
+        while (lon - previous > 180) { lon -= 360; offset -= 360; }
+        while (lon - previous < -180) { lon += 360; offset += 360; }
+      }
+      longitudes[index] = [lon, lat];
+      previous = lon;
+    }
+    const ring = [];
+    const count = points.length;
+    for (let index = 0; index < count; index++) {
+      if (!poleSet.has(index)) {
+        ring.push(longitudes[index]);
+        continue;
+      }
+      let before = (index - 1 + count) % count;
+      let after = (index + 1) % count;
+      while (poleSet.has(before)) before = (before - 1 + count) % count;
+      while (poleSet.has(after)) after = (after + 1) % count;
+      ring.push([longitudes[before][0], poleLatitude], [longitudes[after][0], poleLatitude]);
+    }
+    return { ring: recenter(ring), pole: "vertex" };
+  }
+  if (containsPoint(triangle, NORTH) || containsPoint(triangle, SOUTH)) {
+    const north = containsPoint(triangle, NORTH);
+    const poleLatitude = north ? 90 : -90;
+    const ring = points.map(toLonLat).sort((a, b) => a[0] - b[0]);
+    ring.push([180, poleLatitude], [-180, poleLatitude]);
+    return { ring, pole: "interior" };
+  }
+  return { ring: unwrap(points), pole: "" };
+}
+
+/** Return a closed cell boundary as continuous-longitude coordinates. */
+export function cellRing(address, { depth = EXPORT_DEPTH, precision = 6 } = {}) {
+  const identity = parseAddress(address);
+  const triangle = cellTriangle(identity);
+  const halvings = Math.max(0, depth - identity.digits.length);
+  const points = [
+    ...edgePoints(triangle[0], triangle[1], halvings),
+    ...edgePoints(triangle[1], triangle[2], halvings),
+    ...edgePoints(triangle[2], triangle[0], halvings),
+  ];
+  const exported = exportRing(points, triangle);
+  const ring = exported.ring.map(([lon, lat]) => [
+    Number(lon.toFixed(precision)),
+    Number(lat.toFixed(precision)),
+  ]);
+  ring.push([...ring[0]]);
+  return ring;
+}
+
+export function cellMetrics(address) {
+  const identity = parseAddress(address);
+  const value = encode64(identity.face, identity.digits);
+  const triangle = cellTriangle(identity);
+  return {
+    id: toCompact(identity),
+    path: toPath(identity),
+    addr64: value,
+    rhombusId: rhombusId(identity),
+    rhombusHilbert: rhombus64(identity),
+    hexId: hexId(identity),
+    face: identity.face,
+    level: identity.digits.length,
+    edgeKm: edgeKm(triangle),
+    areaKm2: areaKm2(triangle),
+  };
+}
+
+/** Return a GeoJSON Feature for one address. */
+export function cellFeature(address, { precision = 6 } = {}) {
+  const identity = parseAddress(address);
+  const value = encode64(identity.face, identity.digits);
+  const triangle = cellTriangle(identity);
+  const halvings = Math.max(0, EXPORT_DEPTH - identity.digits.length);
+  const points = [
+    ...edgePoints(triangle[0], triangle[1], halvings),
+    ...edgePoints(triangle[1], triangle[2], halvings),
+    ...edgePoints(triangle[2], triangle[0], halvings),
+  ];
+  const exported = exportRing(points, triangle);
+  const ring = exported.ring.map(([lon, lat]) => [
+    Number(lon.toFixed(precision)),
+    Number(lat.toFixed(precision)),
+  ]);
+  ring.push([...ring[0]]);
+  return {
+    type: "Feature",
+    properties: {
+      id: toCompact(identity),
+      path: toPath(identity),
+      addr64: value.toString(),
+      rhombus_id: rhombusId(identity),
+      rhombus_hilbert: rhombus64(identity).toString(),
+      hex_id: hexId(identity),
+      level: identity.digits.length,
+      pole: exported.pole,
+    },
+    geometry: { type: "Polygon", coordinates: [ring] },
+  };
+}
+
+/** Enumerate all cells on one face, or all faces, at a uniform level. */
+export function levelFeatureCollection(level, { face = null, maxLevel = 5 } = {}) {
+  if (!Number.isInteger(level) || level < 0 || level > maxLevel) {
+    throw new RangeError(`level must be within 0..${maxLevel}`);
+  }
+  const faces = face === null ? [...Array(20).keys()] : [Number(face)];
+  faces.forEach(value => validateIdentity(value, []));
+  const features = [];
+  const generate = (currentFace, digits) => {
+    if (digits.length === level) {
+      features.push(cellFeature({ face: currentFace, digits }));
+      return;
+    }
+    for (let digit = 0; digit < 4; digit++) generate(currentFace, [...digits, digit]);
+  };
+  for (const currentFace of faces) generate(currentFace, []);
+  return { type: "FeatureCollection", features };
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "t3grid",
+  "version": "0.1.0",
+  "description": "Trifold T3: dependency-free JavaScript SDK for a hierarchical triangular DGGS with exact aperture-4 nesting",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./js/trifold.d.ts",
+      "default": "./js/trifold.js"
+    }
+  },
+  "types": "./js/trifold.d.ts",
+  "files": [
+    "js/trifold.js",
+    "js/trifold.d.ts"
+  ],
+  "keywords": [
+    "dggs",
+    "geospatial",
+    "triangular-grid",
+    "global-grid",
+    "icosahedron",
+    "h3-alternative",
+    "spatial-index"
+  ],
+  "homepage": "https://jaakla.github.io/trifold/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jaakla/trifold.git"
+  },
+  "license": "MIT"
+}