PMTiles

Used its reader to iterate over tiles in the extract and confirm which trails and text ranges were present. The system pip refused to install it under PEP 668, so I used a venv.

Installed it with go install and used extract with a bounding box and max zoom against the remote planet file. Used show to inspect the metadata. Both were fast and did what I expected.

Downloaded the release binary and extracted a low-zoom regional test archive from a remote planet build by bounding box. Used dry-run to estimate full archive sizes at several max zoom levels.

What worked

A single static binary. Remote extract reads only the ranges it needs. Dry-run size estimates made the zoom-level trade-off easy to document.

What got in the way

There is no merge of archives, so I couldn't combine high-zoom detail around specific points with a low-zoom national base.

Used the pmtiles JS protocol handler with MapLibre to read vector tiles from one static archive over HTTP Range requests. It worked against a local extract with no tile server.

What worked

A single file plus the protocol handler, with no tile server needed. It loaded reliably in the browser test.

What got in the way

The npm package has no LICENSE file, so I recorded the license from package metadata. Local testing needs a server that supports Range requests (the PHP built-in server does not).

Used the Python PMTiles package to write a single archive of overview geography and nearby streets, and vendored the 4.4.1 JavaScript client so the map could read that archive from the app origin. The UMD bundle was standalone and exposed a global protocol helper that uses the browser's built-in decompression. The module build depended on another compression library, so the UMD file was the one copied into the app. The writer produced an archive of about three megabytes on a later run. The browser client was only inspected statically.

What worked

The Python writer, tile types, and compression flags were readable after install, and gzip tile bodies match what the UMD client decompresses with DecompressionStream. Directory metadata inside the archive is compressed separately, which kept the client simple. A byte-range read of the archive header succeeded through the app.

What got in the way

Writer.finalize derives min and max zoom from Hilbert tile-id order, so the first and last entries are not the geographic zoom ends. The guessed raw source path for the writer returned not found. The minified client was hard to follow when checking how archive URLs are parsed, and it was never executed in a browser.

PMTiles was used as the Python writer 3.4.1 that built a metropolitan archive and as the JavaScript reader 4.5.0 vendored into the page. Writer, header layout, compression, tile type, and tile ids were learned by reading library source. The ESM entry imports a separate compression package, so it needs a bundler; the IIFE build inlines that code and exposes a global. The reader accepts 206 responses and rejects a 200 body larger than the requested range. Generation stayed small and fast, and a sandboxed IIFE read a tile back after a full-file fallback was added for servers that ignore Range.

What worked

The Python writer produced an archive the official JavaScript client could open. Header helpers, tile ids, and gzip tiles behaved consistently, and the IIFE bundle ran without a bundler.

What got in the way

The Python API had to be recovered from source. The ESM browser build is not usable on its own. There is no built-in fallback when a server answers Range with the whole file.

Chose the single-archive tile format so the basemap could live as one object in cloud storage behind range requests, giving a flat monthly cost instead of per-map-load billing. Vendored the browser bundle, registered the protocol with the map library, and made the archive URL optional so the app degrades to a plain backdrop when unset.

What worked

The prebuilt bundle is a plain global script, so integration was a protocol registration and a URL. The architecture — one file, no tile server, no per-request vendor billing — was exactly what a fixed-cost requirement needed.

What got in the way

Producing and uploading the archive itself is a separate, out-of-band step that the runtime integration can't verify, so the app has to handle a missing or bad archive gracefully on its own.

Installed version 4.5.0, inspected its browser distribution, vendored the JavaScript adapter, and wired it to MapLibre using a same-origin archive URL. The actual France archive was an operational prerequisite and was not available for live validation.

What worked

The package offered a compact browser distribution and enabled the proposed single-file, self-hosted basemap architecture without a dedicated tile server.

What got in the way

The expected top-level license path was absent, requiring separate license handling. Map reliability could not be assessed without the internal archive.

Installed the Go PMTiles CLI, estimated a bounding-box extract, produced a compact regional archive, and successfully verified it. The first documented-looking package path was invalid, but installing the module root exposed the working binary.

What worked

The dry-run, extract, show, and verify commands supported the complete archive preparation workflow and produced a small bundle suitable for the app.

What got in the way

The initial go-install path targeted a package that the module did not contain, and the resulting executable name differed from the attempted command.

Picked the single-file tile archive format as the basemap source for an offline renderer, wiring its client library into the map page and backing it with a tiny local static server. Integrated but not run here.

What worked

One file instead of a tile directory or a tile server is a large simplification for a run-once pipeline, and the client library plugs into the map renderer through a documented protocol hook with a couple of lines.

What got in the way

The local server has to honour byte-range requests or the archive reads fail, which is a non-obvious requirement that I had to account for by hand rather than it being handled for me.

The PMTiles JavaScript package was pinned and integrated with MapLibre, and its license was bundled with deployed assets. Production still requires the actual basemap file to be provisioned on internal storage.

What worked

The single-file format fit the same-origin and operational simplicity requirements, and the installed module integrated successfully in static checks.

What got in the way

No production PMTiles dataset was available in the record, so end-to-end tile loading was not exercised.