@chrtco/sdk 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -18,10 +18,10 @@ import { ExpressionSpecification } from '@maplibre/maplibre-gl-style-spec';
  *      MapLibre clients (iOS/Android/desktop) that don't have the JS atlas
  *      available.
  *
- *   2. Generate the online style themselves (e.g. via the React app's
- *      `src/lib/atlas/style-generator.ts`) and call `buildOfflineStyle()`
- *      locally — recommended for JS/web SDK consumers who already use the
- *      atlas at runtime.
+ *   2. Generate the online style themselves (e.g. via this SDK's
+ *      `generateStyle()` export from `@chrtco/sdk`) and call
+ *      `buildOfflineStyle()` locally — recommended for JS/web SDK
+ *      consumers who already use the atlas at runtime.
  *
  * Both paths produce equivalent output.
  */
@@ -672,6 +672,21 @@ interface LookupEntry {
     viewingGroup?: number;
     /** Minimum compilation scale for display (SCAMIN) */
     scamin?: number;
+    /**
+     * Mark this class as deliberately invisible (label-only or metadata-only)
+     * so the layer-coverage audit doesn't flag its geometry-type gaps as bugs.
+     *
+     * Examples:
+     *   - SOUNDG: rendered as depth numbers via labels.ts, not as visible dots
+     *   - LNDRGN: region NAME labels only, no shape
+     *   - M_NPUB / M_NSYS / M_QUAL / M_SREL / DSID: S-57 metadata classes;
+     *     present for click-query attributes, never drawn
+     *
+     * Without this flag, `scripts/audit-layer-coverage.ts` reports the
+     * thousands of features in these classes as "gaps" every week even
+     * though the invisibility is intentional.
+     */
+    auditIgnore?: boolean;
 }
 /** Resolved style ready for Mapbox GL (tokens → hex) */
 interface ResolvedStyle {
@@ -743,12 +758,12 @@ interface LabelLayerConfig {
     textField: ExpressionSpecification | string;
     /** Text size in pixels */
     textSize: number | ExpressionSpecification;
-    /** Text color */
-    textColor: string;
+    /** Text color (hex) or data-driven expression */
+    textColor: string | ExpressionSpecification;
     /** Halo color for contrast */
     textHaloColor: string;
-    /** Halo width */
-    textHaloWidth: number;
+    /** Halo width — pixels or zoom-interpolation expression */
+    textHaloWidth: number | ExpressionSpecification;
     /** Text offset [x, y] in ems */
     textOffset: [number, number];
     /** Font stack */
@@ -758,8 +773,56 @@ interface LabelLayerConfig {
     /** Minimum zoom level for this label */
     minzoom?: number;
 }
+/**
+ * Optional palette-and-data-driven options for label config.
+ *
+ * Currently used by SOUNDG to pick palette-aware text/halo colors and to
+ * drive the S-52 safety-contour two-shade rule. Other classes ignore
+ * these options.
+ */
+interface LabelConfigOptions {
+    /** S-52 colour table — drives palette-aware text and halo colors. */
+    colorTable?: ColorTableName;
+    /**
+     * Safety contour depth in metres. Soundings shoaler than this render in
+     * `SNDG2` (high-contrast); deeper soundings render in `SNDG1` (muted).
+     * S-52 §SOUNDG02 conditional symbology.
+     */
+    safetyContour?: number;
+    /**
+     * When false, all soundings render in `SNDG2` (single-shade). Default
+     * true — emit the safety-contour case expression.
+     */
+    twoShadeSoundings?: boolean;
+    /**
+     * When "semibold", SOUNDG labels use Open Sans Semibold for crisper
+     * numerals at small sizes. Default "semibold".
+     */
+    soundingFontWeight?: "regular" | "semibold";
+}
+/**
+ * Two-tier label rendering strategy for the band-priority style.
+ *
+ * `feature-band-gated` — emit one variant per source band, each gated to
+ * its band's zoom window (the existing `makeBandVariants` behaviour). Right
+ * for dense feature labels where seeing the same buoy designation or
+ * sounding twice across overlapping bands is visual noise.
+ *
+ * `orientation-cross-band` — emit a SINGLE label layer with no band
+ * filter. The per-class `minzoom` is honoured. Right for orientation
+ * "where am I" labels (sea-area names, land regions, cities) — these
+ * must persist as the user zooms in, even if the broader-scope cell
+ * carrying the OBJNAM is from a coarser band than the one rendering
+ * features at the current zoom. Collision arbitration via
+ * `ORIENTATION_BAND_SORT_KEY` gives the broader-scope (lower-band) copy
+ * priority where the same OBJNAM exists in multiple bands.
+ */
+type LabelBehavior = "feature-band-gated" | "orientation-cross-band";
+declare const LABEL_BEHAVIOR: Record<string, LabelBehavior>;
+/** Returns the rendering strategy for an S-57 class. Unknown classes default to band-gated. */
+declare function getLabelBehavior(layerName: string): LabelBehavior;
 /** Get label config for a given S-57 layer, or null if no labels */
-declare function getLabelConfig(layerName: string): LabelLayerConfig | null;
+declare function getLabelConfig(layerName: string, opts?: LabelConfigOptions): LabelLayerConfig | null;
 /**
  * Build a Mapbox symbol layer spec from a label config.
  */
@@ -1171,6 +1234,148 @@ 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, blended fills) 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 =
+ * BAND_PRIORITY_RANGES[D].minzoom`. The dominated feature renders until
+ * exactly the zoom where its dominator becomes eligible — 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. At any pixel, exactly ONE band's data renders — the
+ * most-detailed band whose minzoom has been reached and whose cells
+ * actually cover that pixel.
+ *
+ * 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.
+ */
+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;
+
 /**
  * Generates a complete Mapbox GL Style Specification v8 JSON
  * from the S-52 atlas definitions.
@@ -1185,8 +1390,57 @@ interface MapboxStyle {
     glyphs: string;
     layers: StyleLayer[];
 }
-declare function generateStyle(palette?: ColorTableName, opts?: BuildSourcesOptions): MapboxStyle;
-declare function generateStyleJSON(palette?: ColorTableName, opts?: BuildSourcesOptions): string;
+interface StyleGeneratorOptions extends BuildSourcesOptions {
+    /**
+     * When set, emit a "paper chart" style centered on the selected scale
+     * band, with graceful coverage fallback: the requested band's layers
+     * draw on top where its cells have data; coarser bands (driven by
+     * `CHART_CASCADE_CODES`) fill gaps where the requested band has no
+     * cells. Per-feature SCAMIN minzooms are preserved on every cascade
+     * variant; `maxzoom` is dropped so the user can zoom in indefinitely.
+     *
+     * When omitted (default), continuous mode emits one layer copy per
+     * source band with strict per-band zoom windows so exactly one band
+     * renders at any given continuous zoom.
+     *
+     * `lockedBounds` (optional) restricts chart-mode rendering to a
+     * specific bbox via a `["within"]` filter — applied ONLY to the
+     * requested band's variants. Cascade fallback bands render across the
+     * full viewport so a chart-Harbor user panning offshore still sees
+     * Approach/Coastal data. The frontend pairs this with a translucent
+     * grey overlay outside the bbox so the lock boundary is still visible
+     * to the user (the fallback data is dimmed by the overlay but not
+     * filtered out).
+     */
+    chartMode?: {
+        band: ScaleBand;
+        lockedBounds?: BBox;
+    };
+    /**
+     * Display unit for depth labels (SOUNDG soundings, DEPCNT contour
+     * values). Source data is always meters (S-57 / VALSOU / VALDCO);
+     * "feet" wraps the text-field expression with a unit conversion +
+     * round so the rendered numbers match. Default "meters".
+     */
+    depthUnits?: "meters" | "feet";
+    /**
+     * S-52 §SOUNDG02 — soundings shoaler than this depth (metres) render in
+     * the high-contrast color; deeper soundings render in the muted color.
+     * Default 10 m.
+     */
+    safetyContour?: number;
+    /**
+     * When false, all soundings render in a single shade. Default true.
+     */
+    twoShadeSoundings?: boolean;
+    /**
+     * Font weight for SOUNDG labels. Default "semibold" — crisper numerals
+     * at small sizes on screen.
+     */
+    soundingFontWeight?: "regular" | "semibold";
+}
+declare function generateStyle(palette?: ColorTableName, opts?: StyleGeneratorOptions): MapboxStyle;
+declare function generateStyleJSON(palette?: ColorTableName, opts?: StyleGeneratorOptions): string;
 /** Get summary stats about the generated style */
 declare function getStyleStats(style: MapboxStyle): {
     totalLayers: number;
@@ -1256,4 +1510,4 @@ declare class Chrt {
     transformRequest(): (url: string) => TransformRequest | undefined;
 }
 
-export { type AtlasStyle, BUILD_MAXZOOM, BUILD_MINZOOM, type BuildOfflineStyleOptions, type BuildSourcesOptions, CHART_SECTIONS, type CellDeletedEvent, type CellDetail, type CellEventData, type CellNewEvent, type CellUpdatedData, type CellUpdatedEvent, type CellsOptions, type CellsResponse, type ChartSection, Chrt, type ChrtConfig, ChrtError, ColorTableName, type CoverageOptions, type CoverageResponse, type CoverageSource, DEFAULT_REGION, DEFAULT_TILE_BASE_URL, type DisplayCategory, type DisplayMode, type FeatureCollection, type FeaturesOptions, FileSystemAdapter, type GeoJsonFeature, type GeoJsonGeometry, type GeomType, LABELED_LAYERS, type LabelLayerConfig, type LookupEntry, type MapLibreStyle, type MapboxStyle, type MapboxVectorSource, NAUTICAL_SYMBOLS, type NauticalCategory, type NauticalSymbol, 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 QueryOptions, type ResolvedStyle, type RouteFeatureQueryOptions, type RouteFeatureQueryResponse, type RouteQueryOptions, type RouteQueryResponse, type S101Feature, S101_CHART_SECTIONS, S101_FEATURES, S101_NEW_SYMBOLS, S101_SYMBOL_GROUPS, S52_DRAW_ORDER, S52_LOOKUP, SYMBOL_GROUPS, SYMBOL_MAP, type SourceMode, type StyleLayer, type SymbolGroup, type TileGroup, type TileGroupsResponse, type TransformRequest, type VectorSourceSpec, type WebhookEvent, type WebhookEventType, type WebhookPayload, applyColorTheme, buildLabelLayer, buildLayersForClass, buildOfflineStyle, buildSources, daymarkColor, decimateFeatures, depareColor, depareFillExpression, generateSpriteManifest, generateSpriteSheet, generateStyle, generateStyleJSON, getAvailableLineSymbols, getAvailablePatterns, getAvailablePointSymbols, getCollisionSettings, getDrawPriority, getGridSizeForZoom, getIconExpression, getLabelConfig, getLookupEntry, getMaxCellsForZoom, getOrderedClasses, getS52SvgString, getS52SymbolStats, getStyleStats, getSymbolSvgString, getThemedS52Svg, hazardColor, hazardFillExpression, isNavAidLayer, isVisibleInMode, lateralColor, lateralFillExpression, lightColor, lightFillExpression, paginate, parseWebhook, preprocessLights, preprocessNavAids, preprocessSoundings, preprocessWaterBodies, resolveStyle, scaminToMinZoom };
+export { type AtlasStyle, BAND_DRAW_ORDER, BAND_PRIORITY_RANGES, type BBox, BUILD_MAXZOOM, BUILD_MINZOOM, type BandCode, type BandPriorityRange, type BuildOfflineStyleOptions, type BuildSourcesOptions, CHART_BAND_CODES, CHART_CASCADE_CODES, CHART_SECTIONS, type CellDeletedEvent, type CellDetail, type CellEventData, type CellNewEvent, type CellUpdatedData, type CellUpdatedEvent, type CellsOptions, type CellsResponse, type ChartSection, Chrt, type ChrtConfig, ChrtError, ColorTableName, type CoverageOptions, type CoverageResponse, type CoverageSource, DEFAULT_REGION, DEFAULT_TILE_BASE_URL, type DisplayCategory, type DisplayMode, type FeatureCollection, type FeaturesOptions, FileSystemAdapter, type GeoJsonFeature, type GeoJsonGeometry, type GeomType, LABELED_LAYERS, LABEL_BEHAVIOR, type LabelBehavior, type LabelConfigOptions, type LabelLayerConfig, type LookupEntry, type MapLibreStyle, type MapboxStyle, type MapboxVectorSource, NAUTICAL_SYMBOLS, type NauticalCategory, type NauticalSymbol, 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 QueryOptions, type ResolvedStyle, type RouteFeatureQueryOptions, type RouteFeatureQueryResponse, type RouteQueryOptions, type RouteQueryResponse, type S101Feature, S101_CHART_SECTIONS, S101_FEATURES, S101_NEW_SYMBOLS, S101_SYMBOL_GROUPS, S52_DRAW_ORDER, S52_LOOKUP, SYMBOL_GROUPS, SYMBOL_MAP, type ScaleBand, type SourceMode, type StyleGeneratorOptions, type StyleLayer, type SymbolGroup, type TileGroup, type TileGroupsResponse, type TransformRequest, type VectorSourceSpec, type WebhookEvent, type WebhookEventType, type WebhookPayload, applyColorTheme, bandFilterExpression, buildLabelLayer, buildLayersForClass, buildOfflineStyle, buildSources, combineWithBandFilter, daymarkColor, decimateFeatures, depareColor, depareFillExpression, generateSpriteManifest, generateSpriteSheet, generateStyle, generateStyleJSON, getAvailableLineSymbols, getAvailablePatterns, getAvailablePointSymbols, getCollisionSettings, getDrawPriority, getGridSizeForZoom, getIconExpression, getLabelBehavior, getLabelConfig, getLookupEntry, getMaxCellsForZoom, getOrderedClasses, getS52SvgString, getS52SymbolStats, getStyleStats, getSymbolSvgString, getThemedS52Svg, hazardColor, hazardFillExpression, isNavAidLayer, isVisibleInMode, lateralColor, lateralFillExpression, lightColor, lightFillExpression, paginate, parseWebhook, preprocessLights, preprocessNavAids, preprocessSoundings, preprocessWaterBodies, resolveStyle, scaminToMinZoom, withinBboxFilter, worldMinusBboxPolygon };

package/dist/index.d.ts

@@ -18,10 +18,10 @@ import { ExpressionSpecification } from '@maplibre/maplibre-gl-style-spec';
  *      MapLibre clients (iOS/Android/desktop) that don't have the JS atlas
  *      available.
  *
- *   2. Generate the online style themselves (e.g. via the React app's
- *      `src/lib/atlas/style-generator.ts`) and call `buildOfflineStyle()`
- *      locally — recommended for JS/web SDK consumers who already use the
- *      atlas at runtime.
+ *   2. Generate the online style themselves (e.g. via this SDK's
+ *      `generateStyle()` export from `@chrtco/sdk`) and call
+ *      `buildOfflineStyle()` locally — recommended for JS/web SDK
+ *      consumers who already use the atlas at runtime.
  *
  * Both paths produce equivalent output.
  */
@@ -672,6 +672,21 @@ interface LookupEntry {
     viewingGroup?: number;
     /** Minimum compilation scale for display (SCAMIN) */
     scamin?: number;
+    /**
+     * Mark this class as deliberately invisible (label-only or metadata-only)
+     * so the layer-coverage audit doesn't flag its geometry-type gaps as bugs.
+     *
+     * Examples:
+     *   - SOUNDG: rendered as depth numbers via labels.ts, not as visible dots
+     *   - LNDRGN: region NAME labels only, no shape
+     *   - M_NPUB / M_NSYS / M_QUAL / M_SREL / DSID: S-57 metadata classes;
+     *     present for click-query attributes, never drawn
+     *
+     * Without this flag, `scripts/audit-layer-coverage.ts` reports the
+     * thousands of features in these classes as "gaps" every week even
+     * though the invisibility is intentional.
+     */
+    auditIgnore?: boolean;
 }
 /** Resolved style ready for Mapbox GL (tokens → hex) */
 interface ResolvedStyle {
@@ -743,12 +758,12 @@ interface LabelLayerConfig {
     textField: ExpressionSpecification | string;
     /** Text size in pixels */
     textSize: number | ExpressionSpecification;
-    /** Text color */
-    textColor: string;
+    /** Text color (hex) or data-driven expression */
+    textColor: string | ExpressionSpecification;
     /** Halo color for contrast */
     textHaloColor: string;
-    /** Halo width */
-    textHaloWidth: number;
+    /** Halo width — pixels or zoom-interpolation expression */
+    textHaloWidth: number | ExpressionSpecification;
     /** Text offset [x, y] in ems */
     textOffset: [number, number];
     /** Font stack */
@@ -758,8 +773,56 @@ interface LabelLayerConfig {
     /** Minimum zoom level for this label */
     minzoom?: number;
 }
+/**
+ * Optional palette-and-data-driven options for label config.
+ *
+ * Currently used by SOUNDG to pick palette-aware text/halo colors and to
+ * drive the S-52 safety-contour two-shade rule. Other classes ignore
+ * these options.
+ */
+interface LabelConfigOptions {
+    /** S-52 colour table — drives palette-aware text and halo colors. */
+    colorTable?: ColorTableName;
+    /**
+     * Safety contour depth in metres. Soundings shoaler than this render in
+     * `SNDG2` (high-contrast); deeper soundings render in `SNDG1` (muted).
+     * S-52 §SOUNDG02 conditional symbology.
+     */
+    safetyContour?: number;
+    /**
+     * When false, all soundings render in `SNDG2` (single-shade). Default
+     * true — emit the safety-contour case expression.
+     */
+    twoShadeSoundings?: boolean;
+    /**
+     * When "semibold", SOUNDG labels use Open Sans Semibold for crisper
+     * numerals at small sizes. Default "semibold".
+     */
+    soundingFontWeight?: "regular" | "semibold";
+}
+/**
+ * Two-tier label rendering strategy for the band-priority style.
+ *
+ * `feature-band-gated` — emit one variant per source band, each gated to
+ * its band's zoom window (the existing `makeBandVariants` behaviour). Right
+ * for dense feature labels where seeing the same buoy designation or
+ * sounding twice across overlapping bands is visual noise.
+ *
+ * `orientation-cross-band` — emit a SINGLE label layer with no band
+ * filter. The per-class `minzoom` is honoured. Right for orientation
+ * "where am I" labels (sea-area names, land regions, cities) — these
+ * must persist as the user zooms in, even if the broader-scope cell
+ * carrying the OBJNAM is from a coarser band than the one rendering
+ * features at the current zoom. Collision arbitration via
+ * `ORIENTATION_BAND_SORT_KEY` gives the broader-scope (lower-band) copy
+ * priority where the same OBJNAM exists in multiple bands.
+ */
+type LabelBehavior = "feature-band-gated" | "orientation-cross-band";
+declare const LABEL_BEHAVIOR: Record<string, LabelBehavior>;
+/** Returns the rendering strategy for an S-57 class. Unknown classes default to band-gated. */
+declare function getLabelBehavior(layerName: string): LabelBehavior;
 /** Get label config for a given S-57 layer, or null if no labels */
-declare function getLabelConfig(layerName: string): LabelLayerConfig | null;
+declare function getLabelConfig(layerName: string, opts?: LabelConfigOptions): LabelLayerConfig | null;
 /**
  * Build a Mapbox symbol layer spec from a label config.
  */
@@ -1171,6 +1234,148 @@ 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, blended fills) 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 =
+ * BAND_PRIORITY_RANGES[D].minzoom`. The dominated feature renders until
+ * exactly the zoom where its dominator becomes eligible — 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. At any pixel, exactly ONE band's data renders — the
+ * most-detailed band whose minzoom has been reached and whose cells
+ * actually cover that pixel.
+ *
+ * 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.
+ */
+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;
+
 /**
  * Generates a complete Mapbox GL Style Specification v8 JSON
  * from the S-52 atlas definitions.
@@ -1185,8 +1390,57 @@ interface MapboxStyle {
     glyphs: string;
     layers: StyleLayer[];
 }
-declare function generateStyle(palette?: ColorTableName, opts?: BuildSourcesOptions): MapboxStyle;
-declare function generateStyleJSON(palette?: ColorTableName, opts?: BuildSourcesOptions): string;
+interface StyleGeneratorOptions extends BuildSourcesOptions {
+    /**
+     * When set, emit a "paper chart" style centered on the selected scale
+     * band, with graceful coverage fallback: the requested band's layers
+     * draw on top where its cells have data; coarser bands (driven by
+     * `CHART_CASCADE_CODES`) fill gaps where the requested band has no
+     * cells. Per-feature SCAMIN minzooms are preserved on every cascade
+     * variant; `maxzoom` is dropped so the user can zoom in indefinitely.
+     *
+     * When omitted (default), continuous mode emits one layer copy per
+     * source band with strict per-band zoom windows so exactly one band
+     * renders at any given continuous zoom.
+     *
+     * `lockedBounds` (optional) restricts chart-mode rendering to a
+     * specific bbox via a `["within"]` filter — applied ONLY to the
+     * requested band's variants. Cascade fallback bands render across the
+     * full viewport so a chart-Harbor user panning offshore still sees
+     * Approach/Coastal data. The frontend pairs this with a translucent
+     * grey overlay outside the bbox so the lock boundary is still visible
+     * to the user (the fallback data is dimmed by the overlay but not
+     * filtered out).
+     */
+    chartMode?: {
+        band: ScaleBand;
+        lockedBounds?: BBox;
+    };
+    /**
+     * Display unit for depth labels (SOUNDG soundings, DEPCNT contour
+     * values). Source data is always meters (S-57 / VALSOU / VALDCO);
+     * "feet" wraps the text-field expression with a unit conversion +
+     * round so the rendered numbers match. Default "meters".
+     */
+    depthUnits?: "meters" | "feet";
+    /**
+     * S-52 §SOUNDG02 — soundings shoaler than this depth (metres) render in
+     * the high-contrast color; deeper soundings render in the muted color.
+     * Default 10 m.
+     */
+    safetyContour?: number;
+    /**
+     * When false, all soundings render in a single shade. Default true.
+     */
+    twoShadeSoundings?: boolean;
+    /**
+     * Font weight for SOUNDG labels. Default "semibold" — crisper numerals
+     * at small sizes on screen.
+     */
+    soundingFontWeight?: "regular" | "semibold";
+}
+declare function generateStyle(palette?: ColorTableName, opts?: StyleGeneratorOptions): MapboxStyle;
+declare function generateStyleJSON(palette?: ColorTableName, opts?: StyleGeneratorOptions): string;
 /** Get summary stats about the generated style */
 declare function getStyleStats(style: MapboxStyle): {
     totalLayers: number;
@@ -1256,4 +1510,4 @@ declare class Chrt {
     transformRequest(): (url: string) => TransformRequest | undefined;
 }
 
-export { type AtlasStyle, BUILD_MAXZOOM, BUILD_MINZOOM, type BuildOfflineStyleOptions, type BuildSourcesOptions, CHART_SECTIONS, type CellDeletedEvent, type CellDetail, type CellEventData, type CellNewEvent, type CellUpdatedData, type CellUpdatedEvent, type CellsOptions, type CellsResponse, type ChartSection, Chrt, type ChrtConfig, ChrtError, ColorTableName, type CoverageOptions, type CoverageResponse, type CoverageSource, DEFAULT_REGION, DEFAULT_TILE_BASE_URL, type DisplayCategory, type DisplayMode, type FeatureCollection, type FeaturesOptions, FileSystemAdapter, type GeoJsonFeature, type GeoJsonGeometry, type GeomType, LABELED_LAYERS, type LabelLayerConfig, type LookupEntry, type MapLibreStyle, type MapboxStyle, type MapboxVectorSource, NAUTICAL_SYMBOLS, type NauticalCategory, type NauticalSymbol, 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 QueryOptions, type ResolvedStyle, type RouteFeatureQueryOptions, type RouteFeatureQueryResponse, type RouteQueryOptions, type RouteQueryResponse, type S101Feature, S101_CHART_SECTIONS, S101_FEATURES, S101_NEW_SYMBOLS, S101_SYMBOL_GROUPS, S52_DRAW_ORDER, S52_LOOKUP, SYMBOL_GROUPS, SYMBOL_MAP, type SourceMode, type StyleLayer, type SymbolGroup, type TileGroup, type TileGroupsResponse, type TransformRequest, type VectorSourceSpec, type WebhookEvent, type WebhookEventType, type WebhookPayload, applyColorTheme, buildLabelLayer, buildLayersForClass, buildOfflineStyle, buildSources, daymarkColor, decimateFeatures, depareColor, depareFillExpression, generateSpriteManifest, generateSpriteSheet, generateStyle, generateStyleJSON, getAvailableLineSymbols, getAvailablePatterns, getAvailablePointSymbols, getCollisionSettings, getDrawPriority, getGridSizeForZoom, getIconExpression, getLabelConfig, getLookupEntry, getMaxCellsForZoom, getOrderedClasses, getS52SvgString, getS52SymbolStats, getStyleStats, getSymbolSvgString, getThemedS52Svg, hazardColor, hazardFillExpression, isNavAidLayer, isVisibleInMode, lateralColor, lateralFillExpression, lightColor, lightFillExpression, paginate, parseWebhook, preprocessLights, preprocessNavAids, preprocessSoundings, preprocessWaterBodies, resolveStyle, scaminToMinZoom };
+export { type AtlasStyle, BAND_DRAW_ORDER, BAND_PRIORITY_RANGES, type BBox, BUILD_MAXZOOM, BUILD_MINZOOM, type BandCode, type BandPriorityRange, type BuildOfflineStyleOptions, type BuildSourcesOptions, CHART_BAND_CODES, CHART_CASCADE_CODES, CHART_SECTIONS, type CellDeletedEvent, type CellDetail, type CellEventData, type CellNewEvent, type CellUpdatedData, type CellUpdatedEvent, type CellsOptions, type CellsResponse, type ChartSection, Chrt, type ChrtConfig, ChrtError, ColorTableName, type CoverageOptions, type CoverageResponse, type CoverageSource, DEFAULT_REGION, DEFAULT_TILE_BASE_URL, type DisplayCategory, type DisplayMode, type FeatureCollection, type FeaturesOptions, FileSystemAdapter, type GeoJsonFeature, type GeoJsonGeometry, type GeomType, LABELED_LAYERS, LABEL_BEHAVIOR, type LabelBehavior, type LabelConfigOptions, type LabelLayerConfig, type LookupEntry, type MapLibreStyle, type MapboxStyle, type MapboxVectorSource, NAUTICAL_SYMBOLS, type NauticalCategory, type NauticalSymbol, 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 QueryOptions, type ResolvedStyle, type RouteFeatureQueryOptions, type RouteFeatureQueryResponse, type RouteQueryOptions, type RouteQueryResponse, type S101Feature, S101_CHART_SECTIONS, S101_FEATURES, S101_NEW_SYMBOLS, S101_SYMBOL_GROUPS, S52_DRAW_ORDER, S52_LOOKUP, SYMBOL_GROUPS, SYMBOL_MAP, type ScaleBand, type SourceMode, type StyleGeneratorOptions, type StyleLayer, type SymbolGroup, type TileGroup, type TileGroupsResponse, type TransformRequest, type VectorSourceSpec, type WebhookEvent, type WebhookEventType, type WebhookPayload, applyColorTheme, bandFilterExpression, buildLabelLayer, buildLayersForClass, buildOfflineStyle, buildSources, combineWithBandFilter, daymarkColor, decimateFeatures, depareColor, depareFillExpression, generateSpriteManifest, generateSpriteSheet, generateStyle, generateStyleJSON, getAvailableLineSymbols, getAvailablePatterns, getAvailablePointSymbols, getCollisionSettings, getDrawPriority, getGridSizeForZoom, getIconExpression, getLabelBehavior, getLabelConfig, getLookupEntry, getMaxCellsForZoom, getOrderedClasses, getS52SvgString, getS52SymbolStats, getStyleStats, getSymbolSvgString, getThemedS52Svg, hazardColor, hazardFillExpression, isNavAidLayer, isVisibleInMode, lateralColor, lateralFillExpression, lightColor, lightFillExpression, paginate, parseWebhook, preprocessLights, preprocessNavAids, preprocessSoundings, preprocessWaterBodies, resolveStyle, scaminToMinZoom, withinBboxFilter, worldMinusBboxPolygon };