PMTiles source and protocol

Replicates the MapLibre example PMTiles source and protocol. Protocol plugins register on the maplibre-gl module, not a map instance — which is why this was an unreachable gap until 0.7: @maplibre-yaml/core/maplibre re-exports the exact module <ml-map> renders with, so addProtocol lands where the document’s requests actually go.

The YAML half

pmtiles-source-and-protocol.yaml

# PMTiles vector source via the pmtiles:// protocol. The page registers the
# protocol through `@maplibre-yaml/core/maplibre` (see the docs page); this
# config is plain declarative YAML — the URL scheme is the only hint a
# protocol plugin is involved. Data: Protomaps' Florence sample (ODbL).
#
# NOTE for the live sweep: this config cannot render without the page's
# protocol registration — scripts/verify-docs-gallery.mjs skips it by name;
# the hermetic regression test is e2e/gallery-hatch.spec.ts (stub protocol).
type: map
id: pmtiles-source-and-protocol
config:
  center: [11.2558, 43.7696]
  zoom: 12.5
  mapStyle: "https://demotiles.maplibre.org/style.json"
sources:
  firenze:
    type: vector
    url: "pmtiles://https://pmtiles.io/protomaps(vector)ODbL_firenze.pmtiles"
layers:
  - id: firenze-landuse
    type: fill
    source: firenze
    source-layer: landuse
    paint:
      fill-color: "#7b2cbf"
      fill-opacity: 0.25
  - id: firenze-roads
    type: line
    source: firenze
    source-layer: roads
    paint:
      line-color: "#5a189a"
      line-width: 1

The JavaScript half

import { addProtocol } from "@maplibre-yaml/core/maplibre";
import { Protocol } from "pmtiles";

const protocol = new Protocol();
addProtocol("pmtiles", protocol.tile);

What to notice

• The YAML stays purely declarative — pmtiles:// in the source URL is the only trace of the plugin. Validation and export treat it as an ordinary vector source.
• The import path matters: registering addProtocol from a separately loaded maplibre-gl (a CDN copy, a second bundle) registers on a module the map never consults, and the source fails with no obvious cause. The @maplibre-yaml/core/maplibre subpath guarantees module identity with the renderer.
• The same page code covers COG, custom tile transforms, and any other addProtocol plugin.
• Data: Protomaps Florence sample extract (ODbL).