map-gl-offline 0.6.0 → 0.7.0

package/dist/managers/offlineMapManager/resourceManagement.d.ts

@@ -20,5 +20,9 @@ export interface ResourceManagement {
     loadGlyphsForStyle: ResourceService['loadGlyphsForStyle'];
     cleanupOldGlyphs: ResourceService['cleanupOldGlyphs'];
     verifyAndRepairGlyphs: ResourceService['verifyAndRepairGlyphs'];
+    downloadModelsWithOptions: ResourceService['downloadModelsWithOptions'];
+    getModelStats: ResourceService['getModelStats'];
+    cleanupOldModels: ResourceService['cleanupOldModels'];
+    verifyAndRepairModels: ResourceService['verifyAndRepairModels'];
 }
 export declare const createResourceManagement: (services: OfflineManagerServices) => ResourceManagement;

package/dist/services/modelService.d.ts

@@ -0,0 +1,57 @@
+import type { ModelEntry, ModelDownloadOptions, ModelDownloadResult, EnhancedModelStats } from '@/types';
+/** True when the given key belongs to the given styleId's model store prefix. */
+export declare function modelKeyBelongsToStyle(key: string, styleId: string): boolean;
+/**
+ * Service for downloading, storing, and serving Mapbox 3D model (.glb) files.
+ *
+ * Mapbox Standard declares 32 models at the top of `style.models`:
+ *
+ * ```json
+ * {
+ *   "maple1-lod1": "mapbox://models/mapbox/maple1-v4-lod1.glb",
+ *   ...
+ * }
+ * ```
+ *
+ * `model` layers (e.g. `trees`, `wind-turbine-towers`) pick one by name at
+ * render time. For offline use each referenced URL is fetched and stored
+ * here, and `patchStyleForOffline` rewrites the dictionary entries to
+ * `idb://{styleId}/model/{name}` URLs.
+ */
+export declare class ModelService {
+    private db;
+    /**
+     * Download the set of models referenced by `style.models` for one style.
+     *
+     * @param models   `{ modelName: resolvedHttpUrl }` — URLs must already be
+     *                 resolved (mapbox:// URLs should be resolved by the caller).
+     * @param styleId  The owning style's key.
+     */
+    downloadModels(models: Record<string, string>, styleId: string, options?: ModelDownloadOptions): Promise<ModelDownloadResult>;
+    /** Retrieve a single model by `{styleId, modelName}`. */
+    getModel(styleId: string, modelName: string): Promise<ModelEntry | undefined>;
+    /** Aggregate stats across all stored models. */
+    getModelStats(): Promise<EnhancedModelStats>;
+    /**
+     * Delete models older than `maxAge` days. Defaults to 30.
+     */
+    cleanupOldModels(maxAge?: number): Promise<number>;
+    /**
+     * Basic integrity check: remove entries with empty/missing data.
+     */
+    verifyAndRepairModels(): Promise<{
+        verified: number;
+        repaired: number;
+        removed: number;
+    }>;
+}
+export declare const modelService: ModelService;
+export declare const downloadModels: (models: Record<string, string>, styleId: string, options?: ModelDownloadOptions) => Promise<ModelDownloadResult>;
+export declare const getModel: (styleId: string, modelName: string) => Promise<ModelEntry | undefined>;
+export declare const getModelStats: () => Promise<EnhancedModelStats>;
+export declare const cleanupOldModels: (maxAge?: number) => Promise<number>;
+export declare const verifyAndRepairModels: () => Promise<{
+    verified: number;
+    repaired: number;
+    removed: number;
+}>;

package/dist/services/resourceService.d.ts

@@ -1,5 +1,5 @@
 import { EnhancedGlyphStats } from './glyphService';
-import type { OfflineRegionOptions, MapboxStyle, TileDownloadOptions, TileDownloadResult, TileStats, SpriteDownloadOptions, SpriteDownloadResult, EnhancedSpriteStats, FontDownloadOptions, FontDownloadResult, EnhancedFontStats, GlyphDownloadOptions, GlyphDownloadResult } from '@/types';
+import type { OfflineRegionOptions, MapboxStyle, TileDownloadOptions, TileDownloadResult, TileStats, SpriteDownloadOptions, SpriteDownloadResult, EnhancedSpriteStats, FontDownloadOptions, FontDownloadResult, EnhancedFontStats, GlyphDownloadOptions, GlyphDownloadResult, ModelDownloadOptions, ModelDownloadResult, EnhancedModelStats } from '@/types';
 export declare class ResourceService {
     downloadTilesWithOptions(region: OfflineRegionOptions, style: MapboxStyle, styleId: string, options?: TileDownloadOptions): Promise<TileDownloadResult>;
     getTileStats(styleId?: string): Promise<TileStats>;
@@ -39,4 +39,14 @@ export declare class ResourceService {
         repaired: number;
         removed: number;
     }>;
+    downloadModelsWithOptions(models: Record<string, string>, styleId: string, options?: ModelDownloadOptions): Promise<ModelDownloadResult>;
+    getModelStats(): Promise<EnhancedModelStats>;
+    cleanupOldModels(options?: {
+        maxAge?: number;
+    }): Promise<number>;
+    verifyAndRepairModels(): Promise<{
+        verified: number;
+        repaired: number;
+        removed: number;
+    }>;
 }

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

@@ -2,11 +2,12 @@ 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' | 'tiles' | 'metadata';
+export type DownloadRegionPhase = 'style' | 'sprites' | 'glyphs' | 'models' | 'tiles' | 'metadata';
 /**
  * Progress update emitted by `OfflineMapManager.downloadRegion`.
  */
@@ -31,6 +32,14 @@ export interface DownloadRegionOptions {
     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. */
@@ -45,6 +54,7 @@ export interface DownloadRegionResult {
     styleResult?: StyleDownloadResult;
     spriteResults: SpriteDownloadResult[];
     glyphResult?: GlyphDownloadResult;
+    modelResult?: ModelDownloadResult;
     tileResult: TileDownloadResult;
 }
 /**

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/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.

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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "map-gl-offline",
-  "version": "0.6.0",
+  "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",