map-gl-offline 0.8.9 → 0.9.1

package/dist/ui/controls/polygonControl.d.ts

@@ -3,7 +3,7 @@
  * Handles polygon drawing, area calculation, and map visualization
  */
 import type { Map as MaplibreMap } from 'maplibre-gl';
-import type { CssPrefix } from '../../utils/cssPrefix';
+import type { CssPrefix } from '../../utils/cssPrefix.js';
 export interface PolygonControlOptions {
     onSave: (bounds: [number, number, number, number], area: number) => void;
     onCancel: () => void;
@@ -74,6 +74,12 @@ export declare class PolygonControl {
      * Handle map move/zoom events
      */
     private handleMapMove;
+    /**
+     * The area to select: the middle of what's on screen. On a tilted or rotated map
+     * `getBounds()` reaches far past the view, so insetting it would miss the part
+     * nearest the camera. There, measure from the map's centre to the screen's edges.
+     */
+    private getSelectionBbox;
     /**
      * Update polygon visualization based on current map bounds
      */

package/dist/ui/controls/regionControl.d.ts

@@ -3,9 +3,9 @@
  * Manages region selection, form modal, and saves
  */
 import type { Map as MaplibreMap } from 'maplibre-gl';
-import { DownloadManager } from '../../ui/managers/downloadManager';
-import { ModalManager } from '../../ui/modals/modalManager';
-import type { CssPrefix } from '../../utils/cssPrefix';
+import { DownloadManager } from '../managers/downloadManager.js';
+import { ModalManager } from '../modals/modalManager.js';
+import type { CssPrefix } from '../../utils/cssPrefix.js';
 export interface RegionControlOptions {
     map: MaplibreMap;
     downloadManager: DownloadManager;

package/dist/ui/managers/ControlButtonManager.d.ts

@@ -3,7 +3,7 @@
  * Manages the main control button and progress badge states
  * Refactored to use modular Button component
  */
-import type { CssPrefix } from '../../utils/cssPrefix';
+import type { CssPrefix } from '../../utils/cssPrefix.js';
 export interface ButtonManagerOptions {
     onTogglePanel: () => void;
     cssPrefix?: CssPrefix;

package/dist/ui/managers/PanelManager.d.ts

@@ -3,10 +3,10 @@
  * Handles rendering of the main offline manager panel
  * Refactored to use modular components
  */
-import { OfflineMapManager } from '../../managers/offlineMapManager';
+import { OfflineMapManager } from '../../managers/offlineMapManager.js';
 import { DownloadManager } from './downloadManager';
-import { ModalManager } from '../../ui/modals/modalManager';
-import { BaseComponent } from '../../ui/components/shared/BaseComponent';
+import { ModalManager } from '../modals/modalManager.js';
+import { BaseComponent } from '../components/shared/BaseComponent.js';
 type MaplibreMap = unknown;
 export interface PanelRendererOptions {
     offlineManager: OfflineMapManager;
@@ -31,10 +31,12 @@ export declare class PanelRenderer extends BaseComponent {
     private headerContainer?;
     private actionButtonsContainer?;
     private regionsList?;
+    private awaitingProgressRender;
     private downloadProgressContainer?;
     private languageSelector?;
     private refreshTimeout?;
     private isRefreshing;
+    private refreshQueued;
     private unsubscribeLanguage?;
     private regionActionHandler?;
     constructor(options: PanelRendererOptions);
@@ -79,6 +81,13 @@ export declare class PanelRenderer extends BaseComponent {
      * Create orphaned regions header template
      */
     private createOrphanedRegionsHeaderTemplate;
+    /**
+     * Show the latest download progress. Called on every update, so it only
+     * redraws the progress section rather than the whole panel.
+     */
+    updateDownloadProgress(downloads: ReadonlyMap<string, unknown>): void;
+    /** What the current phase is doing, such as "Tiles: 64 of 128". */
+    private describeDownloadPhase;
     /**
      * Create download progress HTML
      */
@@ -158,6 +167,10 @@ export declare class PanelRenderer extends BaseComponent {
     /**
      * Handle loading a style to the map
      */
+    /** Whether the map is drawing this stored style, through `idb://` or the Service Worker. */
+    private isStyleShown;
+    /** After its stored copy is deleted, show a style from its original URL, not a blank map. */
+    private showOnlineStyle;
     private handleLoadStyle;
     /**
      * Handle deleting a style

package/dist/ui/managers/downloadManager.d.ts

@@ -44,8 +44,8 @@
  *
  * @module downloadManager
  */
-import { OfflineMapManager } from '../../managers/offlineMapManager';
-import { RegionFormData } from '../../ui/modals/regionFormModal';
+import { OfflineMapManager } from '../../managers/offlineMapManager.js';
+import { RegionFormData } from '../modals/regionFormModal.js';
 /**
  * Progress information for an active download.
  *
@@ -70,8 +70,10 @@ export interface DownloadProgress {
     completed: number;
     /** Total number of resources in current phase */
     total: number;
-    /** Completion percentage (0-100) */
+    /** How far through the whole download (0-100). Only moves forward. */
     percentage: number;
+    /** How far through the current phase (0-100). */
+    phasePercentage?: number;
     /** Human-readable description of current activity */
     currentResource: string;
     /** Current download phase */
@@ -119,6 +121,8 @@ export declare class DownloadManager {
     private offlineManager;
     /** Map of region IDs to their download progress */
     private currentDownloads;
+    /** Aborts each running download, by region id. */
+    private controllers;
     private options;
     /**
      * Create a new DownloadManager instance.

package/dist/ui/modals/mbtilesModal.d.ts

@@ -4,7 +4,7 @@
  * Focused modal for exchanging regions as binary SQLite MBTiles archives.
  * Replaces the previous multi-format import/export modal.
  */
-import type { StoredRegion, ImportExportOptions, MBTilesExportOptions, ExportResult, ImportResult, RegionImportData } from '../../types';
+import type { StoredRegion, ImportExportOptions, MBTilesExportOptions, ExportResult, ImportResult, RegionImportData } from '../../types/index.js';
 type MBTilesExportRequestOptions = ImportExportOptions & MBTilesExportOptions;
 export interface MBTilesModalOptions {
     region: StoredRegion;

package/dist/ui/modals/regionDetailsModal.d.ts

@@ -3,7 +3,7 @@
  * Shows detailed information about a specific region
  * Refactored to use modular components
  */
-import { StoredRegion } from '../../types/region';
+import { StoredRegion } from '../../types/region.js';
 export interface RegionDetailsOptions {
     region: StoredRegion;
     onClose: () => void;

package/dist/ui/modals/regionFormModal.d.ts

@@ -12,7 +12,7 @@ export interface RegionFormData {
     provider?: 'mapbox' | 'maplibre' | 'auto';
     accessToken?: string | null;
     /** Additional tile sources to download alongside the style's own sources */
-    extraSources?: import('../../types/region').ExtraSource[];
+    extraSources?: import('../../types/region.js').ExtraSource[];
 }
 /**
  * A tile source discovered on the live map, presented to the user for selection.
@@ -42,6 +42,11 @@ export interface RegionFormOptions {
     /** Tile sources discovered from the live map for user selection */
     mapSources?: MapTileSource[];
 }
+/**
+ * True when a region of Mapbox Standard stops below the zoom where its buildings
+ * start. Standard Satellite has no buildings, so it doesn't count.
+ */
+export declare function regionMissesBuildings(styleUrl: string, maxZoom: number): boolean;
 export declare class RegionFormModal {
     private options;
     private modal?;
@@ -49,6 +54,7 @@ export declare class RegionFormModal {
     private minZoomInput?;
     private maxZoomInput?;
     private styleUrlInput?;
+    private buildingsHint?;
     private providerSelect?;
     private accessTokenInput?;
     private accessTokenGroup?;
@@ -73,6 +79,8 @@ export declare class RegionFormModal {
     /**
      * Handle style URL changes to auto-detect provider
      */
+    /** Warn when a region would be saved without the style's buildings. */
+    private updateBuildingsHint;
     private handleStyleUrlChange;
     /**
      * Handle provider selection changes
@@ -90,6 +98,8 @@ export declare class RegionFormModal {
      * Create the footer with action buttons
      */
     private createFooter;
+    /** Check the zoom fields, showing the browser's message on the first bad one. */
+    private zoomRangeIsValid;
     /**
      * Handle form save
      */

package/dist/ui/offlineManagerControl.d.ts

@@ -35,7 +35,7 @@
  * @module offlineManagerControl
  */
 import type { IControl } from 'maplibre-gl';
-import { OfflineMapManager } from '../managers/offlineMapManager';
+import { OfflineMapManager } from '../managers/offlineMapManager.js';
 /**
  * Request shape MapLibre passes to a protocol handler. `type` indicates how
  * the response will be consumed — `"json"` for sprite atlases / TileJSON,
@@ -127,6 +127,9 @@ export declare class OfflineManagerControl implements IControl {
     private regionControl;
     private downloadManager;
     private modalManager;
+    /** Percentages of this batch's downloads, finished ones at 100, for the badge. */
+    private badgeBatch;
+    private badgePercentage;
     /** Whether the bounding box visualization layer has been added to the map */
     private bboxLayerAdded;
     /** Map library module for protocol registration (null if not provided) */

package/dist/ui/translations/ar.d.ts

@@ -24,7 +24,7 @@ export declare const ar: {
     readonly 'language.en': "الإنجليزية";
     readonly 'language.ar': "العربية";
     readonly 'header.title': "مدير الخرائط غير المتصلة";
-    readonly 'header.subtitle': "{{count}} منطقة • {{size}} إجمالي";
+    readonly 'header.subtitle': "{{regions}} • {{size}} إجمالي";
     readonly 'actions.addRegion': "إضافة منطقة";
     readonly 'actions.refresh': "تحديث";
     readonly 'actions.loadStyle': "تحميل النمط";
@@ -38,6 +38,8 @@ export declare const ar: {
     readonly 'regionForm.namePlaceholder': "مثال: وسط المدينة";
     readonly 'regionForm.minZoom': "أدنى تكبير";
     readonly 'regionForm.maxZoom': "أقصى تكبير";
+    readonly 'regionForm.buildingsHint': "تبدأ مباني Mapbox Standard عند مستوى التكبير 15. اضبط أقصى تكبير على 15 أو أكثر لتضمينها.";
+    readonly 'regionForm.zoomRangeError': "يجب ألا يقل أقصى تكبير عن أدنى تكبير.";
     readonly 'regionForm.styleUrl': "رابط النمط";
     readonly 'regionForm.provider': "مزود النمط";
     readonly 'regionForm.providerAuto': "اكتشاف تلقائي";
@@ -66,7 +68,10 @@ export declare const ar: {
     readonly 'regionList.downloaded': "تم التحميل";
     readonly 'regionList.size': "الحجم";
     readonly 'regionList.tiles': "البلاطات";
+    readonly 'regionList.resources': "الخطوط والرموز والنماذج";
     readonly 'regionList.styleData': "النمط";
+    readonly 'regionList.regionCountOne': "منطقة واحدة";
+    readonly 'regionList.regionCount': "{{count}} منطقة";
     readonly 'regionList.totalSize': "الإجمالي";
     readonly 'regionList.styleId': "معرف النمط";
     readonly 'regionDetails.title': "تفاصيل المنطقة";
@@ -138,6 +143,14 @@ export declare const ar: {
     readonly 'mbtiles.importComplete': "اكتمل الاستيراد!";
     readonly 'mbtiles.importFailed': "فشل الاستيراد. يرجى المحاولة مرة أخرى.";
     readonly 'download.activeCount': "التحميلات النشطة ({{count}})";
+    readonly 'download.status.style': "جارٍ تجهيز النمط";
+    readonly 'download.status.sprites': "الرموز: {{completed}} من {{total}}";
+    readonly 'download.status.glyphs': "الخطوط: {{completed}} من {{total}}";
+    readonly 'download.status.models': "النماذج ثلاثية الأبعاد: {{completed}} من {{total}}";
+    readonly 'download.status.tiles': "البلاطات: {{completed}} من {{total}}";
+    readonly 'download.status.planning': "جارٍ تخطيط البلاطات";
+    readonly 'download.cancelRegion': "إلغاء تحميل {{name}}";
+    readonly 'download.status.saving': "جارٍ حفظ المنطقة";
     readonly 'panel.downloadedRegions': "المناطق المحملة";
     readonly 'panel.noExpiry': "بدون انتهاء";
     readonly 'panel.noBounds': "بدون حدود";
@@ -153,6 +166,8 @@ export declare const ar: {
     readonly 'control.cancelSelection': "إلغاء التحديد";
     readonly 'control.saveSelectedRegion': "حفظ المنطقة المحددة";
     readonly 'alert.unknownError': "حدث خطأ غير معروف";
+    readonly 'alert.downloadFailed': "فشل التحميل";
+    readonly 'alert.needsMapboxGl': "يستخدم هذا النمط ميزات Mapbox GL JS، مثل النماذج ثلاثية الأبعاد أو إعدادات النمط، لذا لا يمكن عرضه إلا على خريطة Mapbox GL.";
     readonly 'alert.downloadNotImplemented': "ميزة التحميل غير مطبقة في هذه النسخة";
     readonly 'alert.mapNotAvailable': "الخريطة غير متاحة";
     readonly 'alert.invalidBounds': "حدود غير صالحة للمنطقة";

package/dist/ui/translations/en.d.ts

@@ -23,7 +23,7 @@ export declare const en: {
     readonly 'language.en': "English";
     readonly 'language.ar': "Arabic";
     readonly 'header.title': "Offline Manager";
-    readonly 'header.subtitle': "{{count}} regions • {{size}} total";
+    readonly 'header.subtitle': "{{regions}} • {{size}} total";
     readonly 'actions.addRegion': "Add Region";
     readonly 'actions.refresh': "Refresh";
     readonly 'actions.loadStyle': "Load Style";
@@ -37,6 +37,8 @@ export declare const en: {
     readonly 'regionForm.namePlaceholder': "e.g., Downtown District";
     readonly 'regionForm.minZoom': "Min Zoom";
     readonly 'regionForm.maxZoom': "Max Zoom";
+    readonly 'regionForm.buildingsHint': "Mapbox Standard's buildings start at zoom 15. Set Max Zoom to 15 or more to include them.";
+    readonly 'regionForm.zoomRangeError': "Max Zoom must be at least Min Zoom.";
     readonly 'regionForm.styleUrl': "Style URL";
     readonly 'regionForm.provider': "Style Provider";
     readonly 'regionForm.providerAuto': "Auto-detect";
@@ -65,7 +67,10 @@ export declare const en: {
     readonly 'regionList.downloaded': "Downloaded";
     readonly 'regionList.size': "Size";
     readonly 'regionList.tiles': "Tiles";
+    readonly 'regionList.resources': "Fonts, icons and models";
     readonly 'regionList.styleData': "Style";
+    readonly 'regionList.regionCountOne': "1 region";
+    readonly 'regionList.regionCount': "{{count}} regions";
     readonly 'regionList.totalSize': "Total";
     readonly 'regionList.styleId': "Style ID";
     readonly 'regionDetails.title': "Region Details";
@@ -137,6 +142,14 @@ export declare const en: {
     readonly 'mbtiles.importComplete': "Import complete!";
     readonly 'mbtiles.importFailed': "Import failed. Please try again.";
     readonly 'download.activeCount': "Active Downloads ({{count}})";
+    readonly 'download.status.style': "Preparing style";
+    readonly 'download.status.sprites': "Sprites: {{completed}} of {{total}}";
+    readonly 'download.status.glyphs': "Fonts: {{completed}} of {{total}}";
+    readonly 'download.status.models': "3D models: {{completed}} of {{total}}";
+    readonly 'download.status.tiles': "Tiles: {{completed}} of {{total}}";
+    readonly 'download.status.planning': "Planning tiles";
+    readonly 'download.cancelRegion': "Cancel downloading {{name}}";
+    readonly 'download.status.saving': "Saving region";
     readonly 'panel.downloadedRegions': "Downloaded Regions";
     readonly 'panel.noExpiry': "No expiry";
     readonly 'panel.noBounds': "No bounds";
@@ -152,6 +165,8 @@ export declare const en: {
     readonly 'control.cancelSelection': "Cancel Selection";
     readonly 'control.saveSelectedRegion': "Save Selected Region";
     readonly 'alert.unknownError': "Unknown error occurred";
+    readonly 'alert.downloadFailed': "Download failed";
+    readonly 'alert.needsMapboxGl': "This style uses Mapbox GL JS features, such as 3D models or style config, so only a Mapbox GL map can show it.";
     readonly 'alert.downloadNotImplemented': "Download feature not implemented in this refactored version";
     readonly 'alert.mapNotAvailable': "Map not available";
     readonly 'alert.invalidBounds': "Invalid bounds for region";

package/dist/ui/translations/index.d.ts

@@ -57,5 +57,7 @@ declare class I18nManager {
 }
 export declare const i18n: I18nManager;
 export declare const t: (key: TranslationKey, replacements?: Record<string, string | number>) => string;
+/** "1 region" or "3 regions", in the current language. */
+export declare const regionCountLabel: (count: number) => string;
 export { i18next };
 export { en, ar };

package/dist/utils/constants.d.ts

@@ -84,8 +84,10 @@ export declare const MAPBOX_API: {
 /**
  * Mapbox Standard sub-tilesets that are sparse-by-design across the planet.
  * These only have tiles where the underlying feature (indoor venues, landmark
- * POIs, 3D procedural buildings) actually exists, and return 404 for nearly
- * every other coordinate. The tile downloader pre-skips any source whose tile
+ * POIs, 3D procedural buildings) actually exists, and return 404 for every other
+ * coordinate, though they can be dense inside a major city. Unless the style's
+ * config has switched on a feature that needs one, the tile downloader pre-skips
+ * any source whose tile
  * URL templates reference one of these tileset IDs, so we never issue probe
  * or download requests for them — eliminating the 404 noise in devtools.
  *

package/dist/utils/convertStyleForSW.d.ts

@@ -1,4 +1,4 @@
-import type { MapboxStyle } from '../types/style';
+import type { MapboxStyle } from '../types/style.js';
 /**
  * Convert a style with `idb://` URLs to use absolute `/__offline__/` HTTP URLs
  * so that a Service Worker can intercept the requests from web workers.

package/dist/utils/download.d.ts

@@ -1,4 +1,4 @@
-import type { DownloadProgress } from '../types';
+import type { DownloadProgress } from '../types/index.js';
 import { type ProxyType } from './proxyConfig';
 export type FetchResourceResult = {
     type: 'json';

package/dist/utils/formatting.d.ts

@@ -5,6 +5,17 @@
  * Format bytes to human readable string
  */
 export declare function formatBytes(bytes: number): string;
+/**
+ * A stored style's display name: its own `name`, or else the last meaningful
+ * part of its URL ("liberty" for `.../styles/liberty`), or else its key.
+ */
+export declare function styleDisplayName(entry: {
+    key: string;
+    originalUrl?: string;
+    style?: {
+        name?: string;
+    };
+}): string;
 /**
  * Format date to human readable string
  */

package/dist/utils/importResolver.d.ts

@@ -6,7 +6,7 @@
  * into the outer style. This allows the existing download pipeline to work
  * unchanged with import-based styles like Mapbox Standard.
  */
-import type { BaseStyle } from '../types/style';
+import type { BaseStyle } from '../types/style.js';
 /** A single import entry in a style's `imports` array */
 export interface StyleImport {
     id: string;

package/dist/utils/styleConfig.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Mapbox GL v3 style-config helpers.
+ *
+ * Mapbox Standard is one style with switchable features: most of its layers set
+ * `layout.visibility` from `["config", key]` expressions backed by `style.schema`
+ * defaults. These helpers work out which sources the style actually needs for
+ * the current config, so features that are switched off aren't downloaded and
+ * features that are switched on aren't skipped.
+ */
+import type { BaseStyle } from '../types/style.js';
+type ConfigValues = Record<string, unknown>;
+/**
+ * True for styles whose feature set is config-driven: they declare a `schema`,
+ * or were flattened from `imports` (whose config is already resolved into the
+ * layers). Other styles are never filtered by config.
+ */
+export declare function isConfigDrivenStyle(style: unknown): boolean;
+/**
+ * Sources a config-driven style uses under its current config (`active`), and
+ * those it references but only from hidden layers or unused iconsets (`inactive`).
+ *
+ * Deliberately errs towards keeping sources: a visibility expression that can't
+ * be decided counts as visible. Sources nothing in the style references
+ * (`extraSources`, ones a caller adds at runtime) are in neither set.
+ */
+export declare function classifySources(style: unknown): {
+    active: Set<string>;
+    inactive: Set<string>;
+};
+/** The sources {@link classifySources} found to be unneeded under the current config. */
+export declare function findInactiveSources(style: unknown): Set<string>;
+/**
+ * Write config values into a style's `schema` defaults. `["config", key]` reads
+ * those defaults at render time, so this one edit drives both what gets
+ * downloaded and what the stored style shows offline. Keys the schema doesn't
+ * declare are ignored with a warning.
+ */
+export declare function applyStyleConfig(style: BaseStyle, config: ConfigValues): void;
+export {};

package/dist/utils/styleProviderUtils.d.ts

@@ -2,7 +2,7 @@
  * Style Provider Detection and Handling Utilities
  * Supports both Mapbox GL and MapLibre GL styles
  */
-import type { BaseStyle, StyleProvider } from '../types/style';
+import type { BaseStyle, StyleProvider } from '../types/style.js';
 /**
  * Check if a URL uses the mapbox:// protocol
  */
@@ -34,17 +34,30 @@ export declare function isMapboxHost(url: string, base?: string): boolean;
  */
 export declare function resolveMapboxUrl(mapboxUrl: string, accessToken: string): string;
 /**
- * Rewrite Mapbox CDN tile URLs to use the api.mapbox.com/v4 endpoint.
+ * Pick the TileJSON variant Mapbox GL renders from, the way its `mergeVariants`
+ * does: `meshopt-v2+lod`, then `meshopt`, then the base tileset.
  *
- * TileJSON responses from Mapbox return tile URLs on *.tiles.mapbox.com CDN
- * which may use paths like /raster/v1/ that require an SKU session token
- * generated by the Mapbox GL JS SDK at runtime. Since we fetch tiles directly
- * without the SDK, these 401. The /v4/ API endpoint on api.mapbox.com works
- * with just an access_token, so we rewrite CDN URLs to use it.
+ * These aren't just different encodings of one dataset. For
+ * `mapbox.mapbox-3dbuildings-v1`, the base tile over central Dubai is empty while
+ * the variants hold its 3D buildings, so downloading the base loses them offline.
+ * Variant tiles are `mapbox://3dtiles/...` URLs, resolved here using the base
+ * URL's query string, which carries the access token.
+ */
+export declare function selectTileJsonVariant<T extends object>(tileJson: T): T;
+/**
+ * Add the `sku` session token that Mapbox `/raster/v1/` tile URLs need.
+ *
+ * TileJSON returns these URLs without one, and without it they 401. Mapbox GL
+ * adds it at request time, but this library fetches tiles itself.
+ *
+ * Don't switch these to the `/v4/` endpoint, which needs no token: it serves a
+ * different tile. For `mapbox.mapbox-terrain-dem-v1`, `/v4/….png` is a 256px
+ * palette PNG with elevations off by up to ~200 m, while the renderer expects
+ * the 514px RGB tile (`tileSize: 514`) that `/raster/v1/` returns.
  *
  * Example:
  *   https://a.tiles.mapbox.com/raster/v1/mapbox.mapbox-terrain-dem-v1/{z}/{x}/{y}.png?access_token=...
- *   -> https://api.mapbox.com/v4/mapbox.mapbox-terrain-dem-v1/{z}/{x}/{y}.png?access_token=...
+ *   -> https://a.tiles.mapbox.com/raster/v1/mapbox.mapbox-terrain-dem-v1/{z}/{x}/{y}.png?access_token=...&sku=101...
  */
 export declare function rewriteMapboxCdnTileUrl(tileUrl: string): string;
 /**

package/dist/utils/styleUtils.d.ts

@@ -1,22 +1,72 @@
-import type { MapboxStyle } from '../types/style';
+import type { MapboxStyle } from '../types/style.js';
 /**
- * Patches a MapboxStyle for offline use by replacing URLs with IndexedDB references
+ * Patches a MapboxStyle for offline use by replacing URLs with IndexedDB references.
+ *
+ * Safe to call repeatedly on the same stored style (every `addRegion` does):
+ * the first call stashes each source's upstream `tiles` / `maxzoom` under
+ * `__originalTiles` / `__originalMaxzoom`, and later calls patch from those,
+ * so the download pipeline can still reach the network and `maxzoom` can grow
+ * again when a deeper region is added.
+ *
  * @param style - The style to patch
- * @param downloadId - The download/region ID for tiles and other resources
- * @param maxZoom - Optional max zoom level for sources
+ * @param downloadId - Fallback ID for `idb://` URLs when `styleId` is omitted
+ * @param maxZoom - Max zoom downloaded for this style (the highest across its regions)
  * @param tileExtension - Optional tile extension
- * @param styleId - Optional style ID for sprites (if different from downloadId). Sprites are shared
- *                  across regions and stored with the style ID, so this parameter allows the sprite
- *                  URLs to correctly reference the style ID.
+ * @param styleId - Style ID used in all `idb://` URLs. Tiles, glyphs, sprites and
+ *                  models are stored per style, so URLs keyed by style keep working
+ *                  when any one region is deleted.
+ */
+/**
+ * Add a region's extra tile sources to a style, unless one with that id is
+ * already there. Sources must be in the style before it's patched for offline use.
+ */
+export declare function injectExtraSources(style: {
+    sources: Record<string, unknown>;
+}, extraSources?: ReadonlyArray<{
+    id: string;
+    tiles: string[];
+    type?: string;
+    minzoom?: number;
+    maxzoom?: number;
+    attribution?: string;
+}>): void;
+/**
+ * Keep each model's upstream URL before the style is patched, the first time
+ * only. Patching points every model at `idb://`, so without this a model that
+ * failed to download couldn't be fetched again.
+ */
+export declare function stashOriginalModels(entry: {
+    style: object;
+    originalModels?: Record<string, unknown>;
+}): void;
+/**
+ * Point models that aren't stored back at their upstream URLs. Run after
+ * patching, which points every model at `idb://`.
  */
+export declare function restoreUnstoredModels(entry: {
+    style: object;
+    originalModels?: Record<string, unknown>;
+}, storedNames: ReadonlySet<string>): void;
+/**
+ * Whether a style uses parts of the spec only Mapbox GL JS v3 draws: config
+ * (`schema`), 3D `models`, `lights` or `imports`. MapLibre rejects these.
+ */
+export declare function needsMapboxGl(style: object): boolean;
+/** Whether a map instance is Mapbox GL JS v3, the only renderer with style config. */
+export declare function isMapboxGlMap(map: unknown): boolean;
 export declare function patchStyleForOffline(style: MapboxStyle, downloadId: string, maxZoom?: number, tileExtension?: string, styleId?: string): MapboxStyle;
+type FontSchema = Record<string, {
+    default?: unknown;
+}>;
 /**
  * Extract individual font names from a `text-font` layout property value.
  *
- * Handles both simple arrays (`["Font A", "Font B"]`) and Mapbox GL expression
- * syntax (e.g. `["step", ["zoom"], ["literal", ["Font A"]], 10, ["literal", ["Font B"]]]`).
+ * Handles simple arrays (`["Font A", "Font B"]`), Mapbox GL expression syntax
+ * (e.g. `["step", ["zoom"], ["literal", ["Font A"]], 10, ["literal", ["Font B"]]]`),
+ * and Mapbox Standard's config-built stacks
+ * (`[["concat", ["config", "font"], " Medium"], "Arial Unicode MS Bold"]`).
  */
-export declare function extractFontNamesFromTextField(textFont: unknown): string[];
+export declare function extractFontNamesFromTextField(textFont: unknown, schema?: FontSchema): string[];
 /**
  * Normalize a style's `sprite` property into a uniform array of {id, url} sources.
  * Handles string format, array format, and filters out already-patched idb:// URLs.
@@ -51,3 +101,4 @@ export declare function generateGlyphUrlsFromStyle(style: {
         };
     }>;
 }, glyphsUrlTemplate: string, ranges?: Array<[number, number]>): string[];
+export {};

package/dist/utils/tileRange.d.ts

@@ -0,0 +1,63 @@
+export interface TileRange {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+}
+/**
+ * XYZ tile range covering `bounds` at zoom `z`. Shared by the download
+ * pipeline (which fetches exactly this range) and region-scoped consumers
+ * like MBTiles export, so both agree on which tiles belong to a region.
+ */
+export declare function getTileRangeAtZoom(bounds: [[number, number], [number, number]], z: number): TileRange;
+/**
+ * Whether tile `z/x/y` falls inside `bounds` and `[minZoom, maxZoom]`.
+ */
+export declare function isTileInRegion(z: number, x: number, y: number, region: {
+    bounds: [[number, number], [number, number]];
+    minZoom: number;
+    maxZoom: number;
+}): boolean;
+/**
+ * Zoom levels to download for one source in `region`: the overlap of the
+ * region's and the source's zoom ranges. When they don't overlap, the source
+ * still gets the zooms the map needs from it:
+ * - source ends below the region (`maxzoom` < region min) → its `maxzoom`,
+ *   which the renderer overzooms for the region's zooms;
+ * - source starts above the region (`minzoom` > region max) → `minzoom`
+ *   through `maxzoom` (or just `minzoom` if unbounded).
+ */
+export declare function sourceZoomRange(region: {
+    minZoom: number;
+    maxZoom: number;
+}, sourceMinZoom?: number, sourceMaxZoom?: number): {
+    min: number;
+    max: number;
+};
+/** Zoom fields of a stored style source (possibly patched by patchStyleForOffline). */
+export interface SourceZoomConfig {
+    minzoom?: number;
+    maxzoom?: number;
+    __originalMaxzoom?: number | null;
+}
+/**
+ * A stored source's upstream `maxzoom`. Patched styles cap `maxzoom` for
+ * rendering and stash the upstream value under `__originalMaxzoom`.
+ */
+export declare function upstreamMaxzoom(source: SourceZoomConfig | undefined): number | undefined;
+/**
+ * Whether a stored tile was downloaded for `region`: inside its bounds, at a
+ * zoom the download pipeline fetches for the tile's source (which can fall
+ * outside the region's own range — see `sourceZoomRange`). `sources` is the
+ * stored style's `sources`. Regions with malformed bounds match nothing.
+ */
+export declare function tileBelongsToRegion(tile: {
+    sourceId?: string;
+    z: number;
+    x: number;
+    y: number;
+}, region: {
+    bounds: [[number, number], [number, number]];
+    minZoom: number;
+    maxZoom: number;
+}, sources: Record<string, SourceZoomConfig | undefined>): boolean;

package/dist/utils/validation.d.ts

@@ -2,7 +2,7 @@
  * Validation utilities for common patterns
  * Provides reusable validation functions to ensure data integrity
  */
-import type { OfflineRegionOptions } from '../types';
+import type { OfflineRegionOptions } from '../types/index.js';
 /**
  * Validate geographic bounds
  * @param bounds - Array of two [lng, lat] coordinate pairs