@chrtco/sdk 0.4.1 → 0.6.0

package/dist/index.d.cts

@@ -1,3 +1,112 @@
+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
+ * vector source to point at a local MBTiles file. Layers, paint, layout,
+ * glyphs, and sprite are untouched.
+ *
+ * This is the JS counterpart of the offline-worker's server-side rewriter
+ * (see `cloudflare/offline-worker/src/common.ts:rewriteStyleSources`).
+ * Customers can either:
+ *
+ *   1. Fetch a pre-baked offline style from the worker via
+ *      `chrt.offline.fetchStyle(region, opts)` — recommended for native
+ *      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.
+ *
+ * Both paths produce equivalent output.
+ */
+/**
+ * MapLibre style specification (subset). Matches the JSON shape MapLibre GL
+ * JS, MapLibre Native iOS/Android, and the MapLibre style spec all consume.
+ * Customers who want full TypeScript style typing should reference
+ * `@maplibre/maplibre-gl-style-spec.StyleSpecification` directly.
+ */
+interface MapLibreStyle {
+    version: number;
+    name?: string;
+    metadata?: Record<string, unknown>;
+    sources: Record<string, MapLibreSource | unknown>;
+    sprite?: string;
+    glyphs?: string;
+    layers: unknown[];
+}
+interface MapLibreSource {
+    type: string;
+    tiles?: string[];
+    url?: string;
+    minzoom?: number;
+    maxzoom?: number;
+    [key: string]: unknown;
+}
+/** Target platform — drives the URL scheme used in the rewritten source. */
+type OfflineStylePlatform = "ios" | "android" | "desktop";
+interface BuildOfflineStyleOptions {
+    /**
+     * Target platform. iOS + Android use the `mbtiles://` scheme MapLibre Native
+     * understands; desktop uses `file://`. Default: `"ios"`.
+     */
+    platform?: OfflineStylePlatform;
+    /**
+     * Name of the source to rewrite. If omitted, defaults to the only vector
+     * source in the input style. Throws `OfflineStyleError` if there are zero
+     * or more than one vector sources and `sourceName` isn't provided.
+     */
+    sourceName?: string;
+}
+/**
+ * Thrown when `buildOfflineStyle` can't determine which source to swap or
+ * the named source isn't present in the input style.
+ */
+declare class OfflineStyleError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Returns a deep-copy of `onlineStyle` with the named (or auto-detected)
+ * vector source rewritten to point at `mbtilesPath`. Other sources, layers,
+ * paint, layout, glyphs, and sprite pass through unmodified.
+ *
+ * URL scheme:
+ *
+ *   platform="ios"     → `mbtiles://<mbtilesPath>`   MLN Native iOS
+ *   platform="android" → `mbtiles://<mbtilesPath>`   MLN Native Android
+ *   platform="desktop" → `file://<mbtilesPath>`      MLN GL native (Win/Mac/Linux)
+ *
+ * The `mbtilesPath` is intentionally treated as opaque text. Most native MLN
+ * bindings accept the bare scheme + filename and resolve against an
+ * app-defined root (typically the app's Documents directory). Pass an
+ * absolute path on desktop, or a relative filename on iOS/Android.
+ *
+ * @param onlineStyle  The base MapLibre style. Not mutated.
+ * @param mbtilesPath  Local-file path component (e.g. `"NOAA_ENC.mbtiles"`).
+ * @param opts         Platform + optional explicit `sourceName`.
+ *
+ * @example
+ *   import { buildOfflineStyle } from "@chrtco/sdk";
+ *
+ *   // Online style obtained however you like — generated client-side or
+ *   // fetched from a server.
+ *   const onlineStyle = generateStyle("DAY", { region: "NOAA_ENC" });
+ *
+ *   const offlineStyle = buildOfflineStyle(
+ *     onlineStyle,
+ *     "NOAA_ENC.mbtiles",
+ *     { platform: "ios" },
+ *   );
+ *   // → hand `offlineStyle` to MapLibre.
+ */
+declare function buildOfflineStyle(onlineStyle: MapLibreStyle, mbtilesPath: string, opts?: BuildOfflineStyleOptions): MapLibreStyle;
+
 interface GeoJsonGeometry {
     type: string;
     coordinates: unknown;
@@ -68,6 +177,48 @@ interface CellsResponse {
     limit: number;
     offset: number;
 }
+interface RouteQueryOptions {
+    /** Array of [longitude, latitude] waypoints forming the route */
+    route: [number, number][];
+    /** Buffer distance in metres (default 1000, max 50000) */
+    buffer?: number;
+    /** Filter by chart source, e.g. "NOAA" */
+    source?: string;
+    /** Filter by scale band, e.g. "4" */
+    scaleBand?: string;
+    /** Max cells to return (default 100) */
+    limit?: number;
+    /** AbortSignal to cancel the request */
+    signal?: AbortSignal;
+}
+interface RouteQueryResponse {
+    cells: CellDetail[];
+    query: {
+        buffer_m: number;
+        cell_count: number;
+    };
+    total_count: number;
+}
+interface RouteFeatureQueryOptions {
+    /** Array of [longitude, latitude] waypoints forming the route */
+    route: [number, number][];
+    /** Buffer distance in metres (default 1000, max 50000) */
+    buffer?: number;
+    /** Comma-separated layer codes to filter */
+    layer?: string;
+    /** Max features to return (default 100) */
+    limit?: number;
+    /** Pagination offset */
+    offset?: number;
+    /** AbortSignal to cancel the request */
+    signal?: AbortSignal;
+}
+interface RouteFeatureQueryResponse extends FeatureCollection {
+    query: {
+        buffer_m: number;
+        route_length_m?: number;
+    };
+}
 interface CoverageSource {
     /** Chart source ID, e.g. "NOAA" */
     source: string;
@@ -117,6 +268,119 @@ interface ChrtConfig {
     baseUrl?: string;
     /** Max retries on 5xx/network errors (default 2) */
     retries?: number;
+    /**
+     * Stable per-install device identifier. Required to call `chrt.offline.*`.
+     * Generate once at first launch (e.g. UUIDv4), persist, reuse forever.
+     * Echoed into the offline JWT + heartbeat for device-level correlation.
+     */
+    deviceId?: string;
+    /**
+     * Absolute path to a JSON file where the SDK tracks local offline state
+     * (which regions are downloaded, their sizes and hashes, the storage
+     * budget). Optional — if unset, `setStorageBudget` throws and
+     * budget enforcement in `download` is skipped. No hidden state otherwise.
+     */
+    manifestPath?: string;
+}
+interface OfflineRegionSummary {
+    region: string;
+    build_id: string;
+    build_tag: string;
+    total_bytes: number;
+    issued_at: number | null;
+}
+/**
+ * Response shape from `GET /v1/offline/bundles/{region}`.
+ *
+ * Designed against the post-groups-collapse single-URL shape. A parallel task
+ * is migrating the offline-worker from `groups[]` → one URL per region; this
+ * SDK expects that migration to land before end-to-end integration.
+ */
+interface OfflineBundleResponse {
+    region: string;
+    build_id: string;
+    build_tag: string;
+    signed_url: string;
+    expires_at: number;
+    bytes: number;
+    sha256: string;
+    offline_until: number;
+    heartbeat_after: number;
+    server_time: number;
+}
+interface OfflineDownloadProgress {
+    bytesDownloaded: number;
+    bytesTotal: number;
+    fraction: number;
+}
+interface OfflineDownloadOptions {
+    /** Final destination path for the downloaded MBTiles. SDK writes to `<path>.partial` first, then renames. */
+    path: string;
+    /** FileSystem adapter (e.g. `nodeFileSystemAdapter()` from `@chrtco/sdk/node`). */
+    fs: FileSystemAdapter;
+    /**
+     * Progress callback. Throttled to max(1 MB, 1%) boundaries. Always fires
+     * once at 0 bytes and once at completion regardless of threshold.
+     */
+    onProgress?: (p: OfflineDownloadProgress) => void;
+    /** AbortSignal — on abort, any bytes written persist as `<path>.partial` for resume. */
+    signal?: AbortSignal;
+}
+interface OfflineDownloadResult {
+    path: string;
+    bytes: number;
+    sha256: string;
+    build_id: string;
+    build_tag: string;
+    /** True if this call finished an in-flight download rather than starting fresh. */
+    resumed: boolean;
+}
+interface OfflineRemoveOptions {
+    path: string;
+    fs: FileSystemAdapter;
+}
+interface OfflineHeartbeatOptions {
+    /** Regions currently downloaded. If omitted, derived from manifest (requires `fs`). */
+    regions?: string[];
+    /** Total bytes on device. If omitted, derived from manifest (requires `fs`). */
+    total_bytes?: number;
+    /** FileSystem adapter. Required iff `regions`/`total_bytes` are omitted and manifestPath is set. */
+    fs?: FileSystemAdapter;
+    sdk_version?: string;
+    platform?: string;
+}
+/**
+ * Options for `chrt.offline.fetchStyle()` — fetch a pre-baked offline style
+ * from `GET /v1/offline/styles/{region}`.
+ */
+interface OfflineFetchStyleOptions {
+    /** S-52 colour palette. Default: `"DAY"`. */
+    palette?: "DAY" | "DUSK" | "NIGHT";
+    /**
+     * URL scheme baked into the source. Default: `"mbtiles"` (iOS/Android via
+     * MLN Native). Use `"file"` for desktop (Win/macOS/Linux).
+     */
+    protocol?: "mbtiles" | "file";
+    /** AbortSignal to cancel the request. */
+    signal?: AbortSignal;
+}
+/**
+ * Response shape from `GET /v1/offline/styles/{region}`. The `style` field is
+ * a MapLibre style spec ready to hand to MLN; the surrounding metadata mirrors
+ * the bundle response so callers can refresh `offline_until` from the same
+ * call without a separate heartbeat.
+ */
+interface OfflineStyleResponse {
+    region: string;
+    palette: "DAY" | "DUSK" | "NIGHT";
+    protocol: "mbtiles" | "file";
+    build_id: string;
+    build_tag: string;
+    /** Full MapLibre style JSON. Pass directly to `Map({ style: ... })`. */
+    style: MapLibreStyle;
+    offline_until: number;
+    heartbeat_after: number;
+    server_time: number;
 }
 
 declare class ChrtError extends Error {
@@ -133,6 +397,27 @@ declare class HttpClient {
     getBaseUrl(): string;
     getApiKey(): string;
     request<T>(path: string, params?: Record<string, string | number | undefined>, signal?: AbortSignal): Promise<T>;
+    /**
+     * Typed wrapper for non-GET JSON requests. Returns the parsed body and HTTP
+     * status together so callers (e.g. offline endpoints) can map error bodies
+     * to typed errors without throwing at the HTTP layer. Auth defaults to
+     * `x-api-key` header; pass `bearerToken` to swap to `Authorization: Bearer`.
+     * No retry — the offline flow owns its own retry logic.
+     */
+    postJson<T>(path: string, body: unknown, opts?: {
+        bearerToken?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        ok: boolean;
+        status: number;
+        body: T | null;
+    }>;
+    /** GET with Bearer auth (for offline-worker endpoints that require a JWT). */
+    getJsonWithBearer<T>(path: string, bearerToken: string, signal?: AbortSignal): Promise<{
+        ok: boolean;
+        status: number;
+        body: T | null;
+    }>;
 }
 
 declare class TilesEndpoint {
@@ -162,6 +447,100 @@ declare class CoverageEndpoint {
     list(options?: CoverageOptions): Promise<CoverageResponse>;
 }
 
+/**
+ * Fresh-token shape from POST `/v1/mint/offline-token` (proxied to Supabase
+ * `mint-offline-token`). Mirrors docs/api/tile-jwt-claims.md §4.
+ */
+interface MintedOfflineToken {
+    token: string;
+    expiresAt: number;
+    kid: string;
+    offlineUntil: number;
+    /** Per-region build_tag map returned by the mint function. */
+    buildTags: Record<string, string>;
+    gracePeriodDays: number;
+}
+/**
+ * Cache + single-flight mint for offline JWTs.
+ *
+ * - Keyed by `(deviceId, sorted-regions)` so a token scoped to one region
+ *   doesn't accidentally get reused for a broader request.
+ * - Refreshes 30s before `exp`.
+ * - While a mint is in flight, concurrent callers share the same promise.
+ */
+declare class OfflineTokenManager {
+    private readonly http;
+    private readonly cache;
+    private readonly pending;
+    constructor(http: HttpClient);
+    /**
+     * Get a fresh-enough token for the caller's device + requested regions.
+     * If `regions` is omitted, the mint function defaults to the key's full
+     * `allowed_sources`.
+     */
+    getToken(deviceId: string, regions?: string[]): Promise<MintedOfflineToken>;
+    /** Force-evict the cached token for a (deviceId, regions) pair. Used after a 401. */
+    invalidate(deviceId: string, regions?: string[]): void;
+    private cacheKey;
+    private mintFresh;
+}
+
+declare class OfflineEndpoint {
+    private readonly http;
+    private readonly deviceId;
+    private readonly manifestPath;
+    readonly tokenManager: OfflineTokenManager;
+    constructor(http: HttpClient, deviceId: string | undefined, manifestPath: string | undefined);
+    /** List regions downloadable under the caller's API key. */
+    list(): Promise<OfflineRegionSummary[]>;
+    /**
+     * Download an MBTiles bundle for `region` to `opts.path`. Resumable via a
+     * `<path>.partial` sidecar on interrupt. SHA-256 verified before rename.
+     */
+    download(region: string, opts: OfflineDownloadOptions): Promise<OfflineDownloadResult>;
+    /** Delete local file and, if manifest is configured, drop its row + heartbeat. */
+    remove(region: string, opts: OfflineRemoveOptions): Promise<void>;
+    /**
+     * Pure helper — rewrites the named (or auto-detected) vector source in
+     * `onlineStyle` to point at a local MBTiles file. Layers/paint/glyphs
+     * untouched. Use when you already have an online style (e.g. generated
+     * client-side via the React app's atlas) and want the offline variant.
+     *
+     * Equivalent to importing `buildOfflineStyle` directly — exposed on the
+     * endpoint for discoverability.
+     */
+    style(onlineStyle: MapLibreStyle, mbtilesPath: string, opts?: BuildOfflineStyleOptions): MapLibreStyle;
+    /**
+     * Fetch a pre-baked offline style for `region` from
+     * `GET /v1/offline/styles/{region}`. The worker's response already has the
+     * source rewritten to `mbtiles://` (default) or `file://`, so the returned
+     * `style` is ready to hand directly to MapLibre.
+     *
+     * Recommended for native MLN clients (iOS/Android/desktop) that don't have
+     * the JS atlas available. JS/web SDK consumers can equivalently generate
+     * the online style themselves and call `chrt.offline.style(...)`.
+     */
+    fetchStyle(region: string, opts?: OfflineFetchStyleOptions): Promise<OfflineStyleResponse>;
+    /**
+     * Set the local storage budget in bytes. Requires `manifestPath`. Enforced
+     * at the start of each `download()`. A budget smaller than current usage
+     * does not auto-prune; it only refuses new downloads until the customer
+     * calls `remove()`.
+     */
+    setStorageBudget(bytes: number, fs: FileSystemAdapter): Promise<void>;
+    /**
+     * Send a heartbeat. If `opts.regions` / `opts.total_bytes` are omitted and
+     * a manifest is configured, values are derived from it. v1 is manual-call
+     * only; auto-scheduling is a follow-up phase.
+     */
+    heartbeat(opts?: OfflineHeartbeatOptions): Promise<void>;
+    private requireDeviceId;
+    private requireToken;
+    private fetchBundle;
+    private downloadInternal;
+    private persistManifestEntry;
+}
+
 /**
  * Generic async auto-pagination generator.
  *
@@ -241,6 +620,584 @@ type WebhookEventType = WebhookEvent["type"];
  */
 declare function parseWebhook(body: unknown): WebhookEvent;
 
+/**
+ * Typed errors surfaced by `chrt.offline.*`.
+ *
+ * Callers switch on `.code` — never parse `.message`. `.status` is set only
+ * when the error originated from an HTTP response. `.detail` carries
+ * machine-readable context for programmatic handling (byte math for budget
+ * violations, `resumable: true` for interrupts, etc.).
+ */
+type OfflineErrorCode = "budget_exceeded" | "coverage_denied" | "quota_exceeded" | "download_corrupt" | "network_interrupted" | "partial_file_invalid" | "invalid_api_key" | "region_not_available" | "offline_not_enabled" | "missing_device_id" | "missing_manifest_path" | "sha_missing" | "unexpected_response";
+declare class OfflineError extends Error {
+    readonly code: OfflineErrorCode;
+    readonly status?: number;
+    readonly detail?: Record<string, unknown>;
+    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;
+}
+/** 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 */
+    textColor: string;
+    /** Halo color for contrast */
+    textHaloColor: string;
+    /** Halo width */
+    textHaloWidth: number;
+    /** 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;
+}
+/** Get label config for a given S-57 layer, or null if no labels */
+declare function getLabelConfig(layerName: string): 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[];
+
+/**
+ * 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[];
+}
+declare function generateStyle(palette?: ColorTableName, opts?: BuildSourcesOptions): MapboxStyle;
+declare function generateStyleJSON(palette?: ColorTableName, opts?: BuildSourcesOptions): 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;
@@ -248,6 +1205,12 @@ declare class Chrt {
     readonly cells: CellsEndpoint;
     /** Coverage data — list available chart sources */
     readonly coverage: CoverageEndpoint;
+    /**
+     * CHRToffline — download MBTiles bundles for offline use.
+     * Requires `deviceId` in config. Manifest-based budget enforcement
+     * requires `manifestPath`.
+     */
+    readonly offline: OfflineEndpoint;
     private featuresEp;
     private queryEp;
     private http;
@@ -293,4 +1256,4 @@ declare class Chrt {
     transformRequest(): (url: string) => TransformRequest | undefined;
 }
 
-export { 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, type GeoJsonFeature, type GeoJsonGeometry, type QueryOptions, type TileGroup, type TileGroupsResponse, type TransformRequest, type WebhookEvent, type WebhookEventType, type WebhookPayload, paginate, parseWebhook };
+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 };