@chrtco/sdk 0.6.0 → 0.7.1

package/dist/atlas/browser.d.cts

@@ -17,6 +17,68 @@ declare function loadS52SymbolImages(map: maplibregl.Map, colorTable?: ColorTabl
  */
 declare function reloadS52SymbolImages(map: maplibregl.Map, colorTable: ColorTableName): Promise<void>;
 
+/**
+ * Browser-only IndexedDB cache for S-52 symbol bitmaps.
+ *
+ * **First visit** — decodes 363 themed SVGs via the proven `new Image()` +
+ * `data:` URL path (identical to `./s52-svg-loader-browser`), adds them to
+ * the map immediately, AND in a non-blocking background task converts each
+ * decoded image to an `ImageBitmap` and persists it to IndexedDB keyed by
+ * `(atlasVersion, colorTable, symbolName)`.
+ *
+ * **Subsequent visits** — bulk-reads the bitmaps from IDB in a single
+ * transaction and `addImage`s them synchronously before any SVG parsing.
+ * The live-decode loop only runs for cache misses (atlas version mismatch,
+ * cleared storage, theme switch with no prior visit on that theme).
+ *
+ * **Hardening pass after PR #513**:
+ *
+ * - Originally tried `createImageBitmap(svgBlob)` — Chromium silently throws
+ *   `InvalidStateError` for SVG inputs even though the function exists. The
+ *   per-symbol catch swallowed the error and zero symbols got added to the
+ *   map. Buoys / lights / beacons disappeared.
+ * - The fix is to NEVER let an SVG go through `createImageBitmap` directly.
+ *   We decode via `new Image()` (which DOES handle SVG everywhere), then
+ *   route the decoded image through a canvas → `createImageBitmap(canvas)`
+ *   to get an IDB-storable bitmap. Canvas inputs to `createImageBitmap` are
+ *   universally supported.
+ * - First-visit `addImage` happens off the HTMLImageElement, not the
+ *   bitmap. The IDB persist is "best effort, never blocks the map" — any
+ *   bitmap-conversion failure leaves the symbol on the map and just skips
+ *   the cache write.
+ *
+ * Gracefully degrades to `loadS52SymbolImages` when IndexedDB is
+ * unavailable (private-mode lockdown, exotic browser).
+ */
+
+interface LoadCachedOptions {
+    /**
+     * If true, skip the IDB read and force a full live-decode + repopulate.
+     * Theme is part of the key so this is rarely needed; left as an escape
+     * hatch.
+     */
+    forceRefresh?: boolean;
+}
+/** Stable atlas version, exposed for diagnostics and tests. */
+declare function getS52AtlasVersion(): string;
+/**
+ * Drop-in replacement for `loadS52SymbolImages`. On first visit, decodes
+ * via the same `new Image()` path the live loader uses and persists each
+ * decoded symbol to IndexedDB in a non-blocking background task. On
+ * subsequent visits, bulk-hydrates from IDB before any SVG parsing.
+ *
+ * Falls back to `loadS52SymbolImages` when IndexedDB or canvas-to-bitmap
+ * conversion isn't available.
+ */
+declare function loadS52SymbolImagesCached(map: maplibregl.Map, colorTable?: ColorTableName, opts?: LoadCachedOptions): Promise<void>;
+/**
+ * Theme-switch equivalent of `reloadS52SymbolImages` that routes through
+ * the IDB-backed path.
+ */
+declare function reloadS52SymbolImagesCached(map: maplibregl.Map, colorTable: ColorTableName): Promise<void>;
+/** Test/debug helper — wipes the entire bitmap store. */
+declare function clearS52SymbolImageCache(): Promise<void>;
+
 /**
  * Browser-only nautical symbol image loaders. Sourced from `./symbols.ts`'s
  * pure data; pushes themed icons into a MapLibre map via `new Image()` +
@@ -30,4 +92,4 @@ declare function loadSymbolImages(map: maplibregl.Map): Promise<void>;
  */
 declare function loadThemedBridgeImages(map: maplibregl.Map, colorTable: ColorTableName): Promise<void>;
 
-export { loadS52SymbolImages, loadSymbolImages, loadThemedBridgeImages, reloadS52SymbolImages };
+export { type LoadCachedOptions, clearS52SymbolImageCache, getS52AtlasVersion, loadS52SymbolImages, loadS52SymbolImagesCached, loadSymbolImages, loadThemedBridgeImages, reloadS52SymbolImages, reloadS52SymbolImagesCached };

package/dist/atlas/browser.d.ts

@@ -17,6 +17,68 @@ declare function loadS52SymbolImages(map: maplibregl.Map, colorTable?: ColorTabl
  */
 declare function reloadS52SymbolImages(map: maplibregl.Map, colorTable: ColorTableName): Promise<void>;
 
+/**
+ * Browser-only IndexedDB cache for S-52 symbol bitmaps.
+ *
+ * **First visit** — decodes 363 themed SVGs via the proven `new Image()` +
+ * `data:` URL path (identical to `./s52-svg-loader-browser`), adds them to
+ * the map immediately, AND in a non-blocking background task converts each
+ * decoded image to an `ImageBitmap` and persists it to IndexedDB keyed by
+ * `(atlasVersion, colorTable, symbolName)`.
+ *
+ * **Subsequent visits** — bulk-reads the bitmaps from IDB in a single
+ * transaction and `addImage`s them synchronously before any SVG parsing.
+ * The live-decode loop only runs for cache misses (atlas version mismatch,
+ * cleared storage, theme switch with no prior visit on that theme).
+ *
+ * **Hardening pass after PR #513**:
+ *
+ * - Originally tried `createImageBitmap(svgBlob)` — Chromium silently throws
+ *   `InvalidStateError` for SVG inputs even though the function exists. The
+ *   per-symbol catch swallowed the error and zero symbols got added to the
+ *   map. Buoys / lights / beacons disappeared.
+ * - The fix is to NEVER let an SVG go through `createImageBitmap` directly.
+ *   We decode via `new Image()` (which DOES handle SVG everywhere), then
+ *   route the decoded image through a canvas → `createImageBitmap(canvas)`
+ *   to get an IDB-storable bitmap. Canvas inputs to `createImageBitmap` are
+ *   universally supported.
+ * - First-visit `addImage` happens off the HTMLImageElement, not the
+ *   bitmap. The IDB persist is "best effort, never blocks the map" — any
+ *   bitmap-conversion failure leaves the symbol on the map and just skips
+ *   the cache write.
+ *
+ * Gracefully degrades to `loadS52SymbolImages` when IndexedDB is
+ * unavailable (private-mode lockdown, exotic browser).
+ */
+
+interface LoadCachedOptions {
+    /**
+     * If true, skip the IDB read and force a full live-decode + repopulate.
+     * Theme is part of the key so this is rarely needed; left as an escape
+     * hatch.
+     */
+    forceRefresh?: boolean;
+}
+/** Stable atlas version, exposed for diagnostics and tests. */
+declare function getS52AtlasVersion(): string;
+/**
+ * Drop-in replacement for `loadS52SymbolImages`. On first visit, decodes
+ * via the same `new Image()` path the live loader uses and persists each
+ * decoded symbol to IndexedDB in a non-blocking background task. On
+ * subsequent visits, bulk-hydrates from IDB before any SVG parsing.
+ *
+ * Falls back to `loadS52SymbolImages` when IndexedDB or canvas-to-bitmap
+ * conversion isn't available.
+ */
+declare function loadS52SymbolImagesCached(map: maplibregl.Map, colorTable?: ColorTableName, opts?: LoadCachedOptions): Promise<void>;
+/**
+ * Theme-switch equivalent of `reloadS52SymbolImages` that routes through
+ * the IDB-backed path.
+ */
+declare function reloadS52SymbolImagesCached(map: maplibregl.Map, colorTable: ColorTableName): Promise<void>;
+/** Test/debug helper — wipes the entire bitmap store. */
+declare function clearS52SymbolImageCache(): Promise<void>;
+
 /**
  * Browser-only nautical symbol image loaders. Sourced from `./symbols.ts`'s
  * pure data; pushes themed icons into a MapLibre map via `new Image()` +
@@ -30,4 +92,4 @@ declare function loadSymbolImages(map: maplibregl.Map): Promise<void>;
  */
 declare function loadThemedBridgeImages(map: maplibregl.Map, colorTable: ColorTableName): Promise<void>;
 
-export { loadS52SymbolImages, loadSymbolImages, loadThemedBridgeImages, reloadS52SymbolImages };
+export { type LoadCachedOptions, clearS52SymbolImageCache, getS52AtlasVersion, loadS52SymbolImages, loadS52SymbolImagesCached, loadSymbolImages, loadThemedBridgeImages, reloadS52SymbolImages, reloadS52SymbolImagesCached };