@chrtco/sdk 0.7.7 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to `@chrtco/sdk` will be documented in this file.
 
+## [0.8.0] — 2026-06-30
+- **Online tile rendering now works end-to-end against `tiles.chrt.co`.** `chrt.transformRequest()` mints a short-lived ES256 tile JWT from your API key (`POST {baseUrl}/mint/tile-token`), caches and refreshes it, and attaches `Authorization: Bearer` on `tiles.chrt.co/v1/tiles/{region}/…/.mvt` requests only. This replaces the previous no-op transformer that injected `x-api-key` against a removed `api.chrt.co/v1/tiles/…?key=` path.
+- **New `chrt.style(opts?)`** — returns a ready-to-use IHO **S-52** MapLibre / Mapbox GL style object (`palette`: `DAY` | `DUSK` | `NIGHT`, plus `region`, `depthUnits`, and the other atlas options), with the tile source wired in. Mutate the returned object, or build a fully custom style over `buildSources()`. S-101 portrayal is on the roadmap.
+- **New `chrt.warmTiles(region?)`** — optionally pre-mint the tile token to surface `region_not_licensed` / `tile_quota_exceeded` before the map loads.
+- **New config options**: `region` (default `NOAA_ENC`) and `tileBaseUrl` (default `https://tiles.chrt.co`).
+- **New exports**: `TileAuth`, `TileTokenError`, and the `TileTokenResponse` / `TileTokenErrorCode` / `ChrtStyleOptions` types.
+- **Deprecated**: `styleUrl()` — CHRT serves no remote `style.json`; it now throws with guidance to use `style()`. `tiles.groups()` — legacy pre-consolidation per-group catalogue. `tiles.tileUrl()` now returns the real `tiles.chrt.co` URL.
+- `TransformRequest.headers` is now optional (matches MapLibre; the transformer omits headers on unauthenticated passthrough).
+- **Requires** the public `POST /v1/mint/tile-token` route on `api.chrt.co` (the sibling of the existing `/v1/mint/offline-token`).
+
 ## [0.7.0] — 2026-05-08
 - **Atlas — dominance cascade & scale-band rendering**: per-feature dominance cascade in continuous mode, cascading band fallback, band-then-class layer emission, chart-mode per-cell cascade fallback to coarser bands, dominance filter on orientation-cross-band labels.
 - **Atlas — cartographic labels**: orientation labels + typography hierarchy.

package/README.md

@@ -37,30 +37,56 @@ const cells = await chrt.cells.list({ source: 'NOAA' });
 const cell = await chrt.cells.get('US5MA11M');
 ```
 
-## Mapbox GL JS / MapLibre
+## Maps (MapLibre GL JS / Mapbox GL JS)
+
+`chrt.style()` returns a ready-to-use IHO **S-52** nautical style; `chrt.transformRequest()`
+mints a short-lived tile token from your API key and attaches it to tile requests
+automatically. Examples use MapLibre — substitute `mapbox-gl` if you're already on Mapbox.
 
 ```typescript
-import mapboxgl from 'mapbox-gl';
+import maplibregl from 'maplibre-gl';
 import { Chrt } from '@chrtco/sdk';
 
 const chrt = new Chrt('chrt_live_...');
 
-const map = new mapboxgl.Map({
+const map = new maplibregl.Map({
   container: 'map',
-  style: chrt.styleUrl(),
+  style: chrt.style({ palette: 'DAY' }),   // 'DAY' | 'DUSK' | 'NIGHT'
   center: [-70.25, 43.66],
   zoom: 12,
   transformRequest: chrt.transformRequest(),
 });
 ```
 
+Tiles are served from `tiles.chrt.co` and gated by a short-lived ES256 JWT. The SDK mints
+it from your key, attaches it as `Authorization: Bearer` on tile requests only, and refreshes
+it before expiry — you never handle tokens directly.
+
+### Custom styles
+
+`chrt.style()` returns a standard MapLibre style object you can mutate. For a fully custom
+look, build your own style over CHRT's vector source with `buildSources()` and keep
+`chrt.transformRequest()` for auth:
+
+```typescript
+import { buildSources } from '@chrtco/sdk';
+
+const sources = buildSources({ region: 'NOAA_ENC' });
+// sources['NOAA_ENC'].tiles → ['https://tiles.chrt.co/v1/tiles/NOAA_ENC/{z}/{x}/{y}.mvt']
+// Each S-57 class (DEPARE, LIGHTS, BOYLAT, …) is a `source-layer` inside that one source.
+```
+
+> S-101 portrayal is on the roadmap; today `chrt.style()` emits S-52.
+
 ## Configuration
 
 ```typescript
 const chrt = new Chrt({
   apiKey: 'chrt_live_...',
-  baseUrl: 'https://api.chrt.co/v1', // default
-  retries: 2,                         // retry on 5xx, default 2
+  baseUrl: 'https://api.chrt.co/v1',     // default
+  retries: 2,                             // retry on 5xx, default 2
+  region: 'NOAA_ENC',                     // default tile region
+  tileBaseUrl: 'https://tiles.chrt.co',   // override for staging tiles
 });
 ```
 
@@ -92,20 +118,27 @@ List available ENC cells.
 ### `chrt.cells.get(cellId)`
 Get metadata for a specific cell.
 
-### `chrt.tiles.styleUrl()`
-Returns a Mapbox/MapLibre-compatible `style.json` URL.
+### `chrt.style(opts?)`
+Returns a ready-to-use MapLibre/Mapbox GL **S-52** style object. Options: `palette`
+(`'DAY'` | `'DUSK'` | `'NIGHT'`), `region`, `depthUnits`, plus the other atlas style options.
 
-### `chrt.tiles.tileUrl(z, x, y)`
-Returns a single vector tile URL.
+### `chrt.transformRequest(opts?)`
+Returns a `transformRequest` that mints a short-lived tile JWT from your API key and attaches
+it as `Authorization: Bearer` on `tiles.chrt.co` requests only. Pass `{ region }` to override
+the default region.
 
-### `chrt.tiles.groups()`
-List available tileset groups.
+### `chrt.warmTiles(region?)`
+Pre-mints the tile token so you can surface auth errors (e.g. `region_not_licensed`,
+`tile_quota_exceeded`) before the map loads. Optional — `transformRequest()` warms the cache
+on its own.
 
-### `chrt.styleUrl()`
-Shortcut for `chrt.tiles.styleUrl()`.
+### `chrt.tiles.tileUrl(z, x, y)`
+Single vector tile URL template at `tiles.chrt.co`. Prefer `chrt.style()`, which wires the
+source for you.
 
-### `chrt.transformRequest()`
-Returns a `transformRequest` function for Mapbox GL / MapLibre that auto-injects the API key.
+### `chrt.styleUrl()` · `chrt.tiles.groups()` — deprecated
+CHRT serves no remote `style.json` — use `chrt.style()`. Tilesets were consolidated to one
+source per region (2026-04), so the per-group catalogue is legacy.
 
 ## Error Handling
 

package/dist/index.cjs

@@ -31,6 +31,7 @@ __export(index_exports, {
   ChrtError: () => ChrtError,
   DEFAULT_REGION: () => DEFAULT_REGION,
   DEFAULT_TILE_BASE_URL: () => DEFAULT_TILE_BASE_URL,
+  DEFAULT_TILE_REGION: () => DEFAULT_TILE_REGION,
   LABELED_LAYERS: () => LABELED_LAYERS,
   LABEL_BEHAVIOR: () => LABEL_BEHAVIOR,
   NAUTICAL_SYMBOLS: () => NAUTICAL_SYMBOLS,
@@ -48,6 +49,8 @@ __export(index_exports, {
   S52_NIGHT: () => S52_NIGHT,
   SYMBOL_GROUPS: () => SYMBOL_GROUPS,
   SYMBOL_MAP: () => SYMBOL_MAP,
+  TileAuth: () => TileAuth,
+  TileTokenError: () => TileTokenError,
   applyColorTheme: () => applyColorTheme,
   bandFilterExpression: () => bandFilterExpression,
   buildLabelLayer: () => buildLabelLayer,
@@ -226,20 +229,243 @@ function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
 
+// src/tile-auth.ts
+var DEFAULT_TILE_REGION = "NOAA_ENC";
+var DEFAULT_TILE_BASE_URL = "https://tiles.chrt.co";
+var TileTokenError = class extends Error {
+  code;
+  status;
+  constructor(code, message, status) {
+    super(message);
+    this.name = "TileTokenError";
+    this.code = code;
+    this.status = status;
+  }
+};
+var TILE_URL_PATH = /\/v1\/tiles\/[A-Za-z0-9_]+(?:\/[a-z][a-z0-9-]*)?\/\d+\/\d+\/\d+\.mvt(?:\?.*)?$/i;
+var REFRESH_MARGIN_SECONDS = 30;
+var STALE_GRACE_SECONDS = 1;
+var MINT_RETRY_DELAYS_MS = [500, 1e3, 2e3];
+function nowSeconds() {
+  return Math.floor(Date.now() / 1e3);
+}
+function sleep2(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+function mapErrorCode(raw, status) {
+  const known = [
+    "invalid_api_key",
+    "feature_flag_disabled",
+    "region_not_licensed",
+    "tile_quota_exceeded",
+    "region_not_available"
+  ];
+  if (typeof raw === "string" && known.includes(raw)) {
+    return raw;
+  }
+  if (status === 401) return "invalid_api_key";
+  if (status === 403) return "feature_flag_disabled";
+  if (status === 429) return "tile_quota_exceeded";
+  if (status === 503) return "region_not_available";
+  return "unexpected_response";
+}
+var TileAuth = class {
+  constructor(http, opts) {
+    this.http = http;
+    this.defaultRegion = opts?.region ?? DEFAULT_TILE_REGION;
+    this.tileBaseUrl = (opts?.tileBaseUrl ?? DEFAULT_TILE_BASE_URL).replace(/\/+$/, "");
+  }
+  cache = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Map();
+  defaultRegion;
+  tileBaseUrl;
+  lifecycleRegistered = false;
+  /** Mint once via the HTTP client (POST `/mint/tile-token`, `x-api-key`). */
+  async mintOnce(region) {
+    let res;
+    try {
+      res = await this.http.postJson("/mint/tile-token", { region });
+    } catch (err) {
+      throw new TileTokenError(
+        "network_error",
+        err instanceof Error ? err.message : "mint request failed"
+      );
+    }
+    if (!res.ok) {
+      const code = mapErrorCode(res.body?.error, res.status);
+      const msg = typeof res.body?.error === "string" ? res.body.error : `HTTP ${res.status}`;
+      throw new TileTokenError(code, msg, res.status);
+    }
+    const b = res.body;
+    if (!b || typeof b.token !== "string" || typeof b.expires_at !== "number" || typeof b.kid !== "string" || typeof b.build_tag !== "string" || typeof b.region !== "string") {
+      throw new TileTokenError(
+        "unexpected_response",
+        "mint-tile-token returned a malformed body",
+        res.status
+      );
+    }
+    return {
+      token: b.token,
+      expiresAt: b.expires_at,
+      kid: b.kid,
+      buildTag: b.build_tag,
+      region: b.region
+    };
+  }
+  /** Mint with exponential backoff on network errors only. */
+  async mintWithRetry(region) {
+    let lastErr;
+    for (let attempt = 0; attempt <= MINT_RETRY_DELAYS_MS.length; attempt++) {
+      try {
+        return await this.mintOnce(region);
+      } catch (err) {
+        lastErr = err;
+        if (err instanceof TileTokenError && err.code !== "network_error") throw err;
+        if (attempt === MINT_RETRY_DELAYS_MS.length) break;
+        await sleep2(MINT_RETRY_DELAYS_MS[attempt]);
+      }
+    }
+    throw lastErr instanceof Error ? lastErr : new TileTokenError("network_error", "mint failed");
+  }
+  scheduleRefresh(region, expiresAt) {
+    const delaySeconds = expiresAt - nowSeconds() - REFRESH_MARGIN_SECONDS;
+    if (delaySeconds <= 0) return null;
+    const timer = setTimeout(() => {
+      void this.refreshInBackground(region);
+    }, delaySeconds * 1e3);
+    timer.unref?.();
+    return timer;
+  }
+  async refreshInBackground(region) {
+    try {
+      const response = await this.mintWithRetry(region);
+      this.store(region, response);
+    } catch {
+      this.invalidate(region);
+    }
+  }
+  store(region, response) {
+    const existing = this.cache.get(region);
+    if (existing?.refreshTimer) clearTimeout(existing.refreshTimer);
+    this.cache.set(region, {
+      response,
+      refreshTimer: this.scheduleRefresh(region, response.expiresAt)
+    });
+    this.registerLifecycleHandlers();
+  }
+  /**
+   * Fetch (or reuse a cached) tile token for `region`. Concurrent callers for
+   * the same region await the same in-flight mint.
+   */
+  async getToken(region) {
+    const r = region ?? this.defaultRegion;
+    const cached = this.cache.get(r);
+    if (cached && cached.response.expiresAt - nowSeconds() > REFRESH_MARGIN_SECONDS) {
+      return cached.response;
+    }
+    const inflight = this.pending.get(r);
+    if (inflight) return inflight;
+    const promise = (async () => {
+      try {
+        const response = await this.mintWithRetry(r);
+        this.store(r, response);
+        return response;
+      } finally {
+        this.pending.delete(r);
+      }
+    })();
+    this.pending.set(r, promise);
+    return promise;
+  }
+  /** Synchronous cache peek — null if absent or within the stale grace window. */
+  peek(region) {
+    const entry = this.cache.get(region ?? this.defaultRegion);
+    if (!entry) return null;
+    if (entry.response.expiresAt - nowSeconds() <= STALE_GRACE_SECONDS) return null;
+    return entry.response.token;
+  }
+  /**
+   * 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.
+   */
+  transformRequest(region) {
+    const r = region ?? this.defaultRegion;
+    void this.getToken(r).catch(() => void 0);
+    return (url) => {
+      if (!url.startsWith(this.tileBaseUrl) || !TILE_URL_PATH.test(url)) return void 0;
+      const token = this.peek(r);
+      if (!token) return { url };
+      return { url, headers: { Authorization: `Bearer ${token}` } };
+    };
+  }
+  /** Clear the cached token + timer for a region. */
+  invalidate(region) {
+    const r = region ?? this.defaultRegion;
+    const entry = this.cache.get(r);
+    if (entry?.refreshTimer) clearTimeout(entry.refreshTimer);
+    this.cache.delete(r);
+  }
+  /**
+   * 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.
+   */
+  registerLifecycleHandlers() {
+    if (this.lifecycleRegistered) return;
+    if (typeof document === "undefined" || typeof window === "undefined") return;
+    const onWake = () => {
+      if (document.visibilityState !== "visible") return;
+      for (const [region, entry] of this.cache.entries()) {
+        if (entry.response.expiresAt - nowSeconds() >= REFRESH_MARGIN_SECONDS) continue;
+        void this.refreshInBackground(region);
+      }
+    };
+    document.addEventListener("visibilitychange", onWake);
+    window.addEventListener("pageshow", (e) => {
+      if (e.persisted) onWake();
+    });
+    this.lifecycleRegistered = true;
+  }
+};
+
 // src/endpoints/tiles.ts
 var TilesEndpoint = class {
-  constructor(http) {
+  constructor(http, opts) {
     this.http = http;
+    this.region = opts?.region ?? DEFAULT_TILE_REGION;
+    this.tileBaseUrl = (opts?.tileBaseUrl ?? DEFAULT_TILE_BASE_URL).replace(/\/+$/, "");
   }
-  /** Full style.json URL with API key as query param */
+  region;
+  tileBaseUrl;
+  /**
+   * @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.
+   */
   styleUrl() {
-    return `${this.http.getBaseUrl()}/tiles/style.json?key=${this.http.getApiKey()}`;
+    throw new Error(
+      "chrt.tiles.styleUrl() is no longer supported: CHRT serves no remote style.json. Use chrt.style(opts) to generate an S-52 MapLibre style object, and chrt.transformRequest() for tile auth. See https://chrt.co/docs/vector-tiles"
+    );
   }
-  /** Individual tile URL template */
-  tileUrl(z, x, y, format = "mvt") {
-    return `${this.http.getBaseUrl()}/tiles/${z}/${x}/${y}.${format}?key=${this.http.getApiKey()}`;
+  /**
+   * Vector tile URL template for the configured region, served by the
+   * tile-worker at `tiles.chrt.co`. Tiles are JWT-gated — pair this with
+   * `chrt.transformRequest()`, which attaches the `Authorization: Bearer`
+   * header. Prefer `chrt.style()`, which wires the source for you.
+   */
+  tileUrl(z, x, y) {
+    return `${this.tileBaseUrl}/v1/tiles/${this.region}/${z}/${x}/${y}.mvt`;
   }
-  /** List available tileset groups */
+  /**
+   * @deprecated Tilesets were consolidated to one PMTiles per region (2026-04);
+   * the per-group catalogue endpoint is legacy and no longer served. Render via
+   * `chrt.style()` instead, which emits a single vector source per region.
+   */
   async groups() {
     return this.http.request("/tiles/groups");
   }
@@ -431,7 +657,7 @@ function mapServerError(body, status) {
 }
 
 // src/endpoints/offline-token-manager.ts
-var REFRESH_MARGIN_SECONDS = 30;
+var REFRESH_MARGIN_SECONDS2 = 30;
 function now() {
   return Math.floor(Date.now() / 1e3);
 }
@@ -452,7 +678,7 @@ var OfflineTokenManager = class {
     }
     const key = this.cacheKey(deviceId, regions);
     const cached = this.cache.get(key);
-    if (cached && cached.expiresAt - now() > REFRESH_MARGIN_SECONDS) {
+    if (cached && cached.expiresAt - now() > REFRESH_MARGIN_SECONDS2) {
       return cached;
     }
     const inflight = this.pending.get(key);
@@ -1074,47 +1300,6 @@ function dirname(p) {
   return p.slice(0, k);
 }
 
-// src/pagination.ts
-async function* paginate(fetchPage, getItems, getTotalCount, options) {
-  const pageSize = options?.pageSize ?? 100;
-  const signal = options?.signal;
-  let offset = 0;
-  while (true) {
-    if (signal?.aborted) return;
-    const response = await fetchPage(offset, signal);
-    const items = getItems(response);
-    for (const item of items) {
-      yield item;
-    }
-    if (items.length === 0) return;
-    offset += items.length;
-    const total = getTotalCount(response);
-    if (total > 0 && offset >= total) return;
-  }
-}
-
-// src/webhooks.ts
-var VALID_TYPES = /* @__PURE__ */ new Set(["cell.updated", "cell.new", "cell.deleted"]);
-function parseWebhook(body) {
-  if (typeof body !== "object" || body === null) {
-    throw new Error("Invalid webhook payload: expected an object");
-  }
-  const obj = body;
-  if (typeof obj.id !== "string") {
-    throw new Error("Invalid webhook payload: missing 'id'");
-  }
-  if (typeof obj.timestamp !== "string") {
-    throw new Error("Invalid webhook payload: missing 'timestamp'");
-  }
-  if (typeof obj.type !== "string" || !VALID_TYPES.has(obj.type)) {
-    throw new Error(`Invalid webhook payload: unknown type '${String(obj.type)}'`);
-  }
-  if (typeof obj.data !== "object" || obj.data === null) {
-    throw new Error("Invalid webhook payload: missing 'data'");
-  }
-  return obj;
-}
-
 // src/atlas/s52-colors.ts
 var S52_DAY = {
   // Depth
@@ -9479,7 +9664,7 @@ var BUILD_MINZOOM = 3;
 var BUILD_MAXZOOM = 14;
 
 // src/atlas/source-registry.ts
-var DEFAULT_TILE_BASE_URL = "https://tiles.chrt.co";
+var DEFAULT_TILE_BASE_URL2 = "https://tiles.chrt.co";
 var DEFAULT_REGION = "NOAA_ENC";
 function buildSources(opts = {}) {
   const mode = opts.mode ?? "pmtiles";
@@ -9492,7 +9677,7 @@ function buildSources(opts = {}) {
       }
     };
   }
-  const base = (opts.tileBaseUrl ?? DEFAULT_TILE_BASE_URL).replace(/\/+$/, "");
+  const base = (opts.tileBaseUrl ?? DEFAULT_TILE_BASE_URL2).replace(/\/+$/, "");
   return {
     [region]: {
       type: "vector",
@@ -11219,6 +11404,47 @@ function getStyleStats(style) {
   };
 }
 
+// src/pagination.ts
+async function* paginate(fetchPage, getItems, getTotalCount, options) {
+  const pageSize = options?.pageSize ?? 100;
+  const signal = options?.signal;
+  let offset = 0;
+  while (true) {
+    if (signal?.aborted) return;
+    const response = await fetchPage(offset, signal);
+    const items = getItems(response);
+    for (const item of items) {
+      yield item;
+    }
+    if (items.length === 0) return;
+    offset += items.length;
+    const total = getTotalCount(response);
+    if (total > 0 && offset >= total) return;
+  }
+}
+
+// src/webhooks.ts
+var VALID_TYPES = /* @__PURE__ */ new Set(["cell.updated", "cell.new", "cell.deleted"]);
+function parseWebhook(body) {
+  if (typeof body !== "object" || body === null) {
+    throw new Error("Invalid webhook payload: expected an object");
+  }
+  const obj = body;
+  if (typeof obj.id !== "string") {
+    throw new Error("Invalid webhook payload: missing 'id'");
+  }
+  if (typeof obj.timestamp !== "string") {
+    throw new Error("Invalid webhook payload: missing 'timestamp'");
+  }
+  if (typeof obj.type !== "string" || !VALID_TYPES.has(obj.type)) {
+    throw new Error(`Invalid webhook payload: unknown type '${String(obj.type)}'`);
+  }
+  if (typeof obj.data !== "object" || obj.data === null) {
+    throw new Error("Invalid webhook payload: missing 'data'");
+  }
+  return obj;
+}
+
 // src/index.ts
 var Chrt = class {
   /** Tile endpoints — styleUrl, tileUrl, groups */
@@ -11236,15 +11462,22 @@ var Chrt = class {
   featuresEp;
   queryEp;
   http;
+  tileAuth;
+  region;
+  tileBaseUrl;
   constructor(apiKeyOrConfig) {
     const config = typeof apiKeyOrConfig === "string" ? { apiKey: apiKeyOrConfig } : apiKeyOrConfig;
+    this.region = config.region ?? DEFAULT_TILE_REGION;
+    this.tileBaseUrl = config.tileBaseUrl ?? DEFAULT_TILE_BASE_URL;
     this.http = new HttpClient(config.apiKey, config.baseUrl, config.retries);
-    this.tiles = new TilesEndpoint(this.http);
+    const tileOpts = { region: this.region, tileBaseUrl: this.tileBaseUrl };
+    this.tiles = new TilesEndpoint(this.http, tileOpts);
     this.cells = new CellsEndpoint(this.http);
     this.coverage = new CoverageEndpoint(this.http);
     this.featuresEp = new FeaturesEndpoint(this.http);
     this.queryEp = new QueryEndpoint(this.http);
     this.offline = new OfflineEndpoint(this.http, config.deviceId, config.manifestPath);
+    this.tileAuth = new TileAuth(this.http, tileOpts);
   }
   /* ── Convenience shortcuts ───────────────────────── */
   /** Query GeoJSON features by bounding box */
@@ -11321,28 +11554,63 @@ var Chrt = class {
     );
   }
   /* ── Map integration helpers ─────────────────────── */
-  /** Returns a style.json URL ready for Mapbox GL / MapLibre */
+  /**
+   * Build a ready-to-use MapLibre / Mapbox GL style object for CHRT's nautical
+   * charts. The default is the full IHO **S-52** portrayal; pick a palette and
+   * tweak rendering via `opts`. The returned object is a standard MapLibre
+   * style — mutate it freely, or build your own from scratch over the CHRT
+   * vector source (see `buildSources`) for a fully custom look.
+   *
+   * Pair with `transformRequest()` so tile requests carry their auth token.
+   *
+   * @example
+   * const map = new maplibregl.Map({
+   *   container: 'map',
+   *   style: chrt.style({ palette: 'DAY' }),
+   *   transformRequest: chrt.transformRequest(),
+   * });
+   *
+   * @remarks S-101 portrayal is on the roadmap; today `style()` emits S-52.
+   */
+  style(opts = {}) {
+    const { palette = "DAY", ...styleOpts } = opts;
+    return generateStyle(palette, {
+      region: this.region,
+      tileBaseUrl: this.tileBaseUrl,
+      ...styleOpts
+    });
+  }
+  /**
+   * @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.
+   */
   styleUrl() {
     return this.tiles.styleUrl();
   }
   /**
-   * Returns a `transformRequest` function for Mapbox GL JS / MapLibre GL JS.
-   * Injects the API key header for requests to api.chrt.co.
+   * 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
+   * `Authorization: Bearer` on requests to `tiles.chrt.co` only. Style, sprite,
+   * and glyph URLs pass through untouched. The cache warms in the background on
+   * first call, so the first tile or two may be retried by the renderer.
    *
    * @example
-   * const map = new mapboxgl.Map({
-   *   style: chrt.styleUrl(),
+   * const map = new maplibregl.Map({
+   *   style: chrt.style(),
    *   transformRequest: chrt.transformRequest(),
    * });
    */
-  transformRequest() {
-    const apiKey = this.http.getApiKey();
-    return (url) => {
-      if (url.includes("api.chrt.co")) {
-        return { url, headers: { "x-api-key": apiKey } };
-      }
-      return void 0;
-    };
+  transformRequest(opts) {
+    return this.tileAuth.transformRequest(opts?.region);
+  }
+  /**
+   * Pre-mint the tile token for a region. Optional — `transformRequest()` warms
+   * the cache automatically — but useful if you want to surface a mint error
+   * (e.g. `region_not_licensed`, `tile_quota_exceeded`) before the map loads.
+   */
+  async warmTiles(region) {
+    await this.tileAuth.getToken(region);
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
@@ -11358,6 +11626,7 @@ var Chrt = class {
   ChrtError,
   DEFAULT_REGION,
   DEFAULT_TILE_BASE_URL,
+  DEFAULT_TILE_REGION,
   LABELED_LAYERS,
   LABEL_BEHAVIOR,
   NAUTICAL_SYMBOLS,
@@ -11375,6 +11644,8 @@ var Chrt = class {
   S52_NIGHT,
   SYMBOL_GROUPS,
   SYMBOL_MAP,
+  TileAuth,
+  TileTokenError,
   applyColorTheme,
   bandFilterExpression,
   buildLabelLayer,