@chrtco/sdk 0.5.0 → 0.7.0

package/dist/index.d.cts

@@ -1,4 +1,8 @@
 import { F as FileSystemAdapter } from './fs-adapter-D5iwdb1Q.cjs';
+import { C as ColorTableName } from './s52-colors-CdVzqt2K.cjs';
+export { S as S52_COLORS, a as S52_DAY, b as S52_DUSK, c as S52_NIGHT, g as getColorTable, r as resolveColor } from './s52-colors-CdVzqt2K.cjs';
+import maplibregl from 'maplibre-gl';
+import { ExpressionSpecification } from '@maplibre/maplibre-gl-style-spec';
 
 /**
  * Pure helper: take an online MapLibre style and rewrite the named region's
@@ -14,10 +18,10 @@ import { F as FileSystemAdapter } from './fs-adapter-D5iwdb1Q.cjs';
  *      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.
  */
@@ -632,6 +636,822 @@ declare class OfflineError extends Error {
     constructor(code: OfflineErrorCode, message: string, status?: number, detail?: Record<string, unknown>);
 }
 
+/** S-52 display categories – controls default visibility */
+type DisplayCategory = "BASE" | "STANDARD" | "OTHER" | "MARINERS" | "META";
+/** Mapbox GL layer type we'll use for this entry */
+type GeomType = "fill" | "line" | "circle" | "symbol";
+/** Nautical groupings (loosely follows Chart No. 1 sections) */
+type NauticalCategory = "Depths" | "Land" | "Navigation Aids" | "Hazards" | "Regulated Areas" | "Infrastructure" | "Meta";
+/** Paint properties – a subset we actually use */
+interface AtlasStyle {
+    type: GeomType;
+    paint: Record<string, unknown>;
+    layout?: Record<string, unknown>;
+    /** Nautical symbol ID for symbol-type layers */
+    iconImage?: string;
+}
+/** One row in the S-52 lookup table */
+interface LookupEntry {
+    /** S-57 object class acronym */
+    objectClass: string;
+    /** Human-readable name */
+    name: string;
+    /** Chart No. 1 section */
+    category: NauticalCategory;
+    /** S-52 display category */
+    displayCategory: DisplayCategory;
+    /** Default style using S-52 color tokens (resolved later) */
+    style: AtlasStyle;
+    /** Whether conditional symbology may override the style */
+    hasConditional?: boolean;
+    /** Attributes that affect styling */
+    conditionalAttributes?: string[];
+    /** INT1 / Chart No. 1 reference (e.g. "Q130.1") */
+    int1Ref?: string;
+    /** S-52 viewing group number */
+    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 {
+    type: GeomType;
+    paint: Record<string, unknown>;
+    layout?: Record<string, unknown>;
+    minzoom?: number;
+    maxzoom?: number;
+}
+
+/**
+ * S-52 lookup table covering all S-57 object classes found in NOAA ENCs.
+ * Colours reference S-52 tokens (resolved at render time).
+ * INT1 references per NOAA Chart No. 1 (Ed 13).
+ */
+declare const S52_LOOKUP: Record<string, LookupEntry>;
+
+/**
+ * S-52 draw order: layers listed bottom → top.
+ * Layers not in this list are inserted before point features.
+ */
+declare const S52_DRAW_ORDER: string[];
+/** Get numeric draw priority for a layer (lower = drawn first / below) */
+declare function getDrawPriority(layerName: string): number;
+
+/** S-52 display modes */
+type DisplayMode = "BASE" | "STANDARD" | "ALL";
+/** Check if a layer's display category is visible in the given mode */
+declare function isVisibleInMode(displayCategory: DisplayCategory, mode: DisplayMode): boolean;
+/**
+ * Convert S-52 SCAMIN (scale minimum) to Mapbox GL minzoom.
+ */
+declare function scaminToMinZoom(scamin?: number): number | undefined;
+declare function getCollisionSettings(viewingGroup?: number): {
+    iconAllowOverlap: boolean;
+    iconOptional: boolean;
+    symbolSortKey?: number;
+};
+/**
+ * Get the resolved Mapbox GL style for a given S-57 layer.
+ */
+declare function resolveStyle(layerName: string, geomKind?: GeomType, ct?: ColorTableName): ResolvedStyle;
+declare function getLookupEntry(layerName: string): LookupEntry;
+
+/**
+ * S-52 Conditional Symbology Procedures.
+ * Each function takes feature properties and returns paint overrides (hex colours).
+ * All expression builders accept an optional colorTable parameter.
+ */
+declare function depareColor(props: Record<string, unknown>, ct?: ColorTableName): string;
+declare function depareFillExpression(ct?: ColorTableName): unknown[];
+declare function lightColor(props: Record<string, unknown>, ct?: ColorTableName): string;
+declare function lightFillExpression(ct?: ColorTableName): unknown[];
+declare function lateralColor(props: Record<string, unknown>, ct?: ColorTableName): string;
+declare function lateralFillExpression(ct?: ColorTableName): unknown[];
+declare function hazardColor(props: Record<string, unknown>, ct?: ColorTableName): string;
+declare function hazardFillExpression(ct?: ColorTableName): unknown[];
+declare function daymarkColor(props: Record<string, unknown>, ct?: ColorTableName): string;
+
+/**
+ * Label configurations for S-57 layers.
+ * Defines which layers get text labels and how to extract label text.
+ */
+
+interface LabelLayerConfig {
+    /** Mapbox source layer type */
+    type: "symbol";
+    /** Text field expression or string */
+    textField: ExpressionSpecification | string;
+    /** Text size in pixels */
+    textSize: number | ExpressionSpecification;
+    /** Text color (hex) or data-driven expression */
+    textColor: string | ExpressionSpecification;
+    /** Halo color for contrast */
+    textHaloColor: string;
+    /** Halo width — pixels or zoom-interpolation expression */
+    textHaloWidth: number | ExpressionSpecification;
+    /** Text offset [x, y] in ems */
+    textOffset: [number, number];
+    /** Font stack */
+    textFont?: string[];
+    /** Additional layout properties */
+    layout?: Record<string, unknown>;
+    /** 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, opts?: LabelConfigOptions): LabelLayerConfig | null;
+/**
+ * Build a Mapbox symbol layer spec from a label config.
+ */
+declare function buildLabelLayer(layerId: string, sourceId: string, config: LabelLayerConfig, visible: boolean, overrides?: {
+    textScale?: number;
+    minzoom?: number | null;
+    allowOverlap?: boolean;
+}): maplibregl.LayerSpecification;
+/**
+ * Pre-process SOUNDG GeoJSON to extract Z coordinates as `depth` properties.
+ * Soundings are MultiPoint with Z values in geometry.coordinates[][2].
+ * This explodes MultiPoints into individual Points with a `depth` property.
+ */
+declare function preprocessSoundings(fc: GeoJSON.FeatureCollection): GeoJSON.FeatureCollection;
+/**
+ * Pre-process LIGHTS GeoJSON to derive compact light characteristic labels.
+ * Adds `_lightLabel` property (e.g., "Fl R 4s").
+ */
+declare function preprocessLights(fc: GeoJSON.FeatureCollection): GeoJSON.FeatureCollection;
+/** List of layers that have labels */
+declare const LABELED_LAYERS: Set<string>;
+/**
+ * Pre-process buoy/beacon GeoJSON to derive concise mariner-style labels.
+ * Adds `_navAidLabel` property (e.g., 'R "8"', 'G "5"').
+ */
+declare function preprocessNavAids(fc: GeoJSON.FeatureCollection): GeoJSON.FeatureCollection;
+/** Check if a layer name needs nav aid preprocessing */
+declare function isNavAidLayer(layerName: string): boolean;
+/**
+ * Pre-process water body polygon GeoJSON into centroid points for label placement.
+ * Computes a simple average-coordinate centroid for each polygon feature that has OBJNAM.
+ */
+declare function preprocessWaterBodies(fc: GeoJSON.FeatureCollection): GeoJSON.FeatureCollection;
+
+/**
+ * Spatial grid-based feature decimation for performance at low zoom levels.
+ * Thins dense GeoJSON feature sets by keeping only one representative
+ * feature per grid cell per layer.
+ */
+interface DecimationOptions {
+    /** Grid resolution (cells per axis). Default 80. */
+    gridSize?: number;
+    /** Zoom level below which decimation kicks in. Default 12. */
+    zoomThreshold?: number;
+}
+/**
+ * Zoom-adaptive grid resolution for decimation.
+ */
+declare function getGridSizeForZoom(zoom: number): number;
+/**
+ * Decimate a GeoJSON FeatureCollection using spatial grid thinning.
+ * Only runs when zoom < zoomThreshold. Returns the original FC otherwise.
+ *
+ * @param fc - Input FeatureCollection
+ * @param layerName - S-57 layer name (affects priority logic)
+ * @param currentZoom - Current map zoom level
+ * @param bounds - Current viewport bounds
+ * @param opts - Decimation options
+ */
+declare function decimateFeatures(fc: GeoJSON.FeatureCollection, layerName: string, currentZoom: number, bounds: {
+    west: number;
+    south: number;
+    east: number;
+    north: number;
+}, opts?: DecimationOptions): GeoJSON.FeatureCollection;
+/**
+ * Get the max number of cells to load based on zoom level.
+ */
+declare function getMaxCellsForZoom(zoom: number): number;
+
+/**
+ * IHO S-52 / NOAA Chart No. 1 / INT1 nautical symbol SVGs.
+ *
+ * Complete symbology suite following:
+ *   - IHO S-52 Presentation Library (Ed 4.0)
+ *   - IALA Maritime Buoyage System R1001 (Region B for US waters)
+ *   - NOAA Chart No. 1 (Ed 13) / INT1
+ *
+ * Buoy shape terminology (US / Chart No. 1):
+ *   - CAN (Q20): Flat-top cylindrical buoy — Port mark in IALA-B (red)
+ *   - NUN (Q21): Conical/pointed-top buoy — Starboard mark in IALA-B (green)
+ *   - PILLAR: Tall narrow buoy — used for cardinal, isolated danger, etc.
+ *   - SPAR: Tall thin pole buoy
+ *   - SPHERICAL: Round buoy — safe water marks
+ *   - BARREL: Barrel/tun shaped buoy
+ *   - SUPER: Large navigation buoy / LANBY
+ *
+ * Cardinal mark topmark orientations (IALA):
+ *   - North: both cones point UP ▲▲
+ *   - South: both cones point DOWN ▼▼
+ *   - East:  cones base-to-base (diamond) ◆
+ *   - West:  cones point-to-point (hourglass) ⊗
+ *
+ * Each symbol is a compact SVG at 32×32 for Mapbox GL `map.addImage()`.
+ */
+/** Color used in the SVG with its S-52 token name, hex, and usage */
+interface SymbolColor {
+    token: string;
+    hex: string;
+    usage: string;
+}
+/** Line style used in the SVG */
+interface SymbolLineStyle {
+    element: string;
+    width: number;
+    pattern?: string;
+    color: string;
+}
+/** Fill element used in the SVG */
+interface SymbolFillElement {
+    element: string;
+    color: string;
+    opacity?: number;
+}
+interface NauticalSymbol {
+    id: string;
+    label: string;
+    /** INT1 / Chart No. 1 reference */
+    int1Ref: string;
+    /** Chart No. 1 section letter */
+    section: string;
+    getSvg: () => string;
+    /** Generate SVG with theme-specific colors (for bridge icons etc.) */
+    getThemedSvg?: (chblk: string, movable: string) => string;
+    /** What this symbol represents on a chart */
+    description?: string;
+    /** S-52 Presentation Library symbol name */
+    s52PlRef?: string;
+    /** Grouping key for family clustering */
+    group?: string;
+    /** IDs of related variant symbols */
+    variants?: string[];
+    /** S-57 attribute that selects this variant */
+    attributeKey?: string;
+    /** Value of that attribute for this variant */
+    attributeValue?: number;
+    /** Example label strings seen on charts */
+    labelExamples?: string[];
+    /** What the color represents */
+    colorMeaning?: string;
+    /** Colors used in the SVG */
+    colors?: SymbolColor[];
+    /** Line/stroke styles used in the SVG */
+    lineStyles?: SymbolLineStyle[];
+    /** Fill regions in the SVG */
+    fillElements?: SymbolFillElement[];
+    /** Expanded navigational usage context (2-4 sentences) */
+    usageContext?: string;
+    /** Render size for documentation */
+    renderSize?: string;
+}
+/** A logical grouping of related symbols */
+interface SymbolGroup {
+    id: string;
+    label: string;
+    section: string;
+    description: string;
+    symbolIds: string[];
+}
+/** Chart No. 1 section metadata */
+interface ChartSection {
+    id: string;
+    label: string;
+    description: string;
+}
+declare const NAUTICAL_SYMBOLS: NauticalSymbol[];
+/** S-57 object class → default symbol ID mapping.
+ *  Values are S-52 PL symbol names (matching SVG filenames in s52/point/).
+ *  Conditional expressions in getIconExpression() override these for classes
+ *  with attribute-dependent variants.
+ */
+declare const SYMBOL_MAP: Record<string, string>;
+/** Get the Mapbox icon-image expression for data-driven symbol selection.
+ *  Returns S-52 PL symbol names that correspond to SVG files in s52/point/.
+ */
+declare function getIconExpression(layerName: string): string | unknown[];
+/**
+ * Browser-only image loaders (`loadSymbolImages`, `loadThemedBridgeImages`)
+ * live in `./symbols-browser.ts` (sub-export `@chrtco/sdk/atlas/browser`) —
+ * they require a DOM (use `new Image()` + `map.addImage()`).
+ */
+/** Get inline SVG string for a symbol by ID (for the Atlas legend) */
+declare function getSymbolSvgString(symbolId: string): string | null;
+declare const CHART_SECTIONS: ChartSection[];
+declare const SYMBOL_GROUPS: SymbolGroup[];
+/** Generate a single SVG sprite sheet containing all symbols as <symbol> elements */
+declare function generateSpriteSheet(): string;
+/** Generate a JSON manifest mapping symbol IDs to metadata */
+declare function generateSpriteManifest(): Record<string, {
+    label: string;
+    int1Ref: string;
+    section: string;
+    group?: string;
+    s52PlRef?: string;
+    description?: string;
+    attributeKey?: string;
+    attributeValue?: number;
+}>;
+
+/**
+ * IHO S-101 ENC Product Specification — Feature Catalogue
+ *
+ * S-101 replaces S-57 as the data model for Electronic Navigational Charts.
+ * This catalogue maps S-101 feature classes to:
+ *   - S-57 equivalents (where they exist)
+ *   - Chart No. 1 sections (same organizational structure)
+ *   - Portrayal catalogue references (S-100 Portrayal Model)
+ *
+ * Key S-101 changes from S-57:
+ *   - CamelCase feature class names (DepthArea vs DEPARE)
+ *   - Complex/structured attributes (nested objects vs flat)
+ *   - New feature types for AIS, quality, under-keel clearance
+ *   - Removed/merged features for simplification
+ *
+ * Reference: IHO S-101 Product Specification (Ed 1.1.0)
+ *            IHO S-100 Universal Hydrographic Data Model
+ */
+interface S101Feature {
+    /** S-101 camelCase feature class name */
+    featureClass: string;
+    /** Human-readable name */
+    name: string;
+    /** S-57 6-char equivalent acronym, if any */
+    s57Equivalent?: string;
+    /** Chart No. 1 section letter */
+    section: string;
+    /** Group key for clustering */
+    group: string;
+    /** Feature category */
+    category: "geo" | "meta" | "info";
+    /** Description of the feature */
+    description: string;
+    /** S-100 Portrayal Catalogue reference */
+    portrayalRef?: string;
+    /** True if this feature has no S-57 equivalent */
+    isNewInS101: boolean;
+    /** Key attributes specific to this feature */
+    attributes?: string[];
+}
+declare const S101_FEATURES: S101Feature[];
+declare const S101_CHART_SECTIONS: {
+    id: string;
+    label: string;
+    description: string;
+}[];
+declare const S101_SYMBOL_GROUPS: {
+    id: string;
+    label: string;
+    section: string;
+    description: string;
+}[];
+
+/**
+ * S-101 Portrayal Catalogue — New Symbol SVGs
+ *
+ * These symbols represent features introduced in S-101 that have no
+ * direct S-57/S-52 equivalent. The existing S-52 symbols are reused
+ * where S-101 retains visual continuity with the S-57 portrayal.
+ *
+ * Reference: IHO S-101 Portrayal Catalogue (Ed 1.1.0)
+ */
+
+declare const S101_NEW_SYMBOLS: NauticalSymbol[];
+
+/**
+ * S-52 SVG Loader — pure (DOM-free) string operations over the inlined S-52
+ * SVG catalogue in `s52-svgs-generated.ts`. SVG files use S-52 color token
+ * names (e.g., CHBLK, LITRD) as fill/stroke values; `applyColorTheme` swaps
+ * those tokens for hex from the active palette.
+ *
+ * Browser-only image loaders live in `./s52-svg-loader-browser.ts` (sub-export
+ * `@chrtco/sdk/atlas/browser`) — they use `new Image()` and require a DOM.
+ */
+
+/**
+ * Get raw SVG string for an S-52 symbol by name (e.g., "BOYCAN01").
+ * Returns null if the symbol is not found.
+ */
+declare function getS52SvgString(symbolName: string): string | null;
+/**
+ * Get an S-52 SVG string with color tokens resolved to hex values
+ * from the specified color table.
+ */
+declare function getThemedS52Svg(symbolName: string, colorTable?: ColorTableName): string | null;
+/**
+ * Replace S-52 color token names in an SVG string with hex colors
+ * from the active color table.
+ *
+ * Matches tokens in fill="TOKEN" and stroke="TOKEN" attribute values.
+ */
+declare function applyColorTheme(svgString: string, colorTable?: ColorTableName): string;
+/** Get a list of all available S-52 point symbol names. */
+declare function getAvailablePointSymbols(): string[];
+/** Get a list of all available S-52 pattern names. */
+declare function getAvailablePatterns(): string[];
+/** Get a list of all available S-52 line symbol names. */
+declare function getAvailableLineSymbols(): string[];
+/** Stats for debugging */
+declare function getS52SymbolStats(): {
+    pointCount: number;
+    patternCount: number;
+    lineCount: number;
+    totalCount: number;
+};
+
+/**
+ * Zoom range of CHRT tile builds — kept in lockstep with the baremetal
+ * tippecanoe invocation (tools/chrt-baremetal/server/src/tilebuild/per-layer-zoom.ts).
+ *
+ * Per-S-57-class minzoom/maxzoom narrowing is handled inside the MVT at
+ * tile-build time via per-feature `tippecanoe.minzoom/maxzoom`; these two
+ * constants are the outer envelope the MapLibre source declares, so the
+ * client doesn't request tiles outside what the pmtiles can actually serve.
+ */
+declare const BUILD_MINZOOM = 3;
+declare const BUILD_MAXZOOM = 14;
+
+/**
+ * Post-consolidation (2026-04): one consolidated PMTiles per region, all
+ * S-57 classes as distinct MVT layers inside. The MapLibre style emits one
+ * vector source (id = region) and N paint layers that reference it via
+ * `source-layer` = S-57 class name.
+ *
+ * `buildSources()` returns either the legacy Mapbox MTS shape (preserved for
+ * demos / external style export — see generateStyle comments) or the PMTiles
+ * shape pointing at a single tile URL per region.
+ */
+/** Vector source emitted for the legacy Mapbox MTS path. */
+interface MapboxVectorSource {
+    type: "vector";
+    url: string;
+}
+/**
+ * Vector source emitted for the tiles.chrt.co PMTiles path. Uses an explicit
+ * `tiles` array (not a TileJSON `url`) because the tile-worker serves raw MVT
+ * bytes without a TileJSON descriptor.
+ */
+interface PmtilesVectorSource {
+    type: "vector";
+    tiles: string[];
+    minzoom: number;
+    maxzoom: number;
+}
+type VectorSourceSpec = MapboxVectorSource | PmtilesVectorSource;
+type SourceMode = "mapbox" | "pmtiles";
+/**
+ * Default tile-worker origin for PMTiles mode. Callers should pass
+ * `tileBaseUrl` explicitly via `BuildSourcesOptions` to override (e.g. the
+ * React app reads `import.meta.env.VITE_TILE_WORKER_BASE`; the offline-worker
+ * reads `env.TILE_BASE_URL`). This constant is the prod fallback only.
+ */
+declare const DEFAULT_TILE_BASE_URL = "https://tiles.chrt.co";
+/** Canonical source id used in `generateStyle()` — matches the region name
+ *  of the one consolidated PMTiles served by the tile-worker for this region. */
+declare const DEFAULT_REGION = "NOAA_ENC";
+interface BuildSourcesOptions {
+    /** Which tile path to emit. Default: "pmtiles" (the supported path post-Mapbox). */
+    mode?: SourceMode;
+    /** Chart region. Default: "NOAA_ENC". */
+    region?: string;
+    /**
+     * Reserved for future cache-busting on KV-pointer flips. Currently unused;
+     * build pinning rides in the JWT, not the URL.
+     */
+    buildTag?: string;
+    /** Override tile-worker origin (e.g. staging). Default: DEFAULT_TILE_BASE_URL. */
+    tileBaseUrl?: string;
+}
+/**
+ * Build the "sources" block for a CHRT style.
+ *
+ * - `mode: "mapbox"`: one mapbox:// url (kept for external style export only).
+ * - `mode: "pmtiles"` (default): one vector tile endpoint for the region,
+ *   routed by the Worker to the one consolidated PMTiles:
+ *   `${tileBaseUrl}/v1/tiles/{region}/{z}/{x}/{y}.mvt`
+ */
+declare function buildSources(opts?: BuildSourcesOptions): Record<string, VectorSourceSpec>;
+
+/**
+ * Builds Mapbox GL Style layer specs from S-52 lookup entries.
+ * Wraps the existing atlas resolveStyle() and adds source/source-layer/filter.
+ */
+
+interface StyleLayer {
+    id: string;
+    type: string;
+    source: string;
+    "source-layer": string;
+    filter?: unknown[];
+    paint: Record<string, unknown>;
+    layout?: Record<string, unknown>;
+    minzoom?: number;
+    maxzoom?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Build all Mapbox GL layers for a given S-57 object class.
+ * Returns multiple layers (fill, outline, symbol, label, etc.).
+ *
+ * Post-consolidation: all S-57 classes live as MVT layers inside one
+ * consolidated PMTiles per region; `source` is always the region name.
+ */
+declare function buildLayersForClass(objectClass: string, ct: ColorTableName, sourceId?: string): StyleLayer[];
+/**
+ * Get the full ordered list of object classes for style generation.
+ * Uses S52_DRAW_ORDER as base, then adds any missing classes from the
+ * S-52 lookup table so a newly-ingested class automatically gets styled
+ * without touching this file.
+ */
+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.
+ */
+
+interface MapboxStyle {
+    version: 8;
+    name: string;
+    metadata: Record<string, unknown>;
+    sources: Record<string, unknown>;
+    sprite?: string;
+    glyphs: string;
+    layers: StyleLayer[];
+}
+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;
+    fillLayers: number;
+    lineLayers: number;
+    symbolLayers: number;
+    circleLayers: number;
+    sources: number;
+    objectClasses: Set<string>;
+};
+
 declare class Chrt {
     /** Tile endpoints — styleUrl, tileUrl, groups */
     readonly tiles: TilesEndpoint;
@@ -690,4 +1510,4 @@ declare class Chrt {
     transformRequest(): (url: string) => TransformRequest | undefined;
 }
 
-export { type BuildOfflineStyleOptions, type CellDeletedEvent, type CellDetail, type CellEventData, type CellNewEvent, type CellUpdatedData, type CellUpdatedEvent, type CellsOptions, type CellsResponse, Chrt, type ChrtConfig, ChrtError, type CoverageOptions, type CoverageResponse, type CoverageSource, type FeatureCollection, type FeaturesOptions, FileSystemAdapter, type GeoJsonFeature, type GeoJsonGeometry, type MapLibreStyle, 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 QueryOptions, type RouteFeatureQueryOptions, type RouteFeatureQueryResponse, type RouteQueryOptions, type RouteQueryResponse, type TileGroup, type TileGroupsResponse, type TransformRequest, type WebhookEvent, type WebhookEventType, type WebhookPayload, buildOfflineStyle, paginate, parseWebhook };
+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 };