@chrtco/sdk 0.10.41 → 0.10.43

package/dist/atlas/browser.d.cts

@@ -1,5 +1,75 @@
 import maplibregl from 'maplibre-gl';
-import { C as ColorTableName } from '../s52-colors-CdVzqt2K.cjs';
+import { C as ColorTableName, f as SymbolFamily } from '../symbol-families-D2Kx20HJ.cjs';
+
+/**
+ * Every style image a chart registers for one palette and symbol family, as
+ * DATA: the image id, the themed SVG to rasterise, the bitmap size, and how it
+ * is registered.
+ *
+ * ⚠ ONE LIST, THREE READERS, AND THAT IS THE POINT.
+ *
+ *   1. The first load (`loadSymbolImageSpecs`) registers it.
+ *   2. A palette switch (`rethemeSymbolImages`) rewrites it IN PLACE, and an
+ *      in-place rewrite only works when the new bitmap is exactly the size the
+ *      first load chose — `map.updateImage` refuses anything else. Two copies
+ *      of the sizing rules would drift, and a drifted size silently falls back
+ *      to the slow path this file exists to retire.
+ *   3. `night-luminance.test.ts` reads the NIGHT list to measure the artwork
+ *      that is actually drawn at night, not the tokens it was built from.
+ *
+ * Pure: no DOM, no MapLibre. The loaders in `*-browser.ts` turn specs into
+ * bitmaps. The per-family rules here are lifted verbatim from those loaders,
+ * which now build from this list.
+ */
+
+interface SymbolImageSpec {
+    /** The style image id (`icon-image` / `*-pattern` value). */
+    id: string;
+    /** The SVG to rasterise: themed, stroke-boosted, sized. */
+    svg: string;
+    /** Bitmap size in device pixels. */
+    width: number;
+    height: number;
+    pixelRatio: number;
+    /** Registered as SDF — its colour is a mask and `icon-color` paints it. */
+    sdf: boolean;
+}
+/**
+ * The world-map hatches, registered for EVERY family (see
+ * `chrt-svg-loader-browser.ts`): un-supersampled, pixel ratio 1. They come
+ * first in every list so the house glyph list can never register them twice
+ * at a different size.
+ */
+declare const BASE_PATTERN_GLYPHS: readonly string[];
+
+/** The two world hatches, in this palette. */
+declare function basePatternImageSpecs(palette: ColorTableName): SymbolImageSpec[];
+/** The CHRT house glyphs (not the hatches, which `basePatternImageSpecs` owns). */
+declare function chrtImageSpecs(palette: ColorTableName): SymbolImageSpec[];
+/** The CHRTraster paper-chart variants (`raster:` namespace). */
+declare function rasterImageSpecs(palette: ColorTableName): SymbolImageSpec[];
+/** The vendored S-101 symbols (`s101:` namespace). */
+declare function s101ImageSpecs(palette: ColorTableName): SymbolImageSpec[];
+/**
+ * Everything a chart in `family` registers, in registration order: the S-52
+ * set, the world hatches, then the family's own set. This is what
+ * `ChartCanvas`'s first load registers and what a palette switch re-themes.
+ */
+declare function symbolImageSpecs(palette: ColorTableName, family: SymbolFamily): SymbolImageSpec[];
+interface StyleImageIds {
+    /** Every image id the layers can draw. */
+    readonly ids: ReadonlySet<string>;
+    /**
+     * True when some image name is built at render time (`["concat"]`) and so
+     * is NOT in `ids`. A caller that skips images outside `ids` must not, then.
+     */
+    readonly dynamic: boolean;
+}
+/** The image ids a set of style layers can draw. */
+declare function styleImageIds(layers: ReadonlyArray<{
+    layout?: unknown;
+    paint?: unknown;
+}>): StyleImageIds;
 
 /**
  * Browser-only S-52 SVG image loaders. Uses `new Image()` and `map.addImage()`
@@ -8,12 +78,23 @@ import { C as ColorTableName } from '../s52-colors-CdVzqt2K.cjs';
  * don't pull DOM-typed code into their bundle.
  */
 
+/**
+ * The S-52 set as data — one `SymbolImageSpec` per image, built from the same
+ * helpers the bitmaps were always built from. Defined HERE, beside them, so
+ * `symbol-image-specs.ts` (which re-exports it) imports this file and not the
+ * other way round.
+ */
+declare function s52ImageSpecs(colorTable: ColorTableName): SymbolImageSpec[];
 /**
  * Load all S-52 symbol images into a MapLibre map with the given color theme.
  */
 declare function loadS52SymbolImages(map: maplibregl.Map, colorTable?: ColorTableName): Promise<void>;
 /**
- * Reload all S-52 symbol images with a new color theme.
+ * Re-theme every S-52 symbol image to a new colour table — IN PLACE.
+ *
+ * This used to remove each image and add it back, which reloads every tile
+ * that draws it (see `symbol-images-browser.ts`). Same name and signature, so
+ * every caller gets the in-place path.
  */
 declare function reloadS52SymbolImages(map: maplibregl.Map, colorTable: ColorTableName): Promise<void>;
 
@@ -72,8 +153,14 @@ declare function getS52AtlasVersion(): string;
  */
 declare function loadS52SymbolImagesCached(map: maplibregl.Map, colorTable?: ColorTableName, opts?: LoadCachedOptions): Promise<void>;
 /**
- * Theme-switch equivalent of `reloadS52SymbolImages` that routes through
- * the IDB-backed path.
+ * Theme-switch equivalent of `reloadS52SymbolImages`.
+ *
+ * ⚠ IT NO LONGER GOES THROUGH THE CACHE, AND THAT IS DELIBERATE. It used to
+ * remove every image and re-add it from IndexedDB, and a remove/add pair
+ * reloads every tile that draws the image — the cache made the bitmaps cheap
+ * and the switch no cheaper. A switch now rewrites the pixels in place
+ * (`symbol-images-browser.ts`), which needs no cache. The cache keeps doing
+ * the job it was built for: a COLD START's first load.
  */
 declare function reloadS52SymbolImagesCached(map: maplibregl.Map, colorTable: ColorTableName): Promise<void>;
 /** Test/debug helper — wipes the entire bitmap store. */
@@ -107,7 +194,10 @@ declare function loadThemedBridgeImages(map: maplibregl.Map, colorTable: ColorTa
  * a missing icon renders as a gap, never breaks the map.
  */
 declare function loadS101SymbolImages(map: maplibregl.Map, colorTable?: ColorTableName): Promise<void>;
-/** Reload the S-101 set with a new colour profile (theme switch). */
+/**
+ * Re-theme the S-101 set to a new colour profile (theme switch) — IN PLACE.
+ * See `symbol-images-browser.ts` for why it no longer removes and re-adds.
+ */
 declare function reloadS101SymbolImages(map: maplibregl.Map, colorTable: ColorTableName): Promise<void>;
 
 /**
@@ -117,8 +207,26 @@ declare function reloadS101SymbolImages(map: maplibregl.Map, colorTable: ColorTa
  * from the feature's COLOUR attribute (see chrt-style.ts).
  */
 
-declare function loadBasePatternImages(map: maplibregl.Map): Promise<void>;
-declare function loadChrtSymbolImages(map: maplibregl.Map): Promise<void>;
+/**
+ * The world-map hatch patterns, registered REGARDLESS of symbol family.
+ *
+ * `loadChrtSymbolImages` below runs only when the active family is "chrt" —
+ * correct for the ATON glyphs it owns, and exactly wrong for the two hatch
+ * patterns the CHRT_BASE layers reference: under the default s52 family they
+ * were never registered, and a fill-pattern whose image is missing renders as
+ * NOTHING with no error anywhere (the crosshatch silently absent from the
+ * whole world map). Two images, loaded beside every family's loader.
+ *
+ * Themed per palette (`themeChrtGlyph`): the hatches cover the whole uncharted
+ * world, and at NIGHT they were the one grey-blue texture on a dark chart.
+ */
+declare function loadBasePatternImages(map: maplibregl.Map, colorTable?: ColorTableName): Promise<void>;
+/**
+ * Load the house glyphs into the map as `chrt:{name}` images. Tintable bodies
+ * are SDF (the style's `icon-color` paints them per palette); the
+ * fixed-palette glyphs are themed here (`themeChrtGlyph`).
+ */
+declare function loadChrtSymbolImages(map: maplibregl.Map, colorTable?: ColorTableName): Promise<void>;
 
 /**
  * Browser-only CHRTraster image loader. Registers the synthesized
@@ -132,7 +240,93 @@ declare function loadChrtSymbolImages(map: maplibregl.Map): Promise<void>;
 /** Load every synthesized CHRTraster variant as `raster:{NAME}`. Individual
  *  image failures resolve silently (matching the S-52 loader). */
 declare function loadChrtRasterSymbolImages(map: maplibregl.Map, colorTable?: ColorTableName): Promise<void>;
-/** Reload the CHRTraster set with a new colour table (theme switch). */
+/**
+ * Re-theme the CHRTraster set to a new colour table (theme switch) — IN
+ * PLACE. See `symbol-images-browser.ts` for why it no longer removes and
+ * re-adds.
+ */
 declare function reloadChrtRasterSymbolImages(map: maplibregl.Map, colorTable: ColorTableName): Promise<void>;
 
-export { type LoadCachedOptions, clearS52SymbolImageCache, getS52AtlasVersion, loadBasePatternImages, loadChrtRasterSymbolImages, loadChrtSymbolImages, loadS101SymbolImages, loadS52SymbolImages, loadS52SymbolImagesCached, loadSymbolImages, loadThemedBridgeImages, reloadChrtRasterSymbolImages, reloadS101SymbolImages, reloadS52SymbolImages, reloadS52SymbolImagesCached };
+/**
+ * Browser-only: turn `SymbolImageSpec`s into MapLibre style images.
+ *
+ * ===========================================================================
+ * ⚠ A PALETTE SWITCH MUST NOT REMOVE AN IMAGE. IT REWRITES ITS PIXELS.
+ * ===========================================================================
+ *
+ * The old switch (`reloadS52SymbolImages` and its siblings) removed every
+ * image, re-decoded every SVG and added it back. In MapLibre 5.24 both
+ * `removeImage` and `addImage` go through `Style._afterImageUpdated`, which:
+ *
+ *   · marks the id CHANGED, so the next frame's `_updateTilesForChangedImages`
+ *     RELOADS every tile that uses it (`reloadTilesForDependencies(['icons',
+ *     'patterns'])` — a worker re-parse of the whole tile, symbol layout
+ *     included), and
+ *   · broadcasts the full image list to every worker (`setImages`).
+ *
+ * ~570 images arriving over many frames meant the tiles were re-parsed again
+ * and again while the icons blinked out and back, which on a Raspberry Pi is
+ * the "takes forever … only some switched" the owner reported on 2026-09-30.
+ *
+ * `map.updateImage` does neither. It swaps the pixels behind the same id
+ * (`ImageManager.updateImage` bumps a version) and each tile patches its own
+ * atlas texture on the next frame (`ImageAtlas.patchUpdatedImages`). No tile
+ * reload, no broadcast, and the icon never leaves the screen. Its one
+ * condition is that the new bitmap is the SAME SIZE, which a palette change
+ * never alters — `symbol-image-specs.ts` is the single source of sizes so
+ * the first load and the switch cannot disagree.
+ *
+ * The rasterising itself (SVG → canvas → pixels) is main-thread work, so it
+ * runs in slices with a yield between them and reports progress; the chart
+ * keeps drawing while the icons come over.
+ */
+
+interface SymbolImageProgress {
+    done: number;
+    total: number;
+}
+interface RethemeOptions {
+    /**
+     * Main-thread budget per slice, in ms. Rasterising stops at the first image
+     * past it and yields a task so the map can draw a frame. Default 8.
+     */
+    sliceMs?: number;
+    /**
+     * At most how often the re-theme asks MapLibre for a frame, in ms. Default
+     * 250. Asking once per slice is what made a 6x-throttled re-theme take 7 s:
+     * a frame of this chart costs 100–300 ms there, so a repaint per 8 ms slice
+     * spent the switch drawing intermediate states. The pixels are swapped either
+     * way; this only paces how often the progress is SHOWN.
+     */
+    repaintEveryMs?: number;
+    /** Abort a re-theme that a newer switch has made moot. */
+    signal?: AbortSignal;
+    onProgress?: (p: SymbolImageProgress) => void;
+    /** Called once per image whose new pixels are on the map. */
+    onApplied?: (id: string) => void;
+}
+interface RethemeResult {
+    /** Rewritten in place (the fast path). */
+    updated: number;
+    /** Not registered yet, or registered at another size — added fresh. */
+    added: number;
+    /** Failed to decode — left as they were. */
+    failed: number;
+    aborted: boolean;
+}
+/**
+ * Register every spec the map does not already hold. A first load, so there is
+ * nothing to update in place; images the map already has are left alone.
+ */
+declare function loadSymbolImageSpecs(map: maplibregl.Map, specs: readonly SymbolImageSpec[]): Promise<void>;
+/**
+ * Rewrite every spec's pixels in place, a slice at a time.
+ *
+ * An image the map holds at the spec's size is `updateImage`d (no tile
+ * reload). One it does not hold, or holds at another size, is added — the
+ * slow path, which only a first load or a drifted spec should ever take, and
+ * `RethemeResult.added` says how often it did.
+ */
+declare function rethemeSymbolImages(map: maplibregl.Map, specs: readonly SymbolImageSpec[], opts?: RethemeOptions): Promise<RethemeResult>;
+
+export { BASE_PATTERN_GLYPHS, type LoadCachedOptions, type RethemeOptions, type RethemeResult, type StyleImageIds, type SymbolImageProgress, type SymbolImageSpec, basePatternImageSpecs, chrtImageSpecs, clearS52SymbolImageCache, getS52AtlasVersion, loadBasePatternImages, loadChrtRasterSymbolImages, loadChrtSymbolImages, loadS101SymbolImages, loadS52SymbolImages, loadS52SymbolImagesCached, loadSymbolImageSpecs, loadSymbolImages, loadThemedBridgeImages, rasterImageSpecs, reloadChrtRasterSymbolImages, reloadS101SymbolImages, reloadS52SymbolImages, reloadS52SymbolImagesCached, rethemeSymbolImages, s101ImageSpecs, s52ImageSpecs, styleImageIds, symbolImageSpecs };

package/dist/atlas/browser.d.ts

@@ -1,5 +1,75 @@
 import maplibregl from 'maplibre-gl';
-import { C as ColorTableName } from '../s52-colors-CdVzqt2K.js';
+import { C as ColorTableName, f as SymbolFamily } from '../symbol-families-D2Kx20HJ.js';
+
+/**
+ * Every style image a chart registers for one palette and symbol family, as
+ * DATA: the image id, the themed SVG to rasterise, the bitmap size, and how it
+ * is registered.
+ *
+ * ⚠ ONE LIST, THREE READERS, AND THAT IS THE POINT.
+ *
+ *   1. The first load (`loadSymbolImageSpecs`) registers it.
+ *   2. A palette switch (`rethemeSymbolImages`) rewrites it IN PLACE, and an
+ *      in-place rewrite only works when the new bitmap is exactly the size the
+ *      first load chose — `map.updateImage` refuses anything else. Two copies
+ *      of the sizing rules would drift, and a drifted size silently falls back
+ *      to the slow path this file exists to retire.
+ *   3. `night-luminance.test.ts` reads the NIGHT list to measure the artwork
+ *      that is actually drawn at night, not the tokens it was built from.
+ *
+ * Pure: no DOM, no MapLibre. The loaders in `*-browser.ts` turn specs into
+ * bitmaps. The per-family rules here are lifted verbatim from those loaders,
+ * which now build from this list.
+ */
+
+interface SymbolImageSpec {
+    /** The style image id (`icon-image` / `*-pattern` value). */
+    id: string;
+    /** The SVG to rasterise: themed, stroke-boosted, sized. */
+    svg: string;
+    /** Bitmap size in device pixels. */
+    width: number;
+    height: number;
+    pixelRatio: number;
+    /** Registered as SDF — its colour is a mask and `icon-color` paints it. */
+    sdf: boolean;
+}
+/**
+ * The world-map hatches, registered for EVERY family (see
+ * `chrt-svg-loader-browser.ts`): un-supersampled, pixel ratio 1. They come
+ * first in every list so the house glyph list can never register them twice
+ * at a different size.
+ */
+declare const BASE_PATTERN_GLYPHS: readonly string[];
+
+/** The two world hatches, in this palette. */
+declare function basePatternImageSpecs(palette: ColorTableName): SymbolImageSpec[];
+/** The CHRT house glyphs (not the hatches, which `basePatternImageSpecs` owns). */
+declare function chrtImageSpecs(palette: ColorTableName): SymbolImageSpec[];
+/** The CHRTraster paper-chart variants (`raster:` namespace). */
+declare function rasterImageSpecs(palette: ColorTableName): SymbolImageSpec[];
+/** The vendored S-101 symbols (`s101:` namespace). */
+declare function s101ImageSpecs(palette: ColorTableName): SymbolImageSpec[];
+/**
+ * Everything a chart in `family` registers, in registration order: the S-52
+ * set, the world hatches, then the family's own set. This is what
+ * `ChartCanvas`'s first load registers and what a palette switch re-themes.
+ */
+declare function symbolImageSpecs(palette: ColorTableName, family: SymbolFamily): SymbolImageSpec[];
+interface StyleImageIds {
+    /** Every image id the layers can draw. */
+    readonly ids: ReadonlySet<string>;
+    /**
+     * True when some image name is built at render time (`["concat"]`) and so
+     * is NOT in `ids`. A caller that skips images outside `ids` must not, then.
+     */
+    readonly dynamic: boolean;
+}
+/** The image ids a set of style layers can draw. */
+declare function styleImageIds(layers: ReadonlyArray<{
+    layout?: unknown;
+    paint?: unknown;
+}>): StyleImageIds;
 
 /**
  * Browser-only S-52 SVG image loaders. Uses `new Image()` and `map.addImage()`
@@ -8,12 +78,23 @@ import { C as ColorTableName } from '../s52-colors-CdVzqt2K.js';
  * don't pull DOM-typed code into their bundle.
  */
 
+/**
+ * The S-52 set as data — one `SymbolImageSpec` per image, built from the same
+ * helpers the bitmaps were always built from. Defined HERE, beside them, so
+ * `symbol-image-specs.ts` (which re-exports it) imports this file and not the
+ * other way round.
+ */
+declare function s52ImageSpecs(colorTable: ColorTableName): SymbolImageSpec[];
 /**
  * Load all S-52 symbol images into a MapLibre map with the given color theme.
  */
 declare function loadS52SymbolImages(map: maplibregl.Map, colorTable?: ColorTableName): Promise<void>;
 /**
- * Reload all S-52 symbol images with a new color theme.
+ * Re-theme every S-52 symbol image to a new colour table — IN PLACE.
+ *
+ * This used to remove each image and add it back, which reloads every tile
+ * that draws it (see `symbol-images-browser.ts`). Same name and signature, so
+ * every caller gets the in-place path.
  */
 declare function reloadS52SymbolImages(map: maplibregl.Map, colorTable: ColorTableName): Promise<void>;
 
@@ -72,8 +153,14 @@ declare function getS52AtlasVersion(): string;
  */
 declare function loadS52SymbolImagesCached(map: maplibregl.Map, colorTable?: ColorTableName, opts?: LoadCachedOptions): Promise<void>;
 /**
- * Theme-switch equivalent of `reloadS52SymbolImages` that routes through
- * the IDB-backed path.
+ * Theme-switch equivalent of `reloadS52SymbolImages`.
+ *
+ * ⚠ IT NO LONGER GOES THROUGH THE CACHE, AND THAT IS DELIBERATE. It used to
+ * remove every image and re-add it from IndexedDB, and a remove/add pair
+ * reloads every tile that draws the image — the cache made the bitmaps cheap
+ * and the switch no cheaper. A switch now rewrites the pixels in place
+ * (`symbol-images-browser.ts`), which needs no cache. The cache keeps doing
+ * the job it was built for: a COLD START's first load.
  */
 declare function reloadS52SymbolImagesCached(map: maplibregl.Map, colorTable: ColorTableName): Promise<void>;
 /** Test/debug helper — wipes the entire bitmap store. */
@@ -107,7 +194,10 @@ declare function loadThemedBridgeImages(map: maplibregl.Map, colorTable: ColorTa
  * a missing icon renders as a gap, never breaks the map.
  */
 declare function loadS101SymbolImages(map: maplibregl.Map, colorTable?: ColorTableName): Promise<void>;
-/** Reload the S-101 set with a new colour profile (theme switch). */
+/**
+ * Re-theme the S-101 set to a new colour profile (theme switch) — IN PLACE.
+ * See `symbol-images-browser.ts` for why it no longer removes and re-adds.
+ */
 declare function reloadS101SymbolImages(map: maplibregl.Map, colorTable: ColorTableName): Promise<void>;
 
 /**
@@ -117,8 +207,26 @@ declare function reloadS101SymbolImages(map: maplibregl.Map, colorTable: ColorTa
  * from the feature's COLOUR attribute (see chrt-style.ts).
  */
 
-declare function loadBasePatternImages(map: maplibregl.Map): Promise<void>;
-declare function loadChrtSymbolImages(map: maplibregl.Map): Promise<void>;
+/**
+ * The world-map hatch patterns, registered REGARDLESS of symbol family.
+ *
+ * `loadChrtSymbolImages` below runs only when the active family is "chrt" —
+ * correct for the ATON glyphs it owns, and exactly wrong for the two hatch
+ * patterns the CHRT_BASE layers reference: under the default s52 family they
+ * were never registered, and a fill-pattern whose image is missing renders as
+ * NOTHING with no error anywhere (the crosshatch silently absent from the
+ * whole world map). Two images, loaded beside every family's loader.
+ *
+ * Themed per palette (`themeChrtGlyph`): the hatches cover the whole uncharted
+ * world, and at NIGHT they were the one grey-blue texture on a dark chart.
+ */
+declare function loadBasePatternImages(map: maplibregl.Map, colorTable?: ColorTableName): Promise<void>;
+/**
+ * Load the house glyphs into the map as `chrt:{name}` images. Tintable bodies
+ * are SDF (the style's `icon-color` paints them per palette); the
+ * fixed-palette glyphs are themed here (`themeChrtGlyph`).
+ */
+declare function loadChrtSymbolImages(map: maplibregl.Map, colorTable?: ColorTableName): Promise<void>;
 
 /**
  * Browser-only CHRTraster image loader. Registers the synthesized
@@ -132,7 +240,93 @@ declare function loadChrtSymbolImages(map: maplibregl.Map): Promise<void>;
 /** Load every synthesized CHRTraster variant as `raster:{NAME}`. Individual
  *  image failures resolve silently (matching the S-52 loader). */
 declare function loadChrtRasterSymbolImages(map: maplibregl.Map, colorTable?: ColorTableName): Promise<void>;
-/** Reload the CHRTraster set with a new colour table (theme switch). */
+/**
+ * Re-theme the CHRTraster set to a new colour table (theme switch) — IN
+ * PLACE. See `symbol-images-browser.ts` for why it no longer removes and
+ * re-adds.
+ */
 declare function reloadChrtRasterSymbolImages(map: maplibregl.Map, colorTable: ColorTableName): Promise<void>;
 
-export { type LoadCachedOptions, clearS52SymbolImageCache, getS52AtlasVersion, loadBasePatternImages, loadChrtRasterSymbolImages, loadChrtSymbolImages, loadS101SymbolImages, loadS52SymbolImages, loadS52SymbolImagesCached, loadSymbolImages, loadThemedBridgeImages, reloadChrtRasterSymbolImages, reloadS101SymbolImages, reloadS52SymbolImages, reloadS52SymbolImagesCached };
+/**
+ * Browser-only: turn `SymbolImageSpec`s into MapLibre style images.
+ *
+ * ===========================================================================
+ * ⚠ A PALETTE SWITCH MUST NOT REMOVE AN IMAGE. IT REWRITES ITS PIXELS.
+ * ===========================================================================
+ *
+ * The old switch (`reloadS52SymbolImages` and its siblings) removed every
+ * image, re-decoded every SVG and added it back. In MapLibre 5.24 both
+ * `removeImage` and `addImage` go through `Style._afterImageUpdated`, which:
+ *
+ *   · marks the id CHANGED, so the next frame's `_updateTilesForChangedImages`
+ *     RELOADS every tile that uses it (`reloadTilesForDependencies(['icons',
+ *     'patterns'])` — a worker re-parse of the whole tile, symbol layout
+ *     included), and
+ *   · broadcasts the full image list to every worker (`setImages`).
+ *
+ * ~570 images arriving over many frames meant the tiles were re-parsed again
+ * and again while the icons blinked out and back, which on a Raspberry Pi is
+ * the "takes forever … only some switched" the owner reported on 2026-09-30.
+ *
+ * `map.updateImage` does neither. It swaps the pixels behind the same id
+ * (`ImageManager.updateImage` bumps a version) and each tile patches its own
+ * atlas texture on the next frame (`ImageAtlas.patchUpdatedImages`). No tile
+ * reload, no broadcast, and the icon never leaves the screen. Its one
+ * condition is that the new bitmap is the SAME SIZE, which a palette change
+ * never alters — `symbol-image-specs.ts` is the single source of sizes so
+ * the first load and the switch cannot disagree.
+ *
+ * The rasterising itself (SVG → canvas → pixels) is main-thread work, so it
+ * runs in slices with a yield between them and reports progress; the chart
+ * keeps drawing while the icons come over.
+ */
+
+interface SymbolImageProgress {
+    done: number;
+    total: number;
+}
+interface RethemeOptions {
+    /**
+     * Main-thread budget per slice, in ms. Rasterising stops at the first image
+     * past it and yields a task so the map can draw a frame. Default 8.
+     */
+    sliceMs?: number;
+    /**
+     * At most how often the re-theme asks MapLibre for a frame, in ms. Default
+     * 250. Asking once per slice is what made a 6x-throttled re-theme take 7 s:
+     * a frame of this chart costs 100–300 ms there, so a repaint per 8 ms slice
+     * spent the switch drawing intermediate states. The pixels are swapped either
+     * way; this only paces how often the progress is SHOWN.
+     */
+    repaintEveryMs?: number;
+    /** Abort a re-theme that a newer switch has made moot. */
+    signal?: AbortSignal;
+    onProgress?: (p: SymbolImageProgress) => void;
+    /** Called once per image whose new pixels are on the map. */
+    onApplied?: (id: string) => void;
+}
+interface RethemeResult {
+    /** Rewritten in place (the fast path). */
+    updated: number;
+    /** Not registered yet, or registered at another size — added fresh. */
+    added: number;
+    /** Failed to decode — left as they were. */
+    failed: number;
+    aborted: boolean;
+}
+/**
+ * Register every spec the map does not already hold. A first load, so there is
+ * nothing to update in place; images the map already has are left alone.
+ */
+declare function loadSymbolImageSpecs(map: maplibregl.Map, specs: readonly SymbolImageSpec[]): Promise<void>;
+/**
+ * Rewrite every spec's pixels in place, a slice at a time.
+ *
+ * An image the map holds at the spec's size is `updateImage`d (no tile
+ * reload). One it does not hold, or holds at another size, is added — the
+ * slow path, which only a first load or a drifted spec should ever take, and
+ * `RethemeResult.added` says how often it did.
+ */
+declare function rethemeSymbolImages(map: maplibregl.Map, specs: readonly SymbolImageSpec[], opts?: RethemeOptions): Promise<RethemeResult>;
+
+export { BASE_PATTERN_GLYPHS, type LoadCachedOptions, type RethemeOptions, type RethemeResult, type StyleImageIds, type SymbolImageProgress, type SymbolImageSpec, basePatternImageSpecs, chrtImageSpecs, clearS52SymbolImageCache, getS52AtlasVersion, loadBasePatternImages, loadChrtRasterSymbolImages, loadChrtSymbolImages, loadS101SymbolImages, loadS52SymbolImages, loadS52SymbolImagesCached, loadSymbolImageSpecs, loadSymbolImages, loadThemedBridgeImages, rasterImageSpecs, reloadChrtRasterSymbolImages, reloadS101SymbolImages, reloadS52SymbolImages, reloadS52SymbolImagesCached, rethemeSymbolImages, s101ImageSpecs, s52ImageSpecs, styleImageIds, symbolImageSpecs };