styled-map-package 5.0.0-pre.3 → 5.0.0-pre.5

package/README.md

@@ -25,15 +25,23 @@ smp download https://demotiles.maplibre.org/style.json \
 
 **Options:**
 
-| Option                 | Description                                      |
-| ---------------------- | ------------------------------------------------ |
-| `-o, --output <file>`  | Output file (writes to stdout if omitted)        |
-| `-b, --bbox <w,s,e,n>` | Bounding box (west, south, east, north)          |
-| `-z, --zoom <number>`  | Max zoom level (0-22)                            |
-| `-t, --token <token>`  | Mapbox access token (required for Mapbox styles) |
+| Option                 | Description                                                            |
+| ---------------------- | ---------------------------------------------------------------------- |
+| `-o, --output <file>`  | Output file (writes to stdout if omitted)                              |
+| `-b, --bbox <w,s,e,n>` | Bounding box (west, south, east, north)                                |
+| `-z, --zoom <number>`  | Max zoom level (0-22)                                                  |
+| `-t, --token <token>`  | Mapbox access token (required for Mapbox styles)                       |
+| `-d, --dedupe`         | Deduplicate tiles with identical content to reduce file size           |
+| `--skip-local-glyphs`  | Skip CJK/Hangul/Kana glyph ranges rendered locally by MapLibre GL      |
+| `--buffer-tiles`       | Download an extra tile ring around the bbox at each zoom below maxzoom |
 
 When run interactively, missing options are prompted for.
 
+The `--buffer-tiles` flag downloads one extra tile ring around the bbox at every
+zoom level below maxzoom, so the map is not clipped at the edges of the
+downloaded area when zooming out. The buffer is not added at maxzoom. `smp view`
+automatically renders these buffer tiles.
+
 ### `smp view`
 
 Preview a `.smp` file in a web browser.
@@ -44,10 +52,15 @@ smp view demotiles.smp --open
 
 **Options:**
 
-| Option                | Description                      |
-| --------------------- | -------------------------------- |
-| `-o, --open`          | Open in the default web browser  |
-| `-p, --port <number>` | Port to serve on (default: 3000) |
+| Option                | Description                                                                |
+| --------------------- | -------------------------------------------------------------------------- |
+| `-o, --open`          | Open in the default web browser                                            |
+| `-p, --port <number>` | Port to serve on (default: 3000)                                           |
+| `--no-fallback`       | Return 404 for missing tiles and glyphs instead of serving empty fallbacks |
+
+By default the viewer serves empty tiles and Noto Sans glyphs for any resource not present in the file, so incomplete packages (those covering a partial area or zoom range) preview without 404 errors. Missing vector tiles are served as empty MVTs, missing raster tiles as transparent pixels. Missing glyph ranges are served using bundled [Noto Sans](https://fonts.google.com/noto/specimen/Noto+Sans) glyphs (via [GoNotoKurrent](https://github.com/satbyy/go-noto-universal), covering 80+ scripts including Latin, Cyrillic, Greek, Arabic, Hebrew, Devanagari, Thai, and more). CJK and Hangul ranges are not bundled since MapLibre renders these client-side via `localIdeographFontFamily`. Pass `--no-fallback` to return 404s instead.
+
+For packages downloaded with buffer tiles (recorded as `smp:bufferTiles` in the style metadata), the viewer also widens each source's `bounds` so the lower-zoom buffer tiles that extend beyond the data area are rendered rather than clipped. Combined with the empty-tile fallback, panning beyond the downloaded area shows blank tiles instead of console errors.
 
 ### `smp mbtiles`
 
@@ -65,6 +78,22 @@ smp mbtiles tiles.mbtiles --output map.smp
 | --------------------- | ------------------------------------------------ |
 | `-o, --output <file>` | Output `.smp` file (writes to stdout if omitted) |
 
+### `smp validate`
+
+Validate a `.smp` file against the [SMP specification](../../spec/1.0/).
+
+```sh
+smp validate map.smp
+```
+
+Reports errors (spec MUST violations) and warnings (SHOULD/RECOMMENDED), each annotated with a severity level:
+
+- **fatal** — the file cannot be opened by the reader
+- **rendering** — the map opens but content will be visibly broken (missing tiles, glyphs, sprites)
+- **spec** — non-compliance that doesn't affect practical use
+
+Exits with code 0 if valid, 1 if errors are found.
+
 ## License
 
 MIT

package/bin/smp-download.js

@@ -33,20 +33,49 @@ program
     '-t, --token <token>',
     'Mapbox access token (necessary for Mapbox styles)',
   )
+  .option(
+    '--skip-local-glyphs',
+    'Skip CJK/Hangul/Kana glyph ranges rendered locally by MapLibre GL',
+  )
+  .option(
+    '-d, --dedupe',
+    'deduplicate tiles with identical content to reduce file size',
+  )
+  .option(
+    '--buffer-tiles',
+    'download an extra tile ring around the bbox at each zoom level below maxzoom, so the map is not clipped at the edges when zooming out',
+  )
   .argument('[styleUrl]', 'URL to style to download', parseUrl)
-  .action(async (styleUrl, { bbox, zoom, output, token }) => {
-    await runDownload({ styleUrl, bbox, zoom, output, token }, {
-      download,
-      prompt: { input, number },
-      createOutputStream: (output) =>
-        output
-          ? Writable.toWeb(fs.createWriteStream(output))
-          : Writable.toWeb(process.stdout),
-      reporter: ttyReporter,
-      isMapboxURL,
-      mapboxApiUrl: MAPBOX_API_URL,
-      isTTY: !!process.stdout.isTTY,
-    })
-  })
+  .action(
+    async (
+      styleUrl,
+      { bbox, zoom, output, token, skipLocalGlyphs, dedupe, bufferTiles },
+    ) => {
+      await runDownload(
+        {
+          styleUrl,
+          bbox,
+          zoom,
+          output,
+          token,
+          skipLocalGlyphs,
+          dedupe,
+          bufferTiles,
+        },
+        {
+          download,
+          prompt: { input, number },
+          createOutputStream: (output) =>
+            output
+              ? Writable.toWeb(fs.createWriteStream(output))
+              : Writable.toWeb(process.stdout),
+          reporter: ttyReporter,
+          isMapboxURL,
+          mapboxApiUrl: MAPBOX_API_URL,
+          isTTY: !!process.stdout.isTTY,
+        },
+      )
+    },
+  )
 
 program.parseAsync(process.argv)

package/bin/smp-validate.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import chalk from 'chalk'
+import { Command } from 'commander'
+import logSymbols from 'log-symbols'
+import { validate } from 'styled-map-package-api/validator'
+
+const program = new Command()
+
+program
+  .description('Validate a styled map package file')
+  .argument('<file>', 'path to .smp file to validate')
+  .action(async (filepath) => {
+    const result = await validate(filepath)
+
+    if (result.valid) {
+      console.log(logSymbols.success, chalk.green('Valid SMP file'))
+    } else if (result.usable) {
+      console.log(
+        logSymbols.warning,
+        chalk.yellow('SMP file has issues but is usable'),
+      )
+    } else {
+      console.log(logSymbols.error, chalk.red('Invalid SMP file (unusable)'))
+    }
+
+    /** @param {typeof result.issues[number]} issue */
+    const formatIssue = (issue) => {
+      const path = issue.path ? chalk.dim(`[${issue.path}] `) : ''
+      const sev =
+        issue.severity !== 'spec' ? chalk.dim(` (${issue.severity})`) : ''
+      return `${path}${issue.message}${sev}`
+    }
+
+    const issueErrors = result.issues.filter((i) => i.kind === 'error')
+    const issueWarnings = result.issues.filter((i) => i.kind === 'warning')
+
+    if (issueErrors.length) {
+      console.log('\nErrors:')
+      for (const issue of issueErrors) {
+        console.log(`  ${logSymbols.error} ${formatIssue(issue)}`)
+      }
+    }
+
+    if (issueWarnings.length) {
+      console.log('\nWarnings:')
+      for (const issue of issueWarnings) {
+        console.log(`  ${logSymbols.warning} ${formatIssue(issue)}`)
+      }
+    }
+
+    process.exit(result.valid ? 0 : 1)
+  })
+
+program.parseAsync(process.argv)

package/bin/smp-view.js

@@ -3,6 +3,8 @@ import { createServerAdapter } from '@whatwg-node/server'
 import { Command } from 'commander'
 import http from 'http'
 import openApp from 'open'
+import { notoGlyphFallback } from 'smp-noto-glyphs'
+import { emptyTileFallback } from 'styled-map-package-api/fallbacks'
 import { Reader } from 'styled-map-package-api/reader'
 import { createServer } from 'styled-map-package-api/server'
 
@@ -17,21 +19,30 @@ program
   .description('Preview a styled map package in a web browser')
   .option('-o, --open', 'open in the default web browser')
   .option('-p, --port <number>', 'port to serve on', (v) => parseInt(v), 3000)
+  .option(
+    '--no-fallback',
+    'return 404 for missing tiles and glyphs instead of serving empty fallbacks',
+  )
   .argument('<file>', 'file to serve')
-  .action(async (filepath, { open, port }) => {
+  .action(async (filepath, { open, port, fallback }) => {
     await runView(
-      { port, filepath: path.relative(process.cwd(), filepath), open },
+      {
+        port,
+        filepath: path.relative(process.cwd(), filepath),
+        open,
+        fallback,
+      },
       {
         Reader,
         createServer,
+        emptyTileFallback,
+        emptyGlyphFallback: notoGlyphFallback,
         openApp,
         log: (msg) => console.log(msg),
         readViewerHtml: (filepath) => fsPromises.readFile(filepath),
         listen: (port, handler) =>
           new Promise((resolve, reject) => {
-            const server = http.createServer(
-              createServerAdapter(handler),
-            )
+            const server = http.createServer(createServerAdapter(handler))
             server.listen(port, '127.0.0.1', () => {
               const address = server.address()
               if (typeof address === 'string') {

package/bin/smp.js

@@ -8,5 +8,6 @@ program
   .command('download', 'Download a map style to a styled map package file')
   .command('view', 'Preview a styled map package in a web browser')
   .command('mbtiles', 'Convert a MBTiles file to a styled map package file')
+  .command('validate', 'Validate a styled map package file')
 
 program.parse(process.argv)

package/lib/commands/download.js

@@ -57,6 +57,9 @@ export function parseUrl(url) {
  * @property {number | undefined} zoom
  * @property {string | undefined} output
  * @property {string | undefined} token
+ * @property {boolean | undefined} skipLocalGlyphs
+ * @property {boolean | undefined} dedupe
+ * @property {boolean | undefined} bufferTiles When set, download one extra tile ring around the bbox at each zoom level below maxzoom.
  */
 
 /**
@@ -75,7 +78,7 @@ export function parseUrl(url) {
  * @param {DownloadDeps} deps
  */
 export async function runDownload(
-  { styleUrl, bbox, zoom, output, token },
+  { styleUrl, bbox, zoom, output, token, skipLocalGlyphs, dedupe, bufferTiles },
   deps,
 ) {
   const { download, prompt, isMapboxURL, mapboxApiUrl, isTTY } = deps
@@ -176,7 +179,11 @@ export async function runDownload(
     maxzoom: zoom,
     styleUrl,
     onprogress: (/** @type {any} */ p) => reporter.write(p),
-    accessToken: token,
+    mapboxAccessToken: token,
+    skipLocalGlyphs,
+    dedupe,
+    // `--buffer-tiles` is a boolean flag on the CLI; map it to a one-tile ring.
+    bufferTiles: bufferTiles ? 1 : 0,
   })
   const outputStream = deps.createOutputStream(output)
   await readStream.pipeTo(

package/lib/commands/view.js

@@ -3,6 +3,7 @@
  * @property {number} port
  * @property {string} filepath
  * @property {boolean} [open]
+ * @property {boolean} [fallback] Serve empty tiles and fallback glyphs for missing resources. Defaults to `true`; pass `false` to return 404s instead.
  */
 
 /**
@@ -13,6 +14,8 @@
  * @property {(url: string) => Promise<void>} openApp
  * @property {(url: string) => void} log
  * @property {(url: string) => Promise<Uint8Array>} readViewerHtml
+ * @property {(tileId: any, sourceInfo: any) => Response} [emptyTileFallback]
+ * @property {(fontstack: string, range: string) => Response} [emptyGlyphFallback]
  */
 
 /**
@@ -20,11 +23,23 @@
  * @param {ViewDeps} deps
  * @returns {Promise<string>} The address the server is listening on
  */
-export async function runView({ port, filepath, open }, deps) {
+export async function runView({ port, filepath, open, fallback }, deps) {
   const { Reader, createServer, openApp, log, readViewerHtml } = deps
 
+  // Fallback is on by default; pass `fallback: false` to disable it. Pass the
+  // handlers explicitly (null to disable) rather than relying on the server's
+  // own defaults, since the CLI uses Noto glyphs rather than empty ones.
+  const useFallback = fallback !== false
+
   const reader = new Reader(filepath)
-  const smpServer = createServer({ base: '/map' })
+  const smpServer = createServer({
+    base: '/map',
+    // Render buffer tiles that lie outside the data bounds for packages written
+    // with `smp:bufferTiles`. No-op for packages without that metadata.
+    expandBounds: true,
+    fallbackTile: useFallback ? deps.emptyTileFallback : null,
+    fallbackGlyph: useFallback ? deps.emptyGlyphFallback : null,
+  })
 
   /** @param {Request} request */
   const handler = async (request) => {

package/map-viewer/index.html

@@ -32,6 +32,7 @@
       const map = new maplibregl.Map({
         container: 'map',
         style: 'map/style.json',
+        attributionControl: { compact: true },
       })
 
       map.on('error', (e) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styled-map-package",
-  "version": "5.0.0-pre.3",
+  "version": "5.0.0-pre.5",
   "description": "CLI for creating, viewing, and converting Styled Map Package (.smp) files",
   "type": "module",
   "bin": {
@@ -18,7 +18,8 @@
   "keywords": [],
   "license": "MIT",
   "dependencies": {
-    "styled-map-package-api": "^5.0.0-pre.3",
+    "styled-map-package-api": "^5.0.0-pre.5",
+    "smp-noto-glyphs": "^1.0.0-pre.1",
     "@inquirer/prompts": "^6.0.1",
     "@whatwg-node/server": "^0.10.17",
     "chalk": "^5.4.1",