@zukall/zap 0.2.0 → 0.2.2

package/PROTOCOL.md

@@ -1,7 +1,7 @@
 # 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.0`) and
+unrounded projected GPS coordinates. The npm package version (`0.2.2`) and
 protocol version (`2`) are separate. Previously issued protocol-1 addresses retain
 their original text and identity; see [PROTOCOL-V1.md](PROTOCOL-V1.md).
 

package/README.md

@@ -5,6 +5,95 @@ fixed country/province grids. Protocol **2** encodes **100-meter blocks** and
 separate **whole-meter remainders**. It needs no Google Places API, geocoding
 service, network request, or runtime dependency. Generation works offline.
 
+## See how ZAP works: Haiti’s grid
+
+These illustrations show locations in the same fixed Haiti grid. Each address
+is derived independently from its coordinates. The road can run north–south,
+east–west, diagonally, or curve; the grid origin and axes stay fixed.
+
+### Whole-country grid and fixed center
+
+![Haiti’s entire configured ZAP grid, its fixed center in the Gulf of Gonâve, and a GPS-to-address example](https://cdn.jsdelivr.net/npm/@zukall/zap@0.2.2/asset/zukall-haiti-country-grid.webp)
+
+The Haiti grid has one fixed center: **19.0578675° N, 73.0641385° W**.
+It is the center of the configured rectangle, in the Gulf of Gonâve, rather than
+the capital or a street junction. Every Haiti address uses that same origin.
+North/south and east/west offsets start there and increase away from it.
+
+| Configured rectangle edge | GPS limit |
+| --- | --- |
+| North | 20.089789° N |
+| South | 18.025946° N |
+| West | 74.489167° W |
+| East | 71.639110° W |
+
+The whole-country overview is **schematic and not to scale**. Its grid lines
+make the fixed axes visible; the calculation panel explains **100-meter blocks**
+and the two whole-meter remainders. The coastline is illustrative. The configured
+rectangle includes sea and is not an administrative boundary.
+
+For the Marriott example, GPS **(18.532731, -72.324187)** projects to
+−58,229.5607 meters northing and +78,013.0303 meters easting. Flooring their
+absolute values gives 58,229 whole meters south and 78,013 east: **582 S 780 E
+#29-13, Port-au-Prince, HT ZAP**. The suffix records another 29 whole meters
+south and 13 east after the complete blocks. Use the saved GPS point for navigation.
+
+**Current suffix notation is `#42-68`.** The north–south and east–west images use
+the compact notation `#4268` for the same two remainders: 42 south and 68 east.
+The examples and captions below use the current dashed format.
+
+### North–south: easting stays fixed
+
+![Haiti ZAP grid with five north–south locations, constant easting, and 100-meter projected intervals](https://cdn.jsdelivr.net/npm/@zukall/zap@0.2.2/asset/zukall-north-south-example.webp)
+
+```text
+Point A: 580 S 772 E #42-68, HT ZAP
+Point B: 581 S 772 E #42-68, HT ZAP
+Point C: 582 S 772 E #42-68, HT ZAP
+```
+
+From A to B, the location moves 100 projected meters south: the south block
+increases from 580 to 581, while the east block and both remainders stay fixed.
+Moving north on this side of the origin decreases the south block.
+
+### East–west: northing stays fixed
+
+![Haiti ZAP grid with five east–west locations, constant south offset, and 100-meter projected intervals](https://cdn.jsdelivr.net/npm/@zukall/zap@0.2.2/asset/zukall-west-east.webp)
+
+```text
+Point A: 582 S 770 E #42-68, HT ZAP
+Point B: 582 S 771 E #42-68, HT ZAP
+Point C: 582 S 772 E #42-68, HT ZAP
+```
+
+From A to B, the location moves 100 projected meters east: the east block
+increases from 770 to 771, while the south block and both remainders stay fixed.
+Moving west on this side of the origin decreases the east block.
+
+### Diagonal streets: both axes can change
+
+![Haiti ZAP grid over a diagonal street, showing changing south and east offsets with a fixed grid](https://cdn.jsdelivr.net/npm/@zukall/zap@0.2.2/asset/zukall-diagnol-example.webp)
+
+```text
+Point A: 580 S 770 E #43-46, HT ZAP
+Point B: 581 S 771 E #12-36, HT ZAP
+Point C: 582 S 772 E #08-41, HT ZAP
+```
+
+Both axes and their remainders can change along a diagonal or curved street.
+For point C, the whole-meter magnitudes are `582 × 100 + 08 = 58,208` south
+and `772 × 100 + 41 = 77,241` east. The `#08-41` suffix keeps its leading zero.
+
+The images are illustrative grid examples. To reach a real place, use its saved
+GPS entrance point for road directions; the grid comparison describes relative
+position rather than a route through buildings or other obstacles. The same
+encoding applies to the other configured countries and provinces.
+
+The README uses four compressed WebP illustrations, each below 100 KB.
+Original PNGs remain in the source project; only the smaller WebP versions are
+included in the npm package. The compressed package stays below 400 KB,
+including all four illustrations.
+
 ```text
 1194 S 382 E #16-20, Kampala, UG ZAP
 2106 S 3614 E #22-64, Miami, FL US ZAP
@@ -15,6 +104,82 @@ These illustrate the display format. Actual numbers depend on the original GPS
 point and selected grid; a city label never changes the origin or verifies
 administrative membership.
 
+## Why use ZAP?
+
+**Different countries. Different street addresses. One consistent location format.**
+
+A well-defined address identifies a destination, but it does not automatically tell an unfamiliar person how to reach it. Immokalee, Florida, has formally assigned addresses, yet a newcomer may still need a map, street signs, or knowledge of the road layout.
+
+ZAP gives your application a consistent way to address locations directly from GPS coordinates. It works alongside conventional addresses and can provide a location address where street names or building numbers are missing.
+
+### Addresses without waiting for an address authority
+
+ZAP derives its location code from coordinates and a fixed grid. A country does
+not need an address authority, a complete street-address registry, named roads,
+or assigned building numbers for applications to generate ZAP addresses within
+that grid. A home, business, rural property entrance, or pickup point can receive
+a coordinate address as soon as its GPS location is available.
+
+The same method can be applied in any country with a configured grid. This
+release includes **239 country/territory configurations**, with country-wide
+grids or explicitly selected province/state grids. Coverage follows those
+configurations; adding an unconfigured country requires a versioned grid
+definition. The address structure stays consistent across them.
+
+**Haiti is the illustrated example above.** Its `HT` configuration provides one
+fixed country grid, so a place can be addressed even when its street name,
+building number, or formal address record is unavailable. This shows independence
+from official address assignment; the method also works alongside existing
+Haitian street addresses, such as the hotel example in the table.
+
+A visitor or delivery driver can use a ZAP-aware application to view their
+current location and destination in the same grid. Comparing their blocks,
+directions, and remainders helps them understand the destination's relative
+position. Saved GPS coordinates connect that destination to road directions.
+
+### Different local addresses, the same ZAP structure
+
+| Location | Conventional address | ZAP address |
+| --- | --- | --- |
+| **Miami, USA — City Hall** | 3500 Pan American Drive, Miami, FL 33133, USA. (25.7276845, -80.2337652) | `2220 S 3602 E #92-35, Miami, FL US ZAP` |
+| **Beijing, China — Sofitel Beijing Central** | No. 2 Jianguomen South Avenue, Chaoyang District, Beijing 100022, China. (39.906274, 116.436733) | `375 S 15 W #62-74, Beijing, BJ CN ZAP` |
+| **Abidjan, Côte d’Ivoire — Sofitel Hotel Ivoire** | Boulevard Hassan II, Cocody, 08 BP 01 Abidjan, Côte d’Ivoire. (5.326842, -4.005485) | `2452 S 1724 E #88-29, Abidjan, CI ZAP` |
+| **Port-au-Prince, Haiti — Marriott Hotel** | 147 Avenue Jean Paul II, Turgeau, Port-au-Prince, HT 6113, Haiti. (18.532731, -72.324187) | `582 S 780 E #29-13, Port-au-Prince, HT ZAP` |
+| **Berlin, Germany — Brandenburg Gate** | Pariser Platz 5, 10117 Berlin, Germany. (52.5162, 13.3780) | `1538 N 1989 E #91-52, Berlin, DE ZAP` |
+
+*Coordinates are (latitude, longitude), in decimal degrees. Each displayed GPS point reproduces the adjacent ZAP address using package version 0.2.0. They demonstrate the format; the points are not independently verified entrances.*
+
+Map/GPS references: [Miami City Hall](https://www.miami.gov/Notices/Events-Activities/City-of-Miami-Holiday-Festival), [Sofitel Beijing Central](https://all.accor.com/hotel/B628/index.en.shtml), [Sofitel Hotel Ivoire](https://all.accor.com/hotel/8844/index.en.shtml), [Marriott Port-au-Prince](https://www.marriott.com/en-us/hotels/papmc-marriott-port-au-prince-hotel/overview/), and [Brandenburg Gate visitor information](https://www.visitberlin.de/en/brandenburg-gate).
+
+Street names, languages, address order, and postal components vary. ZAP uses the same generation function and encoding structure across its configured grids.
+
+### Understand the address
+
+In `582 S 780 E #29-13, Port-au-Prince, HT ZAP`:
+
+- **582 S:** 582 complete 100-meter blocks south of the selected grid origin.
+- **780 E:** 780 complete 100-meter blocks east of that origin.
+- **#29-13:** another 29 whole projected meters south and 13 east within those blocks.
+- **HT:** Haiti’s country code.
+
+The directions refer to the grid’s fixed origin. The suffix describes coordinate detail, rather than a sequential house number.
+
+### Why developers choose ZAP
+
+- **Generate addresses from GPS**, including locations without useful street addresses.
+- **Use one format across configured countries and provinces.**
+- **Generate offline**, without a geocoding API, API key, or runtime dependency once coordinates are available.
+- **Get repeatable results** from the same coordinates, grid, and protocol version.
+- **Keep local context**, displaying street addresses, landmarks, and unit details alongside ZAP.
+
+### Identifying a destination and reaching it
+
+ZAP works with straight, diagonal, and curved streets. Its grid stays fixed; both coordinate numbers can change along a diagonal road.
+
+For navigation, use the original saved GPS coordinates—preferably the entrance point—to open road directions. Keep helpful street names and landmarks visible.
+
+ZAP complements existing addresses. Whole-meter encoding does not guarantee one-meter GPS accuracy, and a location code does not automatically identify a unique household or apartment.
+
 ## Installation and local verification
 
 After publication:
@@ -26,13 +191,13 @@ npm install @zukall/zap
 Before publication, install the verified local package:
 
 ```sh
-npm install /absolute/path/to/your-address-protocol/.artifacts/zukall-zap-0.2.0.tgz
+npm install /absolute/path/to/zukall-address-protocol/.artifacts/zukall-zap-0.2.2.tgz
 ```
 
 Build and verify the source:
 
 ```sh
-cd /absolute/path/to/your-address-protocol
+cd /absolute/path/to/zukall-address-protocol
 npm ci
 npm run check
 npm run pack:check
@@ -406,11 +571,11 @@ removed-option error.
 ```sh
 npm login
 npm run pack:check
-npm publish .artifacts/zukall-zap-0.2.0.tgz --access public
+npm publish ./.artifacts/zukall-zap-0.2.2.tgz --access public
 ```
 
 An npm account with permission to publish `@zukall/zap` is required. Building and
-packing do not publish the package. Package version is `0.2.0`; current protocol
+packing do not publish the package. Package version is `0.2.2`; current protocol
 version is `2`, while preserved legacy results remain version `1`.
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zukall/zap",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "ZAP (Zukall Addressing Protocol): deterministic 100-meter grid blocks with whole-meter detail from GPS coordinates.",
   "license": "MIT",
   "type": "module",
@@ -32,6 +32,7 @@
   },
   "files": [
     "dist",
+    "asset/*.webp",
     "README.md",
     "PROTOCOL.md",
     "PROTOCOL-V1.md",