@chrtco/sdk 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -434,21 +434,167 @@ declare class HttpClient {
     }>;
 }
 
+/**
+ * Tile authentication for the `tiles.chrt.co` PMTiles path.
+ *
+ * The CHRT tile-worker serves raw MVT at
+ *   `https://tiles.chrt.co/v1/tiles/{region}/{z}/{x}/{y}.mvt`
+ * and authenticates each request with a short-lived ES256 JWT (5-min default,
+ * 15-min max) carried in the `Authorization: Bearer` header. This module mints
+ * those JWTs from the customer's API key and produces a MapLibre / Mapbox GL
+ * `transformRequest` that attaches the Bearer to tile requests only.
+ *
+ * Responsibilities (mirrors the first-party web client at
+ * `src/lib/map/tile-token-client.ts`, adapted to be instance-scoped and
+ * zero-dependency so it runs in browsers, Node 18+, Deno, and Bun):
+ *   - Mint via `POST {baseUrl}/mint/tile-token` (default
+ *     `https://api.chrt.co/v1/mint/tile-token`) with the `x-api-key` header.
+ *   - Cache tokens in memory, keyed by region; refresh silently 30s before
+ *     expiry so long-lived maps never flicker.
+ *   - Expose a SYNC `transformRequest` (MapLibre requires sync) that attaches
+ *     the cached Bearer; it kicks off a background mint on first use so the
+ *     cache warms within one round-trip.
+ *
+ * NOTE: the public mint route `POST /v1/mint/tile-token` (the sibling of the
+ * existing `/v1/mint/offline-token`) must be present on the `api.chrt.co`
+ * edge worker for this path to serve. Until it lands, mints fail with a
+ * network/HTTP error surfaced through `getToken()`.
+ */
+
+/** Default chart region — the one consolidated PMTiles served per region. */
+declare const DEFAULT_TILE_REGION = "NOAA_ENC";
+/** Default tile-worker origin. Override via `ChrtConfig.tileBaseUrl`. */
+declare const DEFAULT_TILE_BASE_URL = "https://tiles.chrt.co";
+/** Full token response from the mint endpoint. */
+interface TileTokenResponse {
+    /** ES256-signed JWT; do not log. */
+    token: string;
+    /** Unix seconds (matches JWT `exp`). */
+    expiresAt: number;
+    /** Key id used to sign (matches JWT header `kid`). */
+    kid: string;
+    /** Build id/tag pinned into the JWT — the tile-worker cache key. */
+    buildTag: string;
+    /** Echo of the region the token is scoped to. */
+    region: string;
+}
+/** Typed error codes the mint flow surfaces; callers switch on `.code`. */
+type TileTokenErrorCode = "invalid_api_key" | "feature_flag_disabled" | "region_not_licensed" | "tile_quota_exceeded" | "region_not_available" | "network_error" | "unexpected_response";
+declare class TileTokenError extends Error {
+    readonly code: TileTokenErrorCode;
+    readonly status?: number;
+    constructor(code: TileTokenErrorCode, message: string, status?: number);
+}
+/** MapLibre / Mapbox GL `transformRequest` return shape. */
+interface TransformedRequest {
+    url: string;
+    headers?: Record<string, string>;
+}
+/**
+ * Instance-scoped tile-token manager. One per `Chrt` client so multiple
+ * clients (e.g. different API keys) never share a cache.
+ */
+declare class TileAuth {
+    private readonly http;
+    private readonly cache;
+    private readonly pending;
+    private readonly defaultRegion;
+    private readonly tileBaseUrl;
+    private lifecycleRegistered;
+    constructor(http: HttpClient, opts?: {
+        region?: string;
+        tileBaseUrl?: string;
+    });
+    /** Mint once via the HTTP client (POST `/mint/tile-token`, `x-api-key`). */
+    private mintOnce;
+    /** Mint with exponential backoff on network errors only. */
+    private mintWithRetry;
+    private scheduleRefresh;
+    private refreshInBackground;
+    private store;
+    /**
+     * Fetch (or reuse a cached) tile token for `region`. Concurrent callers for
+     * the same region await the same in-flight mint.
+     */
+    getToken(region?: string): Promise<TileTokenResponse>;
+    /** Synchronous cache peek — null if absent or within the stale grace window. */
+    peek(region?: string): string | null;
+    /**
+     * Produce a MapLibre / Mapbox GL `transformRequest`. Attaches
+     * `Authorization: Bearer <jwt>` only to CHRT tile URLs and the CHRT
+     * served-style URL (`/v1/styles/{region}/style.json`); sprite, glyph, and
+     * third-party URLs pass through untouched (never leak the token to
+     * third-party CDNs). Kicks off a background mint immediately so the cache
+     * warms within one round-trip; the first tile or two may go
+     * unauthenticated and be retried by the renderer. When pointing a map's
+     * `style` at the served style URL, obtain it via `chrt.styleUrl()` — it
+     * awaits the mint, so the style request (which MapLibre does NOT retry)
+     * is guaranteed to carry auth.
+     */
+    transformRequest(region?: string): (url: string) => TransformedRequest | undefined;
+    /** Clear the cached token + timer for a region. */
+    invalidate(region?: string): void;
+    /**
+     * Browser-only defense against `setTimeout` freezing while a tab is
+     * suspended (laptop sleep, mobile background, bfcache restore): proactively
+     * re-mint near-expiry entries on wake. Inert under SSR / Node / Deno.
+     */
+    private registerLifecycleHandlers;
+}
+
+/** Palette themes served by the Style API (S-52 colour tables). */
+type ChrtStyleTheme = "day" | "dusk" | "night";
+interface StyleUrlOptions {
+    /** Palette: "day" (default), "dusk", or "night". Omit to get the style's
+     *  default — for keys with a bound CHRTstyle custom style, that's the
+     *  style's default palette. */
+    theme?: ChrtStyleTheme;
+}
+interface FetchStyleOptions extends StyleUrlOptions {
+    signal?: AbortSignal;
+}
 declare class TilesEndpoint {
     private http;
+    private tileAuth;
     private readonly region;
     private readonly tileBaseUrl;
-    constructor(http: HttpClient, opts?: {
+    constructor(http: HttpClient, tileAuth: TileAuth, opts?: {
         region?: string;
         tileBaseUrl?: string;
     });
+    private styleEndpoint;
     /**
-     * @deprecated CHRT has no remote `style.json` endpoint — the S-52 style is
-     * generated client-side. Use `chrt.style(opts)` to get a ready-to-use
-     * MapLibre style object instead. Calling this throws to prevent silently
-     * pointing a map at a dead URL.
+     * URL of the served S-52 style for the configured region — the CHRTstyle
+     * Style API (`GET /v1/styles/{region}/style.json`). The served document
+     * honors the API key's bound custom style (a Dev+ feature configured at
+     * platform → Map Styles); Free keys and unbound keys get the default
+     * themes, identical to the locally generated `chrt.style()`.
+     *
+     * The endpoint is JWT-gated, so pair the URL with
+     * `chrt.transformRequest()`, which attaches the Bearer token to both the
+     * style request and its tile requests. This method is async because it
+     * pre-mints the tile token, guaranteeing the auth cache is warm before
+     * MapLibre fetches the URL.
+     *
+     * @example
+     * const map = new maplibregl.Map({
+     *   container: 'map',
+     *   style: await chrt.styleUrl({ theme: 'dusk' }),
+     *   transformRequest: chrt.transformRequest(),
+     * });
+     */
+    styleUrl(opts?: StyleUrlOptions): Promise<string>;
+    /**
+     * Fetch the served S-52 style as a MapLibre style object (see
+     * {@link styleUrl} for what "served" means). Prefer this over `styleUrl()`
+     * when you want to inspect or mutate the document, or when you can't use
+     * `transformRequest` for the style request itself.
+     *
+     * Falls back nowhere: a network or auth failure throws (`ChrtError` /
+     * `TileTokenError`). For an offline-capable local fallback, use
+     * `chrt.style()` — the client-side generator.
      */
-    styleUrl(): never;
+    fetchStyle(opts?: FetchStyleOptions): Promise<MapLibreStyle>;
     /**
      * Vector tile URL template for the configured region, served by the
      * tile-worker at `tiles.chrt.co`. Tiles are JWT-gated — pair this with
@@ -574,6 +720,468 @@ declare class OfflineEndpoint {
     private persistManifestEntry;
 }
 
+/** Style-layer ids (CHRT S-52 atlas) that carry point nav-aid features. */
+declare const NAV_AID_QUERY_LAYERS: string[];
+/** Style-layer ids for area / hazard / regulated / infrastructure features. */
+declare const AREA_QUERY_LAYERS: string[];
+/**
+ * Bridge style layers, queried separately so bridges win over overlapping
+ * area polygons (click order: nav-aid → bridge → area).
+ */
+declare const BRIDGE_QUERY_LAYERS: string[];
+interface DecodedBridge {
+    name: string | null;
+    categoryCode: number | null;
+    categoryLabel: string | null;
+    verticalClearance: number | null;
+    verticalClearanceClosed: number | null;
+    verticalClearanceOpen: number | null;
+    horizontalClearance: number | null;
+    status: string | null;
+    condition: string | null;
+    information: string | null;
+    nationalName: string | null;
+    sourceIndication: string | null;
+    sourceDate: string | null;
+}
+/** Decode a BRIDGE feature's S-57 attributes into a typed record. */
+declare function decodeBridgeProps(props: Record<string, unknown>): DecodedBridge;
+/** A decoded label/value row, ready for direct display. */
+interface DecodedProperty {
+    label: string;
+    value: string;
+}
+interface DecodedAreaFeature {
+    type: string;
+    title: string;
+    properties: DecodedProperty[];
+}
+/** Decode properties for area/hazard/regulated features into a human-readable record. */
+declare function decodeAreaFeatureProps(layerName: string, props: Record<string, unknown>): DecodedAreaFeature;
+interface SectorInfo {
+    sectorStart: number;
+    sectorEnd: number;
+    colour: string;
+    colourHex: string;
+    notation: string;
+    nominalRange?: number | null;
+}
+interface DecodedNavAid {
+    name: string;
+    /** Full official OBJNAM (e.g., "Boston South Channel Buoy 7") */
+    fullName: string | null;
+    type: string;
+    layerName: string;
+    colour: string | null;
+    colourHex: string;
+    /** Primary light colour hex (from co-located LIGHTS or own COLOUR for LIGHTS features) */
+    lightColourHex: string;
+    /** All light colours for alternating lights (e.g. ["#ffffff", "#ef4444"] for W R) */
+    colourHexList: string[];
+    shape: string | null;
+    topmark: string | null;
+    topmarkMeaning: string | null;
+    lightCharacter: string | null;
+    lightCharacterFull: string | null;
+    period: number | null;
+    group: number[] | null;
+    fogSignal: string | null;
+    fogSignalAbbr: string | null;
+    radarReflector: boolean;
+    depth: number | null;
+    status: string | null;
+    markingSystem: string | null;
+    category: string | null;
+    information: string | null;
+    notation: string;
+    coordinates: [number, number] | null;
+    sectors: SectorInfo[];
+    orientation: number | null;
+    isDirectional: boolean;
+    isSectorLight: boolean;
+}
+/**
+ * Parse ALL numeric codes from a list-type S-57 attribute (COLOUR, RESTRN, …).
+ * List attributes arrive as native arrays (["1","3"]) on the GeoJSON source
+ * path, JSON-stringified arrays ('["1","3"]') after tippecanoe/PMTiles, or
+ * comma/semicolon-separated scalars in legacy/normalized data.
+ */
+declare function parseListCodes(val: unknown): number[];
+/**
+ * Derive a mariner shorthand name from a verbose S-57 OBJNAM + COLOUR.
+ * e.g. "Weymouth Back River Channel Lighted Buoy 8" + COLOUR=3 → R "8"
+ */
+declare function deriveMarinerName(objnam: string, colourCode: number | null): string;
+/**
+ * What an S-57 TOPSHP topmark *denotes* given the parent buoy/beacon layer.
+ *
+ * IALA topmark shapes carry the same meaning in IALA-A and IALA-B regions —
+ * only the colour conventions differ between regions — so the meaning is a
+ * function of (TOPSHP, parent layer) and we don't need to consult MARSYS.
+ *
+ * Returns null when the shape/parent combination has no canonical meaning
+ * (e.g. a board topmark on a private daymark), so callers can simply skip
+ * rendering the hint.
+ */
+declare function getTopmarkMeaning(topshpCode: number | null, rawLayer: string): string | null;
+declare function decodeNavAidProps(layerName: string, props: Record<string, unknown>, coords?: [number, number]): DecodedNavAid;
+interface FlashPhase {
+    on: boolean;
+    duration: number;
+    color?: string;
+}
+interface FlashPattern {
+    phases: FlashPhase[];
+    totalCycle: number;
+    notation: string;
+}
+declare function buildFlashPattern(decoded: DecodedNavAid): FlashPattern | null;
+/** Minimal GeoJSON shapes for the sector-arc builders (kept dependency-free). */
+interface SectorArcFeature {
+    type: "Feature";
+    properties: Record<string, unknown>;
+    geometry: {
+        type: "Polygon" | "LineString" | "Point";
+        coordinates: unknown;
+    };
+}
+interface SectorArcFeatureCollection {
+    type: "FeatureCollection";
+    features: SectorArcFeature[];
+}
+/**
+ * Build all sectors from multiple LIGHTS features at the same position.
+ * Each LIGHTS feature with SECTR1/SECTR2 defines one sector.
+ */
+declare function buildSectorsFromFeatures(features: Array<{
+    properties: Record<string, unknown>;
+}>): SectorInfo[];
+/**
+ * Generate a GeoJSON arc polygon for a sector light.
+ * Bearings are TRUE bearings FROM the light (as seen FROM a vessel).
+ * S-57 SECTR1/SECTR2 define the arc as seen FROM seaward looking AT the light,
+ * so we draw arcs in bearing order from the light's position.
+ *
+ * When `innerRadiusNm > 0`, the polygon is an annulus segment (band) —
+ * a ring slice between the inner and outer radius — instead of a pie wedge.
+ *
+ * @param center [lng, lat]
+ * @param startBearing degrees true (clockwise from north)
+ * @param endBearing degrees true
+ * @param radiusNm outer radius in nautical miles
+ * @param innerRadiusNm inner radius in nautical miles (0 = pie wedge)
+ * @param steps number of arc segments
+ */
+declare function buildSectorArcGeoJSON(center: [number, number], startBearing: number, endBearing: number, radiusNm?: number, innerRadiusNm?: number, steps?: number): SectorArcFeature;
+/**
+ * Build a complete GeoJSON FeatureCollection of sector arcs for rendering.
+ * Each feature has color/notation properties for styling.
+ *
+ * Default behavior is a thin band (annulus segment) at the perimeter —
+ * sectors read as a colored ring around the light rather than a pie wedge.
+ * Set `innerRadiusFrac = 0` for the legacy pie-wedge appearance.
+ */
+declare function buildSectorArcsFC(center: [number, number], sectors: SectorInfo[], radiusNm?: number, innerRadiusFrac?: number): SectorArcFeatureCollection;
+
+/**
+ * Safety & attribution invariants for CHRTinteract.
+ *
+ * Per `.chrt/ai-agent-guide.md` §"Safety & Disclaimers" and the platform's
+ * non-negotiable stewardship invariants, EVERY InspectResult and the built-in
+ * popup MUST carry:
+ *   1. the non-SOLAS "not for primary navigation" disclaimer,
+ *   2. issuing hydrographic-office attribution, and
+ *   3. data currency (edition / update_number / issue_date once known).
+ *
+ * Wording matches the canonical text in `@chrtco/mcp` (`safety.ts`) so it can
+ * never drift between surfaces. Do not weaken or remove.
+ */
+
+/** The canonical non-SOLAS disclaimer. Present on every InspectResult. */
+declare const NON_SOLAS_DISCLAIMER: string;
+/** Short form for space-constrained UI (the built-in popup footer). */
+declare const NON_SOLAS_DISCLAIMER_SHORT = "Not for primary navigation";
+/** Safety, attribution, and currency context attached to every InspectResult. */
+interface InspectNotice {
+    /** Non-SOLAS disclaimer — always `NON_SOLAS_DISCLAIMER`. */
+    disclaimer: string;
+    /** Issuing hydrographic-office / source attribution line. */
+    attribution: string;
+    /**
+     * Data-currency line. Before enrichment this states how to resolve currency;
+     * after `inspect({ enrich: true })` it carries the source cell's edition,
+     * update number, and issue date.
+     */
+    dataCurrency: string;
+}
+
+/**
+ * Public types for CHRTinteract — click-to-inspect for CHRT charts.
+ */
+
+/**
+ * A chart feature to inspect. Structurally compatible with a MapLibre / Mapbox
+ * GL `MapGeoJSONFeature` (what `queryRenderedFeatures` returns), and with a
+ * plain `{ layer, properties }` object for headless use.
+ */
+interface InspectableFeature {
+    /** Vector-tile attributes (LITCHR, COLOUR, OBJNAM, …). */
+    properties?: Record<string, unknown> | null;
+    /** MVT source-layer name, e.g. "BOYLAT" (set by queryRenderedFeatures). */
+    sourceLayer?: string;
+    /** Style layer that rendered the feature, or a raw layer name string. */
+    layer?: {
+        id?: string;
+    } | string;
+    /** GeoJSON geometry — Point coordinates locate the popup / enrichment. */
+    geometry?: {
+        type?: string;
+        coordinates?: unknown;
+    } | null;
+}
+interface InspectOptions {
+    /**
+     * Override the layer used for decoding (style-layer id like "enc-BOYLAT" or
+     * raw S-57 name like "BOYLAT"). Defaults to the feature's own layer.
+     */
+    layer?: string;
+    /** Coordinates [lng, lat] when the feature's geometry doesn't carry them. */
+    coordinates?: [number, number];
+    /**
+     * Fetch full S-57 properties + source-cell provenance (edition, update,
+     * issue date) through the CHRT features API. **Metered** — counts against
+     * the key's monthly `featureCalls` quota.
+     */
+    enrich?: boolean;
+    /** AbortSignal for the enrichment fetches. */
+    signal?: AbortSignal;
+}
+/** Source-cell provenance + full properties resolved by `enrich: true`. */
+interface InspectEnrichment {
+    /** Whether a matching feature was found in the features API. */
+    matched: boolean;
+    /** Full S-57 properties from the source data (superset of tile attrs). */
+    properties: Record<string, unknown> | null;
+    /** The ENC cell the feature came from. */
+    cellId: string | null;
+    /** Cell metadata — edition / update_number / issue_date live here. */
+    cell: CellDetail | null;
+}
+interface InspectResultCommon {
+    /** Raw S-57 object class, e.g. "BOYLAT". */
+    layer: string;
+    /** The style-layer id the feature was resolved from, e.g. "enc-BOYLAT". */
+    layerId: string;
+    /** Human-readable object class, e.g. "Lateral Buoy". */
+    objectClass: string;
+    /** Display title (mariner shorthand, OBJNAM, or object class). */
+    title: string;
+    /** [lng, lat] when known. */
+    coordinates: [number, number] | null;
+    /** Decoded, display-ready label/value rows. */
+    properties: DecodedProperty[];
+    /** The merged tile attributes the decode ran on. */
+    raw: Record<string, unknown>;
+    /** Non-SOLAS disclaimer + HO attribution + data currency. Always present. */
+    notice: InspectNotice;
+    /** Present when `inspect({ enrich: true })` was used. */
+    enrichment: InspectEnrichment | null;
+}
+/** A decoded navigational aid (buoy, beacon, light, fog signal, landmark…). */
+interface NavAidInspectResult extends InspectResultCommon {
+    kind: "navaid";
+    /** Full decoded nav-aid record (colours, topmark, sectors, fog, status…). */
+    navAid: DecodedNavAid;
+    /** Mariner light characteristic, e.g. "Fl(2+1) W 10s". Null when unlit. */
+    characteristic: string | null;
+    /** Flash/eclipse timing phases for animating the light. Null when unlit. */
+    flashPattern: FlashPattern | null;
+}
+/** A decoded bridge (clearances, category, condition). */
+interface BridgeInspectResult extends InspectResultCommon {
+    kind: "bridge";
+    bridge: DecodedBridge;
+}
+/** A decoded area / hazard / regulated / infrastructure feature. */
+interface AreaInspectResult extends InspectResultCommon {
+    kind: "area";
+    area: DecodedAreaFeature;
+}
+type InspectResult = NavAidInspectResult | BridgeInspectResult | AreaInspectResult;
+/** Successful server-side entitlement check. */
+interface InteractEntitlement {
+    enabled: true;
+    /** The team's plan id (e.g. "dev", "pro"), when the server includes it. */
+    plan?: string;
+}
+/**
+ * Structural subset of the MapLibre / Mapbox GL `Map` interface used by
+ * `attach()`. Declared structurally so `maplibre-gl` stays an optional peer
+ * dependency — any GL JS map instance satisfies it.
+ */
+interface InteractMapLike {
+    on(event: string, listener: (ev: InteractMapMouseEvent) => void): unknown;
+    off(event: string, listener: (ev: InteractMapMouseEvent) => void): unknown;
+    queryRenderedFeatures(pointOrBox?: unknown, options?: {
+        layers?: string[];
+    }): InspectableFeature[];
+    getLayer(id: string): unknown;
+    getContainer(): HTMLElement;
+    project(lngLat: [number, number]): {
+        x: number;
+        y: number;
+    };
+}
+/** The subset of a GL JS MapMouseEvent that attach() consumes. */
+interface InteractMapMouseEvent {
+    point: {
+        x: number;
+        y: number;
+    };
+    lngLat: {
+        lng: number;
+        lat: number;
+    };
+}
+/** Context passed to `onInspect` alongside the result. */
+interface InspectEventContext {
+    /** Click location. */
+    lngLat: {
+        lng: number;
+        lat: number;
+    };
+    /** Click location in screen pixels. */
+    point: {
+        x: number;
+        y: number;
+    };
+    /** The rendered feature the result was decoded from. */
+    feature: InspectableFeature;
+}
+interface AttachOptions {
+    /**
+     * Receive every InspectResult (headless mode). Fires whether or not the
+     * built-in popup is enabled.
+     */
+    onInspect?: (result: InspectResult, ctx: InspectEventContext) => void;
+    /** Called when a click hits no inspectable feature. */
+    onMiss?: (ctx: {
+        lngLat: {
+            lng: number;
+            lat: number;
+        };
+    }) => void;
+    /**
+     * Show the built-in minimal popup (plain DOM, no framework). Default: true
+     * when `onInspect` is not provided, false otherwise.
+     */
+    popup?: boolean;
+    /**
+     * Auto-enrich every click through the features API (metered — counts
+     * against the key's `featureCalls` quota). Default: false.
+     */
+    enrich?: boolean;
+    /** Override the queried nav-aid style-layer ids. */
+    navAidLayers?: string[];
+    /** Override the queried bridge style-layer ids. */
+    bridgeLayers?: string[];
+    /** Override the queried area style-layer ids. */
+    areaLayers?: string[];
+}
+/** Handle returned by `attach()`. */
+interface InteractHandle {
+    /** Remove the click handler and any open popup. */
+    detach(): void;
+}
+
+/**
+ * Typed errors for the CHRTinteract flow. Mirrors the `TileTokenError` /
+ * `OfflineError` pattern: a `code` discriminator so callers can branch
+ * messaging (upgrade prompt vs. auth failure vs. transient network).
+ */
+type InteractErrorCode = 
+/** The team's plan does not include CHRTinteract (Dev tier and above). */
+"interact_not_enabled"
+/** The API key was rejected (unknown, disabled, or expired). */
+ | "invalid_api_key"
+/** The key was explicitly narrowed to scopes that exclude interact. */
+ | "missing_scope"
+/** Feature enrichment failed (features/cells API error). */
+ | "enrich_failed"
+/** The inspected feature could not be resolved to a chart layer. */
+ | "unknown_layer"
+/** Transport-level failure reaching the entitlement endpoint. */
+ | "network_error"
+/** The server answered with a shape the SDK doesn't recognize. */
+ | "unexpected_response";
+declare class InteractError extends Error {
+    readonly code: InteractErrorCode;
+    readonly status?: number;
+    /** The team's current plan id, when the server included it (denials). */
+    readonly plan?: string;
+    constructor(code: InteractErrorCode, message: string, opts?: {
+        status?: number;
+        plan?: string;
+    });
+}
+
+/**
+ * CHRTinteract — productized click-to-inspect for CHRT charts.
+ *
+ * `chrt.interact.attach(map)` wires click → decode → popup/callback onto any
+ * MapLibre / Mapbox GL map showing CHRT tiles; `chrt.interact.inspect(feature)`
+ * decodes a single feature headlessly. Both enforce the Dev-tier-and-above
+ * entitlement server-side before doing any work, and every result carries the
+ * non-SOLAS disclaimer, hydrographic-office attribution, and data currency.
+ *
+ * Included with the Dev plan and above. Free-plan keys receive an
+ * `InteractError` with code `interact_not_enabled`.
+ */
+
+declare class InteractClient {
+    private readonly http;
+    private readonly entitlementClient;
+    constructor(http: HttpClient);
+    /**
+     * Check the CHRTinteract entitlement for this API key (server-side, plan
+     * derived, cached per client). Throws `InteractError` with code
+     * `interact_not_enabled` for Free-plan teams.
+     */
+    entitlement(): Promise<InteractEntitlement>;
+    /**
+     * Decode a chart feature (from `queryRenderedFeatures`, the features API,
+     * or plain `{ layer, properties }`) into a typed {@link InspectResult}.
+     *
+     * The first call performs the server-side entitlement check. With
+     * `{ enrich: true }` the result is upgraded with full S-57 properties and
+     * source-cell provenance (edition / update / issue date) via the features
+     * API — metered against the key's `featureCalls` quota.
+     *
+     * @example
+     * const result = await chrt.interact.inspect(feature);
+     * if (result.kind === "navaid") console.log(result.characteristic); // "Fl R 4s"
+     */
+    inspect(feature: InspectableFeature, opts?: InspectOptions): Promise<InspectResult>;
+    /**
+     * Attach click-to-inspect to a MapLibre / Mapbox GL map rendering CHRT
+     * tiles. Resolves once the server-side entitlement check passes; rejects
+     * with `InteractError` (`interact_not_enabled` on Free plans) otherwise —
+     * no listeners are wired on denial.
+     *
+     * Headless-first: pass `onInspect` to receive every decoded
+     * {@link InspectResult} and render your own UI. Without `onInspect`, the
+     * built-in minimal popup is shown (opt back in explicitly with
+     * `popup: true` to have both).
+     *
+     * @example
+     * const handle = await chrt.interact.attach(map, {
+     *   onInspect: (result) => console.log(result.title, result.characteristic),
+     * });
+     * // later: handle.detach();
+     */
+    attach(map: InteractMapLike, opts?: AttachOptions): Promise<InteractHandle>;
+}
+
 /** S-52 display categories – controls default visibility */
 type DisplayCategory = "BASE" | "STANDARD" | "OTHER" | "MARINERS" | "META";
 /** Mapbox GL layer type we'll use for this entry */
@@ -759,6 +1367,72 @@ 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;
+/**
+ * Class-based label priority ladder — THE single collision-priority model
+ * for feature labels (portrayal-excellence P4). Converges the previous
+ * per-mechanism patches (SAFETY_CRITICAL_LABELS allow-overlap, the
+ * band-5/6-only Harbor collision discipline) into one explicit ranking.
+ *
+ * Rank semantics: LOWER rank = higher priority. The rank drives two
+ * mechanisms that must stay in agreement:
+ *
+ *   1. `symbol-sort-key` — every feature label carries
+ *      `rank*1000 + within-class-key`, so if label layers are ever merged
+ *      (the P8 style fan-out reduction), placement priority survives the
+ *      merge unchanged.
+ *   2. Label LAYER ORDER — MapLibre places symbols topmost-layer-first, so
+ *      `style-generator.ts` emits feature-label layers lowest-priority
+ *      first: safety-critical classes end up topmost and claim collision
+ *      space before anything else. (`symbol-sort-key` alone cannot do
+ *      this — it only orders placement WITHIN a layer.)
+ *
+ * The ladder (safety-critical > nav-aids > depth field > structures >
+ * ambient notes):
+ *
+ *   100 — Safety-critical: light characteristics (LIGHTS), hazard depth
+ *         callouts (UWTROC/OBSTRN/WRECKS VALSOU), overhead clearances
+ *         (CBLOHD/PIPOHD VERCLR). Irreducible mariner-safety text.
+ *   200 — Nav-aid designations: buoy / beacon `R "4"` labels.
+ *   250 — Auxiliary nav-aid info: fog signal type (FOGSIG).
+ *   300 — Depth field: soundings, contour values. Individually droppable —
+ *         a hidden sounding has visible neighbors.
+ *   400 — Structures: bridges, landmarks, piers, moorings, buildings.
+ *   500 — Ambient annotation: seabed nature, magnetic variation, kelp.
+ *   900 — Orientation names (SEAARE etc.) — not part of this ladder;
+ *         they keep their settled watermark model (cell-band fan +
+ *         dominance composition + `orientationLabelLayout`) and always
+ *         paint underneath feature labels.
+ *
+ * Safety guardrail: a lower rung never blocks a higher rung — placement
+ * order guarantees the safety-critical label got the space first. Density
+ * relief comes from dropping the LOWEST rung in a pile-up, never the top.
+ */
+declare const LABEL_PRIORITY: Record<string, number>;
+/**
+ * Resolve the priority rank for an S-57 class's label. Orientation classes
+ * report 900 regardless of ladder membership (PRDARE etc.) so the
+ * layer-order sort in style-generator.ts can treat priority uniformly.
+ */
+declare function getLabelPriority(layerName: string): number;
+/**
+ * Compose a `symbol-sort-key` from a class rank and an optional
+ * within-class key expression. The within-class key is clamped to
+ * [0, 999] so it can never bleed into a neighboring rank's band.
+ */
+declare function labelSortKey(rank: number, within?: unknown): ExpressionSpecification | number;
+/**
+ * Extract the trailing designation token from a nav-aid OBJNAM.
+ *
+ * NOAA names channel aids "<waterway> <type> Buoy|Beacon <designation>"
+ * where the designation is 1-4 alphanumerics: "4", "18A", "B", "BG".
+ * Returns null when the name has no designation (trailing token is a
+ * stopword type-name, or longer than 4 chars).
+ *
+ * This is the TS twin of `navAidDesignationTextExpression` — the GeoJSON
+ * preprocessing path uses this function, the PMTiles path uses the GL
+ * expression. Keep the two in agreement (see label-priority.test.ts).
+ */
+declare function extractNavAidDesignation(objnam: string): string | null;
 /** Get label config for a given S-57 layer, or null if no labels */
 declare function getLabelConfig(layerName: string, opts?: LabelConfigOptions): LabelLayerConfig | null;
 /**
@@ -1077,7 +1751,7 @@ declare function getS52SymbolStats(): {
  * 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_MINZOOM = 0;
 declare const BUILD_MAXZOOM = 14;
 
 /**
@@ -1205,24 +1879,39 @@ interface BandPriorityRange {
  * (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
+ * Cross-band visual overlap (doubled coastlines, duplicate labels) is
  * suppressed by the `_dominated_by_min` per-feature tag added at NDJSON
  * export time (see `tools/chrt-baremetal/server/src/tilebuild/dominanceIndex.ts`):
  * every feature whose centroid sits inside a higher-band cell's M_COVR
  * coverage polygon is tagged with the LOWEST band code (2..6) that
  * dominates it, and `makeBandVariants()` in the style generator emits
  * per-(featureBand, dominatorBand) layer variants gated by `maxzoom =
- * 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.
+ * dominatedVariantMaxzoom(D)`. The dominated feature renders until
+ * exactly the zoom where its dominator becomes eligible AND has data in
+ * the tiles — solving the low-zoom "black silhouettes" bug where a
+ * band-3 LNDARE dominated by a band-5 cell was dropped at z7 even
+ * though band 5 wasn't yet rendering at z7.
+ *
+ * Opaque base-area FILLS are exempt from dominance gating entirely (see
+ * `DOMINANCE_EXEMPT_FILL_CLASSES` in the style generator): band-major
+ * draw order already makes the most-detailed band's opaque fill win at
+ * any covered pixel, and the coarser band shows through wherever the
+ * detailed band has no data — which is exactly the fallback semantics
+ * the cascade wants. The 2026-07 E1/E2 void diagnosis
+ * (docs/validation/portrayal-p1-p3-void-diagnosis-2026-07.md) proved
+ * per-feature dominance gating on fills structurally unsound: the tag is
+ * point-sampled but hides the WHOLE feature, so a Gulf-spanning band-1
+ * DEPARE tagged dominated-by-2 left dark voids across every part of the
+ * Gulf that band 2 doesn't actually cover.
  *
  * Bands 5 and 6 both start at z11; band 6 (Berthing) is drawn AFTER
  * band 5 (Harbor) so where Berthing exists it visually wins, and
  * Harbor shows through everywhere else.
+ *
+ * Band 1 starts at z0: the P3 low-zoom contract (charts never disappear
+ * from world view down) needs Overview-band data renderable as soon as
+ * tiles exist. Builds older than the z0 floor simply have no tiles below
+ * z3, so the widened range is a no-op against them.
  */
 declare const BAND_PRIORITY_RANGES: Record<BandCode, BandPriorityRange>;
 /**
@@ -1386,108 +2075,210 @@ declare function getStyleStats(style: MapboxStyle): {
 };
 
 /**
- * Tile authentication for the `tiles.chrt.co` PMTiles path.
+ * CHRTstyle custom styles — the customer-facing map_styles config applied
+ * on top of the generated S-52 style.
  *
- * The CHRT tile-worker serves raw MVT at
- *   `https://tiles.chrt.co/v1/tiles/{region}/{z}/{x}/{y}.mvt`
- * and authenticates each request with a short-lived ES256 JWT (5-min default,
- * 15-min max) carried in the `Authorization: Bearer` header. This module mints
- * those JWTs from the customer's API key and produces a MapLibre / Mapbox GL
- * `transformRequest` that attaches the Bearer to tile requests only.
+ * A team's `map_styles` row (platform → Map Styles) stores S-52 rendering
+ * preferences: which colour tables are enabled, the default palette, the
+ * S-52 display mode, per-group visibility/scale/collision knobs, and an
+ * optional layer whitelist. Keys bind a style via `api_keys.map_style_id`;
+ * `mint-tile-token` embeds `style_id` + `style_rev` claims for entitled
+ * (Dev+) plans, and the tile-worker's `/v1/styles/{region}/style.json`
+ * route resolves the config and calls `generateCustomStyle()` here.
  *
- * Responsibilities (mirrors the first-party web client at
- * `src/lib/map/tile-token-client.ts`, adapted to be instance-scoped and
- * zero-dependency so it runs in browsers, Node 18+, Deno, and Bun):
- *   - Mint via `POST {baseUrl}/mint/tile-token` (default
- *     `https://api.chrt.co/v1/mint/tile-token`) with the `x-api-key` header.
- *   - Cache tokens in memory, keyed by region; refresh silently 30s before
- *     expiry so long-lived maps never flicker.
- *   - Expose a SYNC `transformRequest` (MapLibre requires sync) that attaches
- *     the cached Bearer; it kicks off a background mint on first use so the
- *     cache warms within one round-trip.
+ * This module is the single source of truth for:
+ *   - the settings shapes (`NavAidSettings` etc. — the platform app
+ *     re-exports them from `src/lib/map/nav-aid-settings.ts`),
+ *   - sanitization of the stored JSONB (never trust row contents: the
+ *     table has no CHECK constraints, so clamp + whitelist everything),
+ *   - the static application of those settings to a generated style.
  *
- * NOTE: the public mint route `POST /v1/mint/tile-token` (the sibling of the
- * existing `/v1/mint/offline-token`) must be present on the `api.chrt.co`
- * edge worker for this path to serve. Until it lands, mints fail with a
- * network/HTTP error surfaced through `getToken()`.
+ * Safety invariants honored here:
+ *   - `allowOverlap: false` (the default) leaves the generator's S-52
+ *     collision discipline untouched — safety-critical classes keep their
+ *     forced `*-allow-overlap: true`. `allowOverlap: true` only ever ADDS
+ *     visibility, never removes it.
+ *   - Sanitization can only narrow values into UI-legal ranges; unknown
+ *     fields are dropped, so a hand-crafted row can't smuggle arbitrary
+ *     style JSON into served output.
  */
 
-/** Default chart region — the one consolidated PMTiles served per region. */
-declare const DEFAULT_TILE_REGION = "NOAA_ENC";
-/** Default tile-worker origin. Override via `ChrtConfig.tileBaseUrl`. */
-declare const DEFAULT_TILE_BASE_URL = "https://tiles.chrt.co";
-/** Full token response from the mint endpoint. */
-interface TileTokenResponse {
-    /** ES256-signed JWT; do not log. */
-    token: string;
-    /** Unix seconds (matches JWT `exp`). */
-    expiresAt: number;
-    /** Key id used to sign (matches JWT header `kid`). */
-    kid: string;
-    /** Build id/tag pinned into the JWT — the tile-worker cache key. */
-    buildTag: string;
-    /** Echo of the region the token is scoped to. */
-    region: string;
-}
-/** Typed error codes the mint flow surfaces; callers switch on `.code`. */
-type TileTokenErrorCode = "invalid_api_key" | "feature_flag_disabled" | "region_not_licensed" | "tile_quota_exceeded" | "region_not_available" | "network_error" | "unexpected_response";
-declare class TileTokenError extends Error {
-    readonly code: TileTokenErrorCode;
-    readonly status?: number;
-    constructor(code: TileTokenErrorCode, message: string, status?: number);
-}
-/** MapLibre / Mapbox GL `transformRequest` return shape. */
-interface TransformedRequest {
-    url: string;
-    headers?: Record<string, string>;
-}
-/**
- * Instance-scoped tile-token manager. One per `Chrt` client so multiple
- * clients (e.g. different API keys) never share a cache.
- */
-declare class TileAuth {
-    private readonly http;
-    private readonly cache;
-    private readonly pending;
-    private readonly defaultRegion;
-    private readonly tileBaseUrl;
-    private lifecycleRegistered;
-    constructor(http: HttpClient, opts?: {
-        region?: string;
-        tileBaseUrl?: string;
-    });
-    /** Mint once via the HTTP client (POST `/mint/tile-token`, `x-api-key`). */
-    private mintOnce;
-    /** Mint with exponential backoff on network errors only. */
-    private mintWithRetry;
-    private scheduleRefresh;
-    private refreshInBackground;
-    private store;
+interface NavAidSettings {
+    buoysVisible: boolean;
+    beaconsVisible: boolean;
+    lightsVisible: boolean;
+    /** null = S-52 default, 0 = always show, 1-14 = custom minzoom */
+    scaminOverride: number | null;
+    /** Icon size multiplier (0.2–2.0) */
+    iconScale: number;
+    /** When true, icon-size is a flat value (no zoom interpolation) */
+    iconSizeLocked: boolean;
+    /** Allow icons to overlap at all zooms */
+    allowOverlap: boolean;
+    /** Show sector light arcs on map */
+    showSectorArcs: boolean;
+    /** Show fog signal icons */
+    fogSignalsVisible: boolean;
+    /** Show radar transponder / radar station icons */
+    radarVisible: boolean;
+}
+interface LabelSettings {
+    navAidLabelsVisible: boolean;
+    landLabelsVisible: boolean;
+    structureLabelsVisible: boolean;
+    /** Show depth contour (DEPCNT) value labels */
+    depthContoursVisible: boolean;
+    /** Show full OBJNAM instead of mariner shorthand for nav aids */
+    navAidFullNames: boolean;
+    /** null = use default minzoom, 0-14 = custom override */
+    minzoomOverride: number | null;
+    /** Text size multiplier (0.5–2.0) */
+    textScale: number;
+    /** Allow text labels to overlap */
+    allowOverlap: boolean;
+}
+interface SoundingSettings {
+    visible: boolean;
+    minzoomOverride: number | null;
+    textScale: number;
+    allowOverlap: boolean;
+    /** Show depth units suffix */
+    showUnits: boolean;
     /**
-     * Fetch (or reuse a cached) tile token for `region`. Concurrent callers for
-     * the same region await the same in-flight mint.
+     * S-52 §SOUNDG02 safety contour (metres). Soundings shoaler than this
+     * render in high-contrast SNDG2; deeper soundings render in muted SNDG1.
+     * Default 10 m.
      */
-    getToken(region?: string): Promise<TileTokenResponse>;
-    /** Synchronous cache peek — null if absent or within the stale grace window. */
-    peek(region?: string): string | null;
+    safetyContour: number;
+    /** Numeral weight; semibold reads sharper at small sizes on screen. */
+    fontWeight: "regular" | "semibold";
+    /** When false, all soundings render in a single shade (SNDG2). */
+    twoShade: boolean;
+}
+interface WaterBodySettings {
+    seaAreasVisible: boolean;
+    lakesVisible: boolean;
+    riversVisible: boolean;
+    canalsVisible: boolean;
+    minzoomOverride: number | null;
+    textScale: number;
+    allowOverlap: boolean;
+    /** Uppercase major sea area names (raster chart style) */
+    uppercaseSeaAreas: boolean;
+}
+declare const DEFAULT_NAV_AID_SETTINGS: NavAidSettings;
+declare const DEFAULT_LABEL_SETTINGS: LabelSettings;
+declare const DEFAULT_SOUNDING_SETTINGS: SoundingSettings;
+declare const DEFAULT_WATER_BODY_SETTINGS: WaterBodySettings;
+/** Nav-aid layer groups keyed by toggle name */
+declare const NAV_AID_LAYER_GROUPS: Record<string, string[]>;
+/** All nav-aid layer names (flat set for quick lookups) */
+declare const ALL_NAV_AID_LAYERS: Set<string>;
+/** Label layer groups keyed by toggle name (soundings moved to own panel) */
+declare const LABEL_LAYER_GROUPS: Record<string, string[]>;
+/** Sounding layers */
+declare const SOUNDING_LAYERS: string[];
+/** Water body layer groups keyed by toggle name */
+declare const WATER_BODY_LAYER_GROUPS: Record<string, string[]>;
+/** All water body layer names (flat set for quick lookups) */
+declare const ALL_WATER_BODY_LAYERS: Set<string>;
+/** Check if a nav-aid layer is visible given current settings */
+declare function isNavAidLayerVisible(layerName: string, settings: NavAidSettings): boolean;
+/** Check if a label layer is visible given current settings */
+declare function isLabelLayerVisible(layerName: string, settings: LabelSettings): boolean;
+/** Check if a sounding layer is visible */
+declare function isSoundingLayerVisible(settings: SoundingSettings): boolean;
+/** Check if a water body layer is visible given current settings */
+declare function isWaterBodyLayerVisible(layerName: string, settings: WaterBodySettings): boolean;
+interface CustomStyleConfig {
+    /** Palettes the customer allows their end users to request. Never empty. */
+    enabled_color_tables: ColorTableName[];
+    /** Palette served when the request omits `theme` (or requests a disabled one). */
+    default_color_table: ColorTableName;
     /**
-     * Produce a MapLibre / Mapbox GL `transformRequest`. Attaches
-     * `Authorization: Bearer <jwt>` only to CHRT tile URLs; style, sprite, and
-     * glyph URLs pass through untouched (never leak the token to third-party
-     * CDNs). Kicks off a background mint immediately so the cache warms within
-     * one round-trip; the first tile or two may go unauthenticated and be
-     * retried by the renderer.
+     * S-52 display mode: BASE ⊂ STANDARD ⊂ ALL. Carried through sanitization
+     * but NOT applied as a render filter in v1: the platform's vector map
+     * renders every class regardless of mode (the mode only filters the /map
+     * sidebar list), and several CHRT-structural classes (e.g. SEAARE, the
+     * cross-band base water fill) sit in category OTHER — filtering them out
+     * under the DB-default `STANDARD` would serve charts with the base water
+     * missing. Render-filtering by display category is a documented follow-up
+     * that needs its own category audit first.
      */
-    transformRequest(region?: string): (url: string) => TransformedRequest | undefined;
-    /** Clear the cached token + timer for a region. */
-    invalidate(region?: string): void;
-    /**
-     * Browser-only defense against `setTimeout` freezing while a tab is
-     * suspended (laptop sleep, mobile background, bfcache restore): proactively
-     * re-mint near-expiry entries on wake. Inert under SSR / Node / Deno.
-     */
-    private registerLifecycleHandlers;
+    display_mode: DisplayMode;
+    nav_aid_settings: NavAidSettings;
+    label_settings: LabelSettings;
+    sounding_settings: SoundingSettings;
+    water_body_settings: WaterBodySettings;
+    /** Whitelist of S-57 classes to render; null = all. */
+    visible_layers: string[] | null;
+}
+declare const DEFAULT_CUSTOM_STYLE_CONFIG: CustomStyleConfig;
+/**
+ * Sanitize a raw `map_styles` row (or any untrusted JSON) into a fully
+ * populated `CustomStyleConfig`. Unknown fields are dropped, enums are
+ * validated, numerics are clamped to the UI's legal ranges, and missing
+ * fields fall back to the platform defaults. Never throws.
+ */
+declare function sanitizeCustomStyleConfig(raw: unknown): CustomStyleConfig;
+/** Normalize a `?theme=` value to a colour table name; null for anything else. */
+declare function normalizeTheme(raw: string | null | undefined): ColorTableName | null;
+interface ResolvedTheme {
+    palette: ColorTableName;
+    /** True when the requested theme was disabled by the custom style and the
+     *  default palette was served instead. */
+    themeFellBack: boolean;
+}
+/**
+ * Pick the palette to serve. A requested theme that the custom style has
+ * disabled falls back to the style's default palette — an end user of a
+ * CHRT customer should get a chart, not a dead map, when the customer
+ * narrowed the palette set.
+ */
+declare function resolveCustomTheme(config: CustomStyleConfig, requested: ColorTableName | null): ResolvedTheme;
+/**
+ * Scale the numeric outputs of a size-valued expression. Handles plain
+ * numbers plus the output positions of `interpolate`, `step`, `case`, and
+ * `match` expressions; anything else is returned unchanged (defensive: a
+ * mis-scaled comparison operand would corrupt the expression, so only
+ * positions that are guaranteed to be size outputs are touched).
+ */
+declare function scaleSizeValue(value: unknown, factor: number): unknown;
+/**
+ * Apply a sanitized custom-style config to a generated style, statically.
+ *
+ * Mirrors the platform map's runtime settings semantics (visibility per
+ * class group, icon/text scale, allow-overlap, minzoom overrides, SEAARE
+ * uppercase, layer whitelist) as build-time layer transforms. Fields with
+ * no static vector-tile equivalent (`navAidFullNames`, `showUnits`,
+ * `iconSizeLocked`, `showSectorArcs` need per-feature preprocessing) and
+ * `display_mode` (see `CustomStyleConfig.display_mode`) are not applied
+ * here — documented in the Style API docs.
+ *
+ * Sounding *rendering* settings (safetyContour / twoShade / fontWeight)
+ * are generator options, not layer transforms — `generateCustomStyle()`
+ * threads them into `generateStyle()`.
+ *
+ * The input style is mutated in place and returned (callers generate a
+ * fresh style per request; a defensive deep-clone would be pure waste on
+ * a ~700-layer document).
+ */
+declare function applyCustomStyleSettings(style: MapboxStyle, config: CustomStyleConfig): MapboxStyle;
+interface GenerateCustomStyleOptions extends StyleGeneratorOptions {
+    /** Requested palette (already normalized); null/undefined = style default. */
+    theme?: ColorTableName | null;
+}
+interface GeneratedCustomStyle {
+    style: MapboxStyle;
+    palette: ColorTableName;
+    themeFellBack: boolean;
 }
+/**
+ * Generate the S-52 style for a customer's custom-style config: resolve the
+ * palette against the config's enabled set, thread the sounding rendering
+ * settings into the generator, then apply the static layer transforms.
+ */
+declare function generateCustomStyle(config: CustomStyleConfig, opts?: GenerateCustomStyleOptions): GeneratedCustomStyle;
 
 /**
  * Generic async auto-pagination generator.
@@ -1602,6 +2393,12 @@ declare class Chrt {
      * requires `manifestPath`.
      */
     readonly offline: OfflineEndpoint;
+    /**
+     * CHRTinteract — click-to-inspect: `attach(map)` for wired popups/events,
+     * `inspect(feature)` for headless decode. Included with the Dev plan and
+     * above; enforced server-side at attach/inspect time.
+     */
+    readonly interact: InteractClient;
     private featuresEp;
     private queryEp;
     private http;
@@ -1652,14 +2449,36 @@ declare class Chrt {
      * });
      *
      * @remarks S-101 portrayal is on the roadmap; today `style()` emits S-52.
+     * Generated locally, so it never applies a key-bound CHRTstyle custom
+     * style — use {@link styleUrl} / {@link fetchStyle} (the served Style API)
+     * for that.
      */
     style(opts?: ChrtStyleOptions): MapboxStyle;
     /**
-     * @deprecated CHRT serves no remote `style.json`. Use {@link style} to get a
-     * MapLibre style object instead. Throws to avoid silently pointing a map at a
-     * dead URL.
+     * URL of the served S-52 style — the CHRTstyle Style API at
+     * `tiles.chrt.co/v1/styles/{region}/style.json`. Unlike {@link style}
+     * (generated locally), the served document honors the API key's bound
+     * CHRTstyle custom style: palettes, layer visibility, label/icon scale,
+     * and the rest of the platform's Map Styles settings, applied server-side
+     * and tier-gated (custom styles are Dev+; Free keys get the default
+     * themes). Async because it pre-mints the tile token, so the style
+     * request is guaranteed to carry auth via `transformRequest()`.
+     *
+     * @example
+     * const map = new maplibregl.Map({
+     *   container: 'map',
+     *   style: await chrt.styleUrl({ theme: 'day' }),
+     *   transformRequest: chrt.transformRequest(),
+     * });
+     */
+    styleUrl(opts?: StyleUrlOptions): Promise<string>;
+    /**
+     * Fetch the served S-52 style (see {@link styleUrl}) as a MapLibre style
+     * object — inspect or mutate it before handing it to the map.
+     * `chrt.style()` remains the local generator that needs no network
+     * round-trip (and therefore applies no custom style).
      */
-    styleUrl(): never;
+    fetchStyle(opts?: FetchStyleOptions): Promise<MapLibreStyle>;
     /**
      * Returns a `transformRequest` for Mapbox GL JS / MapLibre GL JS that mints a
      * short-lived tile JWT from your API key and attaches it as
@@ -1684,4 +2503,4 @@ declare class Chrt {
     warmTiles(region?: string): Promise<void>;
 }
 
-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, type ChrtStyleOptions, ColorTableName, type CoverageOptions, type CoverageResponse, type CoverageSource, DEFAULT_REGION, DEFAULT_TILE_BASE_URL, DEFAULT_TILE_REGION, 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, TileAuth, type TileGroup, type TileGroupsResponse, TileTokenError, type TileTokenErrorCode, type TileTokenResponse, type TransformRequest, type TransformedRequest, 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 };
+export { ALL_NAV_AID_LAYERS, ALL_WATER_BODY_LAYERS, AREA_QUERY_LAYERS, type AreaInspectResult, type AtlasStyle, type AttachOptions, BAND_DRAW_ORDER, BAND_PRIORITY_RANGES, type BBox, BRIDGE_QUERY_LAYERS, BUILD_MAXZOOM, BUILD_MINZOOM, type BandCode, type BandPriorityRange, type BridgeInspectResult, type BuildOfflineStyleOptions, type BuildSourcesOptions, CHART_BAND_CODES, CHART_CASCADE_CODES, CHART_SECTIONS, type CellDeletedEvent, type CellDetail, type CellEventData, type CellNewEvent, type CellUpdatedData, type CellUpdatedEvent, type CellsOptions, type CellsResponse, type ChartSection, Chrt, type ChrtConfig, ChrtError, type ChrtStyleOptions, type ChrtStyleTheme, ColorTableName, type CoverageOptions, type CoverageResponse, type CoverageSource, type CustomStyleConfig, DEFAULT_CUSTOM_STYLE_CONFIG, DEFAULT_LABEL_SETTINGS, DEFAULT_NAV_AID_SETTINGS, DEFAULT_REGION, DEFAULT_SOUNDING_SETTINGS, DEFAULT_TILE_BASE_URL, DEFAULT_TILE_REGION, DEFAULT_WATER_BODY_SETTINGS, type DecodedAreaFeature, type DecodedBridge, type DecodedNavAid, type DecodedProperty, type DisplayCategory, type DisplayMode, type FeatureCollection, type FeaturesOptions, type FetchStyleOptions, FileSystemAdapter, type FlashPattern, type FlashPhase, type GenerateCustomStyleOptions, type GeneratedCustomStyle, type GeoJsonFeature, type GeoJsonGeometry, type GeomType, type InspectEnrichment, type InspectEventContext, type InspectNotice, type InspectOptions, type InspectResult, type InspectableFeature, InteractClient, type InteractEntitlement, InteractError, type InteractErrorCode, type InteractHandle, type InteractMapLike, type InteractMapMouseEvent, LABELED_LAYERS, LABEL_BEHAVIOR, LABEL_LAYER_GROUPS, LABEL_PRIORITY, type LabelBehavior, type LabelConfigOptions, type LabelLayerConfig, type LabelSettings, type LookupEntry, type MapLibreStyle, type MapboxStyle, type MapboxVectorSource, NAUTICAL_SYMBOLS, NAV_AID_LAYER_GROUPS, NAV_AID_QUERY_LAYERS, NON_SOLAS_DISCLAIMER, NON_SOLAS_DISCLAIMER_SHORT, type NauticalCategory, type NauticalSymbol, type NavAidInspectResult, type NavAidSettings, type OfflineBundleResponse, type OfflineDownloadOptions, type OfflineDownloadProgress, type OfflineDownloadResult, OfflineError, type OfflineErrorCode, type OfflineFetchStyleOptions, type OfflineHeartbeatOptions, type OfflineRegionSummary, type OfflineRemoveOptions, OfflineStyleError, type OfflineStylePlatform, type OfflineStyleResponse, type PmtilesVectorSource, type QueryOptions, type ResolvedStyle, type ResolvedTheme, 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, SOUNDING_LAYERS, SYMBOL_GROUPS, SYMBOL_MAP, type ScaleBand, type SectorArcFeature, type SectorArcFeatureCollection, type SectorInfo, type SoundingSettings, type SourceMode, type StyleGeneratorOptions, type StyleLayer, type StyleUrlOptions, type SymbolGroup, TileAuth, type TileGroup, type TileGroupsResponse, TileTokenError, type TileTokenErrorCode, type TileTokenResponse, type TransformRequest, type TransformedRequest, type VectorSourceSpec, WATER_BODY_LAYER_GROUPS, type WaterBodySettings, type WebhookEvent, type WebhookEventType, type WebhookPayload, applyColorTheme, applyCustomStyleSettings, bandFilterExpression, buildFlashPattern, buildLabelLayer, buildLayersForClass, buildOfflineStyle, buildSectorArcGeoJSON, buildSectorArcsFC, buildSectorsFromFeatures, buildSources, combineWithBandFilter, daymarkColor, decimateFeatures, decodeAreaFeatureProps, decodeBridgeProps, decodeNavAidProps, depareColor, depareFillExpression, deriveMarinerName, extractNavAidDesignation, generateCustomStyle, generateSpriteManifest, generateSpriteSheet, generateStyle, generateStyleJSON, getAvailableLineSymbols, getAvailablePatterns, getAvailablePointSymbols, getCollisionSettings, getDrawPriority, getGridSizeForZoom, getIconExpression, getLabelBehavior, getLabelConfig, getLabelPriority, getLookupEntry, getMaxCellsForZoom, getOrderedClasses, getS52SvgString, getS52SymbolStats, getStyleStats, getSymbolSvgString, getThemedS52Svg, getTopmarkMeaning, hazardColor, hazardFillExpression, isLabelLayerVisible, isNavAidLayer, isNavAidLayerVisible, isSoundingLayerVisible, isVisibleInMode, isWaterBodyLayerVisible, labelSortKey, lateralColor, lateralFillExpression, lightColor, lightFillExpression, normalizeTheme, paginate, parseListCodes, parseWebhook, preprocessLights, preprocessNavAids, preprocessSoundings, preprocessWaterBodies, resolveCustomTheme, resolveStyle, sanitizeCustomStyleConfig, scaleSizeValue, scaminToMinZoom, withinBboxFilter, worldMinusBboxPolygon };