@chrtco/sdk 0.8.1 → 0.9.1

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 All notable changes to `@chrtco/sdk` will be documented in this file.
 
+## [Unreleased]
+- **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.
+- **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
+- **CHRTinteract v1.1 — multi-feature disambiguation + area-feature selection.** A chart click rarely hits one feature (a buoy on a channel over a DEPARE); interact now collects **everything under the click** instead of silently taking the topmost hit:
+  - **Candidate collection with tolerance** — point and line targets are picked up within a configurable pixel radius (`tolerance`, default 8px; `0` = exact point); area (polygon) candidates always require the exact click point to fall inside them.
+  - **Cross-tile dedupe by S-57 identity** — features split across tile boundaries (or rendered by several style layers) fold into one candidate via the source-cell-scoped `LNAM` (AGEN+FIDN+FIDS long name; carried by CHRT tiles end-to-end — verified 100% present on served tiles), with the `AGEN:FIDN:FIDS` composite as fallback. Identity-less features are never folded.
+  - **Class-priority ordering** — point targets > line targets > area targets, safety-critical classes first within each band (`INSPECT_CLASS_RANK`, kept **value-coherent with the atlas `LABEL_PRIORITY` collision ladder** — one priority model across the platform, enforced by a unit test; documented deviations in `INSPECT_RANK_DEVIATIONS`). **Area features never preempt the buoy on top of them but always remain selectable** — a click on open water resolves to its DEPARE.
+  - **Child-object collapse** — co-located S-57 child objects (LIGHTS, TOPMAR, FOGSIG, RTPBCN, DAYMAR) fold into their parent buoy/beacon candidate (`collapsedChildren`); selecting the parent runs the v1 co-located merge. Opt out with `collapseChildren: false`.
+  - **`attach()` disambiguation modes** — built-in popup: multi-hit shows a minimal candidate list (same invariant disclaimer footer), picking a row opens the result card. New `onCandidates(candidates, ctx)` callback for custom UIs — resolve a choice with `ctx.select(candidate)` (drives `onInspect` + popup as usual). Headless `onInspect`-only: the top candidate is inspected immediately and **clicking the same spot again cycles** to the next candidate (buoy → channel → depth area …). Single hits behave exactly like v1.
+  - **New `chrt.interact.inspectAll(map, point, opts?)`** — headless candidate collection for any screen point or `[lng, lat]`; returns `{ candidates, select }` where `select(candidate, { enrich? })` resolves the full `InspectResult` (v1 co-located merge; enrichment metered as before). Server-side entitlement is checked first, same as `attach`/`inspect`.
+  - **Safety invariants extended** — every `InspectCandidate` carries the same `notice` (non-SOLAS disclaimer + HO attribution + data currency) as results; the candidate-list popup renders the invariant footer.
+  - New exports: `collectCandidates`, `collectClickCandidates`, `featureIdentity`, `resolveTargetClass`, `candidateRank`, `decodeCandidate`, `INSPECT_CLASS_RANK`, `DEFAULT_INSPECT_CLASS_RANK`, `INSPECT_RANK_DEVIATIONS`, `DEFAULT_CLICK_TOLERANCE`; new types `InspectCandidate`, `InspectTargetClass`, `InspectCandidateSet`, `CandidateQueryOptions`, `CandidatesEventContext`, `ClickAnchor`. `InteractMapLike` gains optional `unproject` (used when `inspectAll` receives a screen point). No entitlement or pricing changes.
+
+## [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.