map-gl-offline 0.5.6 → 0.7.0

package/dist/types/database.d.ts

@@ -5,6 +5,7 @@ import type { FontEntry } from './font';
 import type { TileEntry } from './tile';
 import type { SpriteEntry } from './sprite';
 import type { GlyphEntry } from './glyph';
+import type { ModelEntry } from './model';
 export interface OfflineMapDB extends DBSchema {
     /**
      * @deprecated Regions are now stored inside styles.regions[] array.
@@ -35,4 +36,12 @@ export interface OfflineMapDB extends DBSchema {
         key: string;
         value: FontEntry;
     };
+    /**
+     * 3D model files (.glb) referenced by `style.models` entries. Used by
+     * Mapbox Standard for tree / wind-turbine model layers.
+     */
+    models: {
+        key: string;
+        value: ModelEntry;
+    };
 }

package/dist/types/index.d.ts

@@ -4,6 +4,7 @@ export * from './font';
 export * from './tile';
 export * from './sprite';
 export * from './glyph';
+export * from './model';
 export * from './database';
 export * from './maintenance';
 export * from './progress';

package/dist/types/model.d.ts

@@ -0,0 +1,62 @@
+import { DownloadProgress } from './progress';
+/**
+ * 3D model asset (e.g. a tree or turbine .glb) stored in IndexedDB.
+ *
+ * Mapbox Standard references 32 models via the top-level `style.models`
+ * dictionary (`{ "maple1-lod1": "mapbox://models/mapbox/maple1-v4-lod1.glb" }`).
+ * Layers of type `model` then pick one by name at render time.
+ */
+export interface ModelEntry {
+    /** Storage key: `{styleId}::model::{modelName}`. */
+    key: string;
+    /** Model binary (.glb / .gltf) as ArrayBuffer. */
+    data: ArrayBuffer;
+    /** HTTP Content-Type (usually `model/gltf-binary`). */
+    contentType: string;
+    /** Byte length. */
+    size: number;
+    /** URL the model was downloaded from. */
+    url: string;
+    /** Style this model belongs to. */
+    styleId: string;
+    /** Model name (the key in `style.models`). */
+    modelName: string;
+    /** Last-Modified or download timestamp (ms since epoch). */
+    lastModified: number;
+    /** ISO 8601 download timestamp. */
+    downloadedAt: string;
+    /** Optional expiry from HTTP Cache-Control. */
+    expires?: number;
+}
+/** Options for `downloadModels`. */
+export interface ModelDownloadOptions {
+    onProgress?: (progress: DownloadProgress) => void;
+    batchSize?: number;
+    maxRetries?: number;
+    skipExisting?: boolean;
+    timeoutMs?: number;
+}
+/** Result of a model download batch. */
+export interface ModelDownloadResult {
+    totalModels: number;
+    downloadedModels: number;
+    skippedModels: number;
+    failedModels: number;
+    totalSize: number;
+    errors: Array<{
+        url: string;
+        error: string;
+    }>;
+}
+/** Aggregate stats across stored models. */
+export interface EnhancedModelStats {
+    count: number;
+    totalSize: number;
+    averageSize: number;
+    models: Array<{
+        name: string;
+        size: number;
+        lastModified?: number;
+    }>;
+    modelsByStyle: Record<string, number>;
+}

package/dist/types/region.d.ts

@@ -1,3 +1,62 @@
+import type { StyleProvider } from './style';
+import type { TileDownloadOptions, TileDownloadResult } from './tile';
+import type { SpriteDownloadResult } from './sprite';
+import type { GlyphDownloadResult } from './glyph';
+import type { ModelDownloadResult } from './model';
+import type { StyleDownloadResult } from './style';
+/**
+ * Phase of a region download pipeline, reported via `DownloadRegionOptions.onProgress`.
+ */
+export type DownloadRegionPhase = 'style' | 'sprites' | 'glyphs' | 'models' | 'tiles' | 'metadata';
+/**
+ * Progress update emitted by `OfflineMapManager.downloadRegion`.
+ */
+export interface DownloadRegionProgress {
+    phase: DownloadRegionPhase;
+    completed: number;
+    total: number;
+    percentage: number;
+    message?: string;
+}
+/**
+ * Options for the programmatic `downloadRegion` pipeline.
+ */
+export interface DownloadRegionOptions {
+    /** Called with per-phase progress during style → sprites → glyphs → tiles → metadata. */
+    onProgress?: (progress: DownloadRegionProgress) => void;
+    /** Style provider hint when the style needs to be fetched. Defaults to 'auto'. */
+    provider?: StyleProvider;
+    /** Mapbox access token; required when the style or sources use mapbox:// URLs. */
+    accessToken?: string;
+    /** Skip glyph download entirely. Default: false. */
+    skipGlyphs?: boolean;
+    /** Skip sprite download entirely. Default: false. */
+    skipSprites?: boolean;
+    /**
+     * Skip 3D model download. Default: false. Models (e.g. Mapbox Standard
+     * trees / wind turbines) are declared via `style.models` and live at
+     * `mapbox://models/…` URLs that only Mapbox serves. Skip for styles that
+     * don't use model layers, or to reduce storage footprint at the cost of
+     * missing tree/turbine rendering.
+     */
+    skipModels?: boolean;
+    /** Override Unicode glyph ranges fetched per font. Defaults to `GLYPH_CONFIG.COMPREHENSIVE_RANGES`. */
+    glyphRanges?: string[];
+    /** Extra options forwarded to the tile download step. */
+    tileOptions?: TileDownloadOptions;
+}
+/**
+ * Result of a full `downloadRegion` pipeline.
+ */
+export interface DownloadRegionResult {
+    regionId: string;
+    styleId: string;
+    styleResult?: StyleDownloadResult;
+    spriteResults: SpriteDownloadResult[];
+    glyphResult?: GlyphDownloadResult;
+    modelResult?: ModelDownloadResult;
+    tileResult: TileDownloadResult;
+}
 /**
  * Stored region with metadata
  * Extends OfflineRegionOptions with database-specific fields

package/dist/types/style.d.ts

@@ -19,8 +19,17 @@ export interface BaseStyle {
         data?: BaseStyle;
         config?: Record<string, unknown>;
     }>;
-    models?: Record<string, {
-        uri: string;
+    /**
+     * 3D model declarations used by `model` layers (Mapbox Standard trees /
+     * wind turbines). Two shapes are accepted in the wild:
+     *
+     * - Mapbox Standard format — values are plain URI strings:
+     *   `{ "maple1-lod1": "mapbox://models/mapbox/maple1-v4-lod1.glb" }`
+     * - Older / generic format — values wrap the URI in an object:
+     *   `{ "name": { "uri": "mapbox://..." } }`
+     */
+    models?: Record<string, string | {
+        uri?: string;
         [key: string]: unknown;
     }>;
     [key: string]: unknown;

package/dist/types/tile.d.ts

@@ -65,6 +65,21 @@ export interface TileDownloadOptions {
     bandwidthLimit?: number;
     /** Check storage quota before download (default: true) */
     storageQuotaCheck?: boolean;
+    /**
+     * Before committing to download a source's full tile plan, probe one
+     * representative tile. If that probe returns 404, the source is treated
+     * as sparse-for-this-region and skipped entirely. This adapts to the
+     * region (some cities have indoor/landmark/3D-building data, others
+     * don't) without requiring a static skip list.
+     *
+     * One probe HTTP request is added per source. The probe itself may
+     * 404 (visible in the Network tab), but downstream we then avoid
+     * dozens of follow-up 404s.
+     *
+     * Default: `true`. Set `false` to download every source regardless
+     * (old behavior — noisier, but guaranteed-complete).
+     */
+    probeSourcesBeforeDownload?: boolean;
 }
 /**
  * Result of a tile download operation

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

@@ -74,7 +74,7 @@ export interface DownloadProgress {
     /** Human-readable description of current activity */
     currentResource: string;
     /** Current download phase */
-    phase?: 'style' | 'sprites' | 'glyphs' | 'tiles';
+    phase?: 'style' | 'sprites' | 'glyphs' | 'models' | 'tiles';
 }
 /**
  * Configuration options for the DownloadManager.
@@ -172,11 +172,6 @@ export declare class DownloadManager {
      * @internal
      */
     private updateUIForDownloadStart;
-    /**
-     * Normalize the style's sprite property into a uniform array of {id, url} sources.
-     * Handles string format, array format, and filters out already-patched idb:// URLs.
-     */
-    private normalizeSpriteProperty;
     /**
      * Handle successful completion of a region download.
      * Removes from tracking, resets UI if needed, and notifies listeners.

package/dist/ui/offlineManagerControl.d.ts

@@ -232,10 +232,6 @@ export declare class OfflineManagerControl implements IControl {
      * ```
      */
     loadOfflineStyle(styleId: string): Promise<void>;
-    /**
-     * Load styles from IndexedDB and apply to map
-     */
-    private loadStylesFromIDB;
     /**
      * Show modal to select which style to load
      */
@@ -253,13 +249,6 @@ export declare class OfflineManagerControl implements IControl {
      * ```
      */
     loadOfflineStyles(): Promise<void>;
-    /**
-     * Load a specific offline style by its ID.
-     * Alias for `loadOfflineStyle()` for API clarity.
-     *
-     * @param styleId - The unique identifier of the stored style
-     */
-    loadSpecificOfflineStyle(styleId: string): Promise<void>;
     /**
      * Update the style URL used for new region downloads.
      *

package/dist/utils/constants.d.ts

@@ -3,13 +3,14 @@
  * Centralizes magic numbers and configuration values
  */
 export declare const DB_NAME = "offline-map-db";
-export declare const DB_VERSION = 3;
+export declare const DB_VERSION = 4;
 export declare const STORE_NAMES: {
     readonly TILES: "tiles";
     readonly STYLES: "styles";
     readonly SPRITES: "sprites";
     readonly GLYPHS: "glyphs";
     readonly FONTS: "fonts";
+    readonly MODELS: "models";
 };
 export declare const DOWNLOAD_DEFAULTS: {
     readonly BATCH_SIZE: 10;
@@ -27,7 +28,7 @@ export declare const TILE_CONFIG: {
 export declare const GLYPH_CONFIG: {
     readonly DEFAULT_URL: "https://tiles.openfreemap.org/fonts/{fontstack}/{range}.pbf";
     readonly DEFAULT_RANGES: readonly ["0-255"];
-    readonly COMPREHENSIVE_RANGES: readonly ["0-255", "256-511", "512-767", "768-1023", "1024-1279", "1280-1535", "1536-1791", "1792-2047", "2048-2303", "2304-2559", "2560-2815", "2816-3071", "3072-3327", "3328-3583", "3584-3839", "3840-4095", "4096-4351", "4352-4607", "4608-4863", "11904-12031", "12032-12255", "12288-12543", "12544-12799", "19968-20223", "20224-20479", "40960-42127", "44032-55203", "63744-64255", "65280-65535"];
+    readonly COMPREHENSIVE_RANGES: readonly ["0-255", "256-511", "512-767", "768-1023", "1024-1279", "1280-1535", "1536-1791", "1792-2047", "2048-2303", "2304-2559", "2560-2815", "2816-3071", "3072-3327", "3328-3583", "3584-3839", "3840-4095", "4096-4351", "4352-4607", "4608-4863", "7680-7935", "8192-8447", "8448-8703", "11904-12031", "12032-12255", "12288-12543", "12544-12799", "19968-20223", "20224-20479", "40960-42127", "44032-55203", "63744-64255", "64256-64511", "65024-65279", "65280-65535"];
 };
 export declare const STYLE_CONFIG: {
     readonly OPENFREEMAP_BASE: "https://tiles.openfreemap.org/styles";

package/dist/utils/styleUtils.d.ts

@@ -17,6 +17,14 @@ export declare function patchStyleForOffline(style: MapboxStyle, downloadId: str
  * syntax (e.g. `["step", ["zoom"], ["literal", ["Font A"]], 10, ["literal", ["Font B"]]]`).
  */
 export declare function extractFontNamesFromTextField(textFont: unknown): 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.
+ */
+export declare function normalizeSpriteProperty(sprite: unknown): Array<{
+    id: string;
+    url: string;
+}>;
 /**
  * Collect all unique font names referenced in a style's layers.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "map-gl-offline",
-  "version": "0.5.6",
+  "version": "0.7.0",
   "description": "A TypeScript-compatible npm package for MapLibre GL JS that enables comprehensive offline storage and usage of vector/raster tiles, sprites, styles, fonts (glyphs), and entire map regions with advanced analytics, import/export capabilities, and intelligent cleanup.",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",