@chrtco/sdk 0.9.0 → 0.9.2

package/dist/index.d.cts

@@ -549,6 +549,11 @@ interface StyleUrlOptions {
      *  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;
@@ -1031,6 +1036,11 @@ interface InteractMapLike {
         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 {
@@ -1043,6 +1053,20 @@ interface InteractMapMouseEvent {
         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. */
@@ -1058,12 +1082,123 @@ interface InspectEventContext {
     /** The rendered feature the result was decoded from. */
     feature: InspectableFeature;
 }
-interface AttachOptions {
+/**
+ * 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: {
@@ -1072,21 +1207,17 @@ interface AttachOptions {
         };
     }) => void;
     /**
-     * Show the built-in minimal popup (plain DOM, no framework). Default: true
-     * when `onInspect` is not provided, false otherwise.
+     * 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 click through the features API (metered — counts
-     * against the key's `featureCalls` quota). Default: false.
+     * Auto-enrich every inspected result 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 {
@@ -1125,6 +1256,154 @@ declare class InteractError extends Error {
     });
 }
 
+/**
+ * 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.
  *
@@ -1162,6 +1441,29 @@ declare class InteractClient {
      * 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
@@ -1169,10 +1471,20 @@ declare class InteractClient {
      * no listeners are wired on denial.
      *
      * Headless-first: pass `onInspect` to receive every decoded
-     * {@link InspectResult} and render your own UI. Without `onInspect`, the
+     * {@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),
@@ -1701,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 = 0;
-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
@@ -2045,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.
@@ -2074,6 +2342,150 @@ declare function getStyleStats(style: MapboxStyle): {
     objectClasses: Set<string>;
 };
 
+declare const S101_SOURCE_COMMIT = "05063500e898544c90078ab78a61efc72b7e62f3";
+
+/**
+ * S-101 symbol-set support (portrayal-excellence 7c, first slice).
+ *
+ * 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.
+ *
+ * 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).
+ *
+ * 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.
+ */
+
+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>;
+/**
+ * House ATON palette — S-57 COLOUR code → hex. v1 placeholder values
+ * (see module header); chosen for contrast on the CHRT day water ramp.
+ */
+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.
@@ -2448,10 +2860,11 @@ declare class Chrt {
      *   transformRequest: chrt.transformRequest(),
      * });
      *
-     * @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.
+     * @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;
     /**
@@ -2503,4 +2916,4 @@ declare class Chrt {
     warmTiles(region?: string): Promise<void>;
 }
 
-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 };
+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 };