@zukall/zap 0.2.0 → 0.2.1

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.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).
 

package/README.md

@@ -15,6 +15,142 @@ 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 below.** 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. | `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. | `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. | `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. | `582 S 780 E #29-13, Port-au-Prince, HT ZAP` |
+| **Berlin, Germany — Brandenburg Gate** | Pariser Platz 5, 10117 Berlin, Germany. | `1538 N 1989 E #91-52, Berlin, DE ZAP` |
+
+*These examples encode the venues’ published map/GPS points using package version 0.2.0. They demonstrate the format; the points are not independently verified entrances.*
+
+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.
+
+## See the address grid: Haiti illustrations
+
+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.
+
+**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.1/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.1/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.1/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 three compressed WebP illustrations, each 95–98 KB and 1280
+pixels wide. 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 three illustrations.
+
 ## Installation and local verification
 
 After publication:
@@ -26,13 +162,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.1.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 +542,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.1.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.1`; 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.1",
   "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",