@projektemacher/storymapjs 0.10.6 → 0.10.8

package/src/map/openlayers/Map.OpenLayers.ts

@@ -0,0 +1,2492 @@
+import OlMap from "ol/Map";
+import View from "ol/View";
+import type { Control } from "ol/control";
+import type { Interaction } from "ol/interaction";
+import { Tile as TileLayer, Vector as VectorLayer } from "ol/layer";
+import Layer from "ol/layer/Layer";
+import VectorTileLayer from "ol/layer/VectorTile";
+import { XYZ, OSM, IIIF } from "ol/source";
+import type Source from "ol/source/Source";
+import VectorSource from "ol/source/Vector";
+import LineString from "ol/geom/LineString";
+import Feature from "ol/Feature";
+import { Style, Stroke } from "ol/style";
+import { fromLonLat, toLonLat } from "ol/proj";
+import type Projection from "ol/proj/Projection";
+import { boundingExtent, getIntersection } from "ol/extent";
+import type { Extent } from "ol/extent";
+import TileGrid from "ol/tilegrid/TileGrid";
+import type ImageTile from "ol/ImageTile";
+import OverviewMap from "ol/control/OverviewMap";
+import { defaults as interactionDefaults } from "ol/interaction";
+import { applyStyle } from "ol-mapbox-style";
+import IIIFInfo, { type ImageInformationResponse } from "ol/format/IIIFInfo";
+
+import "ol/ol.css";
+
+import Map from "../Map";
+import OpenLayersMapMarker from "./MapMarker.OpenLayers";
+import { padCroppedZoomifyTile } from "./zoomifyTiles";
+import type { LinePoint, ViewToOptions } from "../types";
+import type {
+    LatLngLiteral,
+    StorymapOverlayLayer,
+    StorymapTilejson,
+    StorymapSlide,
+    StorymapSlideLocation,
+} from "../../types";
+import { fitGeoreference, resolveInfoJsonUrl } from "../georeference";
+import {
+    consentManagerOf,
+    tileService,
+    type ConsentManager,
+    type ConsentService,
+} from "../../storymap/Consent";
+import { sanitizeSlideText } from "../../media/EmbedUtil";
+
+/*	Map.OpenLayers
+	Creates a Map using OpenLayers
+================================================= */
+
+const MAX_ZOOM = 19;
+
+/** What kind of imagery an `imageready` source carries. */
+export type ImagereadyKind = "iiif" | "zoomify" | "tiles";
+
+/**
+ * Payload of the `imageready` event: the source that became usable, what
+ * kind of imagery it is, and the layer carrying it (`null` when the source
+ * outlives its layer).
+ */
+export interface ImagereadyPayload {
+    source: { getState?(): string };
+    kind: ImagereadyKind;
+    layer: Layer | null;
+}
+
+/**
+ * Zoom ladder for image-space maps (issue #465): rung 0 shows any image fully
+ * zoomed out, finer rungs reach sub-pixel detail. It keeps view zooms,
+ * marker zooms and tile loading on one consistent ladder (tile enqueueing
+ * silently drops tiles otherwise).
+ */
+const IMAGE_RESOLUTIONS = Array.from({ length: 25 }, (_, i) => 2 ** (16 - i));
+
+export default class OpenLayers extends Map {
+    declare "_map": OlMap;
+    declare "_tile_layer": Layer;
+    declare "_line": VectorLayer;
+    declare "_line_active": VectorLayer;
+    declare "_tile_layer_mini": Layer | null;
+    declare "_mini_map": OverviewMap;
+    declare "_markers": OpenLayersMapMarker[];
+    /** App-level stacked overlays (see the `overlays` option) */
+    declare "_overlay_layers": Layer[];
+    /**
+     * The `overlays[]` entries that produced a layer, parallel to
+     * `_overlay_layers`: a malformed entry is skipped, so the two arrays
+     * can be shorter than the option list.
+     */
+    declare "_overlay_entries": StorymapOverlayLayer[];
+    /** rAF handle of the running active-line draw animation */
+    declare "_line_animation": number | null;
+    /** Sources `imageready` has already been fired for. */
+    declare "_imageready_fired": WeakSet<object>;
+
+    /*	Create the Map
+	================================================== */
+    _createMap(): void {
+        const is_image_map = this.isImageSpace();
+        this._imageready_fired = new WeakSet();
+
+        // Caller-supplied OpenLayers options: `controls` replaces the defaults
+        // (the viewer installs none), `interactions` are added to the viewer's
+        // own pan/zoom set, `view` merges over the computed default, everything
+        // else passes through
+        const user_map_options = this.options.map_options ?? {};
+        const { element: _element, view: user_view, ...passthrough } = user_map_options;
+        const user_view_options = (user_view ?? {}) as Record<string, unknown>;
+
+        // bbox limitation (map_bbox): the view center is constrained to the
+        // box (constrainOnlyCenter) — a hard extent constraint would pin the
+        // center and resolution whenever the viewport fills or aspect-clips
+        // the box, undoing the panel offset and spreading the markers out
+        // (probed: a 640x800 viewport aspect-clips a wide bbox, so the
+        // strict constraint locks the zoom and the route overflows). Image-
+        // space maps use raw pixel coordinates.
+        const bbox_extent = this._bboxExtent();
+
+        // A TileJSON tile source states its own zoom ladder, its covered area
+        // and its default view, and all three are honoured here (§2.9). A
+        // keyword basemap has none of these, so the defaults stand.
+        const tilejson = this._tilejsonFor(this.options.map_type);
+        const tile_min_zoom = tilejson?.minzoom ?? 0;
+        const tile_max_zoom = tilejson?.maxzoom ?? MAX_ZOOM;
+        const tile_extent = tilejson?.bounds
+            ? fromLonLat(tilejson.bounds as [number, number, number, number])
+            : null;
+
+        this._map = new OlMap({
+            ...passthrough,
+            target: this._el.map,
+            controls: (user_map_options.controls as Control[]) ?? [],
+            interactions: (user_map_options.interactions as Interaction[]) ?? [],
+            view: new View({
+                projection: is_image_map ? "EPSG:4326" : "EPSG:3857",
+                ...(tilejson?.center
+                    ? {
+                          center: fromLonLat([tilejson.center[0], tilejson.center[1]]),
+                          zoom: tilejson.center[2],
+                      }
+                    : { center: [0, 0], zoom: 0 }),
+                minZoom: tile_min_zoom,
+                maxZoom: is_image_map ? IMAGE_RESOLUTIONS.length - 1 : tile_max_zoom,
+                // a tile source that only covers part of the world: keep the
+                // view inside what it actually has tiles for
+                ...(tile_extent && !is_image_map
+                    ? { extent: tile_extent, constrainOnlyCenter: true }
+                    : {}),
+                // image maps live outside the 4326 world: opt out of the
+                // global-projection constraints (they cap resolution at
+                // fit-the-world and clamp the center to [-90, 90]) and use
+                // the image zoom ladder instead of the default one
+                // (issue #465)
+                ...(is_image_map ? { multiWorld: true, resolutions: IMAGE_RESOLUTIONS } : {}),
+                // legacy zoomify: the image pyramid needs zooms where the
+                // world is smaller than the viewport (the original renderer
+                // showed the painting at ~487px in a 1280px window)
+                ...(this.options.map_type === "zoomify" ? { multiWorld: true } : {}),
+                ...(bbox_extent ? { extent: bbox_extent, constrainOnlyCenter: true } : {}),
+                ...user_view_options,
+            }),
+        });
+
+        this._map.on("loadend", () => {
+            this._onMapLoaded(undefined);
+        });
+
+        // keep the marker overlays above the layer canvases: OL pins the
+        // overlay container at z-index 0 (inline), and during pan/zoom
+        // animations the composited canvases can transiently paint over it —
+        // the marker icons flicker
+        const overlay_container = this._el.map.querySelector(".ol-overlaycontainer");
+        if (overlay_container) {
+            (overlay_container as HTMLElement).style.zIndex = "1";
+        }
+
+        // Create Tile Layer
+        // Tile Layer — GDPR consent mode defers it until the visitor allows
+        // map tiles (the consent bar renders over the map)
+        const consent = consentManagerOf(this.options);
+        const tile_service = tileService();
+        if (this.options.consent_required && consent) {
+            if (consent.isGranted(tile_service.key)) {
+                this._addTileLayer();
+            } else if (!consent.isDenied(tile_service.key)) {
+                void this._requestTileConsent(consent, tile_service);
+            }
+            // denied → the map renders with background color and markers only
+        } else {
+            this._addTileLayer();
+        }
+
+        // Create Overall Connection Line (reserved z-range 10/11 for the
+        // route lines; see the stack-order note at _addTileLayer)
+        this._line = this._createLine();
+        this._line.setStyle(this._lineStyle(this.options.line_color_inactive));
+        this._addLineToMap(this._line);
+        this._line.setZIndex(10);
+        this._line.setOpacity(this.options.line_opacity);
+
+        // Create Active Line
+        this._line_active = this._createLine();
+        this._line_active.setStyle(this._lineStyle(this.options.line_color));
+        this._addLineToMap(this._line_active);
+        this._line_active.setZIndex(11);
+        this._line_active.setOpacity(1);
+
+        if (this.options.map_as_image) {
+            this._line_active.setVisible(false);
+            this._line.setVisible(false);
+        }
+
+        // Stacked raster overlays (base tiles 1.., below the route lines)
+        this._overlay_layers = [];
+        this._overlay_entries = [];
+        this._buildOverlays();
+
+        // Native interactions (pan/zoom), no scroll zoom by default
+        const interactions = interactionDefaults({ mouseWheelZoom: false });
+        interactions.forEach((i) => this._map.addInteraction(i));
+
+        // Attribution
+        this._updateAttribution();
+    }
+
+    /** Extra attribution fragments (e.g. overlay credits), always listed last. */
+    declare "_extra_attributions": string[];
+
+    /**
+     * Append extra attribution fragments and refresh the line. Hosts with
+     * custom layers use this instead of rewriting `.vco-map-attribution`.
+     */
+    setExtraAttributions(parts: string[]): void {
+        this._extra_attributions = [...parts];
+        this._updateAttribution();
+    }
+
+    /*	Public accessors
+	Consumers get the raw OpenLayers map via `storymap.map`; these hand out
+	the internal objects the viewer keeps private (base/overlay/minimap layers,
+	the route lines, the markers) so nothing has to be reached for through an
+	underscore field. Layer order in `map.getLayers()` is NOT the overlay
+	order (creation order is [base, line, line_active, overlay0…] and zIndex is
+	a separate axis), so `getOverlayLayers()` is the only correct way to map an
+	`overlays[]` index onto a layer.
+	================================================= */
+
+    /** The base tile layer (the one created for `map_type`), if consent has not deferred it. */
+    getBaseLayer(): Layer | null {
+        return this._tile_layer ?? null;
+    }
+
+    /** The stacked `overlays[]` layers, in `overlays[]` order. */
+    getOverlayLayers(): Layer[] {
+        return [...this._overlay_layers];
+    }
+
+    /** One stacked overlay layer by its `overlays[]` index, or `null`. */
+    getOverlayLayer(index: number): Layer | null {
+        return this._overlay_layers[index] ?? null;
+    }
+
+    /** The minimap's OpenLayers map (the `OverviewMap` control's inner map). */
+    getMinimap(): OlMap | null {
+        const overview = this._mini_map?.getOverviewMap?.() ?? null;
+        return overview ?? null;
+    }
+
+    /** The full (inactive) route line layer. */
+    getLine(): Layer | null {
+        return this._line ?? null;
+    }
+
+    /** The highlighted route line layer drawn up to the current slide. */
+    getLineActive(): Layer | null {
+        return this._line_active ?? null;
+    }
+
+    /** The markers, in slide order (the index matches the slide index). */
+    getMarkers(): OpenLayersMapMarker[] {
+        return [...this._markers];
+    }
+
+    /** One marker by slide index, or `null`. */
+    getMarker(index: number): OpenLayersMapMarker | null {
+        return this._markers[index] ?? null;
+    }
+
+    /**
+     * (Re)render the attribution line for the current map type. Called at
+     * creation and on every `map_type` switch, which previously left the
+     * initial text stale.
+     */
+    _updateAttribution(): void {
+        const extras = this._extra_attributions ?? [];
+        // Identical credits (e.g. stacked overlays sharing one source, or the
+        // attribution option restating the base credit) collapse to one entry
+        const parts = [
+            ...new Set([...this._getAttribution(this.options.map_type), ...extras].filter(Boolean)),
+        ].join(" | ");
+        let el = this._el.map.querySelector(".vco-map-attribution") as HTMLElement | null;
+        if (!el) {
+            this._el.map.insertAdjacentHTML("beforeend", `<div class="vco-map-attribution"></div>`);
+            el = this._el.map.querySelector(".vco-map-attribution") as HTMLElement | null;
+        }
+        if (el) {
+            // The library-authored credits are trusted markup, but
+            // `options.attribution` and overlay credits come from the
+            // storymap JSON. Rather than trusting them, the whole line is
+            // re-sanitized: a fragment that is not well-formed markup is
+            // unwrapped to text, so an author-supplied credit can never
+            // inject an element into the map.
+            el.textContent = "";
+            el.appendChild(sanitizeSlideText(parts));
+        }
+    }
+
+    _getAttribution(map_type: string): string[] {
+        const parts = [
+            "<a href='https://storymap.knightlab.com/' target='_blank' class='vco-knightlab-brand'><span>&#x25a0;</span> StoryMapJS</a>",
+        ];
+        // Our own `.vco-map-attribution` line is the rendered default (the
+        // OL attribution control is not added), so this hand-built line is
+        // what the visitor sees. Sources additionally carry the plain-text
+        // credit from `_sourceAttributions`, so `source.getAttributions()`
+        // and a consumer's own Attribution control are not left empty.
+        // Emitting provider credit
+        // only for OSM left Stadia, Mapbox and the OL XYZ template providers
+        // uncredited, which their terms of service require. The credit is
+        // keyed off the resolved map_type, so a custom `{z}` template gets
+        // the generic "map data" line and the author can still override it
+        // with the `attribution` option.
+        if (map_type === "" || map_type.startsWith("osm")) {
+            parts.push(
+                "© <a target='_blank' href='https://www.openstreetmap.org/copyright'>OpenStreetMap</a> contributors",
+            );
+        } else if (map_type.startsWith("stadia") || map_type === "stamen") {
+            parts.push(
+                '© <a target="_blank" rel="noopener noreferrer" href="https://stadiamaps.com/">Stadia Maps</a>, ' +
+                    '© <a target="_blank" rel="noopener noreferrer" href="https://openmaptiles.org/">OpenMapTiles</a> ' +
+                    '© <a target="_blank" rel="noopener noreferrer" href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors',
+            );
+        } else if (map_type.startsWith("mapbox://")) {
+            parts.push('© <a target="_blank" href="https://www.mapbox.com/about/maps/">Mapbox</a>');
+        } else if (map_type.startsWith("ch-") || map_type.startsWith("esri")) {
+            parts.push('Map data © <a target="_blank" href="https://www.esri.com/">Esri</a>');
+        } else {
+            parts.push("Map data");
+        }
+        if (this.options.attribution) {
+            parts.push(this.options.attribution);
+        }
+        return parts;
+    }
+
+    /**
+     * The provider credit for `map_type` as plain text (no HTML), for the
+     * OpenLayers source `attributions`. Our own `.vco-map-attribution` line
+     * stays the rendered default and uses the linked `_getAttribution`
+     * version; this makes `source.getAttributions()` (and a consumer's
+     * `ol/control/Attribution`) work instead of returning nothing.
+     */
+    _sourceAttributions(map_type: string): string[] {
+        const parts: string[] = [];
+        if (map_type === "" || map_type.startsWith("osm")) {
+            parts.push("© OpenStreetMap contributors");
+        } else if (map_type.startsWith("stadia") || map_type === "stamen") {
+            parts.push("© Stadia Maps, © OpenMapTiles © OpenStreetMap contributors");
+        } else if (map_type.startsWith("mapbox://")) {
+            parts.push("© Mapbox");
+        } else if (map_type.startsWith("ch-") || map_type.startsWith("esri")) {
+            parts.push("Map data © Esri");
+        } else {
+            parts.push("Map data");
+        }
+        if (this.options.attribution) {
+            parts.push(this.options.attribution);
+        }
+        return parts;
+    }
+
+    /*	Create Tile Layer
+	================================================== */
+    /**
+     * Create the tile layer and register its load handler. Deferred until
+     * the visitor allows map tiles in consent mode.
+     */
+    _addTileLayer(): void {
+        this._tile_layer = this._createTileLayer(this.options.map_type);
+        // explicit stack order (base tiles 0, overlays 1.., route lines
+        // 10/11): the switch path re-adds the tile layer last, which used
+        // to bury the route lines under fresh tiles
+        this._tile_layer.setZIndex(0);
+        this._map.addLayer(this._tile_layer);
+    }
+
+    /**
+     * Ask for tile consent, then attach the layers if allowed.
+     */
+    async _requestTileConsent(consent: ConsentManager, tile_service: ConsentService) {
+        if (await consent.request(tile_service, "", this._el.map)) {
+            this._onTilesAllowed();
+        }
+    }
+
+    /*	Stacked overlays (the `overlays` option)
+    ================================================== */
+    /**
+     * (Re)build the stacked raster overlays from the `overlays` option.
+     * Overlays sit above the base tiles (z 1..n) and below the route lines
+     * (z 10/11); every entry accepts any `map_type` value plus declarative
+     * presentation, so hosts no longer capture and patch layer objects.
+     * An entry carrying a `georeference` places a IIIF image on the
+     * geographic map instead of stacking a tile source.
+     */
+    _buildOverlays(): void {
+        for (const layer of this._overlay_layers) {
+            this._map.removeLayer(layer);
+        }
+        this._overlay_layers = [];
+        this._overlay_entries = [];
+        if (!this._tilesAllowed()) {
+            return;
+        }
+        const overlays = this.options.overlays ?? [];
+        overlays.forEach((entry, i) => {
+            let layer: Layer | null = null;
+            if (entry.georeference) {
+                layer = this._createGeoreferencedOverlay(entry);
+            } else if (entry.map_type) {
+                layer = this._createTileLayer(entry.map_type);
+            } else {
+                console.warn(
+                    "StoryMapJS: an overlays[] entry has neither map_type nor georeference and was skipped:",
+                    entry,
+                );
+            }
+            if (!layer) {
+                return;
+            }
+            // reserved z-range 1..n for stacked overlays (base tiles 0,
+            // route lines 10/11; see _addTileLayer)
+            layer.setZIndex(1 + i);
+            if (entry.opacity !== undefined) {
+                layer.setOpacity(entry.opacity);
+            }
+            if (entry.visible !== undefined) {
+                layer.setVisible(entry.visible);
+            }
+            if (entry.className) {
+                // OpenLayers exposes no className setter; overriding the
+                // per-frame getClassName hook paints this layer into its own
+                // container div, which blend modes can then target
+                const className = entry.className;
+                layer.getClassName = () => className;
+            }
+            if (entry.extent) {
+                const extent = this._lonLatBboxToExtent(entry.extent);
+                if (extent) {
+                    layer.setExtent(extent);
+                }
+            }
+            this._map.addLayer(layer);
+            this._overlay_layers.push(layer);
+            this._overlay_entries.push(entry);
+            this._paintOverlayBlend(entry);
+        });
+        this._syncOverlayAttributions();
+    }
+
+    /**
+     * Build a stacked overlay from a IIIF Georeference Extension payload
+     * (`overlays[].georeference`): the ground control points are fitted
+     * affinely and the image is placed as a geographic extent, which
+     * OpenLayers reprojects onto the view exactly like the IIIF basemap.
+     *
+     * The layer is returned empty and filled in asynchronously, mirroring
+     * the `iiif` basemap path — only the fit (pure, synchronous) decides
+     * whether a layer exists at all, so overlay indices stay stable.
+     */
+    _createGeoreferencedOverlay(entry: StorymapOverlayLayer): TileLayer | null {
+        const georeference = entry.georeference;
+        if (!georeference) {
+            return null;
+        }
+        // image-space views (iiif/zoomify) have no geographic space to
+        // place the sheet in
+        if (this._map.getView().getProjection().getCode() !== "EPSG:3857") {
+            console.warn(
+                "StoryMapJS: a georeferenced overlay was skipped because this map has no geographic view (image maps cannot place sheets).",
+            );
+            return null;
+        }
+        const fit = fitGeoreference(georeference.body, georeference.width, georeference.height);
+        if (fit.kind === "skipped") {
+            console.warn(
+                `StoryMapJS: georeferenced overlay ${georeference.url} was skipped: ${fit.reason}.`,
+            );
+            return null;
+        }
+        const layer = new TileLayer();
+        const info_url = resolveInfoJsonUrl(georeference.url);
+        fetch(info_url)
+            .then((r) => r.json())
+            .then((info: unknown) => {
+                const parsed = new IIIFInfo(
+                    info as ImageInformationResponse,
+                ).getTileSourceOptions();
+                const size = info as { width?: number; height?: number };
+                if (typeof size.width !== "number" || typeof size.height !== "number") {
+                    console.error("IIIF info.json is missing width/height:", info_url);
+                    layer.setVisible(false);
+                    return;
+                }
+                const geo_source = new IIIF({
+                    ...(parsed ?? {}),
+                    projection: "EPSG:4326",
+                    // the fitted corner box: the affine placement of the
+                    // image in geographic coordinates
+                    extent: fit.bbox,
+                    size: [size.width, size.height],
+                    crossOrigin: "anonymous",
+                    attributions: entry.attribution ? [entry.attribution] : [],
+                });
+                layer.setSource(geo_source);
+                this._fireImageready(geo_source, "iiif", layer);
+            })
+            .catch((err) => {
+                // the layer stays in place (indices must not shift) but
+                // renders nothing; the console carries the reason
+                console.error("IIIF info.json could not be loaded:", info_url, err?.stack || err);
+                layer.setVisible(false);
+            });
+        return layer;
+    }
+
+    /**
+     * Convert a lon/lat clip box to view units. Only meaningful on
+     * mercator maps; image-space maps (iiif/zoomify) and malformed
+     * boxes yield null (no constraint).
+     */
+    _lonLatBboxToExtent(bbox: [number, number, number, number]): Extent | null {
+        if (
+            !Array.isArray(bbox) ||
+            bbox.length !== 4 ||
+            bbox.some((n) => typeof n !== "number" || !isFinite(n))
+        ) {
+            return null;
+        }
+        if (this._map.getView().getProjection().getCode() !== "EPSG:3857") {
+            return null;
+        }
+        return boundingExtent([fromLonLat([bbox[0], bbox[1]]), fromLonLat([bbox[2], bbox[3]])]);
+    }
+
+    /**
+     * Apply an overlay's blend mode to its layer container. The container
+     * div only exists once the layer has rendered, so retry on later
+     * frames (bounded: rendering settles within a frame or two of any
+     * add/visibility change).
+     */
+    _paintOverlayBlend(entry: { className?: string; blendMode?: string }, retries = 60): void {
+        if (!entry.blendMode || !entry.className) {
+            return;
+        }
+        // OpenLayers replaces the container class wholesale (it is not
+        // merged with the default), so match every safe token instead of
+        // assuming a lone class name
+        const tokens = entry.className.split(/\s+/).filter((token) => /^[\w-]+$/.test(token));
+        if (tokens.length === 0) {
+            return;
+        }
+        const el = this._el.map.querySelector("." + tokens.join("."));
+        if (el) {
+            (el as HTMLElement).style.mixBlendMode = entry.blendMode;
+            return;
+        }
+        // the container div only exists once the layer has rendered
+        if (retries > 0) {
+            requestAnimationFrame(() => this._paintOverlayBlend(entry, retries - 1));
+        }
+    }
+
+    /** Refresh the attribution line with the visible overlays' credits. */
+    _syncOverlayAttributions(): void {
+        const parts: string[] = [];
+        this._overlay_layers.forEach((layer, i) => {
+            const credit = this._overlay_entries[i]?.attribution;
+            if (credit && layer.getVisible()) {
+                parts.push(credit);
+            }
+        });
+        this.setExtraAttributions(parts);
+    }
+
+    /**
+     * Number of stacked overlay layers (see the `overlays` option). Alias:
+     * `getOverlayLayers().length`.
+     */
+    getOverlayCount(): number {
+        return this._overlay_layers.length;
+    }
+
+    /**
+     * Show or hide a stacked overlay by index (re-syncs attribution). The
+     * index counts built layers, i.e. it skips malformed entries.
+     *
+     * Prefer `getOverlayLayer(index).setVisible(v)` on the layer itself; this
+     * wrapper exists because it also re-syncs the attribution line and the
+     * overlay blend mode, which a bare `setVisible()` does not.
+     */
+    setOverlayVisible(index: number, visible: boolean): void {
+        const layer = this._overlay_layers[index];
+        if (!layer) {
+            return;
+        }
+        layer.setVisible(visible);
+        const entry = this._overlay_entries[index];
+        if (entry && visible) {
+            this._paintOverlayBlend(entry);
+        }
+        this._syncOverlayAttributions();
+    }
+
+    /** Set a stacked overlay's opacity by index. */
+    /**
+     * Alias: `getOverlayLayer(index)?.setOpacity(opacity)`.
+     */
+    setOverlayOpacity(index: number, opacity: number): void {
+        this._overlay_layers[index]?.setOpacity(opacity);
+    }
+
+    /**
+     * Map tiles were allowed: attach the main tile layer, create the
+     * minimap's deferred layer if it was withheld, then re-fit.
+     */
+    _onTilesAllowed(): void {
+        this._addTileLayer();
+        this._buildOverlays();
+        if (!this._tile_layer_mini) {
+            this._tile_layer_mini = this._createTileLayer(this.options.map_type);
+        }
+        if (this._mini_map && this._tile_layer_mini) {
+            const overview = this._mini_map.getOverviewMap();
+            if (!overview.getLayers().getLength()) {
+                overview.addLayer(this._tile_layer_mini);
+            }
+        }
+        if (this._markers.length > 0 && this.current_marker < this._markers.length) {
+            const marker = this._markers[this.current_marker];
+            if (marker.data.type === "overview") {
+                this._markerOverview();
+            } else {
+                const latlon = marker.latLon();
+                if (latlon) {
+                    this._fitView(this._map, [[latlon.lon, latlon.lat]], 0);
+                }
+            }
+        }
+    }
+
+    /**
+     * Legacy zoomify image pyramid: the levels (image size per level), the
+     * max zoom and the mercator bounds the image occupies (stretched from
+     * the world's top-left corner, the original renderer's mapping).
+     */
+    _zoomifyPyramid(): {
+        sizes: Array<[number, number]>;
+        maxZoom: number;
+        extent: number[];
+        tileGrid: TileGrid;
+    } | null {
+        const zoomify = this.options.zoomify;
+        if (!zoomify || typeof zoomify !== "object" || !zoomify.path) return null;
+        const width = zoomify.width ?? 600;
+        const height = zoomify.height ?? 600;
+
+        // pyramid levels: halve the image size until ≤ 256
+        const sizes: Array<[number, number]> = [];
+        let w = width;
+        let h = height;
+        while (w > 256 || h > 256) {
+            sizes.push([w, h]);
+            w = Math.floor(w / 2);
+            h = Math.floor(h / 2);
+        }
+        sizes.push([w, h]);
+        sizes.reverse(); // [0] = smallest level
+
+        const maxZoom = sizes.length - 1;
+        const worldPx = 256 * 2 ** maxZoom;
+        const extent = [
+            -20037508.342789244,
+            20037508.342789244 - (height / worldPx) * 40075016.68557849,
+            -20037508.342789244 + (width / worldPx) * 40075016.68557849,
+            20037508.342789244,
+        ];
+        // tile grid over the image's mercator bounds: the tiles keep their
+        // natural size (the legacy renderer clamped edge tiles the same way).
+        // One extra level below zoom 0 lets the overview show the complete
+        // image (the smallest pyramid tile downscaled)
+        const tileGrid = new TileGrid({
+            extent,
+            origin: [extent[0], extent[3]],
+            resolutions: Array.from(
+                { length: maxZoom + 2 },
+                (_, i) => 40075016.68557849 / (256 * 2 ** (i - 1)),
+            ),
+            tileSize: 256,
+        });
+        return { sizes, maxZoom, extent, tileGrid };
+    }
+
+    /**
+     * The zoomify overview state: the best-fit pyramid level for a map
+     * window (the level whose image, times the tolerance, fits the window —
+     * the legacy `_getBestFitZoom`) and the image's mercator center.
+     */
+    _zoomifyOverview(mapSize: [number, number]): { zoom: number; center: number[] } | null {
+        const pyramid = this._zoomifyPyramid();
+        if (!pyramid) return null;
+        const tolerance = (this.options.zoomify as { tolerance?: number })?.tolerance ?? 0.9;
+        let zoom = pyramid.maxZoom;
+        while (zoom > 0) {
+            const size = pyramid.sizes[zoom];
+            if (
+                size[0] * tolerance < (mapSize[0] || 1) &&
+                size[1] * tolerance < (mapSize[1] || 1)
+            ) {
+                break;
+            }
+            zoom--;
+        }
+        const center = [
+            (pyramid.extent[0] + pyramid.extent[2]) / 2,
+            (pyramid.extent[1] + pyramid.extent[3]) / 2,
+        ];
+        return { zoom, center };
+    }
+
+    _createTileLayer(map_type: string): Layer {
+        // issue #473: custom OpenLayers tile layer/source factory first —
+        // the base layer, overlays, minimap and runtime map_type switches
+        // all funnel through here, so one check covers them
+        const factory = this.options.tile_source_factory;
+        if (typeof factory === "function") {
+            const custom = factory(map_type, {
+                options: this.options,
+                createDefault: () => this._createDefaultTileLayer(map_type),
+            });
+            if (custom) {
+                // any ol/layer/Layer passes through as-is — including
+                // subclasses without a getSource (e.g. an Allmaps
+                // WarpedMapLayer), which must not be wrapped; a bare Source is
+                // wrapped in a TileLayer
+                if (
+                    custom instanceof Layer ||
+                    typeof (custom as { getSource?: unknown }).getSource === "function"
+                ) {
+                    return custom as Layer;
+                }
+                return new TileLayer({ source: custom as unknown as XYZ });
+            }
+        }
+        return this._createDefaultTileLayer(map_type);
+    }
+
+    /**
+     * A layer's source, or null when it has none. Custom `Layer` subclasses
+     * passed through `_createTileLayer` (e.g. Allmaps' `WarpedMapLayer`)
+     * deliberately have no `getSource`, so every read goes through here
+     * instead of calling the method directly.
+     */
+    _sourceOf(layer: Layer | null | undefined): Source | null {
+        if (!layer || typeof (layer as { getSource?: unknown }).getSource !== "function") {
+            return null;
+        }
+        return (layer as TileLayer).getSource();
+    }
+
+    /**
+     * Move the map into another element, keeping OpenLayers in step.
+     *
+     * `DomMixed.addTo()` (the original semantics, unchanged: append the map
+     * container, fire `added`) only moves DOM — the `ol/Map` still has the
+     * viewport it measured at construction, so it would keep painting at the
+     * old size. Re-attach the target, which `removeFrom()` detached, and
+     * re-measure. The argument must be the new parent.
+     */
+    addTo(container: HTMLElement): this {
+        super.addTo(container);
+        this._map.setTarget(this._el.map);
+        this._map.updateSize();
+        return this;
+    }
+
+    /**
+     * Move the map out of `container`. Untargets the OpenLayers map so it
+     * does not render into a detached node; a later {@link addTo} re-attaches
+     * it. The argument must be the current parent.
+     */
+    removeFrom(container: HTMLElement): this {
+        super.removeFrom(container);
+        this._map.setTarget(undefined);
+        return this;
+    }
+
+    /**
+     * True when the map is a plain image in an `EPSG:4326` "image space"
+     * rather than a geographic map: a IIIF image presented as a picture of
+     * the world (`map_as_image`), not georeferenced.
+     *
+     * In this mode the view projection is `EPSG:4326` with degrees as
+     * resolution and the view is fitted to the image extent, so
+     * `getCenter()`/`getZoom()` are in degrees/pixels-per-degree — not
+     * mercator metres. Marker locations are pixel offsets into the image,
+     * not lat/lon. Georeferenced IIIF (`map_bbox` with `map_as_image`
+     * omitted) is a normal mercator map; use `isImageSpace()` rather than
+     * testing `map_type` to tell the two apart.
+     */
+    isImageSpace(): boolean {
+        return this.options.map_type === "iiif" && this.options.map_as_image === true;
+    }
+
+    /**
+     * Stop the line animation, drop the minimap control and dispose the
+     * OpenLayers map. Called by `StoryMap.dispose()`; the engine must not be
+     * used afterwards.
+     */
+    dispose(): void {
+        if (this._line_animation !== null) {
+            cancelAnimationFrame(this._line_animation);
+            this._line_animation = null;
+        }
+        // markers own their click listener and an overlay; disposing the
+        // collection releases both
+        for (const marker of this._markers) {
+            marker.dispose?.();
+        }
+        this._markers = [];
+        // detach the viewport first: dispose() alone leaves the canvas in
+        // the caller's DOM
+        this._map.setTarget(undefined);
+        this._map.dispose();
+    }
+
+    /**
+     * Fire `imageready` once `source` is usable (and immediately when it
+     * already is). Image sources — IIIF, zoomify, the deferred tile layer —
+     * attach asynchronously, so this is the only outward signal that the
+     * imagery is really on the map; the `loaded` event can fire before the
+     * source is attached at all.
+     */
+    _fireImageready(source: { getState?(): string }, kind: ImagereadyKind, layer?: Layer): void {
+        // one event per source: the base layer and the minimap can be asked
+        // about the same source, and a host toggling layers should not have
+        // to filter duplicates
+        if (this._imageready_fired.has(source)) return;
+        this._imageready_fired.add(source);
+        const payload = { source, kind, layer: layer ?? null };
+        if (typeof source.getState !== "function" || source.getState() === "ready") {
+            this.fire("imageready", payload);
+            return;
+        }
+        const onChange = () => {
+            if (source.getState?.() === "ready") {
+                (source as { un?: (t: string, f: () => void) => void }).un?.("change", onChange);
+                this.fire("imageready", payload);
+            }
+        };
+        (source as { once?: (t: string, f: () => void) => void }).once?.("change", onChange);
+    }
+
+    /** Computed zooms take precedence over the authored slide zoom. */
+    _markerZoom(index: number): number | undefined {
+        return this._marker_zooms[index] ?? super._markerZoom(index);
+    }
+
+    /**
+     * The TileJSON metadata, but only when it is describing `url`.
+     *
+     * `tilejson` describes the map's tile source, so its `tiles` template is
+     * the one the map_type resolved to. When it names a different template it
+     * is not about this source, and neither the zoom ladder nor the initial
+     * view should be taken from it.
+     */
+    _tilejsonFor(url: string): StorymapTilejson | undefined {
+        const tilejson = this.options.tilejson;
+        if (tilejson === undefined) return undefined;
+        const tiles = Array.isArray(tilejson.tiles) ? tilejson.tiles[0] : tilejson.tiles;
+        return tiles === url ? tilejson : undefined;
+    }
+
+    /**
+     * An XYZ source for a URL template, honouring the TileJSON metadata of the
+     * map's own tile source if it is describing this template (§2.9).
+     *
+     * `minzoom`/`maxzoom` become the tile grid's zoom range, so OpenLayers asks
+     * for levels the service actually has and stops past the ones it does not.
+     * `scheme: "tms"` is the TMS row order, which is the same URL with the tile
+     * row counted from the bottom.
+     */
+    _xyzSource(url: string): XYZ {
+        const tilejson = this._tilejsonFor(url);
+        const options: Record<string, unknown> = {
+            url,
+            attributions: this._sourceAttributions(url),
+            crossOrigin: "anonymous",
+        };
+        if (tilejson !== undefined) {
+            if (tilejson.minzoom !== undefined || tilejson.maxzoom !== undefined) {
+                options.minZoom = tilejson.minzoom ?? 0;
+                options.maxZoom = tilejson.maxzoom ?? MAX_ZOOM;
+            }
+        }
+        const source = new XYZ(options as never);
+        if (tilejson?.scheme === "tms") {
+            // TMS numbers tile rows from the bottom of the pyramid; XYZ counts
+            // them from the top, so the row is flipped against the source's
+            // deepest zoom.
+            //
+            // This is assigned rather than passed as the `tileUrlFunction`
+            // constructor option, which this version of ol/source/XYZ does not
+            // read.
+            const deepest = tilejson.maxzoom ?? MAX_ZOOM;
+            source.tileUrlFunction = (tileCoord: number[] | undefined): string | undefined => {
+                if (tileCoord === undefined) return undefined;
+                // OpenLayers hands over [z, x, y]
+                const [z, x, y] = tileCoord;
+                return url
+                    .replace("{z}", String(z))
+                    .replace("{x}", String(x))
+                    .replace("{y}", String(2 ** deepest - 1 - y))
+                    .replace("{ratio}", "");
+            };
+        }
+        return source;
+    }
+
+    _createDefaultTileLayer(map_type: string): TileLayer {
+        const _map_type_arr = map_type.split(":");
+
+        switch (_map_type_arr[0]) {
+            case "mapbox": {
+                if (_map_type_arr.length > 2) {
+                    // mapbox://styles/<user>/<style> URLs render via the
+                    // Mapbox styles tiles API (requires map_access_token)
+                    const this_mapbox_map = _map_type_arr[2].slice("//styles/".length);
+                    const mapbox_url =
+                        "https://api.mapbox.com/styles/v1/" +
+                        this_mapbox_map +
+                        "/tiles/256/{z}/{x}/{y}@2x?access_token=" +
+                        this.options.map_access_token;
+                    return new TileLayer({
+                        source: new XYZ({
+                            url: mapbox_url,
+                            attributions: this._sourceAttributions(map_type),
+                            crossOrigin: "anonymous",
+                        }),
+                    });
+                }
+                console.error(
+                    "StoryMapJS: legacy 'mapbox:<style>' map types are no longer supported (the Mapbox v4 tile API was retired); use 'mapbox://styles/<user>/<style>' with map_access_token instead.",
+                );
+                return new TileLayer({
+                    source: new OSM({ attributions: this._sourceAttributions(map_type) }),
+                });
+            }
+
+            case "stadia": {
+                // Stadia hosts a style *set*, not a single style. A bare
+                // `map_type: "stadia"` used to fall back to the literal
+                // "osm:standard", which is not one of them — every tile 404'd.
+                // `alidade_smooth` is the correct default here (matches the
+                // remapped `stamen` case below).
+                let style_url = "alidade_smooth";
+                if (_map_type_arr.length > 1) {
+                    style_url = _map_type_arr.slice(1).join(":");
+                    if (this.options.map_access_token) {
+                        style_url = `${style_url}?api_key=${this.options.map_access_token}`;
+                    }
+                }
+                return new TileLayer({
+                    source: new XYZ({
+                        url: `https://tiles.stadiamaps.com/tiles/${style_url}/{z}/{x}/{y}{r}.png`,
+                        attributions: this._sourceAttributions(map_type),
+                    }),
+                });
+            }
+
+            case "stamen":
+                this._map.getViewport().style.backgroundColor = "#FFFFFF";
+                return new TileLayer({
+                    source: new XYZ({
+                        url: "https://tiles.stadiamaps.com/tiles/stamen_toner_lite/{z}/{x}/{y}.png",
+                        attributions: this._sourceAttributions(map_type),
+                    }),
+                });
+
+            case "iiif": {
+                const iiif_layer: TileLayer = new TileLayer();
+                fetch(this.options.iiif.url)
+                    .then((r) => r.json())
+                    .then((info: unknown) => {
+                        // parse the service description into proper tile
+                        // source options (base URL, version, tiling) so tile
+                        // URLs are valid and the grid matches the service
+                        const parsed = new IIIFInfo(
+                            info as ImageInformationResponse,
+                        ).getTileSourceOptions();
+                        const fallback = info as { width?: number; height?: number };
+                        if (
+                            typeof fallback.width !== "number" ||
+                            typeof fallback.height !== "number"
+                        ) {
+                            console.error(
+                                "IIIF info.json is missing width/height:",
+                                this.options.iiif.url,
+                            );
+                            return;
+                        }
+                        const source = new IIIF({
+                            ...(parsed ?? {}),
+                            projection: "EPSG:4326",
+                            size: [fallback.width, fallback.height],
+                            crossOrigin: "anonymous",
+                            attributions: this.options.iiif.attribution || [],
+                        });
+                        iiif_layer.setSource(source);
+                        this._fireImageready(source, "iiif", iiif_layer);
+                        if (source.getState() === "ready") {
+                            this._markerOverview();
+                        } else {
+                            source.once("change", () => {
+                                if (source.getState() === "ready") {
+                                    this._markerOverview();
+                                }
+                            });
+                        }
+                    })
+                    .catch((err) =>
+                        console.error(
+                            "IIIF info.json could not be loaded:",
+                            this.options.iiif.url,
+                            err?.stack || err,
+                        ),
+                    );
+                return iiif_layer;
+            }
+
+            case "http":
+            case "https":
+                // style JSON URLs (e.g. https://tiles.openfreemap.org/styles/bright)
+                // render a vector style, tile template URLs stay raster
+                if (!map_type.includes("{z}")) {
+                    return this._createVectorStyleLayer(map_type);
+                }
+                return new TileLayer({ source: this._xyzSource(map_type) });
+
+            case "ch-watercolor":
+                return new TileLayer({
+                    source: new XYZ({
+                        url: "https://watercolormaps.collection.cooperhewitt.org/tile/watercolor/{z}/{x}/{y}.jpg",
+                        attributions: this._sourceAttributions(map_type),
+                        maxZoom: 16,
+                    }),
+                });
+
+            case "zoomify": {
+                // Legacy zoomify support: the image pyramid tiles are placed
+                // over the image's mercator bounds (the original renderer's
+                // mapping). Locations use native lat/lon. The tile grid's
+                // ladder is shifted one level down so the overview can show
+                // the complete image.
+                const pyramid = this._zoomifyPyramid();
+                if (!pyramid) {
+                    console.error(
+                        "StoryMapJS: map_type 'zoomify' needs a zoomify image pyramid (path, width, height) in the storymap data.",
+                    );
+                    return new TileLayer({
+                        source: new OSM({ attributions: this._sourceAttributions(map_type) }),
+                    });
+                }
+                const path = (this.options.zoomify as { path?: string }).path ?? "";
+                const { sizes, maxZoom: pyramidMaxZoom } = pyramid;
+                const gridX = (z: number) => Math.ceil(sizes[z][0] / 256);
+                const gridY = (z: number) => Math.ceil(sizes[z][1] / 256);
+
+                const zoomify_source = new XYZ({
+                    tileGrid: pyramid.tileGrid,
+                    crossOrigin: "anonymous",
+                    attributions: this._sourceAttributions(map_type),
+                    tileUrlFunction: (tile: number[]) => {
+                        const [tileZ, x, y] = tile;
+                        // the ladder is shifted one level down: mercator
+                        // zoom z serves the pyramid level max(0, z - 1)
+                        const z = Math.max(0, tileZ - 1);
+                        if (z > pyramidMaxZoom) return undefined;
+                        if (x < 0 || x >= gridX(z) || y < 0 || y >= gridY(z)) {
+                            return undefined;
+                        }
+                        // TileGroup index: the running tile number ÷ 256
+                        let num = 0;
+                        for (let zz = 0; zz < z; zz++) {
+                            num += gridX(zz) * gridY(zz);
+                        }
+                        num += y * gridX(z) + x;
+                        return `${path}TileGroup${Math.floor(num / 256)}/${z}-${x}-${y}.jpg`;
+                    },
+                    // Zoomify edge tiles are cropped to the image bounds
+                    // (e.g. a 256x19 bottom strip); OpenLayers draws the
+                    // loaded image over the whole 256x256 tile box, which
+                    // stretched those strips across the cell (the smeared
+                    // bottom in the Bosch overview, stretched right/bottom
+                    // edges in the Literary Trail). Pad them onto a full
+                    // tile canvas instead.
+                    tileLoadFunction: (tile, src) => {
+                        const imageTile = tile as ImageTile;
+                        const image = imageTile.getImage() as HTMLImageElement;
+                        image.onload = () => padCroppedZoomifyTile(imageTile, image);
+                        image.src = src;
+                    },
+                });
+                const zoomify_layer = new TileLayer({ source: zoomify_source });
+                // the zoomify base never announced itself, so a host waiting
+                // on imageready hung on exactly the legacy stories that need
+                // it most; the per-source dedup keeps this to one event
+                this._fireImageready(zoomify_source, "zoomify", zoomify_layer);
+                return zoomify_layer;
+            }
+
+            case "osm": {
+                // "osm:<style>" uses an OpenFreeMap vector style (osm:bright ->
+                // https://tiles.openfreemap.org/styles/bright), plain "osm" stays
+                // the classic raster tiles
+                const style_name = _map_type_arr.length > 1 ? _map_type_arr[1] : "";
+                if (style_name) {
+                    return this._createVectorStyleLayer(
+                        `https://tiles.openfreemap.org/styles/${style_name}`,
+                    );
+                }
+                return new TileLayer({
+                    source: new OSM({ attributions: this._sourceAttributions(map_type) }),
+                });
+            }
+            default: {
+                // Relative/custom templates (./tiles/{z}/{x}/{y}.png,
+                // /tiles/{z}/..., tiles/{z}/...): render as raster XYZ so
+                // consumers on subpaths (GitLab Pages), bundlers (Vite) and
+                // the Electron kiosk server don't have to expand to an
+                // absolute http(s):// URL first. Style JSON paths without
+                // {z} render as vector styles, anything else falls back to
+                // OSM.
+                if (map_type.includes("{z}")) {
+                    return new TileLayer({ source: this._xyzSource(map_type) });
+                }
+                if (map_type.includes("/") || map_type.endsWith(".json")) {
+                    return this._createVectorStyleLayer(map_type);
+                }
+                return new TileLayer({
+                    source: new OSM({ attributions: this._sourceAttributions(map_type) }),
+                });
+            }
+        }
+    }
+
+    _createVectorStyleLayer(style_url: string): TileLayer {
+        // Mapbox style JSONs (OpenFreeMap, Mapbox) are applied onto a single
+        // vector tile layer, including its background and label decluttering
+        const layer = new VectorTileLayer({ declutter: true, updateWhileAnimating: true });
+        applyStyle(layer, style_url).catch((err: unknown) =>
+            console.error("Vector map style could not be loaded:", style_url, err),
+        );
+        return layer as unknown as TileLayer;
+    }
+
+    /*	Create Mini Map
+	================================================== */
+    _createMiniMap(): void {
+        if (this.options.map_as_image) {
+            this.zoom_min_max.min = 0;
+        }
+
+        if (!this.bounds_array) {
+            this.bounds_array = this._getAllMarkersBounds(this._markers);
+        }
+
+        // consent mode: the minimap layer is only created once map tiles are
+        // allowed — creating an IIIF/vector layer object fetches info.json or
+        // the style JSON immediately, which must not happen while denied
+        this._tile_layer_mini = this._tilesAllowed()
+            ? this._createTileLayer(this.options.map_type)
+            : null;
+        const is_image_map = this.isImageSpace();
+        // Legacy zoomify maps are mercator-based: the minimap fits the image's
+        // mercator bounds with a free zoom so the whole image stays visible
+        // at a downscaled (sharp) pyramid level
+        const is_zoomify = this.options.map_type === "zoomify";
+        const zoomify_pyramid = is_zoomify ? this._zoomifyPyramid() : null;
+        // the overview needs the pyramid's full ladder (including the R0
+        // floor below default zoom 0): fit() settles on a fractional zoom
+        // containing the whole image, which minZoom: 0 on the default ladder
+        // would clip back to a cropped upscale
+        const zoomify_resolutions = zoomify_pyramid
+            ? zoomify_pyramid.tileGrid.getResolutions()
+            : null;
+        // Constrain a standard mercator overview to an explicit lon/lat box
+        // (overview_extent); image maps keep their own views below. Without
+        // a constraint the default overview view roams the whole world.
+        const overview_extent =
+            !is_image_map && !zoomify_pyramid && this.options.overview_extent
+                ? this._lonLatBboxToExtent(this.options.overview_extent)
+                : null;
+        this._mini_map = new OverviewMap({
+            ...(is_image_map || zoomify_pyramid
+                ? {
+                      view: (() => {
+                          const view = new View({
+                              projection: this._map.getView().getProjection(),
+                              center: this._map.getView().getCenter(),
+                              zoom: this.zoom_min_max.min || 0,
+                              // same reasoning as the main image view: no world
+                              // constraints
+                              ...(is_image_map
+                                  ? {
+                                        multiWorld: true,
+                                        resolutions: IMAGE_RESOLUTIONS,
+                                        minZoom: 0,
+                                        maxZoom: IMAGE_RESOLUTIONS.length - 1,
+                                    }
+                                  : {}),
+                              ...(zoomify_pyramid && zoomify_resolutions
+                                  ? {
+                                        // show the whole image: the zoom stays
+                                        // free on the pyramid ladder so fit()
+                                        // settles on the fractional resolution
+                                        // containing the image bounds (a pinned
+                                        // zoom stuck the smallest, blurry
+                                        // pyramid level on screen, cropped);
+                                        // the center stays within the image
+                                        // bounds
+                                        constrainOnlyCenter: true,
+                                        extent: zoomify_pyramid.extent,
+                                        resolutions: zoomify_resolutions,
+                                        minZoom: 0,
+                                        maxZoom: zoomify_resolutions.length - 1,
+                                        center: [
+                                            (zoomify_pyramid.extent[0] +
+                                                zoomify_pyramid.extent[2]) /
+                                                2,
+                                            (zoomify_pyramid.extent[1] +
+                                                zoomify_pyramid.extent[3]) /
+                                                2,
+                                        ],
+                                    }
+                                  : {}),
+                          });
+                          return view;
+                      })(),
+                  }
+                : {}),
+            ...(overview_extent
+                ? {
+                      view: new View({
+                          projection: this._map.getView().getProjection(),
+                          center: [
+                              (overview_extent[0] + overview_extent[2]) / 2,
+                              (overview_extent[1] + overview_extent[3]) / 2,
+                          ],
+                          extent: overview_extent,
+                          constrainOnlyCenter: false,
+                      }),
+                  }
+                : {}),
+            layers: this._tile_layer_mini ? [this._tile_layer_mini] : [],
+            // NB: label = the button shown when COLLAPSED (expands the
+            // minimap), collapseLabel = shown when EXPANDED (collapses it) —
+            // the chevrons point outward when collapsed and inward when open
+            collapseLabel: "\u00ab",
+            label: "\u00bb",
+            collapsed: true,
+        });
+        this._map.addControl(this._mini_map);
+
+        if (zoomify_pyramid) {
+            // show the image pyramid's extent in the minimap: with the zoom
+            // free, fit() picks the fractional resolution containing the
+            // whole image, so the overview serves the smallest pyramid level
+            // downscaled (sharp) instead of a cropped upscale
+            const overview_map = this._mini_map.getOverviewMap();
+            const fitZoomifyMini = () => {
+                const raw_size = overview_map.getSize();
+                // the minimap starts collapsed (no layout size yet) in its
+                // 150x100 box — fall back to that until it expands
+                const size =
+                    raw_size && raw_size[0] >= 50 && raw_size[1] >= 50 ? raw_size : [150, 100];
+                overview_map.getView().fit(zoomify_pyramid.extent, {
+                    size: size,
+                });
+            };
+            fitZoomifyMini();
+            // re-fit once the minimap expands: the collapsed size is unknown
+            // at creation time
+            overview_map.on("change:size", fitZoomifyMini);
+        } else if (!is_zoomify && this.bounds_array && this.bounds_array.length) {
+            // the minimap shows the story's world: with a bbox set, markers
+            // outside of the box are unreachable and must not skew the fit
+            this._fitView(
+                this._mini_map.getOverviewMap(),
+                this.bounds_array,
+                0,
+                this._bboxExtent() !== null,
+            );
+        }
+
+        if (this.isImageSpace()) {
+            // in image mode there are no geo markers to fit, so show the
+            // whole image instead (issues #465, #355)
+            this._fitMiniMapToImage();
+        }
+    }
+
+    _fitMiniMapToImage(): void {
+        if (!this._tile_layer_mini) return;
+        const fit_mini_image = () => {
+            try {
+                const mini_source = this._sourceOf(this._tile_layer_mini) as {
+                    getTileGrid?: () => { getExtent(): number[] };
+                } | null;
+                const grid = mini_source?.getTileGrid?.();
+                if (grid) {
+                    const overview_map = this._mini_map.getOverviewMap();
+                    const raw_size = overview_map.getSize();
+                    // the minimap may still be collapsed (no layout size yet)
+                    const size =
+                        raw_size && raw_size[0] >= 50 && raw_size[1] >= 50 ? raw_size : [150, 150];
+                    overview_map.getView().fit(grid.getExtent(), {
+                        size: size,
+                    });
+                }
+            } catch (e) {
+                console.warn("IIIF minimap fit failed:", e);
+            }
+        };
+        const mini_source = this._sourceOf(this._tile_layer_mini);
+        if (mini_source) {
+            this._fireImageready(
+                mini_source,
+                this.options.map_type === "zoomify"
+                    ? "zoomify"
+                    : this.options.map_type === "iiif"
+                      ? "iiif"
+                      : "tiles",
+                this._tile_layer_mini,
+            );
+            if (mini_source.getState() === "ready") {
+                fit_mini_image();
+            } else {
+                mini_source.once("change", () => {
+                    if (mini_source.getState() === "ready") fit_mini_image();
+                });
+            }
+        } else {
+            // the mini layer sets its source asynchronously
+            this._tile_layer_mini.once("change:source", () => {
+                const src = this._sourceOf(this._tile_layer_mini);
+                if (!src) return;
+                if (src.getState() === "ready") {
+                    fit_mini_image();
+                } else {
+                    src.once("change", () => {
+                        if (src.getState() === "ready") fit_mini_image();
+                    });
+                }
+            });
+        }
+    }
+
+    /*	Create Markers
+	================================================== */
+    _createMarker(d: StorymapSlide): void {
+        const marker = new OpenLayersMapMarker(d, this.options);
+        marker.on("markerclick", this._onMarkerClick, this);
+        this._addMarker(marker);
+        this._markers.push(marker);
+        marker.marker_number = this._markers.length - 1;
+        this.fire("markerAdded", marker);
+    }
+
+    _addMarker(marker: OpenLayersMapMarker): void {
+        marker.addTo(this._map);
+    }
+
+    /**
+     * Position marker overlays on the unwrapped longitude path so they sit on
+     * the same world copy as the fitted view and the line (issue #381).
+     * Image-space coordinates are not degrees and stay untouched.
+     */
+    _afterCreateMarkers(): void {
+        if (this._map.getView().getProjection().getCode() === "EPSG:4326") {
+            return;
+        }
+        const real: { marker: OpenLayersMapMarker; latlon: LatLngLiteral }[] = [];
+        for (const marker of this._markers) {
+            const latlon = marker.latLon();
+            if (latlon) {
+                real.push({ marker: marker, latlon: latlon });
+            }
+        }
+        const unwrapped = this._unwrapLongitudes(real.map((entry) => entry.latlon.lon));
+        real.forEach((entry, i) => {
+            entry.marker._overlay?.setPosition(fromLonLat([unwrapped[i], entry.latlon.lat]));
+        });
+    }
+
+    _removeMarker(marker: OpenLayersMapMarker): void {
+        if (marker && marker.data.real_marker) {
+            marker._removeFrom(this._map);
+        }
+    }
+
+    /*	Marker helpers
+	================================================== */
+    _getAllMarkersBounds(markers_array: OpenLayersMapMarker[]): number[][] {
+        const coords: number[][] = [];
+        for (const marker of markers_array) {
+            const latlon = marker.latLon();
+            if (latlon) {
+                coords.push([latlon.lon, latlon.lat]);
+            }
+        }
+        // unwrap dateline crossings so fits don't span the whole globe
+        // (issue #381)
+        const lons = this._unwrapLongitudes(coords.map((c) => c[0]));
+        return coords.map((c, i) => [lons[i], c[1]]);
+    }
+
+    /**
+     * Normalize a longitude sequence so consecutive values differ by at most
+     * 180 degrees: markers keep their raw coordinates (OpenLayers wraps the
+     * display), but fits and lines use the unwrapped path (issue #381).
+     */
+    _unwrapLongitudes(lons: number[]): number[] {
+        if (lons.length === 0) return [];
+        const out = [lons[0]];
+        for (let i = 1; i < lons.length; i++) {
+            let lon = lons[i];
+            while (lon - out[i - 1] > 180) lon -= 360;
+            while (lon - out[i - 1] < -180) lon += 360;
+            out.push(lon);
+        }
+        return out;
+    }
+
+    _markerCoordsToViewCoords(coords: number[][]): number[][] {
+        const is_image_space = this._map.getView().getProjection().getCode() === "EPSG:4326";
+        if (is_image_space) return coords.map((c) => [c[0], c[1]]);
+        return coords.map((c) => fromLonLat(c));
+    }
+
+    /**
+     * The View extent for the `map_bbox` option, or `null` when unset. The
+     * view uses it with `constrainOnlyCenter` (see _createMap).
+     */
+    _bboxExtent(): number[] | null {
+        const bbox = this.options.map_bbox as number[] | null | undefined;
+        if (!bbox || bbox.length !== 4) return null;
+        if (this.isImageSpace()) return bbox;
+        // NB: fromLonLat transforms a single [lon, lat] pair — transform the
+        // two corners separately
+        const min = fromLonLat([bbox[0], bbox[1]]);
+        const max = fromLonLat([bbox[2], bbox[3]]);
+        return [min[0], min[1], max[0], max[1]];
+    }
+    /**
+     * The slide content panel can be opaque — it then covers part of the map
+     * and the effective visible area shrinks. Returns the pixel padding for
+     * the covered side (right in landscape, bottom in portrait) so fits keep
+     * the story inside the visible region; transparent panels and panels
+     * that do not overlap the map (map_area "left") add nothing.
+     */
+    _opaquePanelPadding(): [number, number, number, number] {
+        const padding: [number, number, number, number] = [15, 15, 15, 15];
+        if (typeof document === "undefined") return padding;
+        // Scope the search to THIS viewer's root. The slide panel is a sibling
+        // of the map, not a descendant, so it is not reachable from
+        // this._el.container (the .vco-map div); a document-wide query would
+        // find whichever panel comes first on the page, and then measure this
+        // map against another viewer's rectangle — the overlap test below then
+        // decides padding for a panel that may not overlap this map at all.
+        const root = this._el.container.closest?.(".vco-storymap");
+        // no viewer root means the map is standalone, so there is no slide
+        // panel to make room for
+        if (!root) return padding;
+        const panel = root.querySelector(".vco-storyslider .vco-slide.vco-active .vco-text");
+        if (!panel) return padding;
+        const bg = getComputedStyle(panel).backgroundColor;
+        const match = /rgba?\(([^)]+)\)/.exec(bg);
+        if (!match) return padding;
+        const parts = match[1]
+            .split(/[,\s/]+/)
+            .filter((v) => v !== "")
+            .map(Number);
+        const alpha = parts.length >= 4 ? parts[3] : 1;
+        if (alpha < 0.9) return padding;
+        const map_rect = this._el.map.getBoundingClientRect();
+        const panel_rect = panel.getBoundingClientRect();
+        if (!map_rect.width || !panel_rect.width) return padding;
+        // the panel must actually overlap the map (it does not in the
+        // map_area "left" layout, where map and panel sit side by side)
+        const overlaps =
+            panel_rect.left < map_rect.right &&
+            panel_rect.right > map_rect.left &&
+            panel_rect.top < map_rect.bottom &&
+            panel_rect.bottom > map_rect.top;
+        if (!overlaps) return padding;
+        const layout = this.options.layout;
+        if (layout === "portrait") {
+            padding[2] += Math.max(0, map_rect.bottom - panel_rect.top);
+        } else {
+            padding[1] += Math.max(0, panel_rect.right - map_rect.left);
+        }
+        return padding;
+    }
+
+    /**
+     * Fit the given coordinates. With `clamp_to_bbox` (the strict bbox
+     * layout, map_area "left"), markers outside of the box are unreachable
+     * by design — they must not skew the fit target, so the extent is
+     * intersected with the box and the in-box markers compose the view.
+     */
+    _fitView(ol_map: OlMap, coords: number[][], duration = 0, clamp_to_bbox = false): void {
+        if (!coords || !coords.length) return;
+        const view_coords = this._markerCoordsToViewCoords(coords);
+        let extent = boundingExtent(view_coords);
+        if (clamp_to_bbox) {
+            const bbox = this._bboxExtent();
+            if (bbox) {
+                const clamped = getIntersection(extent, bbox as Extent);
+                // getIntersection returns an inverted (empty) extent when the
+                // boxes are disjoint — fit the box itself in that case
+                extent =
+                    clamped[0] <= clamped[2] && clamped[1] <= clamped[3]
+                        ? clamped
+                        : (bbox as Extent);
+            }
+        }
+        ol_map.getView().fit(extent, {
+            size: ol_map.getSize(),
+            padding: this._opaquePanelPadding(),
+            maxZoom: 12,
+            duration: duration,
+            easing: this._easing,
+        });
+    }
+
+    _calculateMarkerZooms(): void {
+        const center = this._getMapCenter();
+        for (const [i, marker] of this._markers.entries()) {
+            // a marker with no location object at all is not navigable
+            if (!marker.data.location) {
+                continue;
+            }
+            let calculated_zoom: number | undefined;
+
+            // MARKER LOCATION — the overview fits around the current view
+            // rather than a point on the map
+            const marker_location =
+                marker.data.type && marker.data.type === "overview" ? center : marker.location();
+            if (!marker_location) {
+                continue;
+            }
+
+            // Fit-based zoom: zoom the view to this marker and neighbors
+            const prev_marker = i > 0 ? this._markers[i - 1].location() : center;
+            const next_marker =
+                i < this._markers.length - 1 ? this._markers[i + 1].location() : center;
+
+            const prev_marker_zoom = prev_marker
+                ? this._calculateZoomChange(prev_marker, marker_location)
+                : undefined;
+            const next_marker_zoom = next_marker
+                ? this._calculateZoomChange(next_marker, marker_location)
+                : undefined;
+
+            if (prev_marker_zoom && prev_marker_zoom < (next_marker_zoom ?? Infinity)) {
+                calculated_zoom = prev_marker_zoom;
+            } else if (next_marker_zoom) {
+                calculated_zoom = next_marker_zoom;
+            } else {
+                calculated_zoom = prev_marker_zoom;
+            }
+
+            if (calculated_zoom === undefined) {
+                continue;
+            }
+
+            if (
+                this.options.map_center_offset &&
+                (this.options.map_center_offset.left !== 0 ||
+                    this.options.map_center_offset.top !== 0)
+            ) {
+                calculated_zoom = calculated_zoom - 1;
+            }
+
+            this._marker_zooms[i] = calculated_zoom;
+        }
+    }
+
+    /*	Line
+	================================================== */
+
+    /**
+     * Stroke style for the route lines: the dash pattern and line join are
+     * applied at init too, matching the original rendering (the lines are
+     * dashed "5,5" by default, not solid).
+     */
+    _lineStyle(color: string): Style {
+        return new Style({
+            stroke: new Stroke({
+                color: color,
+                width: this.options.line_weight,
+                lineDash: String(this.options.line_dash)
+                    .split(",")
+                    .map((v) => Number(v)),
+                lineJoin: this.options.line_join as CanvasLineJoin,
+            }),
+        });
+    }
+
+    _createLine(d?: StorymapSlide): VectorLayer {
+        return new VectorLayer({
+            source: new VectorSource({ features: [] }),
+            // re-render vector geometry during view animations: without it
+            // the animated line drawing is only painted after the
+            // transition finishes
+            updateWhileAnimating: true,
+            style: this._lineStyle(this.options.line_color),
+        });
+    }
+
+    _addLineToMap(line: VectorLayer): void {
+        // honor the show_lines option
+        line.setVisible(this.options.show_lines);
+        this._map.addLayer(line);
+    }
+
+    _addToLine(line: VectorLayer, d: StorymapSlide): void {
+        // Append a point to the line's geometry
+        const source = line.getSource();
+        if (!source) {
+            return;
+        }
+        let feature = source.getFeatures()[0];
+        if (!feature) {
+            feature = new Feature({ geometry: new LineString([]) });
+            source.addFeature(feature);
+        }
+        const coords = feature.getGeometry().getCoordinates();
+        let lon = d.location?.lon;
+        const lat = d.location?.lat;
+        if (lat === undefined || lon === undefined) {
+            return;
+        }
+        // unwrap dateline crossings against the previous point (issue #381).
+        // NB: read the previous longitude straight from meters — toLonLat()
+        // wraps into [-180, 180] and would collapse already-unwrapped values.
+        if (coords.length > 0) {
+            const last_lon = coords[coords.length - 1][0] / 111319.49079327358;
+            while (lon - last_lon > 180) lon -= 360;
+            while (lon - last_lon < -180) lon += 360;
+        }
+        coords.push(this._toViewCoords({ lat, lon }));
+        feature.getGeometry().setCoordinates(coords);
+    }
+
+    /**
+     * Replace a line's geometry. With `animate.duration > 0` only the latest
+     * hop animates, in sync with the view animation: the already-traveled
+     * prefix stays drawn while the new segment traces progressively, so half
+     * way through the pan the old connections are fully red and only half
+     * the new hop is. Backward navigation mirrors this: the traveled prefix
+     * stays drawn while the far end pulls back along the abandoned hop.
+     */
+    _replaceLines(
+        line: VectorLayer,
+        array: LinePoint[],
+        animate?: {
+            duration: number;
+            retractFrom?: LinePoint[] | null;
+            growFrom?: LinePoint[] | null;
+        },
+    ): void {
+        const toLonLat = (d: LinePoint): number[] => {
+            const lat = d.location ? d.location.lat : d.lat;
+            const lon = d.location ? d.location.lon : d.lon;
+            return [lon as number, lat as number];
+        };
+        const pts = array.map(toLonLat);
+        const lons = this._unwrapLongitudes(pts.map((p) => p[0] as number));
+        const unwrapped = pts.map((p, i) => [lons[i], p[1]]);
+        const view_coords = this._markerCoordsToViewCoords(unwrapped);
+        const source = line.getSource();
+        if (!source) {
+            return;
+        }
+
+        const setGeometry = (coords: number[][]) => {
+            source.clear();
+            source.addFeature(new Feature({ geometry: new LineString(coords) }));
+        };
+
+        this._cancelLineAnimation();
+
+        const duration = animate?.duration ?? 0;
+        if (duration <= 0 || view_coords.length < 2) {
+            setGeometry(view_coords);
+            return;
+        }
+
+        // The already-traveled prefix, as a leading subsequence of the
+        // target path: verified point-by-point so the shared joint cannot
+        // drift (both go through the same unwrap + view projection).
+        // Falls back to 0 (whole-path animation) on any mismatch.
+        const leadingLength = (candidate: LinePoint[]): number => {
+            const raw = candidate.map(toLonLat);
+            if (raw.length < 1 || raw.length >= unwrapped.length) {
+                return 0;
+            }
+            const cl = this._unwrapLongitudes(raw.map((p) => p[0] as number));
+            for (let i = 0; i < raw.length; i++) {
+                if (cl[i] !== unwrapped[i][0] || raw[i][1] !== unwrapped[i][1]) {
+                    return 0;
+                }
+            }
+            return raw.length;
+        };
+
+        // Retraction (backward navigation): the animation path is the route
+        // up to the previous marker (retractFrom); the traveled prefix
+        // [0..current] stays drawn while the abandoned tail shrinks back to
+        // the joint — the far end pulls back from the old marker to the new
+        // one.
+        const retract_raw = (animate?.retractFrom ?? []).map(toLonLat);
+        let tail: number[][] | null = null;
+        if (retract_raw.length > 0) {
+            const rl = this._unwrapLongitudes(retract_raw.map((p) => p[0] as number));
+            const retract_unwrapped = retract_raw.map((p, i) => [rl[i], p[1]]);
+            // The target must be the leading subsequence of the retraction
+            // path; otherwise fall back to whole-path truncation below.
+            let match = unwrapped.length >= 2 && unwrapped.length < retract_unwrapped.length;
+            for (let i = 0; match && i < unwrapped.length; i++) {
+                if (
+                    retract_unwrapped[i][0] !== unwrapped[i][0] ||
+                    retract_unwrapped[i][1] !== unwrapped[i][1]
+                ) {
+                    match = false;
+                }
+            }
+            if (match) {
+                tail = this._markerCoordsToViewCoords(retract_unwrapped).slice(
+                    unwrapped.length - 1,
+                );
+            }
+        }
+        const tail_total = tail ? this._pathLength(tail) : 0;
+
+        // Growth (forward navigation): the already-traveled prefix
+        // [0..previous] (growFrom) stays drawn while only the new hop
+        // [prev..current] traces progressively.
+        const grow_len = leadingLength(animate?.growFrom ?? []);
+        const prefix = grow_len >= 1 ? view_coords.slice(0, grow_len) : null;
+        const suffix = grow_len >= 1 ? view_coords.slice(grow_len - 1) : null;
+        const suffix_total = suffix ? this._pathLength(suffix) : 0;
+
+        const easing = this._easing;
+        const start_time = performance.now();
+        if (prefix) {
+            // Seed the already-traveled prefix so it stays red from frame 0
+            // (also heals a partially-drawn line when a running animation
+            // is cancelled by rapid stepping).
+            setGeometry(prefix);
+        }
+        const step = (now: number) => {
+            const t = Math.min(1, Math.max(0, (now - start_time) / duration));
+            const eased = easing ? easing(t) : t;
+            if (tail && tail_total > 0) {
+                // pull the far end back along the abandoned hop
+                const drawn = tail_total - eased * tail_total;
+                const drawn_tail = this._truncatePath(tail, drawn);
+                setGeometry([...view_coords, ...drawn_tail.slice(1)]);
+                if (t >= 1) {
+                    setGeometry(view_coords);
+                }
+            } else if (prefix && suffix && suffix_total > 0) {
+                const drawn_suffix = this._truncatePath(suffix, eased * suffix_total);
+                setGeometry([...prefix, ...drawn_suffix.slice(1)]);
+                if (t >= 1) {
+                    setGeometry(view_coords);
+                }
+            } else {
+                const total_length = this._pathLength(view_coords);
+                setGeometry(this._truncatePath(view_coords, eased * total_length));
+            }
+            this._line_animation = t < 1 ? requestAnimationFrame(step) : null;
+        };
+        this._line_animation = requestAnimationFrame(step);
+    }
+
+    /** Cancel a running active-line draw animation. */
+    _cancelLineAnimation(): void {
+        if (this._line_animation !== null) {
+            cancelAnimationFrame(this._line_animation);
+            this._line_animation = null;
+        }
+    }
+
+    /** Total euclidean length of a path in view coordinates. */
+    _pathLength(coords: number[][]): number {
+        let total = 0;
+        for (let i = 1; i < coords.length; i++) {
+            total += Math.hypot(coords[i][0] - coords[i - 1][0], coords[i][1] - coords[i - 1][1]);
+        }
+        return total;
+    }
+
+    /**
+     * The prefix of the path up to `length` (in view units), with the cut
+     * point interpolated inside its segment.
+     */
+    _truncatePath(coords: number[][], length: number): number[][] {
+        if (length <= 0 || coords.length < 2) {
+            return [];
+        }
+        const out = [coords[0]];
+        let acc = 0;
+        for (let i = 1; i < coords.length; i++) {
+            const seg = Math.hypot(
+                coords[i][0] - coords[i - 1][0],
+                coords[i][1] - coords[i - 1][1],
+            );
+            if (acc + seg >= length) {
+                const f = (length - acc) / seg;
+                out.push([
+                    coords[i - 1][0] + f * (coords[i][0] - coords[i - 1][0]),
+                    coords[i - 1][1] + f * (coords[i][1] - coords[i - 1][1]),
+                ]);
+                return out;
+            }
+            acc += seg;
+            out.push(coords[i]);
+        }
+        return out;
+    }
+
+    /*	Map
+	================================================== */
+    _panTo(loc: LatLngLiteral, animate?: boolean): void {
+        this._map.getView().animate({
+            center: this._toViewCoords(loc),
+            duration: this.options.duration,
+            easing: this._easing,
+        });
+    }
+
+    _zoomTo(z: number, animate?: boolean): void {
+        this._map.getView().animate({
+            zoom: z,
+            duration: this.options.duration,
+            easing: this._easing,
+        });
+    }
+
+    _viewTo(loc: StorymapSlideLocation, opts?: ViewToOptions): void {
+        // Image region stops (StrollView-style): in image mode the view is
+        // EPSG:4326 where coordinates are raw image pixels — fit the xywh
+        // region instead of flying to a point. Everything else (geo maps,
+        // absent/invalid regions) keeps the point behavior unchanged.
+        const is_image_space = this._map.getView().getProjection().getCode() === "EPSG:4326";
+        const region =
+            is_image_space && Array.isArray(loc.region) && loc.region.length === 4
+                ? loc.region
+                : null;
+        if (region) {
+            this._fitRegion(region, opts);
+            return;
+        }
+
+        const start = this._latLngOf(loc);
+        if (!start) {
+            return;
+        }
+        let _animate = true,
+            _duration = this.options.duration,
+            _zoom = this._getMapZoom(),
+            _location: LatLngLiteral = start;
+
+        // Show Active Line
+        if (!this.options.map_as_image) {
+            this._line_active.setVisible(true);
+        }
+
+        if (loc.zoom !== undefined && loc.zoom !== null) {
+            _zoom = loc.zoom;
+        }
+
+        // Options
+        if (opts) {
+            if (opts.duration !== undefined) {
+                if (opts.duration === 0) {
+                    _animate = false;
+                } else {
+                    _duration = opts.duration;
+                }
+            }
+
+            if (opts.zoom && this.options.calculate_zoom) {
+                _zoom = opts.zoom;
+            }
+        }
+
+        // OFFSET
+        if (this.options.map_center_offset) {
+            _location = this._getMapCenterOffset(_location, _zoom);
+        }
+
+        this._map.getView().animate({
+            center: this._toViewCoords(_location),
+            zoom: _zoom,
+            duration: _animate ? _duration : 0,
+            easing: this._easing,
+        });
+
+        if (this._mini_map && this.options.width > this.options.skinny_size) {
+            // zoom_min_max stays null until the markers are measured (first
+            // loadend), and `_zoom - 1 <= null` coerces to `<= 0` — the
+            // minimap state was decided by an accidental coercion. Treat an
+            // unmeasured range as "not zoomed out", i.e. keep it expanded.
+            if (this.zoom_min_max.min !== null && _zoom - 1 <= this.zoom_min_max.min) {
+                this._mini_map.setCollapsed(true);
+            } else {
+                this._mini_map.setCollapsed(false);
+            }
+        }
+    }
+
+    /**
+     * Image region stop: fit the xywh bbox ([x, y, w, h] image pixels —
+     * the EPSG:4326 image space) with the shared animation options, then
+     * keep the minimap collapse state in sync like `_viewTo`.
+     */
+    _fitRegion(region: [number, number, number, number], opts?: ViewToOptions): void {
+        const [x, y, w, h] = region;
+        if (!(w > 0) || !(h > 0)) {
+            return;
+        }
+        let _animate = true;
+        let _duration = this.options.duration;
+        if (opts && opts.duration !== undefined) {
+            if (opts.duration === 0) {
+                _animate = false;
+            } else {
+                _duration = opts.duration;
+            }
+        }
+        this._map.getView().fit([x, y, x + w, y + h], {
+            size: this._map.getSize(),
+            padding: this._opaquePanelPadding(),
+            duration: _animate ? _duration : 0,
+            easing: this._easing,
+        });
+        if (this._mini_map && this.options.width > this.options.skinny_size) {
+            this._mini_map.setCollapsed(true);
+        }
+    }
+
+    _toViewCoords(loc: LatLngLiteral): number[] {
+        const is_image_space = this._map.getView().getProjection().getCode() === "EPSG:4326";
+        if (is_image_space) return [loc.lon, loc.lat];
+        return fromLonLat([loc.lon, loc.lat]);
+    }
+
+    _getMapZoom(): number {
+        // fractional zoom on purpose: overview fits produce non-integer zooms and
+        // rounding here would snap the view on the next navigation
+        return this._map.getView().getZoom() || 0;
+    }
+
+    // Note: there is deliberately no offset-aware variant. The exposed
+    // center is panel-shifted (see the migration guide); a previous
+    // `offset?: boolean` parameter promised a correction it never applied.
+    _getMapCenter(): LatLngLiteral {
+        const view = this._map.getView();
+        const center = view.getCenter() ?? [0, 0];
+        const [lon, lat] = toLonLat(center, view.getProjection());
+        return { lat: lat, lon: lon };
+    }
+
+    _getMapCenterOffset(location: LatLngLiteral, zoom: number): LatLngLiteral {
+        // Offset the center by map_center_offset pixels at the given zoom.
+        // A null map_center_offset means "no offset" (the default).
+        const offset = this.options.map_center_offset;
+        if (!offset || (offset.left === 0 && offset.top === 0)) {
+            return location;
+        }
+        const view = this._map.getView();
+        const projection = view.getProjection();
+        const center = this._toViewCoords(location);
+        const resolution = view.getResolutionForZoom(zoom);
+        return this._fromViewCoords(
+            [center[0] - offset.left * resolution, center[1] + offset.top * resolution],
+            projection,
+        );
+    }
+
+    _fromViewCoords(coord: number[], projection: Projection): LatLngLiteral {
+        if (projection.getCode() === "EPSG:4326") return { lat: coord[1], lon: coord[0] };
+        // linear lon inversion without dateline wrapping (issue #381);
+        // lat uses the exact mercator inverse (6378137 = the 3857 sphere radius)
+        const c = toLonLat(coord, projection);
+        return { lat: c[1], lon: (coord[0] / 6378137) * (180 / Math.PI) };
+    }
+
+    /**
+     * May a tile-backed layer (base map, overlay, minimap, overview) be
+     * created right now? Under `consent_required` that is only true once the
+     * visitor has allowed the tile service. This was the same five-line
+     * predicate at five call sites.
+     */
+    private _tilesAllowed(): boolean {
+        const consent = consentManagerOf(this.options);
+        if (!this.options.consent_required || !consent) {
+            return true;
+        }
+        return consent.isGranted(tileService().key);
+    }
+
+    /** A slide's {lat, lon} when both are real numbers, else null. */
+    private _latLngOf(loc: StorymapSlideLocation | null | undefined): LatLngLiteral | null {
+        if (!loc || typeof loc.lat !== "number" || typeof loc.lon !== "number") {
+            return null;
+        }
+        return { lat: loc.lat, lon: loc.lon };
+    }
+
+    /**
+     * The map's pixel size, with a never-zero fallback.
+     *
+     * `getSize()` returns undefined until the map has a size, so the six
+     * call sites that fitted an extent to the viewport all repeated the same
+     * `(size[0] || 1)` guard — which silently fitted against a 1px viewport
+     * rather than bailing out.
+     */
+    private _viewportSize(): [number, number] {
+        const size = this._map?.getSize();
+        return [size?.[0] || 1, size?.[1] || 1];
+    }
+
+    _getBoundsZoom(
+        origin: LatLngLiteral,
+        destination: LatLngLiteral,
+        correct_for_center?: boolean,
+    ): number {
+        const coords = [
+            [origin.lon, origin.lat],
+            [destination.lon, destination.lat],
+        ];
+        const view_coords = this._markerCoordsToViewCoords(coords);
+        const extent = boundingExtent(view_coords);
+        const size = this._map.getSize();
+        if (!size || !size[0] || !size[1]) return 0;
+
+        const resolution_x = (extent[2] - extent[0]) / size[0];
+        const resolution_y = (extent[3] - extent[1]) / size[1];
+        const resolution = Math.max(resolution_x, resolution_y) * 3; // padding factor
+        if (!isFinite(resolution) || resolution <= 0) return 0;
+
+        const z = this._map.getView().getZoomForResolution(resolution);
+        if (z === undefined || !isFinite(z)) return 0;
+        return Math.max(0, Math.round(z));
+    }
+
+    _initialMapLocation(): void {
+        // OpenLayers renders independently; nothing to subscribe for initial location
+    }
+
+    /**
+     * Great-circle (haversine) length of the route through all markers in
+     * kilometers (issue #341).
+     */
+    getRouteDistance(): number | undefined {
+        const coords = this._markers
+            .map((m) => m.location())
+            .filter((l): l is LatLngLiteral => !!l && isFinite(l.lat) && isFinite(l.lon));
+        if (coords.length < 2) {
+            return undefined;
+        }
+        const R = 6371;
+        let total = 0;
+        for (let i = 1; i < coords.length; i++) {
+            const d_lat = ((coords[i].lat - coords[i - 1].lat) * Math.PI) / 180;
+            const d_lon = ((coords[i].lon - coords[i - 1].lon) * Math.PI) / 180;
+            const a =
+                Math.sin(d_lat / 2) ** 2 +
+                Math.cos((coords[i - 1].lat * Math.PI) / 180) *
+                    Math.cos((coords[i].lat * Math.PI) / 180) *
+                    Math.sin(d_lon / 2) ** 2;
+            total += 2 * R * Math.asin(Math.sqrt(a));
+        }
+        return total;
+    }
+
+    _markerOverview(duration?: number): void {
+        // Hide Active Line
+        this._cancelLineAnimation();
+        this._line_active.setVisible(false);
+
+        // repeated presses while an overview animation is running snap
+        // instantly instead of restarting the ~1s animation
+        if (duration && this._map.getView().getAnimating()) {
+            duration = 0;
+        }
+
+        if (this.options.map_type === "zoomify") {
+            // legacy zoomify: show the whole image centered at the best-fit
+            // pyramid level (the original renderer's overview); with the
+            // panel offset the legacy renderer drops one zoom level
+            const size = this._map.getSize();
+            const overview = this._zoomifyOverview([size?.[0] || 1280, size?.[1] || 450]);
+            if (overview) {
+                const offset =
+                    this.options.map_center_offset &&
+                    (this.options.map_center_offset.left !== 0 ||
+                        this.options.map_center_offset.top !== 0);
+                // with the panel offset the legacy renderer drops one zoom
+                // level (the mercator zoom = the pyramid level)
+                const view_zoom = offset ? overview.zoom - 1 : overview.zoom;
+                // offset the center directly in view coords (a lat/lon
+                // round-trip would corrupt the zoomify target)
+                const resolution = this._map.getView().getResolutionForZoom(view_zoom);
+                const center_view = [
+                    overview.center[0] - (this.options.map_center_offset?.left ?? 0) * resolution,
+                    overview.center[1] + (this.options.map_center_offset?.top ?? 0) * resolution,
+                ];
+                this._map.getView().animate({
+                    center: center_view,
+                    zoom: view_zoom,
+                    duration: duration ?? this._transition_duration,
+                    easing: this._easing,
+                });
+            }
+        } else if (this.isImageSpace()) {
+            const source = this._sourceOf(this._tile_layer);
+            if (!source) {
+                return;
+            }
+            const fit = () => {
+                try {
+                    // a custom layer with a source is not necessarily a tile
+                    // source; only tile grids can supply a fit extent
+                    const grid = (
+                        source as {
+                            getTileGrid?: () => { getExtent(): number[] } | null;
+                        }
+                    ).getTileGrid?.();
+                    if (grid) {
+                        // compute the fit target directly and animate once (a
+                        // fit() followed by setCenter() would cancel the fit
+                        // animation, issue #465)
+                        const extent = grid.getExtent();
+                        const size = this._viewportSize();
+                        const resolution_x = (extent[2] - extent[0]) / size[0];
+                        const resolution_y = (extent[3] - extent[1]) / size[1];
+                        const resolution = Math.max(resolution_x, resolution_y);
+                        const view = this._map.getView();
+                        const zoom = view.getZoomForResolution(resolution) ?? 0;
+                        const overview_center = this.options.map_overview_center;
+                        const center_px = overview_center
+                            ? this._toViewCoords({
+                                  lat: overview_center.lat,
+                                  lon: overview_center.lon,
+                              })
+                            : [(extent[0] + extent[2]) / 2, (extent[1] + extent[3]) / 2];
+                        const projection = view.getProjection();
+                        const location = this._fromViewCoords(center_px, projection);
+                        const offset_location = this._getMapCenterOffset(location, zoom);
+                        view.animate({
+                            center: this._toViewCoords(offset_location),
+                            zoom: zoom,
+                            duration: duration ?? this._transition_duration,
+                            easing: this._easing,
+                        });
+                    }
+                } catch (e) {
+                    console.warn("IIIF overview fit failed:", e);
+                }
+            };
+
+            if (source.getState() === "ready") {
+                fit();
+            } else {
+                source.once("change", () => {
+                    if (source.getState() === "ready") fit();
+                });
+            }
+        } else {
+            this.bounds_array = this._getAllMarkersBounds(this._markers);
+
+            // user-selected overview centerpoint (issues #107, #271): fit the
+            // zoom to the markers but center on the configured location
+            const overview_center = this.options.map_overview_center;
+            if (overview_center && this.bounds_array && this.bounds_array.length) {
+                const view_coords = this._markerCoordsToViewCoords(this.bounds_array);
+                const extent = boundingExtent(view_coords);
+                const size = this._viewportSize();
+                const resolution = Math.max(
+                    (extent[2] - extent[0]) / size[0],
+                    (extent[3] - extent[1]) / size[1],
+                );
+                const zoom = Math.max(
+                    0,
+                    Math.round(this._map.getView().getZoomForResolution(resolution) ?? 0) - 1,
+                );
+                const offset_location = this._getMapCenterOffset(
+                    { lat: overview_center.lat, lon: overview_center.lon },
+                    zoom,
+                );
+                this._map.getView().animate({
+                    center: this._toViewCoords(offset_location),
+                    zoom: zoom,
+                    duration: duration ?? this._transition_duration,
+                    easing: this._easing,
+                });
+            } else if (
+                this.options.map_center_offset &&
+                (this.options.map_center_offset.left !== 0 ||
+                    this.options.map_center_offset.top !== 0)
+            ) {
+                if (this.bounds_array && this.bounds_array.length) {
+                    const view_coords = this._markerCoordsToViewCoords(this.bounds_array);
+                    const extent = boundingExtent(view_coords);
+                    const size = this._viewportSize();
+                    const resolution_x = (extent[2] - extent[0]) / size[0];
+                    const resolution_y = (extent[3] - extent[1]) / size[1];
+                    const resolution = Math.max(resolution_x, resolution_y);
+                    const zoom = Math.max(
+                        0,
+                        Math.round(this._map.getView().getZoomForResolution(resolution) ?? 0) - 1,
+                    );
+                    const center_px = [(extent[0] + extent[2]) / 2, (extent[1] + extent[3]) / 2];
+                    const projection = this._map.getView().getProjection();
+                    const location = this._fromViewCoords(center_px, projection);
+                    const offset_location = this._getMapCenterOffset(location, zoom);
+                    this._map.getView().animate({
+                        center: this._toViewCoords(offset_location),
+                        zoom: zoom,
+                        duration: duration ?? this._transition_duration,
+                        easing: this._easing,
+                    });
+                }
+            } else {
+                // fit instantly, then shift the center by the panel offset
+                // and animate there so the markers clear the story panel;
+                // with the strict bbox layout markers outside of the box are
+                // unreachable — they must not skew the fit target
+                this._fitView(this._map, this.bounds_array, 0, this._bboxExtent() !== null);
+                const view = this._map.getView();
+                const zoom = view.getZoom();
+                if (zoom !== undefined) {
+                    const center = this._fromViewCoords(
+                        view.getCenter() ?? [0, 0],
+                        view.getProjection(),
+                    );
+                    const offset_location = this._getMapCenterOffset(center, zoom);
+                    view.animate({
+                        center: this._toViewCoords(offset_location),
+                        zoom: zoom,
+                        duration: duration ?? this._transition_duration,
+                        easing: this._easing,
+                    });
+                }
+            }
+        }
+
+        if (this._mini_map) {
+            this._mini_map.setCollapsed(true);
+        }
+    }
+
+    /**
+     * Swap the minimap's layer for the current `map_type` (mirrors the
+     * initial `_createMiniMap` fitting: zoomify extent, IIIF image extent,
+     * otherwise the marker bounds). No-op when no minimap exists yet.
+     */
+    _refreshMiniMapLayer(): void {
+        if (!this._mini_map) return;
+        const overview = this._mini_map.getOverviewMap();
+        overview.getLayers().clear();
+        if (!this._tilesAllowed()) {
+            this._tile_layer_mini = null;
+            return;
+        }
+        this._tile_layer_mini = this._createTileLayer(this.options.map_type);
+        overview.addLayer(this._tile_layer_mini);
+        const is_zoomify = this.options.map_type === "zoomify";
+        const zoomify_pyramid = is_zoomify ? this._zoomifyPyramid() : null;
+        if (zoomify_pyramid) {
+            const raw_size = overview.getSize();
+            const size = raw_size && raw_size[0] >= 50 && raw_size[1] >= 50 ? raw_size : [150, 100];
+            overview.getView().fit(zoomify_pyramid.extent, { size: size });
+        } else if (this.bounds_array && this.bounds_array.length) {
+            this._fitView(overview, this.bounds_array, 0, this._bboxExtent() !== null);
+        }
+        if (this.isImageSpace()) {
+            this._fitMiniMapToImage();
+        }
+    }
+
+    /*	Display
+	================================================== */
+    /**
+     * Re-apply runtime-changed options (driven by StoryMap.setMapOptions).
+     * Only keys with an immediate effect are handled here; everything else is
+     * picked up on the next navigation or layout pass.
+     */
+    applyOptions(keys: string[]): void {
+        for (const key of keys) {
+            switch (key) {
+                case "map_type": {
+                    // Rebuild the main + minimap tile layers for the new type
+                    if (this._tile_layer) {
+                        this._map.removeLayer(this._tile_layer);
+                    }
+                    if (this._tilesAllowed()) {
+                        this._tile_layer = this._createTileLayer(this.options.map_type);
+                        this._tile_layer.setZIndex(0);
+                        this._map.addLayer(this._tile_layer);
+                    }
+                    this._refreshMiniMapLayer();
+                    this._updateAttribution();
+                    this._el.map.style.backgroundColor = this.options.map_background_color;
+                    break;
+                }
+                case "overlays": {
+                    // Rebuild the stacked overlays from the new option value
+                    this._buildOverlays();
+                    break;
+                }
+                case "show_lines":
+                case "line_color":
+                case "line_color_inactive":
+                case "line_weight":
+                case "line_opacity":
+                case "line_dash":
+                case "line_join": {
+                    const stroke = (color: string) => this._lineStyle(color);
+                    this._line.setStyle(stroke(this.options.line_color_inactive));
+                    this._line.setOpacity(this.options.line_opacity);
+                    this._line.setVisible(this.options.show_lines);
+                    this._line_active.setStyle(stroke(this.options.line_color));
+                    this._line_active.setVisible(this.options.show_lines);
+                    break;
+                }
+                case "map_background_color":
+                    this._el.map.style.backgroundColor = this.options.map_background_color;
+                    break;
+                case "map_bbox": {
+                    // recreate the view so the new extent constraint applies,
+                    // preserving center and zoom. The replacement has to
+                    // rebuild the *same* view configuration _createMap() uses —
+                    // dropping constrainOnlyCenter (which _createMap sets
+                    // deliberately, see above), the image zoom ladder or the
+                    // legacy zoomify multiWorld flag silently reintroduced the
+                    // strict extent constraint this code went out of its way
+                    // to avoid, and broke image-mode zoom (issue #465).
+                    const view = this._map.getView();
+                    const center = view.getCenter();
+                    const zoom = view.getZoom();
+                    const extent = this._bboxExtent();
+                    // must match _createMap's test exactly: a *georeferenced*
+                    // IIIF layer (map_as_image false) is a mercator map, so
+                    // testing map_type alone handed it the image-pixel view
+                    const is_image_map = this.options.map_type === "iiif" && this.isImageSpace();
+                    const user_view = this.options.map_options?.view as
+                        Record<string, unknown> | undefined;
+                    this._map.setView(
+                        new View({
+                            projection: is_image_map ? "EPSG:4326" : "EPSG:3857",
+                            center: center,
+                            zoom: zoom,
+                            minZoom: view.getMinZoom(),
+                            maxZoom: view.getMaxZoom(),
+                            ...(is_image_map
+                                ? { multiWorld: true, resolutions: IMAGE_RESOLUTIONS }
+                                : {}),
+                            ...(this.options.map_type === "zoomify" ? { multiWorld: true } : {}),
+                            ...(extent ? { extent: extent, constrainOnlyCenter: true } : {}),
+                            ...((user_view ?? {}) as Record<string, unknown>),
+                        }),
+                    );
+                    break;
+                }
+                default:
+                    // map_center_offset, duration, ease, calculate_zoom etc.
+                    // take effect on the next navigation
+                    break;
+            }
+        }
+        // Re-fit the current view in case layer changes altered the rendering
+        if (this._markers.length > 0 && this.current_marker < this._markers.length) {
+            const marker = this._markers[this.current_marker];
+            if (marker.data.type === "overview") {
+                this._markerOverview();
+            } else if (marker.data.location) {
+                this._viewTo(marker.data.location, { duration: 0 });
+            }
+        }
+    }
+
+    _updateMapDisplay(animate?: boolean, d?: number, instant?: boolean): void {
+        if (animate) {
+            const duration = d ? d : this.options.duration;
+            if (this.timer) {
+                clearTimeout(this.timer);
+            }
+
+            this.timer = setTimeout(() => {
+                this._refreshMap(false);
+            }, duration);
+        } else {
+            if (!this.timer) {
+                // size changes (resize/fullscreen) re-fit instantly so marker
+                // overlays don't chase an animated view
+                this._refreshMap(instant !== false);
+            }
+        }
+
+        if (this._mini_map) {
+            this._mini_map.setCollapsed(this._el.container.offsetWidth < this.options.skinny_size);
+        }
+    }
+
+    _refreshMap(instant = false): void {
+        if (this._map) {
+            if (this.timer) {
+                clearTimeout(this.timer);
+                this.timer = null;
+            }
+
+            this._map.updateSize();
+
+            // Check to see if it's an overview
+            const marker = this._markers[this.current_marker];
+            if (marker && marker.data.type && marker.data.type === "overview") {
+                this._markerOverview(instant ? 0 : undefined);
+                if (instant) {
+                    this._map.renderSync();
+                }
+            } else if (marker && marker.data.location) {
+                if (instant) {
+                    this._setViewInstant(marker.data.location, this._getMapZoom());
+                } else {
+                    this._viewTo(marker.data.location, {
+                        zoom: this._getMapZoom(),
+                    });
+                }
+            }
+        }
+    }
+
+    /**
+     * Set the view synchronously (resize path): OL's animate() applies its
+     * end state asynchronously which can leave marker overlays rendering
+     * stale positions after a size change.
+     */
+    _setViewInstant(loc: StorymapSlideLocation, zoom: number): void {
+        const start = this._latLngOf(loc);
+        if (!start) {
+            return;
+        }
+        let _location: LatLngLiteral = start;
+        if (this.options.map_center_offset) {
+            _location = this._getMapCenterOffset(_location, zoom);
+        }
+        const view = this._map.getView();
+        view.setZoom(zoom);
+        view.setCenter(this._toViewCoords(_location));
+        this._map.renderSync();
+    }
+}
+
+export { OpenLayers };