@chrtco/sdk 0.10.1 → 0.10.3

package/dist/index.d.cts

@@ -107,6 +107,195 @@ declare class OfflineStyleError extends Error {
  */
 declare function buildOfflineStyle(onlineStyle: MapLibreStyle, mbtilesPath: string, opts?: BuildOfflineStyleOptions): MapLibreStyle;
 
+/**
+ * Strict scale-band priority for continuous-mode rendering.
+ *
+ * Each ENC feature in the served PMTiles carries `_cell_id` (added at
+ * baremetal NDJSON export time). NOAA's cell-id format encodes the source
+ * scale band as the third character: `US5MA85M` is band 5 (Harbor).
+ *
+ * MapLibre layer filters can't read `["zoom"]`, so to enforce "only one
+ * band renders at any given zoom" we emit one layer copy per band, each
+ * with a static band filter and per-band `minzoom`/`maxzoom`. The ranges
+ * below are non-overlapping (`minzoom` inclusive, `maxzoom` exclusive),
+ * so exactly one band is visible at any continuous zoom.
+ *
+ * Long-term cleanup: baremetal should emit a normalized `_band: 1..6`
+ * integer in NDJSON so this works for non-NOAA chart sources too. The
+ * `["slice", _cell_id, 2, 3]` extraction here is NOAA-specific.
+ */
+/**
+ * UI-facing scale-band names (matches the app's `ScaleBand` type in
+ * `src/lib/map/constants.ts`). Defined locally so the SDK doesn't have
+ * to depend on app code.
+ */
+type ScaleBand$1 = "Overview" | "General" | "Coastal" | "Approach" | "Harbor";
+/** S-57 source bands. NOAA cell ids use these as the third character. */
+type BandCode = "1" | "2" | "3" | "4" | "5" | "6";
+interface BandPriorityRange {
+    /** MapLibre `minzoom` (inclusive). */
+    minzoom: number;
+    /** MapLibre `maxzoom` (exclusive). `undefined` means no upper cap. */
+    maxzoom?: number;
+}
+/**
+ * Per-band minzoom thresholds for continuous mode. Bands cascade as
+ * fallbacks for one another — every band whose `minzoom` is satisfied
+ * may render. The deeper-numbered band's features render preferentially
+ * (drawn last in the z-stack, so its opaque fills cover lower bands),
+ * and lower bands fill in where the higher band has no coverage.
+ *
+ * Cross-band visual overlap (doubled coastlines, duplicate labels) is
+ * suppressed by the `_dominated_by_min` per-feature tag added at NDJSON
+ * export time (see `tools/chrt-baremetal/server/src/tilebuild/dominanceIndex.ts`):
+ * every feature whose centroid sits inside a higher-band cell's M_COVR
+ * coverage polygon is tagged with the LOWEST band code (2..6) that
+ * dominates it, and `makeBandVariants()` in the style generator emits
+ * per-(featureBand, dominatorBand) layer variants gated by `maxzoom =
+ * dominatedVariantMaxzoom(D)`. The dominated feature renders until
+ * exactly the zoom where its dominator becomes eligible AND has data in
+ * the tiles — solving the low-zoom "black silhouettes" bug where a
+ * band-3 LNDARE dominated by a band-5 cell was dropped at z7 even
+ * though band 5 wasn't yet rendering at z7.
+ *
+ * Opaque base-area FILLS are exempt from dominance gating entirely (see
+ * `DOMINANCE_EXEMPT_FILL_CLASSES` in the style generator): band-major
+ * draw order already makes the most-detailed band's opaque fill win at
+ * any covered pixel, and the coarser band shows through wherever the
+ * detailed band has no data — which is exactly the fallback semantics
+ * the cascade wants. The 2026-07 E1/E2 void diagnosis
+ * (docs/validation/portrayal-p1-p3-void-diagnosis-2026-07.md) proved
+ * per-feature dominance gating on fills structurally unsound: the tag is
+ * point-sampled but hides the WHOLE feature, so a Gulf-spanning band-1
+ * DEPARE tagged dominated-by-2 left dark voids across every part of the
+ * Gulf that band 2 doesn't actually cover.
+ *
+ * Bands 5 and 6 both start at z11; band 6 (Berthing) is drawn AFTER
+ * band 5 (Harbor) so where Berthing exists it visually wins, and
+ * Harbor shows through everywhere else.
+ *
+ * Band 1 starts at z0: the P3 low-zoom contract (charts never disappear
+ * from world view down) needs Overview-band data renderable as soon as
+ * tiles exist. Builds older than the z0 floor simply have no tiles below
+ * z3, so the widened range is a no-op against them.
+ */
+declare const BAND_PRIORITY_RANGES: Record<BandCode, BandPriorityRange>;
+/**
+ * Order in which band layers are emitted (and thus drawn — earlier = lower
+ * in the z-stack). Band 6 last so Berthing draws on top of Harbor.
+ */
+declare const BAND_DRAW_ORDER: BandCode[];
+/**
+ * UI scale-band names → cell-id band codes that should render in chart mode
+ * for that selection. The UI doesn't expose Berthing separately, so picking
+ * Harbor includes both `5` and `6` cells.
+ *
+ * `CHART_BAND_CODES` is the *requested* band set (what the user picked);
+ * `CHART_CASCADE_CODES` below adds the coarser bands that fall back where
+ * the requested band has no cells.
+ */
+declare const CHART_BAND_CODES: Record<ScaleBand$1, readonly BandCode[]>;
+/**
+ * UI scale-band names → ordered cascade of cell-id band codes for chart-mode
+ * rendering with graceful coverage fallback. Bands are listed coarsest-first
+ * so the style generator can use array order as draw order: lower bands draw
+ * earlier in the z-stack, the requested band draws last on top.
+ *
+ * The chart-mode implementation emits one filtered layer per cascade band per
+ * S-57 class. Where the requested band's cells provide data, its opaque fills
+ * cover the lower bands underneath; where the requested band has no cells
+ * (e.g. Chart→Harbor over Massachusetts Bay offshore), the next-coarser band
+ * shows through. Different cells in the same viewport may end up rendering at
+ * different effective bands.
+ *
+ * The per-feature `_dominated_by_min` tag baked at baremetal NDJSON-export
+ * time (see `tools/chrt-baremetal/server/src/tilebuild/dominanceIndex.ts`)
+ * suppresses lower-band features inside higher-band cell coverage so cell
+ * boundaries don't render with doubled coastlines or contours.
+ *
+ * Lock scope: when chart-Harbor's viewport-lock greyout is active, the
+ * `["within"]` bbox filter is applied ONLY to the requested band's variants
+ * — cascade fallback bands render across the full viewport. The greyout
+ * overlay still cues the lock boundary visually; the user picks Harbor and
+ * gets Harbor inside the lock plus dimmed Approach/Coastal context outside.
+ *
+ * See `.chrt/ux/chart-mode-band-fallback-2026-05-05.md` for the design
+ * rationale and the geographies (Boston Harbor, Massachusetts Bay offshore)
+ * that motivated this.
+ */
+declare const CHART_CASCADE_CODES: Record<ScaleBand$1, readonly BandCode[]>;
+/**
+ * A served-style render mode — the wire vocabulary of the Style API's
+ * `?mode=` parameter, and the exact value the generated document echoes in
+ * `metadata["chrt:render-mode"]`. One string, one meaning: what a consumer
+ * requests is what the style reports.
+ *
+ * `continuous` (the default) is the free-zoom portrayal: one layer copy per
+ * source band with strict per-band zoom windows. `chart:{band}` locks the
+ * portrayal to one scale band (paper-chart semantics) with cascade fallback
+ * to coarser bands where the requested band has no cells.
+ */
+type ChrtStyleMode = "continuous" | `chart:${ScaleBand$1}`;
+/**
+ * Every valid render mode, in presentation order. Derived from
+ * `CHART_BAND_CODES`, so a band is a valid chart mode exactly when it has a
+ * chart-mode band config — Berthing deliberately has none (no NOAA band
+ * ranges are defined for it) and is rejected like any other invalid value,
+ * and a future band that gains codes becomes requestable with no route
+ * change. Single source of truth for both style routes' validation, their
+ * 400 payloads, and the SDK's `StyleUrlOptions["mode"]`.
+ */
+declare const CHRT_STYLE_MODES: readonly ChrtStyleMode[];
+/**
+ * Normalize a raw `?mode=` value to its canonical `ChrtStyleMode`, or null
+ * if invalid. Case-insensitive, same contract as `normalizeTheme`: absent /
+ * empty means the default (`continuous`); a bare `chart` (no band) or an
+ * unknown band is invalid — the caller should answer with a typed 400
+ * listing `CHRT_STYLE_MODES`, never silently fall back to continuous.
+ */
+declare function normalizeStyleMode(raw: string | null | undefined): ChrtStyleMode | null;
+/** The band a mode locks to — null for `continuous`. */
+declare function styleModeBand(mode: ChrtStyleMode): ScaleBand$1 | null;
+/**
+ * Build a MapLibre filter expression that matches features in the given
+ * band code(s) by extracting the band character from `_cell_id`.
+ */
+declare function bandFilterExpression(codes: BandCode | readonly BandCode[]): unknown[];
+/**
+ * Combine a base filter (may be undefined) with a band filter via `["all"]`.
+ * If the base filter is itself an `["all", ...]`, flatten so we don't end
+ * up with `["all", ["all", ...], ...]` (which is legal but ugly).
+ */
+declare function combineWithBandFilter(baseFilter: unknown[] | undefined, bandFilter: unknown[]): unknown[];
+/**
+ * Geographic bounding box used for chart-mode viewport locking.
+ * Coordinates in WGS84 lng/lat. `sw` is south-west corner, `ne` is north-east.
+ */
+interface BBox {
+    sw: [number, number];
+    ne: [number, number];
+}
+/**
+ * Build a MapLibre `["within"]` filter expression that matches features
+ * inside the given bbox. Used by chart mode to spatially limit which
+ * features render — when locked to a Harbor area, only features inside
+ * the locked bbox draw, even though the tile pyramid covers more.
+ *
+ * The polygon is closed (first and last vertex repeated) per the GeoJSON
+ * spec; without that, MapLibre throws on style validation.
+ */
+declare function withinBboxFilter(bbox: BBox): unknown[];
+/**
+ * Build a GeoJSON Polygon for the world MINUS a given bbox — i.e. an
+ * outer ring covering the whole world with a single hole punched at
+ * the bbox. Used by the frontend as the source for a translucent grey
+ * overlay so the user sees clearly where the chart is "locked."
+ *
+ * Outer ring uses the standard antimeridian-safe world extent
+ * (lng [-180, 180], lat [-85, 85] — Web Mercator's safe range).
+ */
+declare function worldMinusBboxPolygon(bbox: BBox): GeoJSON.Polygon;
+
 interface GeoJsonGeometry {
     type: string;
     coordinates: unknown;
@@ -266,7 +455,7 @@ interface QueryResponse extends FeatureCollection<QueryFeatureProperties> {
  * `Harbor` (<1:22k). A closed set: CHRT assigns these itself rather than taking them
  * from the issuing office.
  */
-type ScaleBand$1 = "Overview" | "General" | "Coastal" | "Approach" | "Harbor";
+type ScaleBand = "Overview" | "General" | "Coastal" | "Approach" | "Harbor";
 interface CellsOptions {
     /**
      * Filter by chart-source **id**, e.g. `"NOAA_ENC"` — not the agency name
@@ -277,7 +466,7 @@ interface CellsOptions {
     /** Filter by status, e.g. "CURRENT". Case-insensitive — the server upper-cases it. */
     status?: string;
     /** Filter by scale band. Matched exactly, and **case-sensitively** — `"harbor"` matches nothing. */
-    scaleBand?: ScaleBand$1;
+    scaleBand?: ScaleBand;
     /**
      * Only cells whose bounds intersect this box, as [west, south, east, north]
      * in decimal degrees. Intersection, not containment — a cell that merely
@@ -405,7 +594,7 @@ interface CoverageRouteOptions {
      * bands are words, not band numbers, so `"5"` matches nothing and returns an empty
      * `cells` list rather than an error.
      */
-    scaleBand?: ScaleBand$1;
+    scaleBand?: ScaleBand;
     limit?: number;
     /** AbortSignal to cancel the request */
     signal?: AbortSignal;
@@ -628,6 +817,20 @@ interface OfflineFetchStyleOptions {
      * MLN Native). Use `"file"` for desktop (Win/macOS/Linux).
      */
     protocol?: "mbtiles" | "file";
+    /**
+     * Symbol-artwork family: `"s52"` (default), `"s101"`, `"chrt"`, or
+     * `"raster"` — same lever as the online Style API's `?symbols=`. Offline
+     * clients load the matching image set from the chart-assets pack
+     * (`GET /v1/offline/assets`), same as online clients do from the SDK.
+     */
+    symbols?: ChrtSymbolSet;
+    /**
+     * Render mode: `"continuous"` (default) or `"chart:{band}"` — same lever
+     * as the online Style API's `?mode=`, so an app's chart-mode switch works
+     * identically offshore. The style's `metadata["chrt:render-mode"]` echoes
+     * the resolved mode.
+     */
+    mode?: ChrtStyleMode;
     /** AbortSignal to cancel the request. */
     signal?: AbortSignal;
 }
@@ -641,6 +844,10 @@ interface OfflineStyleResponse {
     region: string;
     palette: "DAY" | "DUSK" | "NIGHT";
     protocol: "mbtiles" | "file";
+    /** Resolved symbol-artwork family (lowercased), echoed from `?symbols=`. */
+    symbols?: ChrtSymbolSet;
+    /** Resolved render mode (canonical casing), echoed from `?mode=`. */
+    mode?: ChrtStyleMode;
     build_id: string;
     build_tag: string;
     /** Full MapLibre style JSON. Pass directly to `Map({ style: ... })`. */
@@ -810,6 +1017,14 @@ interface StyleUrlOptions {
      *  raster charts are scans of). Load the matching images client-side
      *  from `@chrtco/sdk/atlas/browser`. */
     symbols?: ChrtSymbolSet;
+    /** Render mode: `"continuous"` (default — free zoom, per-band zoom
+     *  windows) or `"chart:{band}"` to lock the portrayal to one scale band
+     *  with cascade fallback to coarser bands where that band has no cells —
+     *  the paper-chart semantics of the app's Map Mode toggle. Bands:
+     *  `Overview | General | Coastal | Approach | Harbor` (see
+     *  `CHRT_STYLE_MODES`). The served document echoes the resolved mode in
+     *  `metadata["chrt:render-mode"]` and the `X-Style-Mode` header. */
+    mode?: ChrtStyleMode;
 }
 interface FetchStyleOptions extends StyleUrlOptions {
     signal?: AbortSignal;
@@ -2410,163 +2625,6 @@ declare function buildLayersForClass(objectClass: string, ct: ColorTableName, so
  */
 declare function getOrderedClasses(): string[];
 
-/**
- * Strict scale-band priority for continuous-mode rendering.
- *
- * Each ENC feature in the served PMTiles carries `_cell_id` (added at
- * baremetal NDJSON export time). NOAA's cell-id format encodes the source
- * scale band as the third character: `US5MA85M` is band 5 (Harbor).
- *
- * MapLibre layer filters can't read `["zoom"]`, so to enforce "only one
- * band renders at any given zoom" we emit one layer copy per band, each
- * with a static band filter and per-band `minzoom`/`maxzoom`. The ranges
- * below are non-overlapping (`minzoom` inclusive, `maxzoom` exclusive),
- * so exactly one band is visible at any continuous zoom.
- *
- * Long-term cleanup: baremetal should emit a normalized `_band: 1..6`
- * integer in NDJSON so this works for non-NOAA chart sources too. The
- * `["slice", _cell_id, 2, 3]` extraction here is NOAA-specific.
- */
-/**
- * UI-facing scale-band names (matches the app's `ScaleBand` type in
- * `src/lib/map/constants.ts`). Defined locally so the SDK doesn't have
- * to depend on app code.
- */
-type ScaleBand = "Overview" | "General" | "Coastal" | "Approach" | "Harbor";
-/** S-57 source bands. NOAA cell ids use these as the third character. */
-type BandCode = "1" | "2" | "3" | "4" | "5" | "6";
-interface BandPriorityRange {
-    /** MapLibre `minzoom` (inclusive). */
-    minzoom: number;
-    /** MapLibre `maxzoom` (exclusive). `undefined` means no upper cap. */
-    maxzoom?: number;
-}
-/**
- * Per-band minzoom thresholds for continuous mode. Bands cascade as
- * fallbacks for one another — every band whose `minzoom` is satisfied
- * may render. The deeper-numbered band's features render preferentially
- * (drawn last in the z-stack, so its opaque fills cover lower bands),
- * and lower bands fill in where the higher band has no coverage.
- *
- * Cross-band visual overlap (doubled coastlines, duplicate labels) is
- * suppressed by the `_dominated_by_min` per-feature tag added at NDJSON
- * export time (see `tools/chrt-baremetal/server/src/tilebuild/dominanceIndex.ts`):
- * every feature whose centroid sits inside a higher-band cell's M_COVR
- * coverage polygon is tagged with the LOWEST band code (2..6) that
- * dominates it, and `makeBandVariants()` in the style generator emits
- * per-(featureBand, dominatorBand) layer variants gated by `maxzoom =
- * dominatedVariantMaxzoom(D)`. The dominated feature renders until
- * exactly the zoom where its dominator becomes eligible AND has data in
- * the tiles — solving the low-zoom "black silhouettes" bug where a
- * band-3 LNDARE dominated by a band-5 cell was dropped at z7 even
- * though band 5 wasn't yet rendering at z7.
- *
- * Opaque base-area FILLS are exempt from dominance gating entirely (see
- * `DOMINANCE_EXEMPT_FILL_CLASSES` in the style generator): band-major
- * draw order already makes the most-detailed band's opaque fill win at
- * any covered pixel, and the coarser band shows through wherever the
- * detailed band has no data — which is exactly the fallback semantics
- * the cascade wants. The 2026-07 E1/E2 void diagnosis
- * (docs/validation/portrayal-p1-p3-void-diagnosis-2026-07.md) proved
- * per-feature dominance gating on fills structurally unsound: the tag is
- * point-sampled but hides the WHOLE feature, so a Gulf-spanning band-1
- * DEPARE tagged dominated-by-2 left dark voids across every part of the
- * Gulf that band 2 doesn't actually cover.
- *
- * Bands 5 and 6 both start at z11; band 6 (Berthing) is drawn AFTER
- * band 5 (Harbor) so where Berthing exists it visually wins, and
- * Harbor shows through everywhere else.
- *
- * Band 1 starts at z0: the P3 low-zoom contract (charts never disappear
- * from world view down) needs Overview-band data renderable as soon as
- * tiles exist. Builds older than the z0 floor simply have no tiles below
- * z3, so the widened range is a no-op against them.
- */
-declare const BAND_PRIORITY_RANGES: Record<BandCode, BandPriorityRange>;
-/**
- * Order in which band layers are emitted (and thus drawn — earlier = lower
- * in the z-stack). Band 6 last so Berthing draws on top of Harbor.
- */
-declare const BAND_DRAW_ORDER: BandCode[];
-/**
- * UI scale-band names → cell-id band codes that should render in chart mode
- * for that selection. The UI doesn't expose Berthing separately, so picking
- * Harbor includes both `5` and `6` cells.
- *
- * `CHART_BAND_CODES` is the *requested* band set (what the user picked);
- * `CHART_CASCADE_CODES` below adds the coarser bands that fall back where
- * the requested band has no cells.
- */
-declare const CHART_BAND_CODES: Record<ScaleBand, readonly BandCode[]>;
-/**
- * UI scale-band names → ordered cascade of cell-id band codes for chart-mode
- * rendering with graceful coverage fallback. Bands are listed coarsest-first
- * so the style generator can use array order as draw order: lower bands draw
- * earlier in the z-stack, the requested band draws last on top.
- *
- * The chart-mode implementation emits one filtered layer per cascade band per
- * S-57 class. Where the requested band's cells provide data, its opaque fills
- * cover the lower bands underneath; where the requested band has no cells
- * (e.g. Chart→Harbor over Massachusetts Bay offshore), the next-coarser band
- * shows through. Different cells in the same viewport may end up rendering at
- * different effective bands.
- *
- * The per-feature `_dominated_by_min` tag baked at baremetal NDJSON-export
- * time (see `tools/chrt-baremetal/server/src/tilebuild/dominanceIndex.ts`)
- * suppresses lower-band features inside higher-band cell coverage so cell
- * boundaries don't render with doubled coastlines or contours.
- *
- * Lock scope: when chart-Harbor's viewport-lock greyout is active, the
- * `["within"]` bbox filter is applied ONLY to the requested band's variants
- * — cascade fallback bands render across the full viewport. The greyout
- * overlay still cues the lock boundary visually; the user picks Harbor and
- * gets Harbor inside the lock plus dimmed Approach/Coastal context outside.
- *
- * See `.chrt/ux/chart-mode-band-fallback-2026-05-05.md` for the design
- * rationale and the geographies (Boston Harbor, Massachusetts Bay offshore)
- * that motivated this.
- */
-declare const CHART_CASCADE_CODES: Record<ScaleBand, readonly BandCode[]>;
-/**
- * Build a MapLibre filter expression that matches features in the given
- * band code(s) by extracting the band character from `_cell_id`.
- */
-declare function bandFilterExpression(codes: BandCode | readonly BandCode[]): unknown[];
-/**
- * Combine a base filter (may be undefined) with a band filter via `["all"]`.
- * If the base filter is itself an `["all", ...]`, flatten so we don't end
- * up with `["all", ["all", ...], ...]` (which is legal but ugly).
- */
-declare function combineWithBandFilter(baseFilter: unknown[] | undefined, bandFilter: unknown[]): unknown[];
-/**
- * Geographic bounding box used for chart-mode viewport locking.
- * Coordinates in WGS84 lng/lat. `sw` is south-west corner, `ne` is north-east.
- */
-interface BBox {
-    sw: [number, number];
-    ne: [number, number];
-}
-/**
- * Build a MapLibre `["within"]` filter expression that matches features
- * inside the given bbox. Used by chart mode to spatially limit which
- * features render — when locked to a Harbor area, only features inside
- * the locked bbox draw, even though the tile pyramid covers more.
- *
- * The polygon is closed (first and last vertex repeated) per the GeoJSON
- * spec; without that, MapLibre throws on style validation.
- */
-declare function withinBboxFilter(bbox: BBox): unknown[];
-/**
- * Build a GeoJSON Polygon for the world MINUS a given bbox — i.e. an
- * outer ring covering the whole world with a single hole punched at
- * the bbox. Used by the frontend as the source for a translucent grey
- * overlay so the user sees clearly where the chart is "locked."
- *
- * Outer ring uses the standard antimeridian-safe world extent
- * (lng [-180, 180], lat [-85, 85] — Web Mercator's safe range).
- */
-declare function worldMinusBboxPolygon(bbox: BBox): GeoJSON.Polygon;
-
 /**
  * Dominance fan-out collapse (P8 Phase 3.3 / D4 "axis 1").
  *
@@ -2600,20 +2658,37 @@ declare function worldMinusBboxPolygon(bbox: BBox): GeoJSON.Polygon;
  * `band-collapse.test.ts` re-proves it on every CI run by differentially
  * evaluating legacy-vs-collapsed through MapLibre's real three gates.
  *
- * **Scope.** This is axis 1 ONLY: the per-band layers survive, with identical
- * ids and identical positions, so the band-major draw order is untouched.
- * "Axis 2" (collapsing the per-band copies into one layer per class) was
- * evaluated and **KILLED** — it is unsound for the opaque-fill classes
+ * **Scope.** For FEATURE layers (fills, lines, feature symbols) this is
+ * axis 1 ONLY: the per-band layers survive, with identical ids and identical
+ * positions, so the band-major draw order is untouched. "Axis 2" (collapsing
+ * the per-band copies into one layer per class) was evaluated and **KILLED**
+ * for feature layers — it is unsound for the opaque-fill classes
  * (`DOMINANCE_EXEMPT_FILL_CLASSES` ≡ `OPAQUE_FILL_LAYERS`), where band-major
  * order is the ONLY thing separating the bands, and 15/15 class pairs are
- * provably unsatisfiable with one layer each. Do not reintroduce it.
+ * provably unsatisfiable with one layer each. Do not reintroduce it there.
  * Evidence: `.chrt/perf/2026-07-14-p8-d4-spike.md`.
  *
- * **Load-bearing invariant.** The collapsed layer MUST keep the `-band{B}`
- * id segment: `custom-style.ts` `bandFloor()` parses `/-band(\d)/` to clamp
- * customer minzoom/scamin overrides to the band's data floor, on the live
- * public Style API path. Renaming the id silently unclamps those overrides.
- * Asserted in `band-collapse.test.ts`.
+ * LABEL layers are different (CHRTsail #121 — MapLibre Native iOS silently
+ * collapses its whole render pass above 482 symbol layers, and the served
+ * style carried 575): `makeCollapsedCrossBandLabel` folds a label's ×6 band
+ * fan into ONE layer per class, and `collapsedOrientationGate` folds the
+ * orientation fan's per-dominator variants into its per-cell layers. That is
+ * NOT the killed axis 2, because what the fill argument protects — paint
+ * order as the sole band separator — does not apply to labels: their
+ * load-bearing order is the cross-class P4 priority ladder (each class keeps
+ * exactly one layer in its ladder slot), and within-class placement priority
+ * rides the `rank*1000 + within-key` symbol-sort-key that labels.ts
+ * documents as designed to survive precisely this merge.
+ *
+ * **Load-bearing invariant.** A collapsed per-band FEATURE layer MUST keep
+ * the `-band{B}` id segment: `custom-style.ts` `bandFloor()` parses
+ * `/-band(\d)/` to clamp customer minzoom/scamin overrides to the band's
+ * data floor, on the live public Style API path. Renaming the id silently
+ * unclamps those overrides. Cross-band LABEL layers are the deliberate
+ * exception: they carry every band floor INSIDE the filter (tile-zoom
+ * clauses a customer override cannot touch), which supersedes the clamp —
+ * `bandFloor()` returning 0 for a bare label id is correct, not a gap.
+ * Both halves asserted in `band-collapse.test.ts`.
  */
 
 /**
@@ -2662,7 +2737,7 @@ interface StyleGeneratorOptions extends BuildSourcesOptions {
      * filtered out).
      */
     chartMode?: {
-        band: ScaleBand;
+        band: ScaleBand$1;
         lockedBounds?: BBox;
     };
     /**
@@ -3637,4 +3712,4 @@ declare class Chrt {
     warmTiles(region?: string): Promise<void>;
 }
 
-export { ALL_NAV_AID_LAYERS, ALL_WATER_BODY_LAYERS, AREA_QUERY_LAYERS, ATON_EXPRESSION_CLASSES, type AheadCoverageCell, type AheadFeatureProperties, type AheadOptions, type AheadResponse, type AlongRouteFeatureProperties, type AlongRouteOptions, type AlongRouteResponse, type AreaInspectResult, type AtlasStyle, type AttachOptions, BAND_DRAW_ORDER, BAND_PRIORITY_RANGES, type BBox, BRIDGE_QUERY_LAYERS, BUILD_MAXZOOM, BUILD_MINZOOM, type BandCode, type BandPriorityRange, type BridgeInspectResult, type BuildOfflineStyleOptions, type BuildSourcesOptions, CHART_BAND_CODES, CHART_CASCADE_CODES, CHART_SECTIONS, CHRTRASTER_REF_CROPS, CHRTRASTER_SVGS, CHRT_ATON_COLORS, CHRT_GLYPH_NAMES, CHRT_GLYPH_SVGS, CHRT_ICON_EXPRESSIONS, CHRT_ICON_PREFIX, CHRT_SDF_GLYPHS, type CandidateQueryOptions, type CandidatesEventContext, type CellDeletedEvent, type CellDetail, type CellEventData, type CellNewEvent, type CellUpdatedData, type CellUpdatedEvent, type CellsOptions, type CellsResponse, type ChartSection, Chrt, type ChrtConfig, ChrtError, type ChrtStyleOptions, type ChrtStyleTheme, type ChrtSymbolSet, type ClickAnchor, ColorTableName, type CoverageOptions, type CoverageResponse, type CoverageRouteCell, type CoverageRouteOptions, type CoverageRouteResponse, type CoverageSource, type CustomStyleConfig, DEFAULT_CLICK_TOLERANCE, DEFAULT_CUSTOM_STYLE_CONFIG, DEFAULT_INSPECT_CLASS_RANK, DEFAULT_LABEL_SETTINGS, DEFAULT_NAV_AID_SETTINGS, DEFAULT_REGION, DEFAULT_SAFETY_CONTOUR_M, DEFAULT_SOUNDING_SETTINGS, DEFAULT_TILE_BASE_URL, DEFAULT_TILE_REGION, DEFAULT_WATER_BODY_SETTINGS, type DecodedAreaFeature, type DecodedBridge, type DecodedNavAid, type DecodedProperty, type DisplayCategory, type DisplayMode, type FeatureCollection, type FeaturesOptions, type FetchStyleOptions, FileSystemAdapter, type FlashPattern, type FlashPhase, type GenerateCustomStyleOptions, type GeneratedCustomStyle, type GeoJsonFeature, type GeoJsonGeometry, type GeomType, INSPECT_CLASS_RANK, INSPECT_RANK_DEVIATIONS, type InspectCandidate, type InspectCandidateSet, type InspectEnrichment, type InspectEventContext, type InspectNotice, type InspectOptions, type InspectResult, type InspectTargetClass, type InspectableFeature, InteractClient, type InteractEntitlement, InteractError, type InteractErrorCode, type InteractHandle, type InteractMapLike, type InteractMapMouseEvent, LABELED_LAYERS, LABEL_BEHAVIOR, LABEL_LAYER_GROUPS, LABEL_PRIORITY, type LabelBehavior, type LabelConfigOptions, type LabelLayerConfig, type LabelSettings, type LookupEntry, type MapLibreStyle, type MapboxStyle, type MapboxVectorSource, NAUTICAL_SYMBOLS, NAV_AID_LAYER_GROUPS, NAV_AID_QUERY_LAYERS, NON_SOLAS_DISCLAIMER, NON_SOLAS_DISCLAIMER_SHORT, type NauticalCategory, type NauticalSymbol, type NavAidInspectResult, type NavAidSettings, type OfflineBundleResponse, type OfflineDownloadOptions, type OfflineDownloadProgress, type OfflineDownloadResult, OfflineError, type OfflineErrorCode, type OfflineFetchStyleOptions, type OfflineHeartbeatOptions, type OfflineRegionSummary, type OfflineRemoveOptions, OfflineStyleError, type OfflineStylePlatform, type OfflineStyleResponse, type PmtilesVectorSource, type QueryFeatureProperties, type QueryOptions, type QueryResponse, RASTER_ATON_CLASSES, RASTER_GLYPH_NAMES, RASTER_ICON_PREFIX, type ResolvedStyle, type ResolvedTheme, type S101Feature, S101_CHART_SECTIONS, S101_FEATURES, S101_ICON_PREFIX, S101_NEW_SYMBOLS, S101_SOURCE_COMMIT, S101_SYMBOL_GROUPS, S101_SYMBOL_NAMES, S52_ATON_LOOKUPS, S52_ATON_LOOKUPS_PAPER, S52_DRAW_ORDER, S52_LOOKUP, S52_PATTERN_SPRITE_PREFIX, SOUNDING_LAYERS, SYMBOL_FAMILIES, SYMBOL_FAMILY_META, SYMBOL_GROUPS, SYMBOL_MAP, type ScaleBand$1 as ScaleBand, type SectorArcFeature, type SectorArcFeatureCollection, type SectorInfo, type SoundingSettings, type SourceMode, type StyleGeneratorOptions, type StyleLayer, type StyleUrlOptions, type SymbolFamily, type SymbolFamilyMeta, type SymbolGroup, TileAuth, type TileGroup, type TileGroupsResponse, TileTokenError, type TileTokenErrorCode, type TileTokenResponse, type TransformRequest, type TransformedRequest, type VectorSourceSpec, type VesselProfile, WATER_BODY_LAYER_GROUPS, type WaterBodySettings, type WebhookEvent, type WebhookEventType, type WebhookPayload, applyChrtSymbolSet, applyColorTheme, applyCustomStyleSettings, applyRasterSymbolSet, applyS101SymbolSet, atonIconExpression, bandFilterExpression, buildFlashPattern, buildLabelLayer, buildLayersForClass, buildOfflineStyle, buildSectorArcGeoJSON, buildSectorArcsFC, buildSectorsFromFeatures, buildSources, candidateRank, chrtAtonTintExpression, chrtLightTintExpression, collectCandidates, collectClickCandidates, combineWithBandFilter, daymarkColor, decimateFeatures, decodeAreaFeatureProps, decodeBridgeProps, decodeCandidate, decodeNavAidProps, depareColor, depareFillExpression, deriveMarinerName, extractNavAidDesignation, featureIdentity, generateCustomStyle, generateSpriteManifest, generateSpriteSheet, generateStyle, generateStyleJSON, getAvailableLineSymbols, getAvailablePatterns, getAvailablePointSymbols, getCollisionSettings, getDrawPriority, getGridSizeForZoom, getIconExpression, getLabelBehavior, getLabelConfig, getLabelPriority, getLookupEntry, getMaxCellsForZoom, getOrderedClasses, getRasterSvg, getS52SvgString, getS52SymbolStats, getStyleStats, getSymbolSvgString, getThemedS101Svg, getThemedS52Svg, getTopmarkMeaning, hazardColor, hazardFillExpression, iconExpressionForFamily, isLabelLayerVisible, isNavAidLayer, isNavAidLayerVisible, isSoundingLayerVisible, isVisibleInMode, isWaterBodyLayerVisible, labelSortKey, lateralColor, lateralFillExpression, lightColor, lightFillExpression, lightsIconExpression, normalizeTheme, paginate, parseListCodes, parseSymbolFamily, parseWebhook, patternSpriteId, preprocessLights, preprocessNavAids, preprocessSoundings, preprocessWaterBodies, rasterAtonIconExpression, resolveCustomTheme, resolveRasterImage, resolveS101Color, resolveStyle, resolveTargetClass, sanitizeCustomStyleConfig, scaleSizeValue, scaminToMinZoom, withinBboxFilter, worldMinusBboxPolygon };
+export { ALL_NAV_AID_LAYERS, ALL_WATER_BODY_LAYERS, AREA_QUERY_LAYERS, ATON_EXPRESSION_CLASSES, type AheadCoverageCell, type AheadFeatureProperties, type AheadOptions, type AheadResponse, type AlongRouteFeatureProperties, type AlongRouteOptions, type AlongRouteResponse, type AreaInspectResult, type AtlasStyle, type AttachOptions, BAND_DRAW_ORDER, BAND_PRIORITY_RANGES, type BBox, BRIDGE_QUERY_LAYERS, BUILD_MAXZOOM, BUILD_MINZOOM, type BandCode, type BandPriorityRange, type BridgeInspectResult, type BuildOfflineStyleOptions, type BuildSourcesOptions, CHART_BAND_CODES, CHART_CASCADE_CODES, CHART_SECTIONS, CHRTRASTER_REF_CROPS, CHRTRASTER_SVGS, CHRT_ATON_COLORS, CHRT_GLYPH_NAMES, CHRT_GLYPH_SVGS, CHRT_ICON_EXPRESSIONS, CHRT_ICON_PREFIX, CHRT_SDF_GLYPHS, CHRT_STYLE_MODES, type CandidateQueryOptions, type CandidatesEventContext, type CellDeletedEvent, type CellDetail, type CellEventData, type CellNewEvent, type CellUpdatedData, type CellUpdatedEvent, type CellsOptions, type CellsResponse, type ChartSection, Chrt, type ChrtConfig, ChrtError, type ChrtStyleMode, type ChrtStyleOptions, type ChrtStyleTheme, type ChrtSymbolSet, type ClickAnchor, ColorTableName, type CoverageOptions, type CoverageResponse, type CoverageRouteCell, type CoverageRouteOptions, type CoverageRouteResponse, type CoverageSource, type CustomStyleConfig, DEFAULT_CLICK_TOLERANCE, DEFAULT_CUSTOM_STYLE_CONFIG, DEFAULT_INSPECT_CLASS_RANK, DEFAULT_LABEL_SETTINGS, DEFAULT_NAV_AID_SETTINGS, DEFAULT_REGION, DEFAULT_SAFETY_CONTOUR_M, DEFAULT_SOUNDING_SETTINGS, DEFAULT_TILE_BASE_URL, DEFAULT_TILE_REGION, DEFAULT_WATER_BODY_SETTINGS, type DecodedAreaFeature, type DecodedBridge, type DecodedNavAid, type DecodedProperty, type DisplayCategory, type DisplayMode, type FeatureCollection, type FeaturesOptions, type FetchStyleOptions, FileSystemAdapter, type FlashPattern, type FlashPhase, type GenerateCustomStyleOptions, type GeneratedCustomStyle, type GeoJsonFeature, type GeoJsonGeometry, type GeomType, INSPECT_CLASS_RANK, INSPECT_RANK_DEVIATIONS, type InspectCandidate, type InspectCandidateSet, type InspectEnrichment, type InspectEventContext, type InspectNotice, type InspectOptions, type InspectResult, type InspectTargetClass, type InspectableFeature, InteractClient, type InteractEntitlement, InteractError, type InteractErrorCode, type InteractHandle, type InteractMapLike, type InteractMapMouseEvent, LABELED_LAYERS, LABEL_BEHAVIOR, LABEL_LAYER_GROUPS, LABEL_PRIORITY, type LabelBehavior, type LabelConfigOptions, type LabelLayerConfig, type LabelSettings, type LookupEntry, type MapLibreStyle, type MapboxStyle, type MapboxVectorSource, NAUTICAL_SYMBOLS, NAV_AID_LAYER_GROUPS, NAV_AID_QUERY_LAYERS, NON_SOLAS_DISCLAIMER, NON_SOLAS_DISCLAIMER_SHORT, type NauticalCategory, type NauticalSymbol, type NavAidInspectResult, type NavAidSettings, type OfflineBundleResponse, type OfflineDownloadOptions, type OfflineDownloadProgress, type OfflineDownloadResult, OfflineError, type OfflineErrorCode, type OfflineFetchStyleOptions, type OfflineHeartbeatOptions, type OfflineRegionSummary, type OfflineRemoveOptions, OfflineStyleError, type OfflineStylePlatform, type OfflineStyleResponse, type PmtilesVectorSource, type QueryFeatureProperties, type QueryOptions, type QueryResponse, RASTER_ATON_CLASSES, RASTER_GLYPH_NAMES, RASTER_ICON_PREFIX, type ResolvedStyle, type ResolvedTheme, type S101Feature, S101_CHART_SECTIONS, S101_FEATURES, S101_ICON_PREFIX, S101_NEW_SYMBOLS, S101_SOURCE_COMMIT, S101_SYMBOL_GROUPS, S101_SYMBOL_NAMES, S52_ATON_LOOKUPS, S52_ATON_LOOKUPS_PAPER, S52_DRAW_ORDER, S52_LOOKUP, S52_PATTERN_SPRITE_PREFIX, SOUNDING_LAYERS, SYMBOL_FAMILIES, SYMBOL_FAMILY_META, SYMBOL_GROUPS, SYMBOL_MAP, type ScaleBand, type SectorArcFeature, type SectorArcFeatureCollection, type SectorInfo, type SoundingSettings, type SourceMode, type StyleGeneratorOptions, type StyleLayer, type StyleUrlOptions, type SymbolFamily, type SymbolFamilyMeta, type SymbolGroup, TileAuth, type TileGroup, type TileGroupsResponse, TileTokenError, type TileTokenErrorCode, type TileTokenResponse, type TransformRequest, type TransformedRequest, type VectorSourceSpec, type VesselProfile, WATER_BODY_LAYER_GROUPS, type WaterBodySettings, type WebhookEvent, type WebhookEventType, type WebhookPayload, applyChrtSymbolSet, applyColorTheme, applyCustomStyleSettings, applyRasterSymbolSet, applyS101SymbolSet, atonIconExpression, bandFilterExpression, buildFlashPattern, buildLabelLayer, buildLayersForClass, buildOfflineStyle, buildSectorArcGeoJSON, buildSectorArcsFC, buildSectorsFromFeatures, buildSources, candidateRank, chrtAtonTintExpression, chrtLightTintExpression, collectCandidates, collectClickCandidates, combineWithBandFilter, daymarkColor, decimateFeatures, decodeAreaFeatureProps, decodeBridgeProps, decodeCandidate, decodeNavAidProps, depareColor, depareFillExpression, deriveMarinerName, extractNavAidDesignation, featureIdentity, generateCustomStyle, generateSpriteManifest, generateSpriteSheet, generateStyle, generateStyleJSON, getAvailableLineSymbols, getAvailablePatterns, getAvailablePointSymbols, getCollisionSettings, getDrawPriority, getGridSizeForZoom, getIconExpression, getLabelBehavior, getLabelConfig, getLabelPriority, getLookupEntry, getMaxCellsForZoom, getOrderedClasses, getRasterSvg, getS52SvgString, getS52SymbolStats, getStyleStats, getSymbolSvgString, getThemedS101Svg, getThemedS52Svg, getTopmarkMeaning, hazardColor, hazardFillExpression, iconExpressionForFamily, isLabelLayerVisible, isNavAidLayer, isNavAidLayerVisible, isSoundingLayerVisible, isVisibleInMode, isWaterBodyLayerVisible, labelSortKey, lateralColor, lateralFillExpression, lightColor, lightFillExpression, lightsIconExpression, normalizeStyleMode, normalizeTheme, paginate, parseListCodes, parseSymbolFamily, parseWebhook, patternSpriteId, preprocessLights, preprocessNavAids, preprocessSoundings, preprocessWaterBodies, rasterAtonIconExpression, resolveCustomTheme, resolveRasterImage, resolveS101Color, resolveStyle, resolveTargetClass, sanitizeCustomStyleConfig, scaleSizeValue, scaminToMinZoom, styleModeBand, withinBboxFilter, worldMinusBboxPolygon };