@chrtco/sdk 0.8.1 → 0.9.1

package/dist/index.d.cts

@@ -434,21 +434,172 @@ 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;
+    /** Symbol artwork family: "s52" (default) or "s101" (official S-101
+     *  Portrayal Catalogue symbols). Load the matching images client-side
+     *  via `loadS101SymbolImages` / `loadChrtSymbolImages` from
+     *  `@chrtco/sdk/atlas/browser`. */
+    symbols?: "s52" | "s101" | "chrt";
+}
+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;
+    /**
+     * 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>;
     /**
-     * @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.
+     * 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 +725,775 @@ 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;
+    };
+    /** Present on real GL JS maps; lets `inspectAll()` accept screen points. */
+    unproject?(point: [number, number]): {
+        lng: number;
+        lat: number;
+    };
+}
+/** The subset of a GL JS MapMouseEvent that attach() consumes. */
+interface InteractMapMouseEvent {
+    point: {
+        x: number;
+        y: number;
+    };
+    lngLat: {
+        lng: number;
+        lat: number;
+    };
+}
+/**
+ * A click location for candidate decoding: screen pixels always, geographic
+ * coordinates when resolvable. `InteractMapMouseEvent` is assignable.
+ */
+interface ClickAnchor {
+    point: {
+        x: number;
+        y: number;
+    };
+    lngLat: {
+        lng: number;
+        lat: number;
+    } | null;
+}
+/** 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;
+}
+/**
+ * What kind of click target a candidate is. Drives the primary priority
+ * band (point > line > area) — distinct from `kind`, which describes the
+ * decode shape (a WRECKS point is `kind: "area"` decode-wise but a "point"
+ * click target).
+ */
+type InspectTargetClass = "point" | "line" | "area";
+/**
+ * One deduplicated feature under a click, ready for a disambiguation list.
+ * Plain serializable data — resolve the full {@link InspectResult} (with
+ * the v1 co-located merge and optional enrichment) by selecting it via
+ * `attach()`'s candidate flow or `inspectAll().select()`.
+ */
+interface InspectCandidate {
+    /** Raw S-57 object class, e.g. "BOYLAT". */
+    layer: string;
+    /** Style-layer id the feature was rendered by, e.g. "enc-BOYLAT". */
+    layerId: string;
+    /** Decode shape this candidate resolves to on selection. */
+    kind: "navaid" | "bridge" | "area";
+    /** Click-target class driving the priority band. */
+    targetClass: InspectTargetClass;
+    /**
+     * Priority rank (lower = higher priority): `band * 1000 + classRank`,
+     * band 0/1/2 for point/line/area targets.
+     */
+    rank: number;
+    /** Display title (same derivation as the selected InspectResult's). */
+    title: string;
+    /** Human-readable object class, e.g. "Lateral Buoy". */
+    objectClass: string;
+    /** [lng, lat] when the feature carries Point geometry. */
+    coordinates: [number, number] | null;
+    /**
+     * Source-cell-scoped S-57 identity the dedupe folded on
+     * (`{cell}|{LNAM}`), or null when the tiles carry no identity attrs
+     * (such features are never folded).
+     */
+    identity: string | null;
+    /**
+     * Raw S-57 classes of co-located child objects collapsed into this
+     * candidate (e.g. ["LIGHTS", "TOPMAR"] on a lit buoy). Selecting the
+     * candidate merges their attributes via the v1 pipeline.
+     */
+    collapsedChildren: string[];
+    /** The underlying rendered feature (pass to `inspect()` for headless decode). */
+    feature: InspectableFeature;
+    /** Non-SOLAS disclaimer + attribution + data currency. Always present. */
+    notice: InspectNotice;
+}
+/** Options shared by every candidate-collecting entry point. */
+interface CandidateQueryOptions {
+    /**
+     * Pixel radius around the click for point/line targets (a finger- and
+     * line-width-friendly hit box). Area (polygon) candidates always require
+     * the exact click point to fall inside them. Default: 8. Pass 0 to query
+     * the exact point only.
+     */
+    tolerance?: number;
+    /**
+     * Fold co-located S-57 child objects (LIGHTS, TOPMAR, FOGSIG, RTPBCN,
+     * DAYMAR) into their parent buoy/beacon candidate. Default: true.
+     */
+    collapseChildren?: 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[];
+}
+/** Context passed to `onCandidates` when a click hits several features. */
+interface CandidatesEventContext {
+    /** Click location. */
+    lngLat: {
+        lng: number;
+        lat: number;
+    };
+    /** Click location in screen pixels. */
+    point: {
+        x: number;
+        y: number;
+    };
+    /**
+     * Resolve one candidate to its full InspectResult (v1 co-located merge +
+     * the attach-level `enrich` setting). Also drives the built-in popup and
+     * `onInspect`, so custom candidate UIs stay one line.
+     */
+    select: (candidate: InspectCandidate) => Promise<InspectResult>;
+}
+/** Return shape of `chrt.interact.inspectAll()`. */
+interface InspectCandidateSet {
+    /** Deduplicated candidates under the point, highest priority first. */
+    candidates: InspectCandidate[];
+    /**
+     * Resolve one candidate to its full InspectResult (v1 co-located
+     * attribute merge; `enrich: true` adds source-cell provenance — metered).
+     */
+    select(candidate: InspectCandidate, opts?: {
+        enrich?: boolean;
+        signal?: AbortSignal;
+    }): Promise<InspectResult>;
+}
+interface AttachOptions extends CandidateQueryOptions {
+    /**
+     * 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 SEVERAL features (after dedupe/collapse),
+     * with the priority-ordered candidates — render your own disambiguation
+     * UI and resolve a choice via `ctx.select(candidate)`. When provided,
+     * multi-hit clicks fire this instead of auto-inspecting the top
+     * candidate. Single hits skip straight to `onInspect` / the popup.
+     */
+    onCandidates?: (candidates: InspectCandidate[], ctx: CandidatesEventContext) => 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) — the result
+     * card, and a candidate list when a click hits several features.
+     * Default: true when neither `onInspect` nor `onCandidates` is provided,
+     * false otherwise.
+     */
+    popup?: boolean;
+    /**
+     * Auto-enrich every inspected result through the features API (metered —
+     * counts against the key's `featureCalls` quota). Default: false.
+     */
+    enrich?: boolean;
+}
+/** 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;
+    });
+}
+
+/**
+ * Multi-feature candidate collection for CHRTinteract (interact v1.1).
+ *
+ * A chart click rarely hits exactly one feature: a buoy sits on a channel
+ * over a depth area, dense harbors stack nav aids over regulated areas over
+ * DEPARE. This module turns "everything under (or near) the click" into a
+ * deduplicated, priority-ordered candidate list:
+ *
+ *   1. COLLECT — queryRenderedFeatures over the interact layer sets with a
+ *      pixel tolerance box for point/line targets; polygon (area) targets
+ *      are kept only when they contain the exact click point.
+ *   2. DEDUPE — the same S-57 object comes back once per tile it was split
+ *      into and once per style layer that rendered it. Features are folded
+ *      by source-cell-scoped S-57 identity: LNAM (the AGEN+FIDN+FIDS long
+ *      name — verified present on 100% of features in served CHRT tiles),
+ *      falling back to the AGEN/FIDN/FIDS composite.
+ *   3. COLLAPSE — S-57 child objects (LIGHTS, TOPMAR, FOGSIG, RTPBCN,
+ *      DAYMAR) co-located with a parent buoy/beacon in the same hit set are
+ *      folded into the parent candidate; selecting the parent runs the v1
+ *      co-located merge so the light/topmark attributes surface there. A
+ *      mariner reads a lit buoy as ONE aid, not three S-57 objects.
+ *   4. RANK — class priority: point targets > line targets > area targets,
+ *      with a within-band ladder kept value-coherent with the atlas label
+ *      ladder (`LABEL_PRIORITY` in atlas/labels.ts — the P4 collision
+ *      model). Area features NEVER preempt the buoy above them, but they
+ *      always remain in the list, so open water resolves to its DEPARE.
+ *
+ * Everything here is pure and map-optional: `collectCandidates()` works on
+ * any InspectableFeature[]; `collectClickCandidates()` adds the
+ * queryRenderedFeatures wiring. Entitlement enforcement stays in
+ * `InteractClient` — these are building blocks, useless without CHRT tiles.
+ */
+
+/**
+ * Within-band class ladder — lower = higher priority. Value-coherent with
+ * the atlas label-collision ladder (`LABEL_PRIORITY`, atlas/labels.ts):
+ * classes present in both carry the SAME value, so "what places first on
+ * the chart" and "what lists first under a click" never invert. Documented
+ * exceptions live in {@link INSPECT_RANK_DEVIATIONS}; the coherence unit
+ * test (candidates.test.ts) enforces equal-unless-deviating.
+ *
+ * Rungs (mirroring the label ladder's tiers, extended for area classes the
+ * label ladder never ranks):
+ *
+ *   100 — safety-critical: lights, hazards (rocks, obstructions, wrecks),
+ *         overhead clearances
+ *   200 — nav-aid primaries: buoys, beacons, light vessels/floats
+ *   250 — nav-aid auxiliaries: fog signals, radar beacons, daymarks,
+ *         topmarks, radio stations
+ *   260 — bridges (interact-specific: preempt the water/contours below)
+ *   300 — depth field: contours
+ *   350 — caution / regulated / traffic areas
+ *   400 — structures: landmarks, moorings, shoreline constructions
+ *   410 — subsea infrastructure lines: cables, pipelines
+ *   420 — channel & berthing infrastructure
+ *   500 — ambient annotation: seabed, kelp, magnetic variation
+ *   610 — DEPARE: the canonical "what water is this" answer
+ *   640 — hydrographic context: rivers, canals, lakes, coastline
+ *   700 — land / ambient areas
+ */
+declare const INSPECT_CLASS_RANK: Record<string, number>;
+/** Rank for queried classes not in the ladder (mirrors DEFAULT_LABEL_PRIORITY). */
+declare const DEFAULT_INSPECT_CLASS_RANK = 450;
+/**
+ * Classes whose interact rank deliberately differs from the atlas
+ * LABEL_PRIORITY value, with why. The coherence test allows exactly these.
+ */
+declare const INSPECT_RANK_DEVIATIONS: Record<string, string>;
+/** Compose the candidate rank: primary target band, then class ladder. */
+declare function candidateRank(targetClass: InspectTargetClass, rawLayer: string): number;
+/**
+ * Source-cell-scoped S-57 identity for a rendered feature.
+ *
+ * CHRT tiles carry the GDAL S-57 feature-identity attributes end-to-end
+ * (verified against served prod tiles: LNAM/FIDN/FIDS/AGEN present on
+ * 100% of features): LNAM is the AGEN+FIDN+FIDS "long name" — the stable
+ * object identity that survives a feature being split across tile
+ * boundaries or rendered by several style layers. Scoped by `_cell_id`
+ * because the same real-world object legitimately appears in multiple
+ * source cells (band overlap) with distinct provenance.
+ *
+ * Returns null when the attributes are absent (never dedupe blind).
+ */
+declare function featureIdentity(feature: InspectableFeature): string | null;
+/**
+ * Resolve a candidate's click-target class: rendered geometry first (the
+ * truth for classes with point/line/area variants), style-layer suffix
+ * next, class default last (nav aids → point, everything else → area).
+ */
+declare function resolveTargetClass(layerId: string, feature: InspectableFeature): InspectTargetClass;
+/**
+ * Turn raw rendered features into the deduplicated, priority-ordered
+ * candidate list. Pure — usable on any queryRenderedFeatures result (or
+ * plain `{ layer, properties }` objects) without a map.
+ *
+ * Order in = render order (queryRenderedFeatures returns topmost first);
+ * the sort is stable, so equal-rank candidates keep that visual order.
+ */
+declare function collectCandidates(features: InspectableFeature[], opts?: Pick<CandidateQueryOptions, "collapseChildren">): InspectCandidate[];
+/** Default pixel tolerance around the click for point/line targets. */
+declare const DEFAULT_CLICK_TOLERANCE = 8;
+/**
+ * Collect every inspectable candidate under (or within `tolerance` px of)
+ * a click point: one tolerance-box query over the interact layer sets,
+ * plus an exact-point query that gates polygon candidates — an area
+ * feature is only offered when the click actually falls inside it, while
+ * points and lines get the forgiving hit box.
+ */
+declare function collectClickCandidates(map: InteractMapLike, point: {
+    x: number;
+    y: number;
+}, opts?: CandidateQueryOptions): InspectCandidate[];
+
+/**
+ * Map wiring for CHRTinteract — click → candidates → inspect().
+ *
+ * v1 was a faithful port of the first-party `/map` click pipeline
+ * (`src/hooks/use-map-renderer.tsx` in the platform repo): nav-aid point
+ * features → bridges → area features, taking the topmost hit. v1.1 keeps
+ * that decode intact but routes every click through the candidate
+ * collector (candidates.ts): all features under the click are deduped by
+ * S-57 identity and priority-ordered, `decodeClick` resolves the TOP
+ * candidate, and the attach handler in index.ts surfaces the rest for
+ * disambiguation.
+ *
+ * Attribute merging (S-57 encodes lights/fog/topmarks as separate child
+ * objects co-located with their parent buoy/beacon) — unchanged from v1:
+ *   - OBJNAM / COLOUR inherited from a co-located parent buoy/beacon
+ *   - CATFOG from a co-located FOGSIG
+ *   - RETRFL presence from a co-located RTPBCN
+ *   - TOPSHP from a co-located TOPMAR
+ *   - LITCHR / SIGPER / SIGGRP / LIGHT_COLOUR / CATLIT from the primary
+ *     co-located LIGHTS (preferring a non-sector light)
+ *   - all co-located LIGHTS combined into the sector list
+ *
+ * MapLibre / Mapbox GL is NOT imported — the map is consumed through the
+ * structural `InteractMapLike` interface, so `maplibre-gl` remains an
+ * optional peer dependency.
+ */
+
+/**
+ * Resolve ONE candidate to its full InspectResult at a click location:
+ * nav-aid classes run the co-located child-object merge, everything else
+ * decodes directly (bridges/areas anchor to the click point when the
+ * feature carries no Point geometry). Exported for tests.
+ */
+declare function decodeCandidate(map: InteractMapLike, candidate: InspectCandidate, at: ClickAnchor, opts?: AttachOptions): InspectResult;
+
+/**
+ * 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>;
+    /**
+     * Collect EVERY inspectable feature under a point on a CHRT map —
+     * deduplicated across tile boundaries by S-57 identity (`LNAM`) and
+     * ordered by class priority (point targets > lines > areas, safety
+     * classes first within each band). Area features never preempt the buoy
+     * on top of them but always stay selectable: a click on open water
+     * resolves to its DEPARE.
+     *
+     * `point` is a screen pixel point (`e.point` from a map click) or
+     * `[lng, lat]`. Point/line targets are picked up within
+     * `opts.tolerance` px (default 8); polygon candidates require the exact
+     * point to fall inside them.
+     *
+     * The first call performs the server-side entitlement check.
+     *
+     * @example
+     * const { candidates, select } = await chrt.interact.inspectAll(map, e.point);
+     * const result = await select(candidates[0]); // full decode (+ merge)
+     */
+    inspectAll(map: InteractMapLike, point: {
+        x: number;
+        y: number;
+    } | [number, number], opts?: CandidateQueryOptions): Promise<InspectCandidateSet>;
+    /**
+     * 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 callbacks, the
+     * built-in minimal popup is shown (opt back in explicitly with
+     * `popup: true` to have both).
+     *
+     * A click that hits SEVERAL features (deduplicated by S-57 identity)
+     * disambiguates instead of silently taking the topmost:
+     *   - `onCandidates` provided → it receives the priority-ordered list;
+     *     resolve a choice with `ctx.select(candidate)`.
+     *   - built-in popup → shows a candidate list; picking a row opens the
+     *     result card.
+     *   - `onInspect` only → the top candidate is inspected immediately, and
+     *     clicking the SAME spot again cycles to the next candidate — so an
+     *     area feature under a buoy is reachable with a second click.
+     *
+     * @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 +1679,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;
 /**
@@ -1027,59 +2013,6 @@ declare const S101_SYMBOL_GROUPS: {
 
 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
@@ -1205,24 +2138,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>;
 /**
@@ -1356,6 +2304,15 @@ interface StyleGeneratorOptions extends BuildSourcesOptions {
      * round so the rendered numbers match. Default "meters".
      */
     depthUnits?: "meters" | "feet";
+    /**
+     * Which symbol artwork the style references. "s52" (default) uses the
+     * PresLib-derived S-52 set; "s101" rewrites icon references to the
+     * official S-101 Portrayal Catalogue symbols (s101: image namespace)
+     * where a counterpart exists — see s101-style.ts. "chrt" applies the
+     * CHRT house ATON/LIGHTS glyphs with colour-true tinting — see
+     * chrt-style.ts. Selection logic differences are documented per module.
+     */
+    symbolSet?: "s52" | "s101" | "chrt";
     /**
      * S-52 §SOUNDG02 — soundings shoaler than this depth (metres) render in
      * the high-contrast color; deeper soundings render in the muted color.
@@ -1385,109 +2342,355 @@ declare function getStyleStats(style: MapboxStyle): {
     objectClasses: Set<string>;
 };
 
+declare const S101_SOURCE_COMMIT = "05063500e898544c90078ab78a61efc72b7e62f3";
+
 /**
- * Tile authentication for the `tiles.chrt.co` PMTiles path.
+ * S-101 symbol-set support (portrayal-excellence 7c, first slice).
  *
- * 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.
+ * The vendored official S-101 Portrayal Catalogue symbols (see
+ * `assets/s101/PROVENANCE.md`) are registered on the map under the
+ * `s101:` image namespace so they can coexist with the S-52 set. A style
+ * document is switched to the S-101 symbol set by rewriting every
+ * icon-image reference whose symbol has an official S-101 counterpart —
+ * selection logic (the S-52 lookup expressions) is unchanged, only the
+ * artwork swaps. That is deliberate and documented: the S-101 rule engine
+ * (Lua rules in the PC's `Rules/`) is the later 7c phase; the official
+ * SVGs themselves are exact today.
  *
- * 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.
+ * Colour theming resolves through the OFFICIAL S-101 day/dusk/night
+ * profiles (from the PC's {day,dusk,night}SvgStyle.css), not CHRT's S-52
+ * tables — the S-101 style is spec-true end to end at the symbol level.
+ */
+
+/** MapLibre image-id namespace for the S-101 symbol set. */
+declare const S101_ICON_PREFIX = "s101:";
+/** All vendored S-101 symbol names (unprefixed). */
+declare const S101_SYMBOL_NAMES: ReadonlySet<string>;
+/** Resolve an S-101 colour token via the official profile for `table`. */
+declare function resolveS101Color(token: string, table?: ColorTableName): string;
+/**
+ * Get an S-101 symbol SVG with its colour tokens resolved through the
+ * official S-101 profile. Returns null for unknown symbols.
+ */
+declare function getThemedS101Svg(symbolName: string, table?: ColorTableName): string | null;
+/**
+ * Switch a generated style document to the S-101 symbol set. Symbol names
+ * without an official S-101 counterpart keep their S-52 image (both sets
+ * are loaded by `loadChartSymbolImages`), so coverage can only grow as the
+ * PC adds symbols. Returns the same style object (mutated), for chaining.
+ */
+declare function applyS101SymbolSet(style: MapboxStyle): MapboxStyle;
+
+/**
+ * CHRT house ATON/LIGHTS symbol set (portrayal-excellence 7d, ATON slice).
  *
- * 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()`.
+ * Design intent (Anthony's brief): clear, simplified silhouettes;
+ * colour-true marks — a green buoy IS green, a red buoy IS red, exactly
+ * as encoded in the feature's COLOUR attribute; sound-capable aids show a
+ * sound badge, radar-capable aids show a radar badge.
+ *
+ * Mechanics:
+ *  - Tintable bodies (lateral/special buoys, beacons, daymarks, the light
+ *    flare) ship as single-colour SDF glyphs; a layer-level `icon-color`
+ *    expression tints them from the FIRST listed COLOUR code (the dominant
+ *    band per S-57 encoding). Region conventions fall out of the data —
+ *    nothing here hardcodes IALA A/B.
+ *  - Identity-coloured marks (cardinals, isolated danger, safe water) are
+ *    fixed-palette glyphs: their colour scheme is invariant under IALA and
+ *    single-tint would destroy the meaning. MapLibre ignores `icon-color`
+ *    for non-SDF images, so both kinds coexist in one layer.
+ *  - Capability badges ride the existing child-symbol mechanics: FOGSIG
+ *    features render the sound badge, RTPBCN/RDOSTA the radar badge, at
+ *    their S-52 child offsets beside the parent aid.
+ *
+ * The house palette below is a v1 placeholder tuned for legibility against
+ * CHRT's water fills — the 7d design pass (Anthony + design) owns the
+ * final values. Naming/pricing of the house style is an OPEN decision
+ * (see .chrt/plans/chrt-portrayal-excellence.md P7d); nothing here touches
+ * pricing or entitlements.
  */
 
-/** 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>;
-}
+declare const CHRT_ICON_PREFIX = "chrt:";
+/** Glyphs registered as SDF (tintable via icon-color). */
+declare const CHRT_SDF_GLYPHS: ReadonlySet<string>;
+/** All house glyph names. */
+declare const CHRT_GLYPH_NAMES: ReadonlySet<string>;
 /**
- * Instance-scoped tile-token manager. One per `Chrt` client so multiple
- * clients (e.g. different API keys) never share a cache.
+ * House ATON palette — S-57 COLOUR code → hex. v1 placeholder values
+ * (see module header); chosen for contrast on the CHRT day water ramp.
  */
-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;
+declare const CHRT_ATON_COLORS: Record<string, string>;
+/** First-listed-colour-wins tint expression for SDF bodies. */
+declare function chrtAtonTintExpression(): unknown[];
+/** Lights tint: exact colour (incl. blue/orange — the house style renders
+ *  the encoded colour, unlike the S-52 three-bucket flares); colourless
+ *  lights read as white with the dark halo carrying contrast. */
+declare function chrtLightTintExpression(): unknown[];
+/**
+ * Switch a generated style document to the CHRT house symbol set: rewrite
+ * the ATON/LIGHTS icon expressions and inject the colour-true tint on
+ * tintable layers. Returns the same style object (mutated).
+ */
+declare function applyChrtSymbolSet(style: MapboxStyle): MapboxStyle;
+
+/**
+ * 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 = 0;
+declare const BUILD_MAXZOOM = 14;
+
+/**
+ * CHRTstyle custom styles — the customer-facing map_styles config applied
+ * on top of the generated S-52 style.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+
+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;
     /**
-     * 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 §SOUNDG02 safety contour (metres). Soundings shoaler than this
+     * render in high-contrast SNDG2; deeper soundings render in muted SNDG1.
+     * Default 10 m.
      */
-    transformRequest(region?: string): (url: string) => TransformedRequest | undefined;
-    /** Clear the cached token + timer for a region. */
-    invalidate(region?: string): void;
+    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;
     /**
-     * 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.
+     * 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.
      */
-    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 +2805,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;
@@ -1651,15 +2860,38 @@ declare class Chrt {
      *   transformRequest: chrt.transformRequest(),
      * });
      *
-     * @remarks S-101 portrayal is on the roadmap; today `style()` emits S-52.
+     * @remarks Pass `symbolSet: "s101"` for the official S-101 Portrayal
+     * Catalogue symbol artwork (load images via `loadS101SymbolImages` from
+     * `@chrtco/sdk/atlas/browser`); default is the S-52 set. 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 +2916,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, CHRT_ATON_COLORS, CHRT_GLYPH_NAMES, CHRT_ICON_PREFIX, CHRT_SDF_GLYPHS, type CandidateQueryOptions, type CandidatesEventContext, type CellDeletedEvent, type CellDetail, type CellEventData, type CellNewEvent, type CellUpdatedData, type CellUpdatedEvent, type CellsOptions, type CellsResponse, type ChartSection, Chrt, type ChrtConfig, ChrtError, type ChrtStyleOptions, type ChrtStyleTheme, type ClickAnchor, ColorTableName, type CoverageOptions, type CoverageResponse, type CoverageSource, type CustomStyleConfig, DEFAULT_CLICK_TOLERANCE, DEFAULT_CUSTOM_STYLE_CONFIG, DEFAULT_INSPECT_CLASS_RANK, DEFAULT_LABEL_SETTINGS, DEFAULT_NAV_AID_SETTINGS, DEFAULT_REGION, DEFAULT_SOUNDING_SETTINGS, DEFAULT_TILE_BASE_URL, DEFAULT_TILE_REGION, DEFAULT_WATER_BODY_SETTINGS, type DecodedAreaFeature, type DecodedBridge, type DecodedNavAid, type DecodedProperty, type DisplayCategory, type DisplayMode, type FeatureCollection, type FeaturesOptions, type FetchStyleOptions, FileSystemAdapter, type FlashPattern, type FlashPhase, type GenerateCustomStyleOptions, type GeneratedCustomStyle, type GeoJsonFeature, type GeoJsonGeometry, type GeomType, INSPECT_CLASS_RANK, INSPECT_RANK_DEVIATIONS, type InspectCandidate, type InspectCandidateSet, type InspectEnrichment, type InspectEventContext, type InspectNotice, type InspectOptions, type InspectResult, type InspectTargetClass, type InspectableFeature, InteractClient, type InteractEntitlement, InteractError, type InteractErrorCode, type InteractHandle, type InteractMapLike, type InteractMapMouseEvent, LABELED_LAYERS, LABEL_BEHAVIOR, LABEL_LAYER_GROUPS, LABEL_PRIORITY, type LabelBehavior, type LabelConfigOptions, type LabelLayerConfig, type LabelSettings, type LookupEntry, type MapLibreStyle, type MapboxStyle, type MapboxVectorSource, NAUTICAL_SYMBOLS, NAV_AID_LAYER_GROUPS, NAV_AID_QUERY_LAYERS, NON_SOLAS_DISCLAIMER, NON_SOLAS_DISCLAIMER_SHORT, type NauticalCategory, type NauticalSymbol, type NavAidInspectResult, type NavAidSettings, type OfflineBundleResponse, type OfflineDownloadOptions, type OfflineDownloadProgress, type OfflineDownloadResult, OfflineError, type OfflineErrorCode, type OfflineFetchStyleOptions, type OfflineHeartbeatOptions, type OfflineRegionSummary, type OfflineRemoveOptions, OfflineStyleError, type OfflineStylePlatform, type OfflineStyleResponse, type PmtilesVectorSource, type QueryOptions, type ResolvedStyle, type ResolvedTheme, type RouteFeatureQueryOptions, type RouteFeatureQueryResponse, type RouteQueryOptions, type RouteQueryResponse, type S101Feature, S101_CHART_SECTIONS, S101_FEATURES, S101_ICON_PREFIX, S101_NEW_SYMBOLS, S101_SOURCE_COMMIT, S101_SYMBOL_GROUPS, S101_SYMBOL_NAMES, 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, applyChrtSymbolSet, applyColorTheme, applyCustomStyleSettings, applyS101SymbolSet, bandFilterExpression, buildFlashPattern, buildLabelLayer, buildLayersForClass, buildOfflineStyle, buildSectorArcGeoJSON, buildSectorArcsFC, buildSectorsFromFeatures, buildSources, candidateRank, chrtAtonTintExpression, chrtLightTintExpression, collectCandidates, collectClickCandidates, combineWithBandFilter, daymarkColor, decimateFeatures, decodeAreaFeatureProps, decodeBridgeProps, decodeCandidate, decodeNavAidProps, depareColor, depareFillExpression, deriveMarinerName, extractNavAidDesignation, featureIdentity, generateCustomStyle, generateSpriteManifest, generateSpriteSheet, generateStyle, generateStyleJSON, getAvailableLineSymbols, getAvailablePatterns, getAvailablePointSymbols, getCollisionSettings, getDrawPriority, getGridSizeForZoom, getIconExpression, getLabelBehavior, getLabelConfig, getLabelPriority, getLookupEntry, getMaxCellsForZoom, getOrderedClasses, getS52SvgString, getS52SymbolStats, getStyleStats, getSymbolSvgString, getThemedS101Svg, getThemedS52Svg, getTopmarkMeaning, hazardColor, hazardFillExpression, isLabelLayerVisible, isNavAidLayer, isNavAidLayerVisible, isSoundingLayerVisible, isVisibleInMode, isWaterBodyLayerVisible, labelSortKey, lateralColor, lateralFillExpression, lightColor, lightFillExpression, normalizeTheme, paginate, parseListCodes, parseWebhook, preprocessLights, preprocessNavAids, preprocessSoundings, preprocessWaterBodies, resolveCustomTheme, resolveS101Color, resolveStyle, resolveTargetClass, sanitizeCustomStyleConfig, scaleSizeValue, scaminToMinZoom, withinBboxFilter, worldMinusBboxPolygon };