@chrtco/sdk 0.10.2 → 0.10.3

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to `@chrtco/sdk` will be documented in this file.
 ## [Unreleased]
 
 ### Added
+- **Render-mode lever on the Style API** (`sail#2`): `StyleUrlOptions.mode` /
+  `OfflineFetchStyleOptions.mode` — `"continuous"` (default) or
+  `"chart:{band}"` (`chart:Overview | chart:General | chart:Coastal |
+  chart:Approach | chart:Harbor`) — threads `?mode=` to the served style
+  routes (online `style.json` and offline `/v1/offline/styles/{region}`),
+  which lock the portrayal to one scale band with cascade fallback: the
+  served twin of the app's Map Mode toggle, now available to every API
+  consumer, online and offshore. New exports: `ChrtStyleMode`,
+  `CHRT_STYLE_MODES`, `normalizeStyleMode()`, `styleModeBand()`.
+  `OfflineStyleResponse.mode` echoes the resolved mode. Servers reject
+  invalid modes AND unknown style-route query params with typed 400s
+  (`invalid_mode` / `unknown_param`) instead of silently serving the
+  default document.
+- **`OfflineFetchStyleOptions.symbols`** — the offline style route has
+  accepted `?symbols=s52|s101|chrt|raster` all along, but
+  `chrt.offline.fetchStyle()` had no way to send it, so native clients could
+  only ever fetch the default `s52` offline style. Now threaded through
+  (omitted → worker default `s52`), typed with the same `ChrtSymbolSet` as
+  the online `StyleUrlOptions.symbols`. `OfflineStyleResponse.symbols` types
+  the echoed set the worker already returns.
 - **Served styles now render in MapLibre Native as shipped.** Every generated
   style begins with a `chrt-background` layer (S-52 NODTA backdrop per
   palette) — previously native renderers drew a black void and

package/README.md

@@ -243,7 +243,8 @@ curl -X POST https://api.chrt.co/v1/mint/tile-token \
 curl https://tiles.chrt.co/v1/styles/NOAA_ENC/style.json?theme=day \
   -H "Authorization: Bearer $TOKEN"
 
-curl https://tiles.chrt.co/v1/tiles/NOAA_ENC/12/1234/1543.mvt \
+# --compressed matters: see "Tiles are gzipped" below.
+curl --compressed https://tiles.chrt.co/v1/tiles/NOAA_ENC/12/1234/1543.mvt \
   -H "Authorization: Bearer $TOKEN"
 ```
 
@@ -251,6 +252,29 @@ The returned document is a standard MapLibre style — hand it to MapLibre Nativ
 `maplibre-gl`, or any renderer that speaks the style spec. Point your renderer's request transformer
 at the same `Authorization: Bearer` header so tile requests carry it too.
 
+### Tiles are gzipped — send `Accept-Encoding: gzip`
+
+Tiles are stored gzip-compressed in the PMTiles archive, and the edge negotiates per request:
+ask for `gzip` and you get gzip (`content-encoding: gzip` on the response); ask for `identity`,
+or send no `Accept-Encoding` at all, and you get the uncompressed bytes.
+
+**This changes tile-budget arithmetic by 2–2.5×.** MapLibre GL JS, MapLibre Native, every browser,
+and this SDK all send `Accept-Encoding: gzip` automatically — the compressed figure is what your
+users actually transfer. **Plain `curl` sends no `Accept-Encoding` at all**, so `curl -o tile.mvt`
+measures the *uncompressed* size. Use `curl --compressed` (as above), or read `content-encoding`
+off the response, before sizing a cache, a bundle, or a data plan.
+
+Reference measurement, prod `NOAA_ENC`, 2026-07-27, tile `z11/620/757` (Boston):
+
+| `Accept-Encoding` | Bytes on the wire |
+|---|---|
+| *(absent)* / `identity` | 1,152,506 B (1.10 MB) |
+| `gzip` | 462,273 B (451 KB) |
+
+Tile size tracks **feature density** far more than zoom — a harbor tile over a dense port dwarfs an
+offshore tile at the same zoom, and a tile with no data returns `204` with no body at all. Sample a
+spread of tiles across your own area of operations rather than extrapolating from one.
+
 The REST endpoints in the table below (`/v1/features`, `/v1/query`, `/v1/query/ahead`, `/v1/cells`,
 `/v1/coverage`) take the API key directly as `x-api-key` — no token minting needed.