styled-map-package-api 5.0.0-pre.3 → 5.0.0-pre.4

package/README.md

@@ -43,6 +43,53 @@ const server = createServer()
 // server.fetch(request, reader) returns a WHATWG Response
 ```
 
+### Fallback tiles and glyphs
+
+When an SMP file doesn't contain every tile or glyph range that the style references, `createServer` can call fallback handlers instead of returning a 404. This is useful for previewing incomplete packages or packages that only cover a partial area/zoom range.
+
+Built-in fallback handlers are provided:
+
+```js
+import {
+  emptyTileFallback,
+  emptyGlyphFallback,
+} from 'styled-map-package-api/fallbacks'
+import { createServer } from 'styled-map-package-api/server'
+
+const server = createServer({
+  fallbackTile: emptyTileFallback,
+  fallbackGlyph: emptyGlyphFallback,
+})
+```
+
+- **`emptyTileFallback(tileId, sourceInfo)`** — Returns an appropriate empty tile based on the source's tile format: empty gzipped MVT for vector sources, 1×1 transparent PNG/WebP for raster sources.
+- **`emptyGlyphFallback(fontstack, range)`** — Returns an empty gzipped PBF (valid protobuf with no glyph entries), causing MapLibre to render missing characters as blank space instead of erroring on a 404.
+
+For real glyph rendering with Noto Sans (80+ scripts), use the [`smp-noto-glyphs`](../glyphs/) package:
+
+```js
+import { notoGlyphFallback } from 'smp-noto-glyphs'
+
+const server = createServer({
+  fallbackTile: emptyTileFallback,
+  fallbackGlyph: notoGlyphFallback,
+})
+```
+
+You can also provide custom fallback handlers, for example to proxy missing tiles from an online source:
+
+```js
+const server = createServer({
+  fallbackTile: async (tileId, { sourceId, source }) => {
+    const url = `https://tiles.example.com/${tileId.z}/${tileId.x}/${tileId.y}.mvt`
+    return fetch(url)
+  },
+  fallbackGlyph: async (fontstack, range) => {
+    return fetch(`https://fonts.example.com/${fontstack}/${range}.pbf`)
+  },
+})
+```
+
 ### Downloading a map for offline use
 
 ```js
@@ -52,10 +99,13 @@ const stream = download({
   styleUrl: 'https://demotiles.maplibre.org/style.json',
   bbox: [-180, -80, 180, 80],
   maxzoom: 5,
+  skipLocalGlyphs: true, // skip CJK/Hangul/Kana ranges rendered locally by MapLibre
 })
 // Pipe the ReadableStream to a file
 ```
 
+The `skipLocalGlyphs` option skips downloading glyph ranges that MapLibre GL renders client-side via [`localIdeographFontFamily`](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapOptions/) (CJK, Hangul, Kana, Yi, and Halfwidth/Fullwidth Forms — 163 of 256 ranges). This significantly reduces download size for styles that use these scripts.
+
 ### Converting from MBTiles
 
 > **Note:** MBTiles conversion requires Node >= 20 (uses `better-sqlite3` which dropped Node 18 support).
@@ -82,12 +132,56 @@ const stream = fromMBTiles(buffer)
 | `styled-map-package-api/reader`           | `Reader` class for reading `.smp` files                           |
 | `styled-map-package-api/writer`           | `Writer` class for creating `.smp` files                          |
 | `styled-map-package-api/server`           | `createServer()` — HTTP handler using WHATWG Request/Response     |
+| `styled-map-package-api/fallbacks`        | `emptyTileFallback`, `emptyGlyphFallback` — built-in fallbacks    |
 | `styled-map-package-api/download`         | `download()` — download an online map style for offline use       |
 | `styled-map-package-api/style-downloader` | `StyleDownloader` — downloads styles, sprites, and glyphs         |
 | `styled-map-package-api/tile-downloader`  | `downloadTiles()` — downloads tile data                           |
 | `styled-map-package-api/from-mbtiles`     | `fromMBTiles()` — convert MBTiles to SMP stream                   |
+| `styled-map-package-api/validator`        | `validate()` — validate `.smp` files against the spec             |
 | `styled-map-package-api/utils/mapbox`     | Mapbox URL detection and API utilities                            |
 
+### Validating an SMP file
+
+```js
+import { validate } from 'styled-map-package-api/validator'
+
+const result = await validate('path/to/map.smp')
+
+if (!result.usable) {
+  console.error('File cannot be opened')
+} else if (!result.valid) {
+  console.warn('File has issues but is usable')
+}
+
+for (const issue of result.issues) {
+  console.log(`[${issue.severity}] ${issue.message}`)
+}
+```
+
+The validator checks an `.smp` file against the [SMP specification](../../spec/1.0/) and returns structured issues. Each issue has:
+
+- **`kind`** — `'error'` (spec MUST violation) or `'warning'` (SHOULD/RECOMMENDED)
+- **`severity`** — practical impact on the reader/renderer:
+  - `'fatal'` — the reader will fail to open the file
+  - `'rendering'` — the map opens but content will be visibly broken (missing tiles, glyphs, sprites)
+  - `'spec'` — non-compliance that doesn't affect practical use
+- **`type`** — stable identifier for programmatic filtering (e.g. `'missing_tiles'`, `'incomplete_font_glyphs'`)
+- **`message`** — human-readable description
+- **`path`** — location context (e.g. `'sources.test.tiles'`, `'glyphs'`)
+
+The result includes two convenience booleans:
+
+- **`valid`** — `true` when there are no errors (spec-compliant)
+- **`usable`** — `true` when there are no fatal issues (the file can be opened)
+
+Accepts a file path (Node.js) or a `ZipReader` instance (browser). Options:
+
+```js
+const result = await validate('map.smp', {
+  maxEntries: 500_000, // max ZIP entries before aborting (default: 500,000)
+})
+```
+
 ### Browser support
 
 All stream APIs use WHATWG `ReadableStream`, making the library compatible with both Node.js and browser environments. The `Reader` class accepts either a file path (Node.js) or a `ZipReader` instance (browser).

package/dist/download.d.ts

@@ -1,15 +1,3 @@
-import { GlyphDownloadStats } from './style-downloader.js';
-import { TileDownloadStats } from './tile-downloader.js';
-import { D as DownloadStream } from './types-Bhn0-Ldk.js';
-import { BBox } from './utils/geo.js';
-import 'ky';
-import '@maplibre/maplibre-gl-style-spec';
-import './utils/fetch.js';
-import './utils/streams.js';
-import 'stream/web';
-import 'geojson';
-import 'type-fest';
-
 /**
  * @typedef {object} DownloadProgress
  * @property {import('./tile-downloader.js').TileDownloadStats & { done: boolean }} tiles
@@ -25,22 +13,26 @@ import 'type-fest';
  * containing all the resources needed to serve the style offline.
  *
  * @param {object} opts
- * @param {import("./utils/geo.js").BBox} opts.bbox Bounding box to download tiles for
+ * @param {Readonly<import("./utils/geo.js").BBox>} opts.bbox Bounding box to download tiles for
  * @param {number} opts.maxzoom Max zoom level to download tiles for
  * @param {string} opts.styleUrl URL of the style to download
  * @param { (progress: DownloadProgress) => void } [opts.onprogress] Optional callback for reporting progress
  * @param {string} [opts.accessToken]
+ * @param {boolean} [opts.skipLocalGlyphs] Skip glyph ranges rendered client-side by MapLibre GL via localIdeographFontFamily (CJK, Hangul, Kana, Yi, etc.)
+ * @param {boolean} [opts.dedupe] When true, duplicate tiles are stored only once (see {@link Writer})
  * @returns {import('./types.js').DownloadStream} Readable stream of the output styled map file
  */
-declare function download({ bbox, maxzoom, styleUrl, onprogress, accessToken }: {
-    bbox: BBox;
+export function download({ bbox, maxzoom, styleUrl, onprogress, accessToken, skipLocalGlyphs, dedupe, }: {
+    bbox: Readonly<import("./utils/geo.js").BBox>;
     maxzoom: number;
     styleUrl: string;
     onprogress?: ((progress: DownloadProgress) => void) | undefined;
     accessToken?: string | undefined;
-}): DownloadStream;
-type DownloadProgress = {
-    tiles: TileDownloadStats & {
+    skipLocalGlyphs?: boolean | undefined;
+    dedupe?: boolean | undefined;
+}): import("./types.js").DownloadStream;
+export type DownloadProgress = {
+    tiles: import("./tile-downloader.js").TileDownloadStats & {
         done: boolean;
     };
     style: {
@@ -50,7 +42,7 @@ type DownloadProgress = {
         downloaded: number;
         done: boolean;
     };
-    glyphs: GlyphDownloadStats & {
+    glyphs: import("./style-downloader.js").GlyphDownloadStats & {
         done: boolean;
     };
     output: {
@@ -59,5 +51,3 @@ type DownloadProgress = {
     };
     elapsedMs: number;
 };
-
-export { type DownloadProgress, download };

package/dist/fallbacks.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Fallback tile handler for use with `createServer({ fallbackTile })`.
+ * Returns an appropriate empty tile based on the source's tile format:
+ * - vector sources → empty gzipped MVT
+ * - raster PNG sources → 1×1 transparent PNG
+ * - raster WebP sources → 1×1 transparent WebP
+ * - raster JPEG sources → 1×1 transparent PNG (no such thing as transparent JPEG)
+ *
+ * @param {{ x: number, y: number, z: number }} _tileId
+ * @param {{ sourceId: string, source: SMPSource }} sourceInfo
+ * @returns {Response}
+ */
+export function emptyTileFallback(_tileId: {
+    x: number;
+    y: number;
+    z: number;
+}, { source }: {
+    sourceId: string;
+    source: SMPSource;
+}): Response;
+/**
+ * Fallback glyph handler for use with `createServer({ fallbackGlyph })`.
+ * Returns an empty gzipped PBF (valid protobuf with no glyph entries), which
+ * causes MapLibre to render missing characters as blank space instead of
+ * erroring on a 404.
+ *
+ * @param {string} _fontstack
+ * @param {string} _range
+ * @returns {Response}
+ */
+export function emptyGlyphFallback(_fontstack: string, _range: string): Response;
+import type { SMPSource } from './types.js';

package/dist/from-mbtiles.d.ts

@@ -9,6 +9,4 @@
  *   (Node), OPFS path (browser Worker), or in-memory buffer.
  * @returns {ReadableStream<Uint8Array>}
  */
-declare function fromMBTiles(source: string | ArrayBuffer | Uint8Array): ReadableStream<Uint8Array>;
-
-export { fromMBTiles };
+export function fromMBTiles(source: string | ArrayBuffer | Uint8Array): ReadableStream<Uint8Array>;

package/dist/index.d.ts

@@ -1,24 +1,11 @@
-import { S as SMPSource$1, a as SMPStyle$1 } from './types-Bhn0-Ldk.js';
-export { W as Writer } from './types-Bhn0-Ldk.js';
-export { Reader } from './reader.js';
-export { createServer } from './server.js';
-export { StyleDownloader } from './style-downloader.js';
-export { downloadTiles } from './tile-downloader.js';
-export { download } from './download.js';
-export { fromMBTiles } from './from-mbtiles.js';
-import '@maplibre/maplibre-gl-style-spec';
-import 'geojson';
-import 'type-fest';
-import '@gmaclennan/zip-reader';
-import 'itty-router';
-import 'itty-router/IttyRouter';
-import 'ky';
-import './utils/geo.js';
-import './utils/fetch.js';
-import './utils/streams.js';
-import 'stream/web';
-
-type SMPSource = SMPSource$1;
-type SMPStyle = SMPStyle$1;
-
-export type { SMPSource, SMPStyle };
+export { Reader } from "./reader.js";
+export { Writer } from "./writer.js";
+export { createServer } from "./server.js";
+export { StyleDownloader } from "./style-downloader.js";
+export { downloadTiles } from "./tile-downloader.js";
+export { download } from "./download.js";
+export { fromMBTiles } from "./from-mbtiles.js";
+export { validate } from "./validator.js";
+export type SMPSource = import("./types.js").SMPSource;
+export type SMPStyle = import("./types.js").SMPStyle;
+export { emptyTileFallback, emptyGlyphFallback } from "./fallbacks.js";

package/dist/reader.d.ts

@@ -1,9 +1,3 @@
-import { a as SMPStyle } from './types-Bhn0-Ldk.js';
-import * as _gmaclennan_zip_reader from '@gmaclennan/zip-reader';
-import '@maplibre/maplibre-gl-style-spec';
-import 'geojson';
-import 'type-fest';
-
 /**
  * @typedef {object} Resource
  * @property {string} resourceType
@@ -12,15 +6,25 @@ import 'type-fest';
  * @property {ReadableStream<Uint8Array>} stream
  * @property {'gzip'} [contentEncoding]
  */
+/**
+ * @typedef {object} ReaderOptions
+ * @property {number} [maxEntries=500_000] Maximum number of ZIP entries to
+ *   process. Exceeding this limit throws an error during `opened()`. Default is
+ *   500,000 (~a global z9 tileset).
+ * @property {number} [maxResourceSize=20 * 1024 * 1024] Maximum uncompressed
+ *   size in bytes for a single resource returned by `getResource()`. Default is
+ *   20 MiB.
+ */
 /**
  * A low-level reader for styled map packages. Returns resources in the package
  * as readable streams, for serving over HTTP for example.
  */
-declare class Reader {
+export class Reader {
     /**
      * @param {string | import('@gmaclennan/zip-reader').ZipReader} filepathOrZip Path to styled map package (`.styledmap`) file, or a ZipReader instance
+     * @param {ReaderOptions} [options]
      */
-    constructor(filepathOrZip: string | _gmaclennan_zip_reader.ZipReader);
+    constructor(filepathOrZip: string | import("@gmaclennan/zip-reader").ZipReader, options?: ReaderOptions);
     /**
      * Resolves when the styled map package has been opened and the entries have
      * been read. Throws any error that occurred during opening.
@@ -41,7 +45,7 @@ declare class Reader {
      * @param {string | null} [baseUrl] Base URL where you plan to serve the resources in this styled map package, e.g. `http://localhost:3000/maps/styleA`
      * @returns {Promise<import('./types.js').SMPStyle>}
      */
-    getStyle(baseUrl?: string | null): Promise<SMPStyle>;
+    getStyle(baseUrl?: string | null): Promise<import("./types.js").SMPStyle>;
     /**
      * Get a resource from the styled map package. The path should be relative to
      * the root of the package.
@@ -56,12 +60,24 @@ declare class Reader {
     close(): Promise<void>;
     #private;
 }
-type Resource = {
+export type Resource = {
     resourceType: string;
     contentType: string;
     contentLength: number;
     stream: ReadableStream<Uint8Array>;
     contentEncoding?: "gzip" | undefined;
 };
-
-export { Reader, type Resource };
+export type ReaderOptions = {
+    /**
+     * Maximum number of ZIP entries to
+     * process. Exceeding this limit throws an error during `opened()`. Default is
+     * 500,000 (~a global z9 tileset).
+     */
+    maxEntries?: number | undefined;
+    /**
+     * Maximum uncompressed
+     * size in bytes for a single resource returned by `getResource()`. Default is
+     * 20 MiB.
+     */
+    maxResourceSize?: number | undefined;
+};

package/dist/server.d.ts

@@ -1,12 +1,3 @@
-import { RequestLike } from 'itty-router';
-import { Reader } from './reader.js';
-import { IttyRouter } from 'itty-router/IttyRouter';
-import './types-Bhn0-Ldk.js';
-import '@maplibre/maplibre-gl-style-spec';
-import 'geojson';
-import 'type-fest';
-import '@gmaclennan/zip-reader';
-
 /**
  * Create a server for serving styled map packages (SMP) over http. The server
  * is a `fetch` handler that must be provided a WHATWG `Request` and a SMP
@@ -32,14 +23,32 @@ import '@gmaclennan/zip-reader';
  *
  * @param {object} [options]
  * @param {string} [options.base='/'] Base path for the server routes
+ * @param {(tileId: { x: number, y: number, z: number }, sourceInfo: { sourceId: string, source: import('./types.js').SMPSource }) => Response | Promise<Response>} [options.fallbackTile] Called when a tile is missing from the SMP
+ * @param {(fontstack: string, range: string) => Response | Promise<Response>} [options.fallbackGlyph] Called when a glyph is missing from the SMP
  * @returns {{ fetch: (request: RequestLike, reader: ReaderLike) => Promise<Response> }} server instance
  */
-declare function createServer({ base }?: {
+export function createServer({ base, fallbackTile, fallbackGlyph }?: {
     base?: string | undefined;
+    fallbackTile?: ((tileId: {
+        x: number;
+        y: number;
+        z: number;
+    }, sourceInfo: {
+        sourceId: string;
+        source: import("./types.js").SMPSource;
+    }) => Response | Promise<Response>) | undefined;
+    fallbackGlyph?: ((fontstack: string, range: string) => Response | Promise<Response>) | undefined;
 }): {
     fetch: (request: RequestLike, reader: ReaderLike) => Promise<Response>;
 };
-type ReaderLike = Pick<Reader, keyof Reader>;
-type RouterType = typeof IttyRouter<IRequestStrict, [ReaderLike], Response>;
-
-export { type ReaderLike, type RouterType, createServer };
+export type ReaderLike = Pick<Reader, keyof Reader>;
+export type RouterType = typeof IttyRouter<IRequestStrict, [ReaderLike], Response>;
+export type TileMatcher = {
+    regex: RegExp;
+    sourceId: string;
+    source: import("./types.js").SMPSource;
+};
+import type { RequestLike } from 'itty-router';
+import type { Reader } from './reader.js';
+import { IttyRouter } from 'itty-router/IttyRouter';
+import type { IRequestStrict } from 'itty-router';

package/dist/style-downloader.d.ts

@@ -1,14 +1,3 @@
-import * as ky from 'ky';
-import { BBox } from './utils/geo.js';
-import { b as StyleInlinedSources, G as GlyphInfo, T as TileInfo } from './types-Bhn0-Ldk.js';
-import { TileDownloadStats } from './tile-downloader.js';
-import { StyleSpecification } from '@maplibre/maplibre-gl-style-spec';
-import 'geojson';
-import 'type-fest';
-import './utils/fetch.js';
-import './utils/streams.js';
-import 'stream/web';
-
 /** @import { SourceSpecification, StyleSpecification } from '@maplibre/maplibre-gl-style-spec' */
 /** @import { TileInfo, GlyphInfo, GlyphRange } from './writer.js' */
 /** @import { TileDownloadStats } from './tile-downloader.js' */
@@ -25,7 +14,7 @@ import 'stream/web';
  * Download a style and its resources for offline use. Please check the terms of
  * service of the map provider you are using before downloading any resources.
  */
-declare class StyleDownloader {
+export class StyleDownloader {
     /**
      * @param {string | StyleSpecification} style A url to a style JSON file or a style object
      * @param {object} [opts]
@@ -71,10 +60,12 @@ declare class StyleDownloader {
      *
      * @param {object} opts
      * @param {(progress: GlyphDownloadStats) => void} [opts.onprogress]
+     * @param {boolean} [opts.skipLocalGlyphs] Skip glyph ranges rendered client-side by MapLibre GL via localIdeographFontFamily (CJK, Hangul, Kana, Yi, etc.)
      * @returns {AsyncGenerator<[ReadableStream<Uint8Array>, GlyphInfo]>}
      */
-    getGlyphs({ onprogress }?: {
+    getGlyphs({ onprogress, skipLocalGlyphs }?: {
         onprogress?: ((progress: GlyphDownloadStats) => void) | undefined;
+        skipLocalGlyphs?: boolean | undefined;
     }): AsyncGenerator<[ReadableStream<Uint8Array>, GlyphInfo]>;
     /**
      * Get all the tiles for this style within the given bounds and zoom range.
@@ -87,14 +78,14 @@ declare class StyleDownloader {
      * bytes downloaded.
      *
      * @param {object} opts
-     * @param {import('./utils/geo.js').BBox} opts.bounds
+     * @param {Readonly<import('./utils/geo.js').BBox>} opts.bounds
      * @param {number} opts.maxzoom
      * @param {(progress: TileDownloadStats) => void} [opts.onprogress]
      * @param {boolean} [opts.trackErrors=false] Include errors in the returned array of skipped tiles - this has memory overhead so should only be used for debugging.
      * @returns {AsyncGenerator<[ReadableStream<Uint8Array>, TileInfo]> & { readonly skipped: Array<TileInfo & { error?: Error }>, readonly stats: TileDownloadStats }}
      */
     getTiles({ bounds, maxzoom, onprogress, trackErrors }: {
-        bounds: BBox;
+        bounds: Readonly<import("./utils/geo.js").BBox>;
         maxzoom: number;
         onprogress?: ((progress: TileDownloadStats) => void) | undefined;
         trackErrors?: boolean | undefined;
@@ -106,13 +97,16 @@ declare class StyleDownloader {
     };
     #private;
 }
-type ResponsePromise = ky.ResponsePromise & {
+export type ResponsePromise = import("ky").ResponsePromise & {
     body: ReadableStream<Uint8Array>;
 };
-type GlyphDownloadStats = {
+export type GlyphDownloadStats = {
     total: number;
     downloaded: number;
     totalBytes: number;
 };
-
-export { type GlyphDownloadStats, type ResponsePromise, StyleDownloader };
+import type { StyleInlinedSources } from './types.js';
+import type { GlyphInfo } from './writer.js';
+import type { TileDownloadStats } from './tile-downloader.js';
+import type { TileInfo } from './writer.js';
+import type { StyleSpecification } from '@maplibre/maplibre-gl-style-spec';

package/dist/tile-downloader.d.ts

@@ -1,12 +1,3 @@
-import { T as TileInfo$1 } from './types-Bhn0-Ldk.js';
-import { BBox } from './utils/geo.js';
-import { FetchQueue } from './utils/fetch.js';
-import '@maplibre/maplibre-gl-style-spec';
-import 'geojson';
-import 'type-fest';
-import './utils/streams.js';
-import 'stream/web';
-
 /** @typedef {Omit<import('./writer.js').TileInfo, 'sourceId'>} TileInfo */
 /**
  * @typedef {object} TileDownloadStats
@@ -21,11 +12,11 @@ import 'stream/web';
  *
  * @param {object} opts
  * @param {string[]} opts.tileUrls Array of tile URL templates. Use `{x}`, `{y}`, `{z}` placeholders, and optional `{scheme}` placeholder which can be `xyz` or `tms`.
- * @param {import('./utils/geo.js').BBox} opts.bounds Bounding box of the area to download
+ * @param {Readonly<import('./utils/geo.js').BBox>} opts.bounds Bounding box of the area to download
  * @param {number} opts.maxzoom Maximum zoom level to download
  * @param {(progress: TileDownloadStats) => void} [opts.onprogress] Callback to report download progress
  * @param {boolean} [opts.trackErrors=false] Include errors in the returned array of skipped tiles - this has memory overhead so should only be used for debugging.
- * @param {import('./utils/geo.js').BBox} [opts.sourceBounds=MAX_BOUNDS] Bounding box of source data.
+ * @param {Readonly<import('./utils/geo.js').BBox>} [opts.sourceBounds=MAX_BOUNDS] Bounding box of source data.
  * @param {boolean} [opts.boundsBuffer=false] Buffer the bounds by one tile at each zoom level to ensure no tiles are missed at the edges. With this set to false, in most instances the map will appear incomplete when viewed because the downloaded tiles at lower zoom levels will not cover the map view area.
  * @param {number} [opts.minzoom=0] Minimum zoom level to download (for most cases this should be left as `0` - the size overhead is minimal, because each zoom level has 4x as many tiles)
  * @param {number} [opts.concurrency=8] Number of concurrent downloads (ignored if `fetchQueue` is provided)
@@ -33,13 +24,13 @@ import 'stream/web';
  * @param {'xyz' | 'tms'} [opts.scheme='xyz'] Tile scheme to use for tile URLs
  * @returns {AsyncGenerator<[ReadableStream<Uint8Array>, TileInfo]> & { readonly skipped: Array<TileInfo & { error?: Error }>, readonly stats: TileDownloadStats }}
  */
-declare function downloadTiles({ tileUrls, bounds, maxzoom, onprogress, trackErrors, sourceBounds, boundsBuffer, minzoom, concurrency, fetchQueue, scheme, }: {
+export function downloadTiles({ tileUrls, bounds, maxzoom, onprogress, trackErrors, sourceBounds, boundsBuffer, minzoom, concurrency, fetchQueue, scheme, }: {
     tileUrls: string[];
-    bounds: BBox;
+    bounds: Readonly<import("./utils/geo.js").BBox>;
     maxzoom: number;
     onprogress?: ((progress: TileDownloadStats) => void) | undefined;
     trackErrors?: boolean | undefined;
-    sourceBounds?: BBox | undefined;
+    sourceBounds?: readonly [number, number, number, number] | undefined;
     boundsBuffer?: boolean | undefined;
     minzoom?: number | undefined;
     concurrency?: number | undefined;
@@ -54,15 +45,15 @@ declare function downloadTiles({ tileUrls, bounds, maxzoom, onprogress, trackErr
 /**
  *
  * @param {object} opts
- * @param {import('./utils/geo.js').BBox} [opts.bounds]
- * @param {import('./utils/geo.js').BBox} [opts.sourceBounds]
+ * @param {Readonly<import('./utils/geo.js').BBox>} [opts.bounds]
+ * @param {Readonly<import('./utils/geo.js').BBox>} [opts.sourceBounds]
  * @param {boolean} [opts.boundsBuffer]
  * @param {number} [opts.minzoom]
  * @param {number} opts.maxzoom
  */
-declare function tileIterator({ bounds, minzoom, maxzoom, sourceBounds, boundsBuffer, }: {
-    bounds?: BBox | undefined;
-    sourceBounds?: BBox | undefined;
+export function tileIterator({ bounds, minzoom, maxzoom, sourceBounds, boundsBuffer, }: {
+    bounds?: readonly [number, number, number, number] | undefined;
+    sourceBounds?: readonly [number, number, number, number] | undefined;
     boundsBuffer?: boolean | undefined;
     minzoom?: number | undefined;
     maxzoom: number;
@@ -71,12 +62,11 @@ declare function tileIterator({ bounds, minzoom, maxzoom, sourceBounds, boundsBu
     y: number;
     z: number;
 }, void, unknown>;
-type TileInfo = Omit<TileInfo$1, "sourceId">;
-type TileDownloadStats = {
+export type TileInfo = Omit<import("./writer.js").TileInfo, "sourceId">;
+export type TileDownloadStats = {
     total: number;
     downloaded: number;
     skipped: number;
     totalBytes: number;
 };
-
-export { type TileDownloadStats, type TileInfo, downloadTiles, tileIterator };
+import { FetchQueue } from './utils/fetch.js';

package/dist/types.d.ts

@@ -0,0 +1,61 @@
+import type { SourceSpecification, StyleSpecification, ValidationError, GeoJSONSourceSpecification, VectorSourceSpecification, RasterSourceSpecification, RasterDEMSourceSpecification } from '@maplibre/maplibre-gl-style-spec';
+import type { GeoJSON, BBox } from 'geojson';
+import type { SetRequired } from 'type-fest';
+import { SUPPORTED_SOURCE_TYPES } from './writer.js';
+export type InputSource = Extract<SourceSpecification, {
+    type: (typeof SUPPORTED_SOURCE_TYPES)[number];
+}>;
+type TransformInlinedSource<T extends SourceSpecification> = T extends GeoJSONSourceSpecification ? OmitUnion<T, 'data'> & {
+    data: GeoJSON;
+} : T extends VectorSourceSpecification | RasterSourceSpecification | RasterDEMSourceSpecification ? SetRequired<OmitUnion<T, 'url'>, 'tiles'> : T;
+/**
+ * This is a slightly stricter version of SourceSpecification that requires
+ * sources to be inlined (e.g. no urls to TileJSON or GeoJSON files).
+ */
+export type InlinedSource = TransformInlinedSource<SourceSpecification>;
+type SupportedInlinedSource = Extract<InlinedSource, {
+    type: (typeof SUPPORTED_SOURCE_TYPES)[number];
+}>;
+/**
+ * This is a slightly stricter version of StyleSpecification that requires
+ * sources to be inlined (e.g. no urls to TileJSON or GeoJSON files).
+ */
+export type StyleInlinedSources = Omit<StyleSpecification, 'sources'> & {
+    sources: {
+        [_: string]: InlinedSource;
+    };
+};
+export type SMPSource = TransformSMPInputSource<SupportedInlinedSource>;
+/**
+ * This is a slightly stricter version of StyleSpecification that is provided in
+ * a Styled Map Package. Tile sources must have tile URLs inlined (they cannot
+ * refer to a TileJSON url), and they must have bounds, minzoom, and maxzoom.
+ * GeoJSON sources must have inlined GeoJSON (not a URL to a GeoJSON file).
+ */
+export type SMPStyle = TransformSMPStyle<StyleSpecification>;
+export type TransformSMPInputSource<T extends SupportedInlinedSource> = T extends GeoJSONSourceSpecification ? T & {
+    data: {
+        bbox: BBox;
+    };
+} : T extends RasterSourceSpecification | VectorSourceSpecification ? SetRequired<T, 'bounds' | 'minzoom' | 'maxzoom'> : T;
+type TransformSMPStyle<T extends StyleSpecification> = Omit<T, 'sources'> & {
+    metadata: {
+        'smp:bounds': [number, number, number, number];
+        'smp:maxzoom': 0;
+        'smp:sourceFolders': {
+            [_: string]: string;
+        };
+        [key: string]: unknown;
+    };
+    sources: {
+        [_: string]: SMPSource;
+    };
+};
+export interface ValidateStyle {
+    (style: unknown): style is StyleSpecification;
+    errors: Array<ValidationError>;
+}
+export type DownloadStream = ReadableStream<Uint8Array>;
+export type RequiredUnion<T> = T extends any ? Required<T> : never;
+export type OmitUnion<T, K extends keyof any> = T extends unknown ? Omit<T, K> : never;
+export {};

package/dist/utils/errors.d.ts

@@ -5,14 +5,12 @@
  * @param {unknown} error
  * @returns {error is Error & { code: 'ENOENT' | 'EPERM' }}
  */
-declare function isFileNotThereError(error: unknown): error is Error & {
+export function isFileNotThereError(error: unknown): error is Error & {
     code: "ENOENT" | "EPERM";
 };
-declare class ENOENT extends Error {
+export class ENOENT extends Error {
     /** @param {string} path */
     constructor(path: string);
     code: string;
     path: string;
 }
-
-export { ENOENT, isFileNotThereError };

package/dist/utils/fetch.d.ts

@@ -1,6 +1,3 @@
-import { ProgressCallback } from './streams.js';
-import 'stream/web';
-
 /**
  * @typedef {object} DownloadResponse
  * @property {ReadableStream<Uint8Array>} body Web ReadableStream of the response body
@@ -10,7 +7,7 @@ import 'stream/web';
 /**
  * A wrapper for fetch that limits the number of concurrent downloads.
  */
-declare class FetchQueue {
+export class FetchQueue {
     /** @param {number} concurrency */
     constructor(concurrency: number);
     get activeCount(): number;
@@ -28,11 +25,11 @@ declare class FetchQueue {
      * @returns {Promise<DownloadResponse>}
      */
     fetch(url: string, { onprogress }?: {
-        onprogress?: ProgressCallback;
+        onprogress?: import("./streams.js").ProgressCallback;
     }): Promise<DownloadResponse>;
     #private;
 }
-type DownloadResponse = {
+export type DownloadResponse = {
     /**
      * Web ReadableStream of the response body
      */
@@ -46,5 +43,3 @@ type DownloadResponse = {
      */
     contentLength: number | null;
 };
-
-export { type DownloadResponse, FetchQueue };