@zukall/zap 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zukall Addressing Protocol 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/PROTOCOL-V1.md

@@ -0,0 +1,117 @@
+# ZAP protocol version 1
+
+ZAP stands for **Zukall Address Protocol**. The npm package version and protocol
+version are separate. This specification describes the bundled version-1 grid
+and projection rules.
+
+## Address representation
+
+Address text ends with `ZAP`. Result metadata identifies the protocol as `ZAP`;
+`ZAP_PROTOCOL.addressSuffix` exposes the suffix.
+
+Country-wide grid:
+
+```text
+<northSouthMeters> <N|S> <eastWestMeters> <E|W>, <countryCode>, ZAP
+```
+
+Province grid:
+
+```text
+<northSouthMeters> <N|S> <eastWestMeters> <E|W>, <provinceCode>, <countryCode>, ZAP
+```
+
+Fields are separated by a comma and one ASCII space. Offset magnitudes and their
+directions are separated by one ASCII space within the first field. Country and
+province codes are normalized
+to uppercase and must exist in the bundled snapshot. Source-specific province
+codes, including `NE_` codes and leading-zero strings, are retained.
+
+Offsets are nonnegative integer magnitudes in whole meters. `S` and `W` denote
+negative signed offsets. Zero uses `N` and `E`; the numerical result normalizes
+negative zero. The string identifies a cell under the associated grid rules.
+
+## Inputs and grid selection
+
+- Coordinates are WGS84 decimal degrees, with finite numeric latitude in
+  `[-90, 90]` and longitude in `[-180, 180]`.
+- The interval is an integer from 1 through 1000 meters, defaulting to 5.
+- Selection is explicit: province-grid countries require a configured province;
+  country-wide grids reject a province selection.
+- A point must be inside the selected rectangle, including its edges. This is a
+  rectangle check, not an administrative-boundary or land-membership test.
+
+Corners are ordered top-left, top-right, bottom-right, bottom-left. They describe
+latitude/longitude-aligned rectangles. A western longitude greater than the
+eastern longitude denotes a date-line crossing. The explicit `-180` to `180`
+rectangle denotes a full 360-degree span. Other supported spans are greater than
+zero and below 180 degrees.
+
+The grid center is the midpoint of the north/south bounds and the midpoint of the
+wrapped longitude span, with center longitude normalized to `[-180, 180)`.
+
+## Projection and snapping
+
+The projection is spherical azimuthal equidistant, identified as
+`AEQD-SPHERE-v1`, with mean Earth radius **6,371,008.8 meters**. It is centered on
+the selected rectangle's center.
+
+For location latitude `φ`, origin latitude `φ₀`, and longitude difference `Δλ`
+(all in radians), define:
+
+```text
+eastComponent  = cos(φ) × sin(Δλ)
+northComponent = cos(φ₀) × sin(φ) − sin(φ₀) × cos(φ) × cos(Δλ)
+cosAngle       = sin(φ₀) × sin(φ) + cos(φ₀) × cos(φ) × cos(Δλ)
+sinAngle       = hypot(eastComponent, northComponent)
+angle          = atan2(sinAngle, cosAngle)
+scale          = angle / sinAngle
+```
+
+For `sinAngle < 1e-15`, use `scale = 1`. Points within `1e-10` radians of the
+antipode are rejected because the projection is singular there.
+
+```text
+northing = radius × scale × northComponent
+easting  = radius × scale × eastComponent
+snapped  = Math.round(offset / interval) × interval
+```
+
+Halfway ties round toward the positive axis, following JavaScript `Math.round`.
+Snapping is in the projected plane; the interval is not a promise of uniform
+ground dimensions everywhere in a large grid. Original coordinates remain in
+the result.
+
+Approximate rectangle width follows a parallel at the center latitude; height
+follows a meridian. Both are rounded to whole meters in the result.
+
+## Identity and persistence
+
+Every result includes:
+
+```text
+protocol = ZAP
+protocolVersion = 1
+gridId = ZAP:1:<country/province prefix>:<country snapshot version>:<grid snapshot version>:AEQD-SPHERE-v1:6371008.8:<center latitude>:<center longitude>:<interval>:nearest-positive-tie
+```
+
+Numeric identity components use JavaScript's canonical number-to-string
+representation. Treat `gridId` as opaque and persist it alongside the address,
+original coordinates, and grid interval. The plain address does not encode its
+snapshot, origin, or interval; cell identity includes both `gridId` and address.
+
+The bundled bounds and versions are immutable at runtime. Never change bounds
+under an existing snapshot version. A change to projection, radius, rounding,
+or canonical representation requires a protocol version review. Preserve old
+configuration snapshots when interpreting previously issued addresses.
+
+## Snapshot coverage
+
+The package contains 239 country/territory entries: 217 country-wide grids and
+22 countries with 530 province grids. Thirteen additional Natural Earth source
+areas are exported separately and are outside address generation.
+
+Coverage reflects the supplied Natural Earth snapshot, including historical
+divisions and map conventions. See the exported `provinceDataNotes` and
+[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md). The package does not infer or
+certify sovereignty, current administrative membership, or postal deliverability.

package/PROTOCOL.md

@@ -0,0 +1,176 @@
+# ZAP — Zukall Addressing Protocol, version 2
+
+Protocol 2 uses **100-meter grid blocks** and **1-meter detail**, computed from
+unrounded projected GPS coordinates. The npm package version (`0.2.1`) and
+protocol version (`2`) are separate. Previously issued protocol-1 addresses retain
+their original text and identity; see [PROTOCOL-V1.md](PROTOCOL-V1.md).
+
+## Display representation
+
+```text
+<northSouthBlock> <N|S> <eastWestBlock> <E|W> #<northSouthRemainder>-<eastWestRemainder>, <city>, <provinceCode> <countryCode> ZAP
+```
+
+City and province are optional display components. A province code is required
+when the selected country has province grids. Omit unavailable components,
+including their punctuation. The location tail uses single spaces, not commas:
+
+```text
+1194 S 382 E #16-20, Kampala, UG ZAP
+2106 S 3614 E #22-64, Miami, FL US ZAP
+580 S 770 E #43-46, HT ZAP
+0 N 0 E #03-06, UG ZAP
+0 S 0 W #00-00, UG ZAP
+```
+
+These illustrate the encoding; city labels do not certify a point's location.
+Blocks have an unrestricted number of decimal digits. Both remainders have
+exactly two digits, including leading zeros. The first remainder is always
+north/south; the second is east/west. Apartment, floor, unit and street labels
+remain separate metadata and never replace or extend the coordinate suffix.
+
+Country/province codes are trimmed, uppercased and checked against the bundled
+snapshot. Source-specific province codes, including `NE_` keys and leading-zero
+strings, retain their identities. City labels are trimmed and runs of whitespace
+become one space; empty labels are omitted. Labels never change the grid origin.
+Optional street labels receive the same normalization and are returned only as
+separate display metadata, without entering the coordinate address text.
+
+## Select the grid
+
+Inputs are finite WGS84 decimal degrees: latitude in `[-90, 90]`, longitude in
+`[-180, 180]`, and a configured country code. Select that country's existing
+configuration. If it has `provinces`, require an explicit configured province
+code and use that province's corners. Otherwise, use the country corners and
+reject a province code. Do not select a province by searching rectangles.
+
+Corners remain ordered top-left, top-right, bottom-right, bottom-left and are
+latitude/longitude-aligned. West greater than east denotes a date-line crossing.
+The explicit west `-180`, east `180` rectangle covers all 360 degrees; other
+supported spans are greater than zero and below 180 degrees. Edges are inclusive.
+Rectangles may overlap. Containment does not establish administrative membership.
+
+The fixed center is the midpoint of the north/south bounds and the midpoint of
+the wrapped longitude span, with longitude normalized to `[-180, 180)`. All
+configured corners, origins and country/province snapshot versions remain
+unchanged from protocol 1.
+
+## Original projection
+
+Use spherical azimuthal equidistant (`AEQD-SPHERE-v1`) with Earth radius
+**6,371,008.8 meters**, centered on the selected grid. Preserve the original GPS
+coordinates and full numerical precision throughout the calculation.
+
+For point latitude `φ`, center latitude `φ₀`, and longitude difference `Δλ`, in
+radians:
+
+```text
+eastComponent  = cos(φ) × sin(Δλ)
+northComponent = cos(φ₀) × sin(φ) − sin(φ₀) × cos(φ) × cos(Δλ)
+cosAngle       = sin(φ₀) × sin(φ) + cos(φ₀) × cos(φ) × cos(Δλ)
+sinAngle       = hypot(eastComponent, northComponent)
+angle          = atan2(sinAngle, cosAngle)
+scale          = angle / sinAngle
+northingMeters = radius × scale × northComponent
+eastingMeters  = radius × scale × eastComponent
+```
+
+For `sinAngle < 1e-15`, use `scale = 1`. Reject points within `1e-10` radians of
+the antipode because the projection is singular there. Normalize exact numerical
+zero, including negative zero, to positive zero. Do not round these offsets to
+the old 5-meter interval or adjust values near integer boundaries with epsilon.
+The implementation retains JavaScript number precision.
+
+Approximate rectangle width follows the parallel at the center latitude; height
+follows a meridian. These dimensions alone are rounded to whole meters in the
+result. The returned projected offsets retain their fractional values.
+
+## Encode each signed axis
+
+For each unrounded signed offset `offset`:
+
+```text
+direction  = offset < 0 ? negativeDirection : positiveDirection
+whole      = floor(abs(offset))
+block      = floor(whole / 100)
+remainder  = whole % 100
+```
+
+Northing uses negative `S`, positive `N`. Easting uses negative `W`, positive `E`.
+Exact zero and negative zero use `N/E`. Direction comes from the original signed
+offset, not from its floored magnitude: `-0.3` meters remains `S/W` with block
+`0` and remainder `00`.
+
+Pad each remainder to two decimal digits. Form the suffix as
+`#<northSouthRemainder>-<eastWestRemainder>`. For northing `-119416.594` and easting
+`38220.747`, the position text is `1194 S 382 E #16-20`.
+
+An offset of magnitude `99.999` has block `0`, remainder `99`; magnitude `100`
+has block `1`, remainder `00`. No nearest-meter or nearest-5-meter rounding occurs.
+
+## Roads and sequences
+
+Axes remain fixed north/south and east/west in the selected projected grid. A
+north/south sequence may hold easting constant; an east/west sequence may hold
+northing constant. Diagonal and curved sequences may change both. Generate every
+address independently from its GPS point; do not rotate grids or assign
+sequential house numbers.
+
+Moving exactly 100 projected meters away from the origin on one axis increments
+only that axis's block and preserves both remainders and the other axis. Moving
+toward the origin decrements its magnitude while on the same side; crossing the
+origin can change direction. These are projected-plane distances, not a guarantee
+of uniform ground scale throughout a large spherical projection.
+
+## Structured result and identity
+
+Results include formatted address text, numeric blocks, directions, numeric
+remainders (`0`–`99`), the padded `coordinateSuffix`, original coordinates,
+country/province codes, optional city, grid name, center, country/grid snapshot
+versions, raw signed offsets, approximate dimensions and encoding metadata:
+
+```text
+protocol = ZAP
+protocolVersion = 2
+blockSizeMeters = 100
+detailSizeMeters = 1
+encoding = blocks-100m-detail-1m-floor-absolute-dashed-suffix-2x2-v1
+gridId = ZAP:2:<country/province prefix>:<country version>:<grid version>:AEQD-SPHERE-v1:6371008.8:<center latitude>:<center longitude>:blocks-100m-detail-1m-floor-absolute-dashed-suffix-2x2-v1
+```
+
+The encoding identifies 100-meter blocks, 1-meter detail, absolute-value flooring,
+and two pairs of two digits separated by a dash. Numeric identity components use
+JavaScript's canonical number-to-string representation. Treat `gridId` as opaque;
+persist the complete result with the address and original GPS coordinates.
+
+Display labels do not change `gridId`. When identifying a coordinate cell, use
+`gridId` plus the structured blocks, directions and remainders, without city or
+street labels.
+
+## Preserve previously issued addresses
+
+Protocol-1 addresses used nearest-interval snapping, default 5 meters. Their text,
+`protocolVersion`, original coordinates, interval and `gridId` stay attached to
+the original record. Do not replace them merely because the package was upgraded.
+
+`generateAddress` creates protocol-2 results and rejects the old `gridSizeMeters`
+option at runtime and in TypeScript. `generateLegacyAddress` explicitly
+reproduces protocol 1 using the frozen configurations and original interval.
+Its result schema, address text and grid ID match the original generator.
+
+If a user chooses to issue a protocol-2 address for the same GPS point, save a
+new result and retain the prior record as historical data. No automatic
+conversion, storage mutation or reverse decoding is performed by this package.
+Future configuration changes must retain old snapshots under their old versions.
+
+Directions always use saved GPS coordinates, never the formatted text, city,
+unit, blocks, or a reprojected cell corner. `getDirectionsUrl` accepts either
+version's saved record and builds a link from its original latitude/longitude.
+
+## Snapshot coverage
+
+The immutable snapshot contains 239 country/territory entries: 217 country-wide
+grids and 22 countries with 530 province grids, for 747 selectable grids.
+Thirteen additional Natural Earth source areas are exposed separately and remain
+outside address generation. Snapshot divisions can be historical; see
+`provinceDataNotes` and [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).