@chrtco/sdk 0.9.1 → 0.10.0

package/CHANGELOG.md

@@ -3,11 +3,85 @@
 All notable changes to `@chrtco/sdk` will be documented in this file.
 
 ## [Unreleased]
+- **`/v1/cells` now sends flat `bbox_north` / `bbox_south` / `bbox_east` / `bbox_west`, matching `CellDetail`.** This is a **wire change to `/v1/cells` and `/v1/cells/{id}`**, not just a type change — read it before upgrading a REST client.
+  - The bug: the SDK declared flat `bbox_*`, the endpoint returned a nested `bbox` object. `cell.bbox_north` typechecked and was `undefined` on **every** response — TypeScript vouching for a field that never arrived, which is worse than no type at all.
+  - **The endpoint was the outlier, so the endpoint moved.** `enc_cells`' own columns, `/v1/coverage/route`'s `CoverageRouteCell`, and every published `CellDetail` are flat; `formatCell()` alone nested. One shape across the API is the point.
+  - **REST clients reading `cell.bbox.north` must move to `cell.bbox_north`.** SDK callers need no change: this is the shape `@chrtco/sdk` has always declared, so **0.9.2 callers are fixed the moment the endpoint deploys** — the phantom field starts carrying real values without a release.
+  - Bounds are now passed through **independently** rather than gated on `bbox_west != null`, which would have discarded three real bounds had that one column ever been null alone.
+  - The shape is now pinned from both sides: `serve-cells/format-cell.test.ts` (Deno) asserts what the server emits, `endpoints/cells.test.ts` (vitest) asserts what the SDK expects. Neither existed, which is why the two drifted for months. They cannot share a fixture across runtimes — **change one, change the other.**
+  - New: **`cell.last_checked_at`** (ISO 8601 | null) — when CHRT last checked the issuing office's catalogue for the cell. It is the freshness of the *check*, not of the chart: `edition` / `update_number` / `issue_date` remain the data-currency fields.
+- **CHRToffline is Pro-and-above, and `chrt.offline.*` now says so.** New typed error code `offline_requires_pro_plan` (403 from `POST /v1/mint/offline-token`). This refusal previously fell through to the generic 403 mapping and surfaced as **`coverage_denied`** — reporting a plan gate as a coverage problem, and pointing the user at the one thing that could not fix it. The per-key `offline:download` scope (`offline_not_enabled`) is a **separate, narrower gate that is checked first**: a key without the scope is refused before the plan is ever read.
+- **`chrt.cells.list()` gains the `scaleBand` and `bbox` filters** that `/v1/cells` has always supported and the SDK could not reach:
+  - `scaleBand?: ScaleBand` — new exported union `'Overview' | 'General' | 'Coastal' | 'Approach' | 'Harbor'`, matched **case-sensitively** (`'harbor'` matches nothing). These are the S-57 usage bands CHRT derives from compilation scale; they are **words, not band numbers** — `scale_band: '4'` matches no cell.
+  - `bbox?: [west, south, east, north]` — cells whose bounds *intersect* the box (same tuple encoding as `chrt.features()`).
+- **`chrt.query()` returns the new `QueryResponse`** instead of a bare `FeatureCollection` — a widening, so no caller breaks:
+  - `res.query` (`{ point, radius_m }`) is now declared. The server echoes back what it **actually applied after clamping**, which is the only way to learn that `radius: 90000` was cut to `50000`. It was previously invisible to typed callers.
+  - `res.features[].properties` is typed `QueryFeatureProperties` (`layer`, `cell_id`, `distance_m`, plus an open index signature) — `distance_m` no longer needs a cast, which is the whole point of a proximity search.
+  - Documented that `/v1/query` is **not paginated**: it returns no `offset`. Widen `radius` instead of paging.
+- **Corrected docs that sent callers to empty results** (no code change, but they were wrong in the same way the types were):
+  - `source` takes the chart-source **id** (`'NOAA_ENC'`), not the agency name (`'NOAA'`). Passing the agency **returns an empty list rather than an error** — a silent zero. Affects `CellsOptions`, `CoverageOptions`, `CoverageSource.source`, and the README quick-start, which shipped the broken `{ source: 'NOAA' }`.
+  - `chrt.query()`'s `limit` default (50) and cap (500) are now documented on `QueryOptions`, alongside the `radius` default corrected in the README rewrite below.
+- New exported types: `ScaleBand`, `QueryResponse`, `QueryFeatureProperties`.
+- **`vessel` on `ChrtConfig` — one safety depth, read by every depth-aware call (ADR 0020 F2).** CHRT had grown four disagreeing notions of "how deep is safe"; this is the single place a client states it once.
+  ```ts
+  const chrt = new Chrt({ apiKey, vessel: { safetyDepthM: 3 } });
+  await chrt.ahead({ point, bearing });   // filters at 3 m
+  chrt.style();                           // labels + danger rings at 3 m
+  ```
+  - Defaults `ahead({ safetyDepth })`, `alongRoute({ safetyDepth })` and `style({ safetyContour })`. An explicit per-call value always wins. One `safetyDepthM` drives **30 sites** in the generated style (SOUNDG two-shade + all four danger-ring classes) at a single value.
+  - **Client-side and per-instance, deliberately — never bound to your API key.** A consumer app has one key and many skippers with different boats; a key-scoped draft would give them all the same number, which is worse than none — it's a confidently wrong one. Construct a `Chrt` per user, or pass `safetyDepth` per call.
+  - **With no profile, nothing is sent.** CHRT never guesses a draft: filtering on an invented one silently drops real hazards.
+  - **Known gap:** `styleUrl()` (the *served* style — the only style path for non-JS clients) still takes `theme` + `symbols` only, so a **native app cannot yet give each user their own depth shading**. And `depareFillExpression` bins depth into fixed 0/2/5/10 tiers, so the profile does not reshade depth *areas* — only soundings and danger rings. Both are tracked in ADR 0020.
+  - New type: `VesselProfile`.
+- **`chrt.alongRoute()` + `chrt.coverage.forRoute()` — the along-route pair (CHRTquery; ADR 0020 D1).** Completes the family the staged `routeQuery` / `routeFeatures` stubs never shipped, and **splits them by the question they answer**:
+  - **`chrt.alongRoute({ route, buffer | bufferNm, safetyDepth, layer, limit, offset })`** → `GET /v1/query/route`. What's charted in a corridor either side of a passage — the planning sibling of {@link ahead}. Each feature carries **`along_m`** (metres along the route to closest approach) alongside `distance_m`, `least_depth_m` and `depth_clearance_m`, and results are **ordered by `along_m`** — the order you actually meet them, not lateral offset. `chrt.alongRouteIter()` auto-paginates.
+  - **`chrt.coverage.forRoute({ route, buffer | bufferNm, scaleBand, limit })`** → `GET /v1/coverage/route`. Which ENC cells a passage needs, largest-scale first (S-57 says believe the finer chart), each with `edition` / `update_number` / `issue_date` so you can tell whether the copy you hold is stale. **It lives on `coverage`, not `query`, deliberately** — it returns *cells*, so it answers "which charts must I hold?", a download-planning question and CHRToffline's companion. Filing it with the hazard queries is what made the family look like two overlapping things.
+  - **`alongRoute` does not replace `ahead`, and `ahead` does not replace it.** A boat with a route still drifts, and COG rarely equals the route bearing — a passage app wants both: this once per route edit, `ahead` continuously against the real track.
+  - Same invariants as `ahead`: **facts that sort, never a verdict** (no severity, no `safe` flag), `safetyDepth` omits only what is *known* to be deeper, and **an empty result is not a clear passage** — every response carries `coverage` plus `attribution` / `disclaimer` / `notice`.
+  - Both validate locally before the round trip (≥2 waypoints; `buffer` and `bufferNm` are mutually exclusive).
+  - New types: `AlongRouteOptions`, `AlongRouteResponse`, `AlongRouteFeatureProperties`, `CoverageRouteOptions`, `CoverageRouteResponse`, `CoverageRouteCell`. **Removed** the never-shipped staged types `RouteQueryOptions`, `RouteQueryResponse`, `RouteFeatureQueryOptions`, `RouteFeatureQueryResponse` — they were exported but unreachable (their methods were commented out), so nothing could have depended on them.
+- **`chrt.ahead()` — the fan-ahead query (CHRTquery; ADR 0020).** *"What's charted ahead of me?"* — the significant features in a sector from a point along a bearing. Built for the position-plus-COG case: a craft that has a heading but not a planned route.
+  - `chrt.ahead({ point, bearing, arc, range | rangeNm, safetyDepth, layer, limit })` → `GET /v1/query/ahead`. `bearing` is degrees true (a COG/heading or a fixed input; out-of-range values normalise, so a heading that wraps past north is fine). `arc` is the **full** sector width centred on the bearing — `arc: 60` sweeps ±30°. `arc: 360` degenerates to a full circle, making `ahead` a strict generalisation of `query()`.
+  - **Facts that sort, never a verdict.** Each feature carries `distance_m`, `bearing_deg`, `least_depth_m` and `depth_clearance_m` (negative = shallower than your declared `safetyDepth`). There is **no severity score and no `safe` flag, deliberately**: a risk model is a navigation-grade claim, and CHRT is situational-awareness only. You sort; CHRT ranks nothing.
+  - **`safetyDepth` filters out only what is *known* to be deeper.** Features with no charted depth are always kept — a wreck with no sounded value is still a wreck. Fail-safe by construction.
+  - **An empty result is not an all-clear**, so every response carries a `coverage` block (`covered`, `covered_fraction`, and `cells` with real `edition` / `update_number` / `issue_date` per source cell) alongside inline `attribution`, `disclaimer` and `notice`. Zero features in covered water and zero features because CHRT has no cells there are different answers; `coverage` is what tells them apart. **Check `coverage.covered` before telling a user anything.**
+  - **No `speed` parameter, by design** — deriving range from SOG means deciding how many minutes of lookahead a vessel needs, which is a navigational judgment that belongs to the client. Recipe: `rangeNm = SOG_knots × lookahead_hours`, narrowing `arc` as speed rises; re-fan on a meaningful course change rather than a timer.
+  - Defaults to CHRT's significant-feature set (S-52 viewing group 24020 — wrecks, obstructions, rocks, plus the depth-carrying classes). Pass `layer` for a different set, or use `query()` for an unfiltered point-radius search.
+  - New types: `AheadOptions`, `AheadResponse`, `AheadFeatureProperties`, `AheadCoverageCell`.
+- **README rewritten against the real surface — three artifacts in the published tarball disagreed.**
+  The API Reference had not been updated past 0.8.0, so `README.md`, `CHANGELOG.md` and
+  `dist/index.d.ts` shipped inside `@chrtco/sdk@0.9.2` contradicting each other:
+  - **`styleUrl()` is no longer documented as deprecated.** The README still said *"CHRT serves no
+    remote `style.json` — use `chrt.style()`"*, three minor versions after the served Style API
+    shipped (`GET tiles.chrt.co/v1/styles/{region}/style.json`, live and auth-gated in production).
+    This was the severity-1 case: `chrt.style()` is a **JavaScript function**, so native iOS/Android,
+    Swift, Kotlin and Python clients cannot call it — the served style URL is the only style path
+    they have, and the README told them it did not exist.
+  - **Every method is now marked JS-only or HTTP-backed**, with the HTTP method and path for each, so
+    non-JS clients can see what they can actually reach. New section: *Using CHRT without
+    JavaScript* — the two-call mint → served-style recipe in `curl`, documenting the **wire** shape
+    (`expires_at`, `build_tag` — snake_case; the SDK's `TileTokenResponse` camelCases them).
+  - **`interact`, `fetchStyle()`, `coverage.list()` and `ahead()` are documented for the first time.**
+    `interact`, `fetchStyle` and `coverage` were all present in `0.9.2`'s `.d.ts` but absent from its
+    README — shipped and invisible.
+  - **`tiles.groups()` stays deprecated** — unlike `styleUrl()` it is genuinely gone (`/v1/tiles/*`
+    is absent from the gateway route table; it fails with `ChrtError` 404). The old heading's error
+    was bundling a live method and a dead one under one "deprecated" label.
+  - **Quick Start no longer hard-codes a secret**, and no longer uses `chrt_live_…` — a key format
+    CHRT has never generated. Real keys are `chrt_{pk|sk}_{live|test}_{team}_{random}`. New *API
+    keys* section documents the real `pk`/`sk` distinction: they differ in whether the plaintext can
+    be re-revealed, **not in privilege**. `pk` is not a capability boundary, so the README says to
+    treat any key embedded in a client as public rather than implying the prefix protects it.
+  - **The non-SOLAS disclaimer is now in the README.** The SDK enforces the notice on every
+    `InspectResult`, but the most-read CHRT artifact — the npm landing page — carried no disclaimer
+    at all.
+  - `QueryOptions.radius` JSDoc corrected: the server default is **500 m**, not 1000. `ChrtConfig.apiKey`
+    JSDoc corrected to the real key format. (JSDoc only — no behaviour change; both ship in `.d.ts`.)
 - **Symbol families (`symbolSet`)** — `chrt.style({ symbolSet })`, `styleUrl({ symbols })` and `fetchStyle({ symbols })` select the symbol artwork:
   - **`s52`** (default) — now **spec-exact for ATONs and LIGHTS**: buoy/beacon icon selection is compiled from the S-52 Presentation Library lookup tables (COLOUR-list keyed — preferred-channel junction marks render correctly; no IALA region hardcoding), and light flares follow the LIGHTS05/06 conditional-symbology procedure (LIGHTS11/12/13 colour-specific flares, LIGHTS81/82 strip/floodlight, LITDEF11 default).
   - **`s101`** — the official IHO S-101 Portrayal Catalogue ATON/LIGHTS artwork (vendored at a pinned commit, themed through the official S-101 day/dusk/night profiles). Load images via `loadS101SymbolImages` (`@chrtco/sdk/atlas/browser`).
   - **`chrt`** — the CHRT house set: simplified colour-true silhouettes (tinted at runtime from the feature's COLOUR — green marks render green, red marks red), fixed-palette identity marks (cardinals, isolated danger, safe water), and capability badges (sound for fog signals, radar for racons). Load via `loadChrtSymbolImages`.
-- Served Style API: `GET /v1/styles/{region}/style.json?symbols=s52|s101|chrt` (own cache-key slot, `X-Style-Symbols` response header); composes with Dev+ custom-style claims.
+- Served Style API: `GET /v1/styles/{region}/style.json?symbols=s52|s101|chrt|raster` (own cache-key slot, `X-Style-Symbols` response header). All four families are **free on every plan** — the style route reads no `plan_id`, and the served document is byte-identical across tiers. Composes with a bound **custom style**, which is the one part of CHRTstyle that is paid (Dev and above).
 - **Behaviour change (S-52 correctness):** LIGHTS icons are no longer SDF-tinted by COLOUR; the procedure-selected flare carries its own colour. Blue/orange lights now render the spec's LITDEF11 default flare (use the `chrt` family for exact-colour flares).
 
 ## [0.9.1] — 2026-07-14

package/README.md

@@ -4,6 +4,10 @@ Official TypeScript SDK for the [CHRT](https://chrt.co) nautical chart API.
 
 Zero dependencies · Works in Node 18+, browsers, Deno, Bun · Full TypeScript types
 
+> **Situational awareness only — not for primary navigation.** CHRT is not an ECDIS and is not
+> SOLAS-compliant. Do not use it as your primary means of navigation. Every chart CHRT serves comes
+> from the issuing hydrographic office; keep the source attribution visible in anything you build.
+
 ## Install
 
 ```bash
@@ -15,7 +19,8 @@ npm install @chrtco/sdk
 ```typescript
 import { Chrt } from '@chrtco/sdk';
 
-const chrt = new Chrt('chrt_live_...');
+// Read the key from the environment — never hard-code it in source.
+const chrt = new Chrt(process.env.CHRT_API_KEY!);
 
 // Get depth areas in a bounding box
 const features = await chrt.features({
@@ -30,25 +35,119 @@ const nearby = await chrt.query({
   layer: 'BOYCAR,BOYLAT',
 });
 
-// List ENC cells
-const cells = await chrt.cells.list({ source: 'NOAA' });
+// List ENC cells — `source` takes the chart-source id ('NOAA_ENC'), not the
+// agency name ('NOAA'), which matches nothing. chrt.coverage.list() lists the ids.
+const cells = await chrt.cells.list({ source: 'NOAA_ENC' });
 
 // Get a specific cell
 const cell = await chrt.cells.get('US5MA11M');
+console.log(cell.bbox_north, cell.bbox_west); // → 42.38 -71.05
+```
+
+## API keys
+
+Keys are issued in the CHRT platform under **Settings → API keys** and look like:
+
+```
+chrt_pk_live_<team>_<random>     chrt_sk_live_<team>_<random>
+chrt_pk_test_<team>_<random>     chrt_sk_test_<team>_<random>
+      ▲    ▲
+      │    └── environment: live | test
+      └── key type: pk (publishable) | sk (secret)
+```
+
+| | `pk` — publishable | `sk` — secret |
+|---|---|---|
+| Intended for | client-side code (browser, mobile app) | servers, CI, backend jobs |
+| Retrievable later | ✓ — re-reveal it in the dashboard | ✗ — shown once at creation; regenerate if lost |
+
+> **`pk` and `sk` carry identical API privileges.** The prefix records intent and whether CHRT keeps
+> the plaintext for you to re-reveal — it is **not** a capability boundary. Any key you ship to a
+> client can be extracted from it and replayed with full access.
+>
+> So treat any key embedded in a browser bundle or mobile app as public: develop against a
+> `test`-environment key, grant it only the scopes it needs, and rotate it if it leaks.
+>
+> For a key you ship to a browser, set **Allowed domains** on it (platform → API keys). A browser
+> request whose `Origin` isn't on the list is refused, so a key lifted from your bundle won't work
+> on someone else's site. It is a **browser-only deterrent, never a boundary** — a non-browser
+> caller sends no `Origin` and is allowed through, by design. Do **not** set the **IP allowlist**:
+> it does not work, and setting it bricks the key on every real request path.
+
+## Spatial queries
+
+`query()` answers "what's around me". Underway, the question is narrower.
+
+```typescript
+// What's charted AHEAD — position + bearing, no route needed.
+const fan = await chrt.ahead({
+  point: [-70.9245, 42.33604],
+  bearing: gps.cog,   // degrees true
+  arc: 60,            // FULL sector width, so ±30°
+  rangeNm: 3,
+  safetyDepth: 3,     // omit if you set `vessel`
+});
+
+// What's charted along a PLANNED PASSAGE — ordered by how far in you meet it.
+const passage = await chrt.alongRoute({
+  route: [[-70.95, 42.33], [-71.0, 42.35], [-71.02, 42.36]],
+  bufferNm: 0.5,
+});
+for (const f of passage.features) {
+  const { along_m, distance_m, depth_clearance_m } = f.properties;
+}
+
+// Which CHARTS that passage needs — a different question, so a different call.
+const { cells } = await chrt.coverage.forRoute({ route, bufferNm: 1 });
 ```
 
+Neither replaces the other: a boat with a route still drifts, and COG rarely equals the route
+bearing — so a passage app wants `alongRoute()` once per route edit and `ahead()` continuously
+against the real track.
+
+**These tell you what is CHARTED, never whether it is safe.** There is no severity score and no
+`safe` flag, deliberately — a risk model is a navigation-grade claim, and CHRT is
+situational-awareness only. You get facts that sort (`distance_m`, `bearing_deg`, `along_m`,
+`least_depth_m`, `depth_clearance_m` — negative means shallower than you declared safe) and your
+application owns the judgment.
+
+**An empty result is not an all-clear.** It can mean nothing is charted there, or that CHRT has no
+coverage there at all. Every response carries a `coverage` block — check `coverage.covered` before
+telling a user anything.
+
+```typescript
+if (!fan.coverage.covered) {
+  // CHRT holds no chart for this sector. Say so — do not report "clear".
+}
+```
+
+There is no `speed` parameter, by design: turning SOG into a lookahead distance is a navigational
+judgment that belongs to you. The usual recipe is `rangeNm = SOG_knots × lookahead_hours`,
+narrowing `arc` as speed rises. Re-fan on a meaningful course change rather than on a timer.
+
 ## Maps (MapLibre GL JS / Mapbox GL JS)
 
-`chrt.style()` returns a ready-to-use IHO **S-52** nautical style; `chrt.transformRequest()`
-mints a short-lived tile token from your API key and attaches it to tile requests
-automatically. Examples use MapLibre — substitute `mapbox-gl` if you're already on Mapbox.
+CHRT gives you two ways to get an IHO **S-52** style. They are not interchangeable — pick by whether
+your client runs JavaScript:
+
+| | `chrt.style()` | `chrt.styleUrl()` / `chrt.fetchStyle()` |
+|---|---|---|
+| What it is | a JS function that **builds** the style locally | a **URL CHRT serves** (`tiles.chrt.co/v1/styles/…`) |
+| Network | none — works offline | one authenticated request |
+| Usable from | **JavaScript only** | any HTTP client (Swift, Kotlin, Python, curl) |
+| Custom style bound to your key | not applied | **applied server-side** (Dev plan and above) |
+
+`chrt.transformRequest()` mints a short-lived tile token from your API key and attaches it to tile
+**and served-style** requests automatically. Examples use MapLibre — substitute `mapbox-gl` if you're
+already on Mapbox.
 
 ```typescript
 import maplibregl from 'maplibre-gl';
 import { Chrt } from '@chrtco/sdk';
 
-const chrt = new Chrt('chrt_live_...');
+const chrt = new Chrt(process.env.CHRT_API_KEY!);
 
+// Locally generated style — no network, no custom style applied.
 const map = new maplibregl.Map({
   container: 'map',
   style: chrt.style({ palette: 'DAY' }),   // 'DAY' | 'DUSK' | 'NIGHT'
@@ -58,14 +157,47 @@ const map = new maplibregl.Map({
 });
 ```
 
-Tiles are served from `tiles.chrt.co` and gated by a short-lived ES256 JWT. The SDK mints
-it from your key, attaches it as `Authorization: Bearer` on tile requests only, and refreshes
-it before expiry — you never handle tokens directly.
+Or use the **served** style, which honours the CHRTstyle custom style bound to your key:
+
+```typescript
+const map = new maplibregl.Map({
+  container: 'map',
+  style: await chrt.styleUrl({ theme: 'dusk' }),   // 'day' | 'dusk' | 'night'
+  transformRequest: chrt.transformRequest(),       // required — authenticates the style request too
+});
+```
+
+`styleUrl()` is `async`: it pre-mints the tile token so the style request — which MapLibre does
+**not** retry — is guaranteed to carry auth. Always pair it with `transformRequest()`.
+
+Tiles are served from `tiles.chrt.co` and gated by a short-lived ES256 JWT. The SDK mints it from
+your key, attaches it as `Authorization: Bearer`, and refreshes it before expiry — you never handle
+tokens directly.
+
+### Symbol families
+
+`style()`, `styleUrl()` and `fetchStyle()` all select symbol artwork, but **the option is spelled
+differently** on the local and served paths:
+
+```typescript
+chrt.style({ symbolSet: 's101' });      // local  — symbolSet, palette: 'DAY' | 'DUSK' | 'NIGHT'
+await chrt.styleUrl({ symbols: 's101' }); // served — symbols,   theme:   'day' | 'dusk' | 'night'
+```
+
+| Value | Artwork |
+|---|---|
+| `s52` (default) | IHO S-52 Presentation Library — spec-exact ATON/LIGHTS selection |
+| `s101` | official IHO S-101 Portrayal Catalogue artwork |
+| `chrt` | CHRT house set — colour-true silhouettes, capability badges |
+| `raster` | raster symbol set |
+
+`s101` and `chrt` need their images loaded at runtime via `loadS101SymbolImages` /
+`loadChrtSymbolImages` from `@chrtco/sdk/atlas/browser`.
 
 ### Custom styles
 
-`chrt.style()` returns a standard MapLibre style object you can mutate. For a fully custom
-look, build your own style over CHRT's vector source with `buildSources()` and keep
+`chrt.style()` returns a standard MapLibre style object you can mutate. For a fully custom look,
+build your own style over CHRT's vector source with `buildSources()` and keep
 `chrt.transformRequest()` for auth:
 
 ```typescript
@@ -76,22 +208,146 @@ const sources = buildSources({ region: 'NOAA_ENC' });
 // Each S-57 class (DEPARE, LIGHTS, BOYLAT, …) is a `source-layer` inside that one source.
 ```
 
-> S-101 portrayal is on the roadmap; today `chrt.style()` emits S-52.
+## Using CHRT without JavaScript
+
+Native iOS/Android, Swift, Kotlin, Python and plain `curl` clients cannot call `chrt.style()` — it is
+a JavaScript function that builds a style object in-process. **Use the served style API instead.**
+It is two HTTP calls, no SDK required.
+
+**1. Mint a tile token** (valid for a short window; re-mint before `expires_at`):
+
+```bash
+curl -X POST https://api.chrt.co/v1/mint/tile-token \
+  -H "x-api-key: $CHRT_API_KEY" \
+  -H "content-type: application/json" \
+  -d '{"region":"NOAA_ENC"}'
+```
+
+```jsonc
+{
+  "token": "eyJhbGciOiJFUzI1NiIs…",  // ES256 JWT — do not log
+  "expires_at": 1752600000,          // unix seconds, matches the JWT `exp`
+  "kid": "chrt-tile-2026-04",
+  "build_tag": "…",
+  "region": "NOAA_ENC"
+}
+```
+
+**2. Fetch the style and the tiles** with that token as a Bearer credential:
+
+```bash
+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 \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+The returned document is a standard MapLibre style — hand it to MapLibre Native (iOS/Android),
+`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.
+
+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.
+
+## Click-to-inspect (CHRTinteract)
+
+Wires click → decode onto any MapLibre / Mapbox GL map showing CHRT tiles. **Requires the Dev plan or
+above**; the entitlement is enforced server-side at attach time.
+
+```typescript
+const handle = await chrt.interact.attach(map, {
+  onInspect: (result) => {
+    // result.kind: 'navaid' | 'bridge' | 'area'
+    // e.g. a light characteristic decoded to "Fl(2+1) W 10s", sector arcs,
+    // bridge clearances, restriction lists, coordinates
+    console.log(result);
+  },
+});
+
+handle.detach();
+```
+
+With no `onInspect`/`onCandidates` callback, `attach()` renders a minimal built-in popup instead.
+Every result carries a `notice` — the non-SOLAS disclaimer, issuing-HO attribution and data
+currency. The built-in popup always renders them; **if you build your own UI, render them too.**
+
+A chart click rarely hits exactly one feature (a buoy on a channel over a depth area), so interact
+collects every candidate under the click, dedupes them across tile boundaries by S-57 identity, and
+orders them point → line → area with safety-critical classes first.
+
+```typescript
+// Headless candidate collection for any screen point or [lng, lat].
+const { candidates, select } = await chrt.interact.inspectAll(map, [-70.86, 42.02]);
+const result = await select(candidates[0]);
+
+// Decode a single feature you already have.
+const one = await chrt.interact.inspect(feature);
+
+// Resolve full S-57 source properties + cell provenance (edition, update number,
+// issue date). Metered against your `featureCalls` quota.
+const enriched = await chrt.interact.inspect(feature, { enrich: true });
+```
 
 ## Configuration
 
 ```typescript
 const chrt = new Chrt({
-  apiKey: 'chrt_live_...',
-  baseUrl: 'https://api.chrt.co/v1',     // default
-  retries: 2,                             // retry on 5xx, default 2
+  apiKey: process.env.CHRT_API_KEY!,
+  baseUrl: 'https://api.chrt.co/v1',      // default
+  retries: 2,                             // retry on 5xx + network errors, default 2
   region: 'NOAA_ENC',                     // default tile region
   tileBaseUrl: 'https://tiles.chrt.co',   // override for staging tiles
+  deviceId: 'my-app-install-uuid',        // required for offline.* — see below
+  manifestPath: './chrt-offline-manifest.json', // optional — enables offline budget + list()
+  vessel: { safetyDepthM: 3 },            // one safety depth for every depth-aware call
 });
 ```
 
+`new Chrt('chrt_sk_live_…')` is shorthand for `new Chrt({ apiKey: 'chrt_sk_live_…' })`.
+
+### `vessel` — one safety depth
+
+Set your draft-plus-margin once and every depth-aware call inherits it: `ahead()` and
+`alongRoute()` filter at it, and `style()` shades soundings and draws danger rings at it. An
+explicit per-call `safetyDepth` / `safetyContour` always wins.
+
+It is **client-side and per-instance, deliberately — not bound to your API key**. A consumer app
+has one key and many skippers with different boats; a key-scoped draft would give them all the
+same number. Construct a `Chrt` per user, or pass `safetyDepth` per call.
+
+**With no `vessel`, CHRT sends no depth at all** rather than guessing a draft — filtering on an
+invented one would silently drop real hazards.
+
+> Not yet reachable from the *served* style: `styleUrl()` takes `theme` + `symbols` only, so a
+> non-JS client cannot currently get per-user depth shading.
+
 ## API Reference
 
+**Which methods can a non-JS client use?** Everything under *HTTP endpoint* below is a plain REST
+call any language can make. Everything marked **JS-only** runs in-process and has no HTTP equivalent.
+
+| Method | HTTP endpoint | Notes |
+|---|---|---|
+| `chrt.features(opts)` | `GET /v1/features` | |
+| `chrt.query(opts)` | `GET /v1/query` | |
+| `chrt.ahead(opts)` | `GET /v1/query/ahead` | what's charted in a sector ahead |
+| `chrt.alongRoute(opts)` | `GET /v1/query/route` | same, for a planned passage |
+| `chrt.alongRouteIter(opts)` | `GET /v1/query/route` | auto-paginates |
+| `chrt.cells.list(opts?)` | `GET /v1/cells` | |
+| `chrt.cells.get(id)` | `GET /v1/cells/{id}` | |
+| `chrt.coverage.list(opts?)` | `GET /v1/coverage` | |
+| `chrt.coverage.forRoute(opts)` | `GET /v1/coverage/route` | which cells a passage needs |
+| `chrt.warmTiles(region?)` | `POST /v1/mint/tile-token` | |
+| `chrt.styleUrl(opts?)` | `GET {tileBaseUrl}/v1/styles/{region}/style.json` | mints first |
+| `chrt.fetchStyle(opts?)` | same, then fetches it | |
+| `chrt.interact.entitlement()` | `POST /v1/interact/entitlement` | |
+| `chrt.style(opts?)` | — | **JS-only** — local generator |
+| `chrt.transformRequest(opts?)` | — | **JS-only** — returns a closure |
+| `chrt.tiles.tileUrl(z, x, y)` | — | **JS-only** — string builder |
+| `chrt.interact.attach/inspectAll` | — | **JS-only** — needs a GL JS map |
+| `chrt.featuresIter` / `cellsIter` | — | **JS-only** — async iterators |
+
 ### `chrt.features(options)`
 Query GeoJSON features by bounding box.
 
@@ -99,8 +355,11 @@ Query GeoJSON features by bounding box.
 |--------|------|----------|-------------|
 | `bbox` | `[w, s, e, n]` | ✓ | Bounding box |
 | `layer` | `string` | | S-57 layer code (e.g. `DEPARE`) |
-| `limit` | `number` | | Max results (default 100) |
+| `limit` | `number` | | Max results (default 100, max 1000) |
 | `offset` | `number` | | Pagination offset |
+| `signal` | `AbortSignal` | | |
+
+Returns a GeoJSON `FeatureCollection` with `total_count`, `limit` and `offset` alongside `features`.
 
 ### `chrt.query(options)`
 Spatial proximity search around a point.
@@ -108,37 +367,130 @@ Spatial proximity search around a point.
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
 | `point` | `[lng, lat]` | ✓ | Centre point |
-| `radius` | `number` | | Radius in metres (default 1000) |
+| `radius` | `number` | | Radius in metres (default 500, clamped 1–50 000) |
 | `layer` | `string` | | Comma-separated layer codes |
-| `limit` | `number` | | Max results |
+| `limit` | `number` | | Max results (default 50, max 500) |
+| `signal` | `AbortSignal` | | |
+
+Returns a `QueryResponse`: a GeoJSON `FeatureCollection` whose `properties` carry `layer`, `cell_id`
+and `distance_m` (geodesic metres from `point`), plus a `query` block echoing what the server
+**actually applied after clamping** — read `res.query.radius_m` to see that `radius: 90000` silently
+became `50000`. Unlike `chrt.features()`, this endpoint is **not paginated**: it returns no `offset`,
+so widen `radius` rather than paging.
+
+### `chrt.ahead(options)`
+The fan-ahead query — the significant features in a sector from a point along a bearing. Built for
+the position-plus-COG case: a craft with a heading but no planned route.
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `point` | `[lng, lat]` | ✓ | Origin |
+| `bearing` | `number` | ✓ | Degrees true; out-of-range values normalise |
+| `arc` | `number` | | **Full** sector width centred on `bearing` (default 90 — `arc: 60` sweeps ±30°) |
+| `range` | `number` | | Metres (default 5000, clamped 1–50 000) |
+| `rangeNm` | `number` | | Nautical miles — mutually exclusive with `range` (passing both throws) |
+| `safetyDepth` | `number` | | Filters out only what is **known** to be deeper |
+| `layer` | `string` | | Defaults to CHRT's significant-feature set |
+| `limit` | `number` | | Default 50, max 500 |
+
+Each feature carries `distance_m`, `bearing_deg`, `least_depth_m` and `depth_clearance_m` (negative =
+shallower than your `safetyDepth`).
+
+> **Facts that sort, never a verdict.** There is deliberately no severity score and no `safe` flag —
+> a risk model is a navigation-grade claim. You sort; CHRT ranks nothing.
+>
+> **An empty result is not an all-clear.** Zero features in covered water and zero features because
+> CHRT has no cells there are different answers. Every response carries a `coverage` block
+> (`covered`, `covered_fraction`, `cells`) — **check `coverage.covered` before telling a user
+> anything.**
 
 ### `chrt.cells.list(options?)`
 List available ENC cells.
 
-### `chrt.cells.get(cellId)`
-Get metadata for a specific cell.
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `source` | `string` | | Chart-source **id**, e.g. `'NOAA_ENC'` — *not* the agency name `'NOAA'`, which matches nothing and returns an empty list rather than an error. `chrt.coverage.list()` enumerates the ids. |
+| `status` | `string` | | e.g. `'CURRENT'`. Case-insensitive. |
+| `scaleBand` | `ScaleBand` | | `'Overview'` \| `'General'` \| `'Coastal'` \| `'Approach'` \| `'Harbor'`. Matched **case-sensitively** — `'harbor'` matches nothing. |
+| `bbox` | `[w, s, e, n]` | | Cells whose bounds *intersect* this box |
+| `limit` | `number` | | Max results (default 100, max 1000) |
+| `offset` | `number` | | Pagination offset |
+| `signal` | `AbortSignal` | | |
 
-### `chrt.style(opts?)`
-Returns a ready-to-use MapLibre/Mapbox GL **S-52** style object. Options: `palette`
-(`'DAY'` | `'DUSK'` | `'NIGHT'`), `region`, `depthUnits`, plus the other atlas style options.
+Returns `{ cells, total_count, limit, offset }`. Use `chrt.cellsIter(options?)` to page automatically.
 
-### `chrt.transformRequest(opts?)`
-Returns a `transformRequest` that mints a short-lived tile JWT from your API key and attaches
-it as `Authorization: Bearer` on `tiles.chrt.co` requests only. Pass `{ region }` to override
-the default region.
+### `chrt.cells.get(cellId)`
+Get metadata for a specific cell. Takes the id positionally: `chrt.cells.get('US5MA11M')`.
+Returns a `CellDetail`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `cell_id` | `string` | e.g. `'US5MA11M'` |
+| `title` | `string \| null` | Chart title |
+| `chart_source` | `string` | Source id, e.g. `'NOAA_ENC'` |
+| `status` | `string` | e.g. `'CURRENT'` |
+| `scale` | `number \| null` | Compilation scale denominator |
+| `scale_band` | `string \| null` | Usage band — a `ScaleBand` name, e.g. `'Harbor'` |
+| `edition` · `update_number` · `issue_date` | | **Data currency** — the fields that say how current the chart is |
+| `bbox_north` · `bbox_south` · `bbox_east` · `bbox_west` | `number \| null` | Bounds in decimal degrees (WGS 84), `null` if the issuing office recorded none. Written as a group, so in practice all four are set or all four are `null`. |
+| `last_checked_at` | `string \| null` | ISO 8601 — when CHRT last checked the issuing office's catalogue for this cell. Freshness of the *check*, not of the chart; use `edition` / `update_number` / `issue_date` for chart currency. |
+
+> **Bounds are flat here and on `coverage.forRoute()` — one shape across the API.** Up to
+> 0.9.2 the SDK declared these flat fields while `/v1/cells` alone returned a nested `bbox`
+> object, so `cell.bbox_north` typechecked and read `undefined` on every response. The
+> endpoint was the outlier; it now sends what this type has always declared, and reading
+> `cell.bbox_north` works against any deployed CHRT API.
+
+### `chrt.coverage.list(options?)`
+List the chart sources available to your key. Options: `country` (e.g. `'US'`), `source`.
+Returns `{ sources, total_cells }`, where each source carries `source` (the **id** you filter cells
+by, e.g. `'NOAA_ENC'`), `agency` (the issuing office's display name, e.g. `'NOAA'`), `cell_count` and
+`scale_bands` (counts keyed by band name). This is the endpoint that tells you which `source` ids are
+valid — passing an agency name anywhere else silently matches nothing.
+
+### `chrt.style(opts?)` — **JS-only**
+Returns a ready-to-use MapLibre/Mapbox GL **S-52** style object. Generated locally: no network, works
+offline, and **does not apply a custom style bound to your key**. Options: `palette`
+(`'DAY' | 'DUSK' | 'NIGHT'`), `symbolSet`, `region`, `depthUnits`, `safetyContour`, `chartMode`, plus
+the other atlas style options. Non-JS clients want `styleUrl()` instead.
+
+### `chrt.styleUrl(opts?)`
+URL of the **served** S-52 style — the CHRTstyle Style API at
+`{tileBaseUrl}/v1/styles/{region}/style.json`. `async`: it pre-mints the tile token so the style
+request (which MapLibre does not retry) carries auth. Options: `theme`
+(`'day' | 'dusk' | 'night'`), `symbols`. Always pair with `transformRequest()`.
+
+The served document honours the CHRTstyle custom style bound to your key (a **Dev+** feature; Free
+keys and keys with no bound style get the default themes). This is the style path for any client that
+can't run `chrt.style()`.
+
+### `chrt.fetchStyle(opts?)`
+Fetches the served style as a MapLibre style object. Same options as `styleUrl()`, plus `signal`.
+Prefer it over `styleUrl()` when you want to inspect or mutate the document, or when you can't use
+`transformRequest()` for the style request itself. Throws `ChrtError` on failure; does not retry.
+
+### `chrt.transformRequest(opts?)` — **JS-only**
+Returns a `transformRequest` closure that attaches the tile JWT as `Authorization: Bearer` on
+`tiles.chrt.co` **tile and served-style** requests only. Sprite, glyph and third-party URLs pass
+through untouched. Pass `{ region }` to override the default region.
 
 ### `chrt.warmTiles(region?)`
-Pre-mints the tile token so you can surface auth errors (e.g. `region_not_licensed`,
-`tile_quota_exceeded`) before the map loads. Optional — `transformRequest()` warms the cache
-on its own.
+Pre-mints the tile token so you can surface auth errors (`region_not_licensed`,
+`tile_quota_exceeded`, …) before the map loads. Optional — `transformRequest()` warms the cache on
+its own.
+
+### `chrt.tiles.tileUrl(z, x, y)` — **JS-only**
+Concrete vector tile URL at `tiles.chrt.co` for one tile. Prefer `chrt.style()` / `chrt.styleUrl()`,
+which wire the source for you.
 
-### `chrt.tiles.tileUrl(z, x, y)`
-Single vector tile URL template at `tiles.chrt.co`. Prefer `chrt.style()`, which wires the
-source for you.
+### `chrt.interact.*`
+See [Click-to-inspect](#click-to-inspect-chrtinteract). `attach(map, opts?)` and
+`inspectAll(map, point, opts?)` need a GL JS map instance; `inspect(feature, opts?)` decodes locally
+but checks entitlement over HTTP first.
 
-### `chrt.styleUrl()` · `chrt.tiles.groups()` — deprecated
-CHRT serves no remote `style.json` — use `chrt.style()`. Tilesets were consolidated to one
-source per region (2026-04), so the per-group catalogue is legacy.
+### `chrt.tiles.groups()` — deprecated
+Tilesets were consolidated to one source per region (2026-04). The route no longer exists — calling
+it fails with `ChrtError` 404. Use `chrt.style()` or `chrt.styleUrl()`.
 
 ## Error Handling
 
@@ -154,10 +506,21 @@ try {
 }
 ```
 
+Typed errors by area: `ChrtError` (REST), `TileTokenError` (minting — `invalid_api_key`,
+`region_not_licensed`, `tile_quota_exceeded`, `region_not_available`, `feature_flag_disabled`,
+`network_error`, `unexpected_response`), `InteractError` (`interact_not_enabled` — includes the
+current `plan` and an upgrade hint — `invalid_api_key`, `missing_scope`, `enrich_failed`,
+`unknown_layer`, `network_error`, `unexpected_response`), and `OfflineError` (below).
+
 ## Offline Downloads (CHRToffline)
 
 Download MBTiles bundles for offline rendering. Bundles are SHA-256 verified before commit. Interrupted downloads resume from a `.partial` sidecar file.
 
+**Requires the Pro plan or above**, enforced server-side at mint time — Free and Dev keys get
+`OfflineError` code `offline_requires_pro_plan`. The key also needs the `offline:download`
+scope, which is checked **before** the plan: a key without it gets `offline_not_enabled`
+regardless of tier, so add the scope first or the plan refusal never surfaces.
+
 **Runtime support in v1:** Node 18+, Bun, Deno. Browser and React Native are deferred to a follow-up.
 
 ```typescript
@@ -211,7 +574,8 @@ try {
       case 'download_corrupt': console.log('SHA mismatch'); break;
       case 'network_interrupted': console.log('resume later'); break;
       case 'coverage_denied': console.log('region not licensed'); break;
-      case 'offline_not_enabled': console.log('enable use_offline on this API key'); break;
+      case 'offline_requires_pro_plan': console.log('CHRToffline needs Pro+ — chrt.co/pricing'); break;
+      case 'offline_not_enabled': console.log('add the offline:download scope to this API key'); break;
     }
   }
 }