@chrtco/sdk 0.10.0 → 0.10.2

package/CHANGELOG.md

@@ -3,6 +3,57 @@
 All notable changes to `@chrtco/sdk` will be documented in this file.
 
 ## [Unreleased]
+
+### Added
+- **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
+  `didFinishLoading` never fired, because unlike a web app compositing over a
+  basemap, native draws exactly and only what the style declares.
+- **`sprite` is declared in every served s52/chrt/raster style** —
+  `{tileBaseUrl}/v1/sprites/{family}-{theme}`, a standard GL sprite pair
+  (public, unauthenticated) generated from the same atlas registries the
+  style generator reads. GL JS behaviour is unchanged (runtime-registered
+  images win); native renderers get buoys, beacons, wrecks and patterns with
+  no client work. s101 styles deliberately declare **no** sprite until the
+  vendored S-100 artwork clears licence review.
+- **Offline styles carry everything a chart needs**: `sprite` and `glyphs`
+  now point at `{protocol}://assets/…` inside the chart-assets pack served by
+  `GET /v1/offline/assets` (sprite sheets + Open Sans glyph PBFs). An offline
+  chart previously rendered mute geometry — no labels, no soundings figures,
+  no symbols.
+- Style `metadata` carries `chrt:style-rev` beside `chrt:style-id` when a
+  custom style is bound — provenance that survives every cache and proxy.
+
+### Known limits
+- MapLibre Native iOS silently collapses its entire render pass above ~482
+  symbol layers (measured externally; exact threshold). Served styles
+  currently ship 575 symbol layers, pinned by a ratchet test; reduction below
+  the cliff is in progress. Native consumers should avoid stacking many
+  additional symbol layers on top of the served style.
+
+- **SOUNDG depth-number labels use a single-font stack (`["Open Sans
+  Semibold"]`), and every text-font in every served style is now pinned to
+  one vendored font.** The previous semibold stack carried a Regular
+  "fallback" — but MapLibre joins a multi-font stack into ONE glyph URL
+  (`Open Sans Semibold,Open Sans Regular/0-255.pbf`), which no static glyph
+  host serves. fonts.openmaptiles.org answers it with an HTML error page as
+  HTTP 200: GL JS swallowed the garbage and simply never drew those glyphs,
+  MapLibre **Native fatally parses it as protobuf** — the sounding depth
+  numbers were the casualty, on the one surface where they matter most. The
+  fallback therefore broke the primary; it is gone, and a served-style test
+  now rejects any multi-font stack. Caught by the new MapLibre Native
+  golden-image harness (`scripts/native-render/`) on its first run.
+- **The offline chart-assets pack now vendors Open Sans Semibold** (0-255 /
+  256-511, OFL, same origin as Regular/Italic). Offline charts previously
+  rendered SOUNDG depth numbers and all 60 nav-aid labels (beacons, fog
+  signals…) textless — the zip only carried fonts the style half-used.
+- **`applyChrtSymbolSet` is passed the active palette at both serving
+  routes** (offline styles, and online custom-style composition). Omitting
+  it silently resolved the house cable/pipeline dash colours against DAY —
+  NIGHT/DUSK offline charts shipped day-bright dashes. Caught by the
+  harness's online≡offline twin gate.
+
 - **`/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.

package/README.md

@@ -210,6 +210,10 @@ const sources = buildSources({ region: 'NOAA_ENC' });
 
 ## Using CHRT without JavaScript
 
+> **Prefer codegen?** The whole HTTP surface is described by an OpenAPI 3.1 spec at
+> **https://api.chrt.co/openapi.json** — generate a typed Swift/Kotlin/Python/Go client
+> from it instead of hand-rolling the calls below.
+
 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.

package/dist/index.cjs

@@ -22420,7 +22420,7 @@ function getLabelConfig(layerName, opts = {}) {
         screenColors.deeper
       ] : screenColors.shoaler;
       const haloColor = screenColors.halo;
-      const fontStack = weight === "semibold" ? ["Open Sans Semibold", "Open Sans Regular"] : ["Open Sans Regular"];
+      const fontStack = weight === "semibold" ? ["Open Sans Semibold"] : ["Open Sans Regular"];
       return {
         type: "symbol",
         // Property name varies by source path:
@@ -27478,6 +27478,34 @@ function makeCollapsedBandVariant(layer, B, isExempt) {
   delete collapsed.maxzoom;
   return [collapsed];
 }
+function collapsedOrientationGate(minzoom) {
+  const clauses = [NOT_DOMINATED_FILTER];
+  for (const D of BAND_DRAW_ORDER) {
+    const dMaxzoom = dominatedVariantMaxzoom(D);
+    if (dMaxzoom <= minzoom) continue;
+    clauses.push(["all", dominatedByMinFilter(D), ["<", ["zoom"], dMaxzoom]]);
+  }
+  return ["any", ...clauses];
+}
+function makeCollapsedCrossBandLabel(label, isExempt) {
+  const classMinzoom = label.minzoom ?? 0;
+  const clauses = [];
+  for (const B of BAND_DRAW_ORDER) {
+    const floor = BAND_PRIORITY_RANGES[B].minzoom;
+    const parts = [bandFilterExpression(B)];
+    if (floor > 0) parts.push([">=", ["zoom"], floor]);
+    if (!isExempt) {
+      parts.push(collapsedDominanceGate(B, Math.max(classMinzoom, floor)));
+    }
+    clauses.push(parts.length === 1 ? parts[0] : ["all", ...parts]);
+  }
+  const collapsed = {
+    ...label,
+    filter: combineWithBandFilter(label.filter, ["any", ...clauses])
+  };
+  delete collapsed.maxzoom;
+  return collapsed;
+}
 
 // src/atlas/style-generator.ts
 var META_LAYERS = /* @__PURE__ */ new Set([
@@ -27629,7 +27657,7 @@ var CELL_BAND_OPACITY_CURVE = {
   "5": [[11, 0.6], [13, 0.35], [18, 0.25]],
   "6": [[13, 0.75], [16, 0.55], [22, 0.45]]
 };
-function fanOrientationLabelByCellBand(label) {
+function fanOrientationLabelByCellBand(label, bandFan) {
   const cellBandExpr = [
     "slice",
     ["coalesce", ["get", "_cell_id"], "??9???"],
@@ -27654,6 +27682,16 @@ function fanOrientationLabelByCellBand(label) {
       ...label.paint ?? {},
       "text-opacity": opacityExpr
     };
+    if (bandFan === "collapsed") {
+      variants.push({
+        ...label,
+        id: `${label.id}-cell${code}-notdom`,
+        filter: combineWithBandFilter(cellFiltered, collapsedOrientationGate(minzoom)),
+        minzoom,
+        paint
+      });
+      continue;
+    }
     variants.push({
       ...label,
       id: `${label.id}-cell${code}-notdom`,
@@ -27683,26 +27721,66 @@ function byLabelPriorityBottomUp(bundles) {
     (a, b) => getLabelPriority(b.objectClass) - getLabelPriority(a.objectClass)
   );
 }
-function chartModeFilterForBand(layer, B, higherCascadeBands, lockedBounds, isRequestedBand) {
-  let filter = combineWithBandFilter(layer.filter, bandFilterExpression(B));
+function chartModeBandClauses(layer, B, higherCascadeBands, lockedBounds, isRequestedBand) {
+  const parts = [bandFilterExpression(B)];
   if (!isDominanceExempt(layer)) {
     for (const D of higherCascadeBands) {
-      filter = combineWithBandFilter(filter, ["!", dominatedByMinFilter(D)]);
+      parts.push(["!", dominatedByMinFilter(D)]);
     }
   }
   if (lockedBounds && isRequestedBand) {
-    filter = combineWithBandFilter(filter, withinBboxFilter(lockedBounds));
+    parts.push(withinBboxFilter(lockedBounds));
+  }
+  return parts;
+}
+function chartModeFilterForBand(layer, B, higherCascadeBands, lockedBounds, isRequestedBand) {
+  const [first, ...rest] = chartModeBandClauses(
+    layer,
+    B,
+    higherCascadeBands,
+    lockedBounds,
+    isRequestedBand
+  );
+  let filter = combineWithBandFilter(layer.filter, first);
+  for (const part of rest) {
+    filter = combineWithBandFilter(filter, part);
   }
   return filter;
 }
+function makeCollapsedChartLabel(label, cascade, requestedSet, lockedBounds) {
+  const clauses = cascade.map((B, i) => {
+    const parts = chartModeBandClauses(
+      label,
+      B,
+      cascade.slice(i + 1),
+      lockedBounds,
+      requestedSet.has(B)
+    );
+    return parts.length === 1 ? parts[0] : ["all", ...parts];
+  });
+  const collapsed = {
+    ...label,
+    filter: combineWithBandFilter(label.filter, ["any", ...clauses])
+  };
+  delete collapsed.maxzoom;
+  return collapsed;
+}
 function generateStyle(palette = "DAY", opts = {}) {
   const sources = buildSources(opts);
   const sourceId = opts.region ?? DEFAULT_REGION;
   const orderedClasses = getOrderedClasses();
-  const layers = [];
+  const backgroundLayer = {
+    id: "chrt-background",
+    type: "background",
+    // A background layer takes no source; StyleLayer models sourced layers,
+    // so the never-used source fields are absent via the unknown hop.
+    paint: { "background-color": resolveColor("NODTA", palette) }
+  };
+  const layers = [backgroundLayer];
   const labelLayers = [];
   const chartCascade = opts.chartMode ? CHART_CASCADE_CODES[opts.chartMode.band] : null;
   const chartRequestedCodes = opts.chartMode ? CHART_BAND_CODES[opts.chartMode.band] : null;
+  const bandFan = opts.bandFan ?? "collapsed";
   const lockedBounds = opts.chartMode?.lockedBounds;
   const bundles = [];
   for (const objectClass of orderedClasses) {
@@ -27756,6 +27834,12 @@ function generateStyle(palette = "DAY", opts = {}) {
       )
     );
     for (const { label } of chartLabelBundles) {
+      if (bandFan === "collapsed") {
+        labelLayers.push(
+          makeCollapsedChartLabel(label, chartCascade, requestedSet, lockedBounds)
+        );
+        continue;
+      }
       for (let i = 0; i < chartCascade.length; i++) {
         const B = chartCascade[i];
         const higher = chartCascade.slice(i + 1);
@@ -27778,7 +27862,6 @@ function generateStyle(palette = "DAY", opts = {}) {
     }
     layers.push(...labelLayers);
   } else {
-    const bandFan = opts.bandFan ?? "collapsed";
     const emitBand = (base, code) => bandFan === "legacy" ? makeBandVariants(base, code) : makeCollapsedBandVariant(base, code, isDominanceExempt(base));
     for (const code of BAND_DRAW_ORDER) {
       for (const { featureLayers } of regularBundles) {
@@ -27797,7 +27880,7 @@ function generateStyle(palette = "DAY", opts = {}) {
     for (const { objectClass, label } of bundles) {
       if (!label) continue;
       if (getLabelBehavior(objectClass) === "orientation-cross-band") {
-        labelLayers.push(...fanOrientationLabelByCellBand(label));
+        labelLayers.push(...fanOrientationLabelByCellBand(label, bandFan));
       }
     }
     const featureLabelBundles = byLabelPriorityBottomUp(
@@ -27806,6 +27889,10 @@ function generateStyle(palette = "DAY", opts = {}) {
       )
     );
     for (const { label } of featureLabelBundles) {
+      if (bandFan === "collapsed") {
+        labelLayers.push(makeCollapsedCrossBandLabel(label, isDominanceExempt(label)));
+        continue;
+      }
       for (const code of BAND_DRAW_ORDER) {
         labelLayers.push(...emitBand(label, code));
       }
@@ -27813,6 +27900,7 @@ function generateStyle(palette = "DAY", opts = {}) {
     layers.push(...labelLayers);
   }
   const symbolSet = opts.symbolSet ?? "s52";
+  const spriteBase = `${opts.tileBaseUrl ?? "https://tiles.chrt.co"}/v1/sprites`;
   const style = {
     version: 8,
     name: `CHRT ${SYMBOL_SET_LABELS[symbolSet]} ${PALETTE_NAMES[palette]}${opts.chartMode ? ` \u2014 chart:${opts.chartMode.band}` : ""}`,
@@ -27826,13 +27914,21 @@ function generateStyle(palette = "DAY", opts = {}) {
       "chrt:description": "IHO S-52 portrayal rules for Electronic Navigational Charts (ENCs). Generated from the CHRT atlas engine."
     },
     sources,
-    // TODO(Phase 9): the superadmin style-generator emits a reference JSON
-    // intended for external upload to Mapbox Studio. That flow is vestigial —
-    // we're decommissioning Mapbox MTS. When the page is repurposed to
-    // generate a MapLibre-native style for self-hosted consumers, wire the
-    // `sprite` field back in against a CHRT-hosted sprite route (see
-    // `.chrt/` follow-ups). Runtime maps load S-52 symbols via
-    // `loadS52SymbolImages()` — no sprite fetch happens at runtime.
+    // A standard GL sprite, declared in the style — the mechanism every GL
+    // renderer (JS and native) already implements. The web app additionally
+    // registers atlas images at runtime via loadS52SymbolImages() (which wins
+    // when both are present, so JS behavior is unchanged); native consumers
+    // get their icons from this declaration alone. s52 sheets are per-palette
+    // (the artwork carries S-52 colour tokens); chrt and raster are
+    // fixed-palette, one sheet each. s101 deliberately declares NO sprite
+    // until the vendored S-100 artwork clears licence review — see
+    // assets/s101/PROVENANCE.md. CHRTsail #122.
+    // Every non-s101 family is palette-scoped: chrt and raster keep fixed
+    // palettes for their OWN glyphs, but both fall back to s52 artwork for
+    // classes they don't remap — and that artwork carries colour tokens.
+    ...symbolSet !== "s101" && {
+      sprite: `${spriteBase}/${symbolSet}-${palette.toLowerCase()}`
+    },
     glyphs: "https://fonts.openmaptiles.org/{fontstack}/{range}.pbf",
     layers
   };