@chrtco/sdk 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to `@chrtco/sdk` will be documented in this file.
 
+## [0.9.0] — 2026-07-13
+- **New: CHRTinteract (`chrt.interact.*`)** — productized click-to-inspect for CHRT charts. Included with the **Dev plan and above**; the entitlement is derived from the team's plan and **enforced server-side** at attach time (`POST /v1/interact/entitlement` on `api.chrt.co`).
+  - `await chrt.interact.attach(map, opts?)` — wires click → decode onto any MapLibre / Mapbox GL map showing CHRT tiles. Headless-first (`onInspect(result, ctx)` callback); a minimal built-in plain-DOM popup is the default when no callback is given (`popup: true` keeps both). Click pipeline and co-located S-57 child-object merging (LIGHTS / FOGSIG / TOPMAR / RTPBCN / parent buoy names, sector collection) mirror the first-party CHRT map. Returns `{ detach() }`. MapLibre remains an **optional** peer dependency — the map is consumed structurally.
+  - `await chrt.interact.inspect(feature, opts?)` — headless decode of a single feature into a typed `InspectResult` (`kind: "navaid" | "bridge" | "area"`): mariner light characteristic ("Fl(2+1) W 10s"), flash/eclipse timing phases, sector arcs, colour/topmark/status semantics, bridge clearances, restriction lists, seasonal `INFORM` notes, coordinates.
+  - `inspect(feature, { enrich: true })` (or `attach(map, { enrich: true })`) — resolves full S-57 source properties + **cell provenance / data currency** (edition, update_number, issue_date) through the existing `/v1/features` + `/v1/cells` APIs with your key; the features call is metered against the `featureCalls` quota.
+  - **Safety invariants:** every `InspectResult` carries `notice` — the non-SOLAS "not for primary navigation" disclaimer, issuing hydrographic-office attribution, and data currency; the built-in popup always renders them.
+  - **Typed errors:** `InteractError` with `code`: `interact_not_enabled` (Free plan; includes upgrade hint + `plan`), `invalid_api_key`, `missing_scope`, `enrich_failed`, `unknown_layer`, `network_error`, `unexpected_response`.
+  - New exports: `InteractClient`, `InteractError`, decode tables/helpers (`decodeNavAidProps`, `buildFlashPattern`, `buildSectorArcsFC`, …) and the `InspectResult` type family.
+- **CHRTstyle Style API — served styles.** The tile-worker now serves `GET https://tiles.chrt.co/v1/styles/{region}/style.json?theme=day|dusk|night` (same Bearer tile-JWT as tiles, edge-cached). The served document honors the API key's bound **CHRTstyle custom style** (platform → Map Styles; binding via the key's *Map style* setting): enabled palettes + default palette, layer visibility, nav-aid/label/sounding/water-body settings, applied server-side. Custom styles are a **Dev+ feature** — Free-plan keys (and keys with no bound style) get the default themes; a gated binding falls back to the default style, with `style_applied: false, style_reason: "plan_gated"` surfaced in the mint response.
+- **`styleUrl()` un-deprecated** — `chrt.styleUrl({ theme? })` / `chrt.tiles.styleUrl(...)` now return the served-style URL. Async: it pre-mints the tile token so the style request (which MapLibre does not retry) is guaranteed to carry auth via `transformRequest()`.
+- **New `chrt.fetchStyle({ theme?, signal? })`** — fetches the served style as a MapLibre style object; throws `ChrtError` on failure. `chrt.style()` remains the local, offline-capable generator (applies no custom style).
+- **`transformRequest()` now also authenticates the served-style URL** (`/v1/styles/{region}/style.json` on the configured `tileBaseUrl`) in addition to tile URLs. Sprite/glyph/third-party URLs still pass through untouched.
+- **New atlas exports** — `generateCustomStyle`, `applyCustomStyleSettings`, `sanitizeCustomStyleConfig`, `normalizeTheme`, `resolveCustomTheme`, plus the platform settings shapes (`NavAidSettings`, `LabelSettings`, `SoundingSettings`, `WaterBodySettings`, `CustomStyleConfig`) — the SDK atlas is now the canonical home of those types (the platform app re-exports them).
+- **Served styles carry compliance metadata**: source-HO attribution on the vector source + `chrt:attribution` / `chrt:disclaimer` in style metadata. CHRT remains situational-awareness only — not for primary navigation.
+- **Atlas — sector-light z-order (Portrayal Excellence P6)**: LIGHTS feature layers (light flares, incl. sector lights carrying SECTR1/SECTR2 — and any future sector arc / sector-limit-line layers built for the class) are now emitted **above every scale band's area fills, lines, and general symbology** in both continuous and chart mode, directly below the text-label block. Previously the band-then-class interleave let higher-band opaque fills (DEPARE/LNDARE/UNSARE) paint over lower-band light geometry as zoom/density increased. LIGHTS symbol variants are also pinned collision-immune (`icon-allow-overlap` + `icon-ignore-placement`): the flare can never be culled by symbol placement, and — because it reserves no collision space — the hoist changes paint order only, never other classes' collision outcomes. Layer **ids are unchanged** (only array position moved); text labels still render above light geometry per S-52 text-last convention.
+- **Atlas — unified label priority model (Portrayal Excellence P4)**: one explicit class-based collision ladder (`LABEL_PRIORITY`, exported with `getLabelPriority()` / `labelSortKey()`) replaces the always-paint safety-label flags and the Harbor-band-only collision patch. Safety-critical labels (light characteristics, hazard depth callouts, overhead clearances) > nav-aid designations > depth field > structures > ambient notes; the ladder drives both label layer order (topmost places first) and rank-composed `symbol-sort-key`s, in continuous AND chart mode. Nav-aid/light labels now participate in collision at every band — cross-band duplicate copies of the same aid dedupe by colliding at identical anchors.
+- **Atlas — buoy/beacon designation abbreviation**: labels render chart-convention designations (`R "4"`) instead of the full NOAA name ("R Boston North Channel Lighted Buoy 4") on the tile path — the tile pipeline carries no precomputed `_navAidLabel`, so the full-name fallback was the biggest glyph-footprint driver of harbor-scale overprint. Names without a designation fall back to the full name; `extractNavAidDesignation()` exported (TS twin of the GL expression, also used by `preprocessNavAids`).
+- **Atlas — variable-anchor labels**: hazard depth callouts (UWTROC/OBSTRN/WRECKS) and structure names (LNDMRK, BRIDGE) shift around their symbol via `text-variable-anchor` instead of vanishing or overprinting. Deliberately NOT applied to dominance-exempt nav-aid classes (their cross-band duplicate labels must collide to dedupe).
+- **Atlas — style-spec validation in tests**: the generated style (both modes) is validated against the MapLibre v8 spec via `validateStyleMin`.
+- **Requires** the public `POST /v1/interact/entitlement` route on `api.chrt.co` and the tile-worker style route + mint `style_id`/`style_rev` claims (all ship with this release). New types: `ChrtStyleTheme`, `StyleUrlOptions`, `FetchStyleOptions`.
+
 ## [0.8.0] — 2026-06-30
 - **Online tile rendering now works end-to-end against `tiles.chrt.co`.** `chrt.transformRequest()` mints a short-lived ES256 tile JWT from your API key (`POST {baseUrl}/mint/tile-token`), caches and refreshes it, and attaches `Authorization: Bearer` on `tiles.chrt.co/v1/tiles/{region}/…/.mvt` requests only. This replaces the previous no-op transformer that injected `x-api-key` against a removed `api.chrt.co/v1/tiles/…?key=` path.
 - **New `chrt.style(opts?)`** — returns a ready-to-use IHO **S-52** MapLibre / Mapbox GL style object (`palette`: `DAY` | `DUSK` | `NIGHT`, plus `region`, `depthUnits`, and the other atlas options), with the tile source wired in. Mutate the returned object, or build a fully custom style over `buildSources()`. S-101 portrayal is on the roadmap.