ogm-viewer 0.5.0 → 0.6.0

package/dist/collection/lib/{sources → resources}/iiif-manifest.test.js

@@ -1,8 +1,8 @@
 import { describe, it, expect, vi, afterEach } from "@stencil/vitest";
-import IIIFManifestSource from "./iiif-manifest";
+import IIIFManifestResource from "./iiif-manifest";
 const MANIFEST_URL = 'http://example.com/manifest.json';
 // A source always points at a manifest URL; the manifest itself is fetched lazily
-const createSource = () => new IIIFManifestSource('test-id', MANIFEST_URL);
+const createSource = () => new IIIFManifestResource('test-id', MANIFEST_URL);
 // A minimal IIIF v2 manifest with a single image
 const v2Manifest = {
     '@context': 'http://iiif.io/api/presentation/2/context.json',
@@ -60,7 +60,7 @@ const v3Manifest = {
         },
     ],
 };
-describe('IIIFManifestSource', () => {
+describe('IIIFManifestResource', () => {
     afterEach(() => vi.restoreAllMocks());
     describe('getIIIFImageUrls', () => {
         it('should fetch and extract image URLs from a IIIF v2 manifest', async () => {

package/dist/collection/lib/{sources → resources}/iiif.js

@@ -1,6 +1,6 @@
-import Source from "./source";
+import Resource from "./resource";
 // A source of IIIF image URL(s) to be previewed
-export default class IIIFSource extends Source {
+export default class IIIFResource extends Resource {
     label() {
         return 'IIIF Image';
     }

package/dist/collection/lib/{sources/maplibre.js → resources/map.js}

@@ -1,6 +1,6 @@
-import Source from "./source";
+import Resource from "./resource";
 // A source of mapped vector or raster data, accessed remotely
-export default class MapLibreSource extends Source {
+export default class MapResource extends Resource {
     // URL used to generate a MapLibre source when adding to map
     getMapLibreSourceUrl() {
         return this.url;

package/dist/collection/lib/{sources → resources}/openindexmap.js

@@ -1,5 +1,5 @@
-import GeoJSONSource from "./geojson";
-export default class OpenIndexMapSource extends GeoJSONSource {
+import GeoJsonResource from "./geojson";
+export default class OpenIndexMapResource extends GeoJsonResource {
     // Distinguish the layer name from regular GeoJSON
     async getVectorLayers() {
         return ['indexmap'];

package/dist/collection/lib/{sources → resources}/pmtiles.js

@@ -1,8 +1,8 @@
 // Adapted from https://github.com/protomaps/PMTiles/blob/main/app/src/tileset.ts
 import { PMTiles, TileType } from "pmtiles";
-import Source from "./source";
+import Resource from "./resource";
 // Vector or raster tileset stored in a PMTiles archive at a URL
-export default class PMTilesSource extends Source {
+export default class PMTilesResource extends Resource {
     // PMTiles object for reading metadata and tiles from the archive
     archive;
     // Memoized PMTiles metadata and header

package/dist/collection/lib/{sources → resources}/raster.js

@@ -1,6 +1,6 @@
-import MapLibreSource from "./maplibre";
+import MapResource from "./map";
 // Tiled raster data, accessed remotely
-export default class RasterSource extends MapLibreSource {
+export default class RasterResource extends MapResource {
     async isVector() {
         return false;
     }

package/dist/collection/lib/{sources/source.js → resources/resource.js}

@@ -1,10 +1,10 @@
 // A source of previewable data at a URL
-export default class Source {
+export default class Resource {
     // URL to the remote data source
     url;
     // Explicitly provided bounds for the source, if any
     bounds;
-    // Unique ID for this source
+    // Unique ID for this resource
     id;
     // Store the source URL
     constructor(id, url, bounds) {
@@ -12,7 +12,7 @@ export default class Source {
         this.url = url;
         this.bounds = bounds;
     }
-    // Used to label the tabs for switching between sources, e.g.
+    // Used to label the tabs for switching between previews, e.g.
     label() {
         return this.constructor.name;
     }

package/dist/collection/lib/{sources → resources}/tilejson.js

@@ -1,15 +1,22 @@
-import Source from "./source";
+import { fetchOrThrow } from "../errors";
+import MapResource from "./map";
 // Vector or raster tileset described in a TileJSON document at a URL
-export default class TileJSONSource extends Source {
+export default class TileJsonResource extends MapResource {
     // Metadata parsed from TileJSON document
     metadata;
     label() {
         return 'TileJSON';
     }
+    getMapLibreSourceUrl() {
+        return this.url;
+    }
+    getScheme() {
+        return undefined;
+    }
     // Fetch and memoize metadata
     async getMetadata() {
         if (!this.metadata) {
-            const resp = await fetch(this.url);
+            const resp = await fetchOrThrow(this.url);
             this.metadata = await resp.json();
         }
         return this.metadata;
@@ -21,16 +28,26 @@ export default class TileJSONSource extends Source {
         const pathname = new URL(template).pathname;
         return pathname.endsWith('.pbf') || pathname.endsWith('.mvt') || pathname.endsWith('.mlt');
     }
-    // Used to zoom the map to the data once loaded
+    // Used to zoom the map to the data once loaded; bounds are optional in TileJSON, and
+    // without them we leave the camera wherever it already is
     async getBounds() {
         if (this.bounds)
             return this.bounds;
         const metadata = await this.getMetadata();
+        if (!metadata.bounds)
+            return undefined;
         return [
             [metadata.bounds[0], metadata.bounds[1]],
             [metadata.bounds[2], metadata.bounds[3]],
         ];
     }
+    // TileJSON has no tileSize of its own, though some services add one to the document. Raster
+    // tiles served from a {z}/{x}/{y} template are 256px by convention, so assume that otherwise;
+    // MapLibre would default to 512 and draw them upscaled and blurry.
+    async getTileSize() {
+        const metadata = await this.getMetadata();
+        return metadata.tileSize ?? 256;
+    }
     async getVectorLayers() {
         const metadata = await this.getMetadata();
         return metadata.vector_layers.map((l) => l.id);

package/dist/collection/lib/{sources → resources}/tms.js

@@ -1,5 +1,5 @@
-import RasterSource from "./raster";
-export default class TmsSource extends RasterSource {
+import RasterResource from "./raster";
+export default class TmsResource extends RasterResource {
     label() {
         return 'Tiled Map Service (TMS)';
     }

package/dist/collection/lib/{sources → resources}/vector.js

@@ -1,6 +1,6 @@
-import MapLibreSource from "./maplibre";
+import MapResource from "./map";
 // A source of vector data, accessed remotely
-export default class VectorSource extends MapLibreSource {
+export default class VectorResource extends MapResource {
     async isVector() {
         return true;
     }

package/dist/collection/lib/{sources → resources}/wms.js

@@ -1,21 +1,24 @@
-import RasterSource from "./raster";
-const defaultOptions = {
+import RasterResource from "./raster";
+// Number of features to ask for when inspecting; the spec defaults this to 1, which
+// hides everything under the cursor but the topmost feature
+const DEFAULT_FEATURE_COUNT = 10;
+const defaultWmsOptions = {
     layerIds: [],
     bbox: '{bbox-epsg-3857}',
-    srs: 'EPSG:3857',
+    crs: 'EPSG:3857',
     tileSize: 256,
     format: 'image/png',
     transparent: true,
     version: '1.3.0',
 };
 // Data accessed via WMS GetMap requests, which return raster tiles
-export default class WmsSource extends RasterSource {
+export default class WmsResource extends RasterResource {
     options;
     // Memoized metadata via GetCapabilities request
     metadata;
     constructor(id, url, options, bounds) {
         super(id, url, bounds);
-        this.options = { ...defaultOptions, ...options };
+        this.options = { ...defaultWmsOptions, ...options };
         // Assume we're using one layer with the given ID if no layer IDs are provided
         if (!this.options.layerIds || this.options.layerIds.length === 0) {
             this.options.layerIds = [id];
@@ -43,6 +46,9 @@ export default class WmsSource extends RasterSource {
     getTileSize() {
         return this.options.tileSize;
     }
+    async inspect(options) {
+        return await fetch(this.inspectUrl(options));
+    }
     // WMS GetMap URL that will fetch tiles for this source
     get tilesUrl() {
         const tilesUrl = new URL(this.url);
@@ -54,7 +60,7 @@ export default class WmsSource extends RasterSource {
         tilesUrl.searchParams.set('width', String(this.options.tileSize));
         tilesUrl.searchParams.set('height', String(this.options.tileSize));
         tilesUrl.searchParams.set('transparent', String(this.options.transparent));
-        tilesUrl.searchParams.set('srs', this.options.srs);
+        tilesUrl.searchParams.set(this.isVersion130 ? 'crs' : 'srs', this.options.crs);
         tilesUrl.searchParams.set('format', this.options.format);
         tilesUrl.searchParams.set('version', this.options.version);
         // This param can't be encoded because MapLibre needs to template it
@@ -62,6 +68,40 @@ export default class WmsSource extends RasterSource {
         tilesUrlString += `&bbox=${this.options.bbox}`;
         return tilesUrlString;
     }
+    // WMS GetFeatureInfo URL, used to fetch information about features at a specific point
+    inspectUrl(inspectOptions) {
+        const inspectUrl = new URL(this.url);
+        // Merge the provided options with the instance's options
+        const options = { ...this.options, ...inspectOptions };
+        inspectUrl.searchParams.set('service', 'WMS');
+        inspectUrl.searchParams.set('request', 'GetFeatureInfo');
+        inspectUrl.searchParams.set('info_format', 'application/json');
+        inspectUrl.searchParams.set('layers', options.layerIds.join(','));
+        inspectUrl.searchParams.set('query_layers', options.layerIds.join(','));
+        inspectUrl.searchParams.set('version', options.version);
+        inspectUrl.searchParams.set('bbox', options.bbox);
+        inspectUrl.searchParams.set('width', String(options.width));
+        inspectUrl.searchParams.set('height', String(options.height));
+        inspectUrl.searchParams.set('feature_count', String(DEFAULT_FEATURE_COUNT));
+        // 1.3.0 renamed SRS to CRS, and renamed the pixel coordinates X,Y to I,J. Servers
+        // do enforce the names for the version they were asked for, so pick them to match.
+        if (this.isVersion130) {
+            inspectUrl.searchParams.set('crs', options.crs);
+            inspectUrl.searchParams.set('i', String(Math.round(options.x)));
+            inspectUrl.searchParams.set('j', String(Math.round(options.y)));
+        }
+        else {
+            inspectUrl.searchParams.set('srs', options.crs);
+            inspectUrl.searchParams.set('x', String(Math.round(options.x)));
+            inspectUrl.searchParams.set('y', String(Math.round(options.y)));
+        }
+        return inspectUrl.toString();
+    }
+    // Whether this source speaks WMS 1.3.0 or later, which changed some param names
+    get isVersion130() {
+        const [major, minor] = this.options.version.split('.').map(Number);
+        return major > 1 || (major === 1 && minor >= 3);
+    }
     // WMS GetCapabilities URL, used to fetch metadata about the layers
     get capabilitiesUrl() {
         const capabilitiesUrl = new URL(this.url);

package/dist/collection/lib/resources/wms.test.js

@@ -0,0 +1,63 @@
+import { describe, it, expect } from "@stencil/vitest";
+import WmsResource from "./wms";
+// The GetFeatureInfo URL is built by a protected method, so expose it for testing
+class TestWmsSource extends WmsResource {
+    url_for(options) {
+        return new URL(this.inspectUrl(options));
+    }
+}
+const ENDPOINT = 'https://geoservices.lib.berkeley.edu/geoserver/wms';
+// A click in the middle of a 51x51 pixel window over Calaveras County
+const options = {
+    bbox: '-13416701.09,4600766.56,-13411296.18,4606171.48',
+    width: 51,
+    height: 51,
+    x: 25,
+    y: 25,
+};
+describe('WmsSource#inspectUrl', () => {
+    it('uses the 1.3.0 param names by default', () => {
+        const source = new TestWmsSource('s7st30', ENDPOINT, { layerIds: [] });
+        const params = source.url_for(options).searchParams;
+        expect(params.get('version')).toEqual('1.3.0');
+        // 1.3.0 spells these CRS and I,J rather than SRS and X,Y
+        expect(params.get('crs')).toEqual('EPSG:3857');
+        expect(params.get('i')).toEqual('25');
+        expect(params.get('j')).toEqual('25');
+        expect(params.get('srs')).toBeNull();
+        expect(params.get('x')).toBeNull();
+        expect(params.get('y')).toBeNull();
+    });
+    it('uses the older param names for 1.1.1', () => {
+        const source = new TestWmsSource('s7st30', ENDPOINT, { layerIds: [], version: '1.1.1' });
+        const params = source.url_for(options).searchParams;
+        expect(params.get('srs')).toEqual('EPSG:3857');
+        expect(params.get('x')).toEqual('25');
+        expect(params.get('y')).toEqual('25');
+        expect(params.get('crs')).toBeNull();
+        expect(params.get('i')).toBeNull();
+        expect(params.get('j')).toBeNull();
+    });
+    it('passes through the query window and asks about the layer', () => {
+        const source = new TestWmsSource('s7st30', ENDPOINT, { layerIds: [] });
+        const params = source.url_for(options).searchParams;
+        expect(params.get('request')).toEqual('GetFeatureInfo');
+        expect(params.get('bbox')).toEqual(options.bbox);
+        expect(params.get('width')).toEqual('51');
+        expect(params.get('height')).toEqual('51');
+        // Defaults the layer to the source ID, and asks about it rather than just drawing it
+        expect(params.get('layers')).toEqual('s7st30');
+        expect(params.get('query_layers')).toEqual('s7st30');
+    });
+    it('asks for more than the one feature the spec defaults to', () => {
+        const source = new TestWmsSource('s7st30', ENDPOINT, { layerIds: [] });
+        const params = source.url_for(options).searchParams;
+        expect(Number(params.get('feature_count'))).toBeGreaterThan(1);
+    });
+    it('rounds pixel coordinates, which must be integers', () => {
+        const source = new TestWmsSource('s7st30', ENDPOINT, { layerIds: [] });
+        const params = source.url_for({ ...options, x: 25.4, y: 25.6 }).searchParams;
+        expect(params.get('i')).toEqual('25');
+        expect(params.get('j')).toEqual('26');
+    });
+});

package/dist/collection/lib/resources/wmts.js

@@ -0,0 +1,317 @@
+import { LngLatBounds } from "maplibre-gl";
+import RasterResource from "./raster";
+// Half the circumference of the Web Mercator world in meters. The XYZ grid hangs from
+// (-XYZ_ORIGIN, XYZ_ORIGIN), the northwest corner of the world.
+const XYZ_ORIGIN = 20037508.342789244;
+// How far a set's stated origin may sit from that corner and still count as the same grid.
+// Services round the value to varying precision; half a meter is far below one pixel at any
+// zoom a WMTS publishes.
+const ORIGIN_TOLERANCE = 0.5;
+// Codes that all mean Web Mercator: the EPSG one, the deprecated OGC one, and the ESRI one
+const WEB_MERCATOR_CODES = ['3857', '900913', '102100'];
+// The latitude the Web Mercator world stops at. A layer may claim an extent that runs to the
+// pole, but there is no map there to bound it against.
+const MERCATOR_MAX_LATITUDE = 85.051129;
+// Layers (potentially multiple) accessed via WMTS GetTile requests
+// NOTE: in Aardvark, the reference URL is the GetCapabilities URL, not the tile URL
+export default class WmtsResource extends RasterResource {
+    options;
+    // Memoized metadata via GetCapabilities request
+    metadata;
+    constructor(id, url, options, bounds) {
+        super(id, url, bounds);
+        this.options = options;
+        // Assume we're using one layer with the given ID if no layer IDs are provided
+        if (!this.options.layerIds || this.options.layerIds.length === 0) {
+            this.options.layerIds = [id];
+        }
+    }
+    label() {
+        return 'Web Map Tile Service (WMTS)';
+    }
+    // Fetch and memoize WMTS GetCapabilities XML document
+    async getMetadata() {
+        if (!this.metadata) {
+            const resp = await fetch(this.url);
+            const text = await resp.text();
+            this.metadata = new DOMParser().parseFromString(text, 'application/xml');
+        }
+        return this.metadata;
+    }
+    // Build a spec for each layer we were asked for. Layers published only in tile grids
+    // MapLibre can't draw are dropped, and if that leaves nothing we raise rather than
+    // hand back an empty preview.
+    async getLayers() {
+        const metadata = await this.getMetadata();
+        const tileMatrixSets = this.getTileMatrixSets(metadata);
+        // Narrow to the requested layers before building anything: a service like NASA GIBS
+        // lists close to a thousand, and each one costs a walk of its subtree.
+        const elements = Array.from(metadata.getElementsByTagName('Layer')).filter(element => this.isRequested(element));
+        if (elements.length === 0)
+            throw new Error(`This service doesn't publish a layer named ${this.options.layerIds.join(', ')}.`);
+        const layers = elements.map(element => this.createLayer(element, tileMatrixSets)).filter(layer => layer !== undefined);
+        if (layers.length === 0)
+            throw new Error(this.unsupportedGridMessage(elements, tileMatrixSets));
+        return layers;
+    }
+    // Whether a <Layer> element is one of the layers this resource was constructed for.
+    // An empty list means every layer in the document, which can be a lot of them.
+    isRequested(element) {
+        if (this.options.layerIds.length === 0)
+            return true;
+        const layerId = element.getElementsByTagName('ows:Identifier')[0]?.textContent?.trim();
+        return this.options.layerIds.includes(layerId ?? '');
+    }
+    // Create a WmtsLayer spec from a <Layer> element in the GetCapabilities document, or
+    // undefined if none of the grids it's published in can be drawn
+    createLayer(element, tileMatrixSets) {
+        // Get the identifier and title of the layer
+        const layerId = element.getElementsByTagName('ows:Identifier')[0]?.textContent;
+        const title = element.getElementsByTagName('ows:Title')[0]?.textContent;
+        // Get the identifier of the style with attribute isDefault="true", or the first style if none are marked as default
+        const styles = Array.from(element.getElementsByTagName('Style'));
+        const defaultStyle = styles.find(style => style.getAttribute('isDefault') === 'true');
+        const style = defaultStyle ?? styles[0];
+        const styleId = style?.getElementsByTagName('ows:Identifier')[0]?.textContent?.trim();
+        // Use the first grid the layer offers that MapLibre can actually draw, which is not
+        // necessarily the first one listed: services often lead with a national grid
+        const tileMatrixSet = this.getLinkedTileMatrixSets(element, tileMatrixSets).find(set => set.grid);
+        const grid = tileMatrixSet?.grid;
+        if (!tileMatrixSet || !grid)
+            return undefined;
+        // Get the default values for all dimensions listed for the layer
+        // TODO: actually support adjusting these in the previewer?
+        const dimensions = Array.from(element.getElementsByTagName('Dimension'));
+        const dimensionDefaults = dimensions.reduce((acc, dimension) => {
+            const name = dimension.getElementsByTagName('ows:Identifier')[0]?.textContent?.trim();
+            const defaultValue = dimension.getElementsByTagName('Default')[0]?.textContent?.trim();
+            if (name && defaultValue) {
+                acc[name] = defaultValue;
+            }
+            return acc;
+        }, {});
+        // For each tiled ResourceURL, reformat as XYZ-style URL
+        // Each MapLibre layer will be tied to a MapLibre source with multiple tile URLs
+        const templates = Array.from(element.getElementsByTagName('ResourceURL'))
+            .filter(resourceUrl => resourceUrl.getAttribute('resourceType') === 'tile')
+            .map(resourceUrl => resourceUrl.getAttribute('template') ?? '');
+        const tileUrls = this.preferKnownHost(templates).map(template => this.formatTileUrl(template, styleId, tileMatrixSet, dimensionDefaults));
+        const bounds = this.parseBounds(element) ?? this.recordBounds();
+        return {
+            id: layerId,
+            title: title,
+            tileUrls: tileUrls,
+            tileSize: this.options.tileSize ?? grid.tileSize,
+            minzoom: clamp(this.boundsMinzoom(bounds), grid.minzoom, grid.maxzoom),
+            maxzoom: grid.maxzoom,
+            bounds: bounds,
+        };
+    }
+    // The extent the layer covers, from its <ows:WGS84BoundingBox>. OWS writes both corners as
+    // "longitude latitude" in CRS84 whatever axis order the layer's own CRS uses, so the numbers
+    // come out in MapLibre's order as they are read.
+    parseBounds(element) {
+        const box = element.getElementsByTagName('ows:WGS84BoundingBox')[0];
+        if (!box)
+            return undefined;
+        const [west, south] = numericCorner(box, 'ows:LowerCorner');
+        const [east, north] = numericCorner(box, 'ows:UpperCorner');
+        if ([west, south, east, north].some(value => !Number.isFinite(value)))
+            return undefined;
+        return [west, south, east, north];
+    }
+    // The extent the record claims, for a service that publishes none of its own. Aardvark states
+    // it per record rather than per layer, so it's the coarser of the two, but it still keeps us
+    // from treating a city as if it covered the world.
+    recordBounds() {
+        if (!this.bounds)
+            return undefined;
+        const bounds = LngLatBounds.convert(this.bounds);
+        return [bounds.getWest(), bounds.getSouth(), bounds.getEast(), bounds.getNorth()];
+    }
+    // The first zoom at which a single tile no longer dwarfs the layer. Below it every tile we
+    // could ask for lies mostly outside the layer, and a service that draws that emptiness
+    // instead of answering 404 - Vienna's orthophoto pads it with opaque white, JPEG having no
+    // alpha channel to leave it out with - spreads the padding across the map: at zoom 1 the one
+    // tile that touches Vienna covers a quarter of the world. Bounds alone don't help, since
+    // MapLibre keeps any tile that so much as intersects them. A tile spans 1/2^z of the world
+    // on each axis, so the layer first fills one when 2^z reaches 1 over its widest extent.
+    boundsMinzoom(bounds) {
+        if (!bounds)
+            return 0;
+        const [west, south, east, north] = bounds;
+        const width = east < west ? east - west + 360 : east - west;
+        const extent = Math.max(width / 360, mercatorY(south) - mercatorY(north));
+        // An extent of nothing is a layer we can never fit a tile to; let the caller's clamp put it
+        // at the deepest zoom the grid has rather than the shallowest
+        if (!(extent > 0))
+            return Infinity;
+        return Math.ceil(Math.log2(1 / extent));
+    }
+    // Narrow the tile templates to the host we know answers. Services list several hosts to
+    // shard requests across, but MapLibre assigns each tile to one of them by coordinate -
+    // urls[(x + y) % urls.length] - and never retries elsewhere, so one stale hostname
+    // silently costs that share of the tiles. The host that served the capabilities document
+    // is the one we have evidence for: it resolved, answered, and allowed the cross-origin
+    // read. Where any template is on that host we keep only those, and upgrade them to https
+    // if that's how we reached it, since a document served over https can still advertise its
+    // tiles over http - which the browser then blocks as mixed content. Sharding buys little
+    // over HTTP/2 anyway, where the whole point of it, the per-origin connection limit, is gone.
+    preferKnownHost(templates) {
+        const capabilities = new URL(this.url);
+        const known = templates.filter(template => hostOf(template) === capabilities.host);
+        if (known.length === 0)
+            return templates;
+        if (capabilities.protocol !== 'https:')
+            return known;
+        return known.map(template => template.replace(/^http:/, 'https:'));
+    }
+    // The tile matrix sets a layer links to, in the order it lists them. Links naming a set
+    // the document never defines are skipped.
+    getLinkedTileMatrixSets(element, tileMatrixSets) {
+        return Array.from(element.getElementsByTagName('TileMatrixSetLink'))
+            .map(link => link.getElementsByTagName('TileMatrixSet')[0]?.textContent?.trim())
+            .map(id => (id ? tileMatrixSets.get(id) : undefined))
+            .filter(set => set !== undefined);
+    }
+    // Every <TileMatrixSet> definition in the document, keyed by identifier. Each layer also
+    // nests a <TileMatrixSet> inside its <TileMatrixSetLink> elements, but those hold only an
+    // identifier; the definitions are the ones with <TileMatrix> children.
+    getTileMatrixSets(metadata) {
+        const sets = Array.from(metadata.getElementsByTagName('TileMatrixSet'))
+            .filter(element => element.getElementsByTagName('TileMatrix').length > 0)
+            .map(element => this.parseTileMatrixSet(element))
+            .filter(set => set !== undefined);
+        return new Map(sets.map(set => [set.id, set]));
+    }
+    // Read a <TileMatrixSet> definition, working out whether MapLibre can draw from it
+    parseTileMatrixSet(element) {
+        const id = element.getElementsByTagName('ows:Identifier')[0]?.textContent?.trim();
+        const crs = element.getElementsByTagName('ows:SupportedCRS')[0]?.textContent?.trim();
+        if (!id || !crs)
+            return undefined;
+        return { id, crs, grid: this.parseXyzGrid(element, crs) };
+    }
+    // Reduce a tile matrix set to the numbers MapLibre needs, or undefined if its geometry
+    // isn't the XYZ grid. MapLibre draws raster tiles from that one grid only: Web Mercator,
+    // hung from the northwest corner of the world, 2^z square tiles on a side at zoom z. Tile
+    // indices in any other grid address different ground - a geographic (EPSG:4326) grid, for
+    // instance, spaces its rows evenly in latitude and is twice as wide as it is tall - so
+    // feeding them to MapLibre draws the wrong place, or falls off the edge of the matrix.
+    parseXyzGrid(element, crs) {
+        if (!isWebMercator(crs))
+            return undefined;
+        const elements = Array.from(element.getElementsByTagName('TileMatrix'));
+        const levels = elements.map(matrix => this.parseTileMatrix(matrix)).filter(level => level !== undefined);
+        if (levels.length === 0 || levels.length !== elements.length)
+            return undefined;
+        // Every level has to agree on tile size and on how it spells its identifier, and each
+        // has to hold exactly the tiles that its zoom of the XYZ grid holds
+        const [first] = levels;
+        if (levels.some(level => level.tileWidth !== first.tileWidth || level.prefix !== first.prefix))
+            return undefined;
+        if (levels.some(level => !isXyzLevel(level)))
+            return undefined;
+        const zooms = levels.map(level => level.zoom);
+        return {
+            tileSize: first.tileWidth,
+            levelPrefix: first.prefix,
+            minzoom: Math.min(...zooms),
+            maxzoom: Math.max(...zooms),
+        };
+    }
+    // Read one <TileMatrix>, or undefined if its identifier doesn't end in a zoom level
+    parseTileMatrix(element) {
+        const identifier = element.getElementsByTagName('ows:Identifier')[0]?.textContent?.trim() ?? '';
+        const level = identifier.match(/^(.*[^0-9])?([0-9]+)$/);
+        if (!level)
+            return undefined;
+        // MapLibre writes the zoom into {z} in plain decimal, so a level spelled any other way
+        // (zero-padded, say) would give us a URL the service doesn't answer to
+        if (String(Number(level[2])) !== level[2])
+            return undefined;
+        return {
+            zoom: Number(level[2]),
+            prefix: level[1] ?? '',
+            tileWidth: numericChild(element, 'TileWidth'),
+            tileHeight: numericChild(element, 'TileHeight'),
+            matrixWidth: numericChild(element, 'MatrixWidth'),
+            matrixHeight: numericChild(element, 'MatrixHeight'),
+            topLeft: (element.getElementsByTagName('TopLeftCorner')[0]?.textContent ?? '').trim().split(/\s+/).map(Number),
+        };
+    }
+    // Rewrite the tile URL template to a MapLibre-compatible (XYZ-style) URL
+    formatTileUrl(template, style, tileMatrixSet, dimensionDefaults) {
+        let url = template
+            .replace('{TileMatrixSet}', tileMatrixSet.id)
+            .replace('{Style}', style ?? '')
+            .replace('{TileMatrix}', `${tileMatrixSet.grid?.levelPrefix ?? ''}{z}`)
+            .replace('{TileRow}', '{y}')
+            .replace('{TileCol}', '{x}');
+        if (dimensionDefaults) {
+            for (const [key, value] of Object.entries(dimensionDefaults)) {
+                url = url.replace(`{${key}}`, value);
+            }
+        }
+        return url;
+    }
+    // Explain that we found the layers but can't draw any of them, naming the grids they were
+    // published in so the mismatch is visible without reading the GetCapabilities document
+    unsupportedGridMessage(elements, tileMatrixSets) {
+        const offered = elements.flatMap(element => this.getLinkedTileMatrixSets(element, tileMatrixSets)).map(set => `${set.id} (${set.crs})`);
+        const grids = Array.from(new Set(offered)).join(', ');
+        const named = this.options.layerIds.join(', ');
+        return `This service publishes ${named} only in tile grids that can't be displayed${grids ? `: ${grids}` : ''}. Previewing WMTS needs a Web Mercator (EPSG:3857) grid, such as GoogleMapsCompatible.`;
+    }
+    // We rewrite WMTS tile URLs to XYZ-style URLs, so the scheme is always 'xyz'
+    getScheme() {
+        return 'xyz';
+    }
+}
+// WMTS advertises the CRS in any of several notations - "EPSG:3857",
+// "urn:ogc:def:crs:EPSG:6.18:3:3857", "http://www.opengis.net/def/crs/EPSG/0/3857" - all of
+// which end in the code.
+function isWebMercator(crs) {
+    const code = crs.split(/[:/]/).pop() ?? '';
+    return WEB_MERCATOR_CODES.includes(code);
+}
+// Whether a level holds exactly what its zoom of the XYZ grid holds: square tiles, 2^z of
+// them on a side, hung from the northwest corner of the world
+function isXyzLevel(matrix) {
+    const tiles = 2 ** matrix.zoom;
+    const [x, y] = matrix.topLeft;
+    return (matrix.tileWidth === matrix.tileHeight &&
+        matrix.matrixWidth === tiles &&
+        matrix.matrixHeight === tiles &&
+        Math.abs(x + XYZ_ORIGIN) <= ORIGIN_TOLERANCE &&
+        Math.abs(y - XYZ_ORIGIN) <= ORIGIN_TOLERANCE);
+}
+// The host a tile template points at, or undefined if it isn't an absolute URL. The braces
+// left in the template for MapLibre don't bother the URL parser.
+function hostOf(template) {
+    try {
+        return new URL(template).host;
+    }
+    catch {
+        return undefined;
+    }
+}
+// Read a numeric child element, or NaN when it's missing or isn't a number. NaN fails every
+// comparison the grid checks make, which is what we want from a malformed definition.
+function numericChild(element, tagName) {
+    const text = element.getElementsByTagName(tagName)[0]?.textContent?.trim();
+    return text ? Number(text) : NaN;
+}
+// One corner of an OWS bounding box, written as space-separated ordinates
+function numericCorner(element, tagName) {
+    const text = element.getElementsByTagName(tagName)[0]?.textContent?.trim() ?? '';
+    return text.split(/\s+/).map(Number);
+}
+// Where a latitude falls in the Web Mercator world, 0 at the north edge and 1 at the south
+function mercatorY(lat) {
+    const clamped = clamp(lat, -MERCATOR_MAX_LATITUDE, MERCATOR_MAX_LATITUDE);
+    return (180 - (180 / Math.PI) * Math.log(Math.tan(Math.PI / 4 + (clamped * Math.PI) / 360))) / 360;
+}
+function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}