styled-map-package 5.0.0-pre.2 → 5.0.0-pre.4

package/README.md

@@ -25,12 +25,14 @@ 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 |
 
 When run interactively, missing options are prompted for.
 
@@ -44,10 +46,13 @@ 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)                                  |
+| `-f, --fallback`      | Serve empty tiles and glyphs for missing resources instead of 404 |
+
+The `--fallback` flag is useful for previewing SMP files that don't contain every tile or glyph range referenced by the style. 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`.
 
 ### `smp mbtiles`
 
@@ -65,6 +70,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,36 @@ 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',
+  )
   .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 },
+    ) => {
+      await runDownload(
+        { styleUrl, bbox, zoom, output, token, skipLocalGlyphs, dedupe },
+        {
+          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(
+    '-f, --fallback',
+    'serve empty tiles and glyphs for missing resources instead of 404',
+  )
   .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,8 @@ export function parseUrl(url) {
  * @property {number | undefined} zoom
  * @property {string | undefined} output
  * @property {string | undefined} token
+ * @property {boolean | undefined} skipLocalGlyphs
+ * @property {boolean | undefined} dedupe
  */
 
 /**
@@ -75,7 +77,7 @@ export function parseUrl(url) {
  * @param {DownloadDeps} deps
  */
 export async function runDownload(
-  { styleUrl, bbox, zoom, output, token },
+  { styleUrl, bbox, zoom, output, token, skipLocalGlyphs, dedupe },
   deps,
 ) {
   const { download, prompt, isMapboxURL, mapboxApiUrl, isTTY } = deps
@@ -177,6 +179,8 @@ export async function runDownload(
     styleUrl,
     onprogress: (/** @type {any} */ p) => reporter.write(p),
     accessToken: token,
+    skipLocalGlyphs,
+    dedupe,
   })
   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]
  */
 
 /**
@@ -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,17 @@
  * @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
 
   const reader = new Reader(filepath)
-  const smpServer = createServer({ base: '/map' })
+  const smpServer = createServer({
+    base: '/map',
+    ...(fallback && {
+      fallbackTile: deps.emptyTileFallback,
+      fallbackGlyph: deps.emptyGlyphFallback,
+    }),
+  })
 
   /** @param {Request} request */
   const handler = async (request) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styled-map-package",
-  "version": "5.0.0-pre.2",
+  "version": "5.0.0-pre.4",
   "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.2",
+    "styled-map-package-api": "^5.0.0-pre.4",
+    "smp-noto-glyphs": "^1.0.0-pre.0",
     "@inquirer/prompts": "^6.0.1",
     "@whatwg-node/server": "^0.10.17",
     "chalk": "^5.4.1",