@projektemacher/storymapjs 0.10.7 → 0.10.8

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

@@ -3,8 +3,10 @@ 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";
@@ -26,8 +28,21 @@ import Map from "../Map";
 import OpenLayersMapMarker from "./MapMarker.OpenLayers";
 import { padCroppedZoomifyTile } from "./zoomifyTiles";
 import type { LinePoint, ViewToOptions } from "../types";
-import type { LatLngLiteral, StorymapSlide, StorymapSlideLocation } from "../../types";
-import { consentManagerOf, consentMessage, type ConsentManager } from "../../storymap/Consent";
+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
@@ -35,6 +50,20 @@ import { consentManagerOf, consentMessage, type ConsentManager } from "../../sto
 
 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,
@@ -45,24 +74,35 @@ const IMAGE_RESOLUTIONS = Array.from({ length: 25 }, (_, i) => 2 ** (16 - i));
 
 export default class OpenLayers extends Map {
     declare "_map": OlMap;
-    declare "_tile_layer": TileLayer;
+    declare "_tile_layer": Layer;
     declare "_line": VectorLayer;
     declare "_line_active": VectorLayer;
-    declare "_tile_layer_mini": TileLayer | null;
+    declare "_tile_layer_mini": Layer | null;
     declare "_mini_map": OverviewMap;
     declare "_markers": OpenLayersMapMarker[];
     /** App-level stacked overlays (see the `overlays` option) */
-    declare "_overlay_layers": TileLayer[];
+    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.options.map_type === "iiif" && this.options.map_as_image;
+        const is_image_map = this.isImageSpace();
+        this._imageready_fired = new WeakSet();
 
-        // Caller-supplied OpenLayers options: controls/interactions replace the
-        // defaults, view merges over the computed default, other options pass through
+        // 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>;
@@ -76,6 +116,16 @@ export default class OpenLayers extends Map {
         // 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,
@@ -83,10 +133,19 @@ export default class OpenLayers extends Map {
             interactions: (user_map_options.interactions as Interaction[]) ?? [],
             view: new View({
                 projection: is_image_map ? "EPSG:4326" : "EPSG:3857",
-                center: [0, 0],
-                zoom: 0,
-                minZoom: 0,
-                maxZoom: is_image_map ? IMAGE_RESOLUTIONS.length - 1 : MAX_ZOOM,
+                ...(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
@@ -119,11 +178,11 @@ export default class OpenLayers extends Map {
         // 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 = consentMessage("consent_service_tiles", "map tiles");
+        const tile_service = tileService();
         if (this.options.consent_required && consent) {
-            if (consent.isGranted(tile_service)) {
+            if (consent.isGranted(tile_service.key)) {
                 this._addTileLayer();
-            } else if (!consent.isDenied(tile_service)) {
+            } else if (!consent.isDenied(tile_service.key)) {
                 void this._requestTileConsent(consent, tile_service);
             }
             // denied → the map renders with background color and markers only
@@ -131,7 +190,8 @@ export default class OpenLayers extends Map {
             this._addTileLayer();
         }
 
-        // Create Overall Connection Line
+        // 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);
@@ -152,6 +212,7 @@ export default class OpenLayers extends Map {
 
         // 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
@@ -174,6 +235,57 @@ export default class OpenLayers extends Map {
         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
@@ -181,32 +293,90 @@ export default class OpenLayers extends Map {
      */
     _updateAttribution(): void {
         const extras = this._extra_attributions ?? [];
-        const parts = [this._getAttribution(this.options.map_type), ...extras]
-            .filter(Boolean)
-            .join(" | ");
+        // 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) {
-            el.innerHTML = parts;
+            // 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 {
+    _getAttribution(map_type: string): string[] {
         const parts = [
             "<a href='https://storymap.knightlab.com/' target='_blank' class='vco-knightlab-brand'><span>&#x25a0;</span> StoryMapJS</a>",
         ];
-        if (map_type === "osm" || map_type === "" || map_type.startsWith("osm")) {
+        // 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.join(" | ");
+        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
@@ -227,7 +397,7 @@ export default class OpenLayers extends Map {
     /**
      * Ask for tile consent, then attach the layers if allowed.
      */
-    async _requestTileConsent(consent: ConsentManager, tile_service: string) {
+    async _requestTileConsent(consent: ConsentManager, tile_service: ConsentService) {
         if (await consent.request(tile_service, "", this._el.map)) {
             this._onTilesAllowed();
         }
@@ -240,24 +410,36 @@ export default class OpenLayers extends Map {
      * 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 = [];
-        const consent = consentManagerOf(this.options);
-        const tile_service = consentMessage("consent_service_tiles", "map tiles");
-        if (
-            this.options.consent_required &&
-            consent &&
-            !consent.isGranted(tile_service)
-        ) {
+        this._overlay_entries = [];
+        if (!this._tilesAllowed()) {
             return;
         }
         const overlays = this.options.overlays ?? [];
         overlays.forEach((entry, i) => {
-            const layer = this._createTileLayer(entry.map_type);
+            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);
@@ -280,11 +462,78 @@ export default class OpenLayers extends Map {
             }
             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
@@ -310,10 +559,7 @@ export default class OpenLayers extends Map {
      * frames (bounded: rendering settles within a frame or two of any
      * add/visibility change).
      */
-    _paintOverlayBlend(
-        entry: { className?: string; blendMode?: string },
-        retries = 60,
-    ): void {
+    _paintOverlayBlend(entry: { className?: string; blendMode?: string }, retries = 60): void {
         if (!entry.blendMode || !entry.className) {
             return;
         }
@@ -337,10 +583,9 @@ export default class OpenLayers extends Map {
 
     /** Refresh the attribution line with the visible overlays' credits. */
     _syncOverlayAttributions(): void {
-        const overlays = this.options.overlays ?? [];
         const parts: string[] = [];
         this._overlay_layers.forEach((layer, i) => {
-            const credit = overlays[i]?.attribution;
+            const credit = this._overlay_entries[i]?.attribution;
             if (credit && layer.getVisible()) {
                 parts.push(credit);
             }
@@ -348,19 +593,29 @@ export default class OpenLayers extends Map {
         this.setExtraAttributions(parts);
     }
 
-    /** Number of stacked overlay layers (see the `overlays` option). */
+    /**
+     * 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). */
+    /**
+     * 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.options.overlays ?? [])[index];
+        const entry = this._overlay_entries[index];
         if (entry && visible) {
             this._paintOverlayBlend(entry);
         }
@@ -368,6 +623,9 @@ export default class OpenLayers extends Map {
     }
 
     /** 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);
     }
@@ -392,8 +650,11 @@ export default class OpenLayers extends Map {
             const marker = this._markers[this.current_marker];
             if (marker.data.type === "overview") {
                 this._markerOverview();
-            } else if (this._hasLocation(marker.data)) {
-                this._fitView(this._map, [[marker.data.location.lon, marker.data.location.lat]], 0);
+            } else {
+                const latlon = marker.latLon();
+                if (latlon) {
+                    this._fitView(this._map, [[latlon.lon, latlon.lat]], 0);
+                }
             }
         }
     }
@@ -477,7 +738,206 @@ export default class OpenLayers extends Map {
         return { zoom, center };
     }
 
-    _createTileLayer(map_type: string): TileLayer {
+    _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]) {
@@ -494,7 +954,7 @@ export default class OpenLayers extends Map {
                     return new TileLayer({
                         source: new XYZ({
                             url: mapbox_url,
-                            attributions: [],
+                            attributions: this._sourceAttributions(map_type),
                             crossOrigin: "anonymous",
                         }),
                     });
@@ -502,11 +962,18 @@ export default class OpenLayers extends Map {
                 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: [] }) });
+                return new TileLayer({
+                    source: new OSM({ attributions: this._sourceAttributions(map_type) }),
+                });
             }
 
             case "stadia": {
-                let style_url = "osm:standard";
+                // 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) {
@@ -515,8 +982,8 @@ export default class OpenLayers extends Map {
                 }
                 return new TileLayer({
                     source: new XYZ({
-                        url: `https://tiles.stadiamaps.com/tiles/${style_url}/{z}/{x}/{y}.png`,
-                        attributions: [],
+                        url: `https://tiles.stadiamaps.com/tiles/${style_url}/{z}/{x}/{y}{r}.png`,
+                        attributions: this._sourceAttributions(map_type),
                     }),
                 });
             }
@@ -526,7 +993,7 @@ export default class OpenLayers extends Map {
                 return new TileLayer({
                     source: new XYZ({
                         url: "https://tiles.stadiamaps.com/tiles/stamen_toner_lite/{z}/{x}/{y}.png",
-                        attributions: [],
+                        attributions: this._sourceAttributions(map_type),
                     }),
                 });
 
@@ -560,6 +1027,7 @@ export default class OpenLayers extends Map {
                             attributions: this.options.iiif.attribution || [],
                         });
                         iiif_layer.setSource(source);
+                        this._fireImageready(source, "iiif", iiif_layer);
                         if (source.getState() === "ready") {
                             this._markerOverview();
                         } else {
@@ -587,15 +1055,13 @@ export default class OpenLayers extends Map {
                 if (!map_type.includes("{z}")) {
                     return this._createVectorStyleLayer(map_type);
                 }
-                return new TileLayer({
-                    source: new XYZ({ url: map_type, attributions: [], crossOrigin: "anonymous" }),
-                });
+                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: [],
+                        attributions: this._sourceAttributions(map_type),
                         maxZoom: 16,
                     }),
                 });
@@ -611,50 +1077,56 @@ export default class OpenLayers extends Map {
                     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: [] }) });
+                    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);
 
-                return new TileLayer({
-                    source: new XYZ({
-                        tileGrid: pyramid.tileGrid,
-                        crossOrigin: "anonymous",
-                        attributions: [],
-                        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_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": {
@@ -667,7 +1139,9 @@ export default class OpenLayers extends Map {
                         `https://tiles.openfreemap.org/styles/${style_name}`,
                     );
                 }
-                return new TileLayer({ source: new OSM({ attributions: [] }) });
+                return new TileLayer({
+                    source: new OSM({ attributions: this._sourceAttributions(map_type) }),
+                });
             }
             default: {
                 // Relative/custom templates (./tiles/{z}/{x}/{y}.png,
@@ -678,18 +1152,14 @@ export default class OpenLayers extends Map {
                 // {z} render as vector styles, anything else falls back to
                 // OSM.
                 if (map_type.includes("{z}")) {
-                    return new TileLayer({
-                        source: new XYZ({
-                            url: map_type,
-                            attributions: [],
-                            crossOrigin: "anonymous",
-                        }),
-                    });
+                    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: [] }) });
+                return new TileLayer({
+                    source: new OSM({ attributions: this._sourceAttributions(map_type) }),
+                });
             }
         }
     }
@@ -718,15 +1188,10 @@ export default class OpenLayers extends Map {
         // 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
-        const consent = consentManagerOf(this.options);
-        const tile_service = consentMessage("consent_service_tiles", "map tiles");
-        const tiles_allowed = !(
-            this.options.consent_required &&
-            consent &&
-            !consent.isGranted(tile_service)
-        );
-        this._tile_layer_mini = tiles_allowed ? this._createTileLayer(this.options.map_type) : null;
-        const is_image_map = this.options.map_type === "iiif" && this.options.map_as_image;
+        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
@@ -828,9 +1293,7 @@ export default class OpenLayers extends Map {
                 // 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];
+                    raw_size && raw_size[0] >= 50 && raw_size[1] >= 50 ? raw_size : [150, 100];
                 overview_map.getView().fit(zoomify_pyramid.extent, {
                     size: size,
                 });
@@ -842,10 +1305,15 @@ export default class OpenLayers extends Map {
         } 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);
+            this._fitView(
+                this._mini_map.getOverviewMap(),
+                this.bounds_array,
+                0,
+                this._bboxExtent() !== null,
+            );
         }
 
-        if (this.options.map_type === "iiif" && this.options.map_as_image) {
+        if (this.isImageSpace()) {
             // in image mode there are no geo markers to fit, so show the
             // whole image instead (issues #465, #355)
             this._fitMiniMapToImage();
@@ -856,7 +1324,7 @@ export default class OpenLayers extends Map {
         if (!this._tile_layer_mini) return;
         const fit_mini_image = () => {
             try {
-                const mini_source = this._tile_layer_mini?.getSource() as {
+                const mini_source = this._sourceOf(this._tile_layer_mini) as {
                     getTileGrid?: () => { getExtent(): number[] };
                 } | null;
                 const grid = mini_source?.getTileGrid?.();
@@ -874,8 +1342,17 @@ export default class OpenLayers extends Map {
                 console.warn("IIIF minimap fit failed:", e);
             }
         };
-        const mini_source = this._tile_layer_mini.getSource();
+        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 {
@@ -886,7 +1363,7 @@ export default class OpenLayers extends Map {
         } else {
             // the mini layer sets its source asynchronously
             this._tile_layer_mini.once("change:source", () => {
-                const src = this._tile_layer_mini?.getSource();
+                const src = this._sourceOf(this._tile_layer_mini);
                 if (!src) return;
                 if (src.getState() === "ready") {
                     fit_mini_image();
@@ -923,12 +1400,16 @@ export default class OpenLayers extends Map {
         if (this._map.getView().getProjection().getCode() === "EPSG:4326") {
             return;
         }
-        const real = this._markers.filter(
-            (m) => m.data.real_marker && m.data.location?.lon !== undefined,
-        );
-        const unwrapped = this._unwrapLongitudes(real.map((m) => m.data.location.lon as number));
-        real.forEach((m, i) => {
-            m._overlay?.setPosition(fromLonLat([unwrapped[i], m.data.location.lat as number]));
+        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]));
         });
     }
 
@@ -941,18 +1422,16 @@ export default class OpenLayers extends Map {
     /*	Marker helpers
 	================================================== */
     _getAllMarkersBounds(markers_array: OpenLayersMapMarker[]): number[][] {
-        const coords = [];
-        for (let i = 0; i < markers_array.length; i++) {
-            if (markers_array[i].data.real_marker) {
-                coords.push([
-                    markers_array[i].data.location.lon,
-                    markers_array[i].data.location.lat,
-                ]);
+        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] as number));
+        const lons = this._unwrapLongitudes(coords.map((c) => c[0]));
         return coords.map((c, i) => [lons[i], c[1]]);
     }
 
@@ -986,8 +1465,7 @@ export default class OpenLayers extends Map {
     _bboxExtent(): number[] | null {
         const bbox = this.options.map_bbox as number[] | null | undefined;
         if (!bbox || bbox.length !== 4) return null;
-        const is_image_space = this.options.map_type === "iiif" && this.options.map_as_image;
-        if (is_image_space) return bbox;
+        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]]);
@@ -1004,7 +1482,17 @@ export default class OpenLayers extends Map {
     _opaquePanelPadding(): [number, number, number, number] {
         const padding: [number, number, number, number] = [15, 15, 15, 15];
         if (typeof document === "undefined") return padding;
-        const panel = document.querySelector(".vco-storyslider .vco-slide.vco-active .vco-text");
+        // 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);
@@ -1062,52 +1550,60 @@ export default class OpenLayers extends Map {
             padding: this._opaquePanelPadding(),
             maxZoom: 12,
             duration: duration,
-            easing: this.options.ease as ((t: number) => number) | undefined,
+            easing: this._easing,
         });
     }
 
     _calculateMarkerZooms(): void {
-        for (let i = 0; i < this._markers.length; i++) {
-            if (this._markers[i].data.location) {
-                const marker = this._markers[i];
-                let marker_location, calculated_zoom;
-
-                // MARKER LOCATION
-                if (marker.data.type && marker.data.type === "overview") {
-                    marker_location = this._getMapCenter(true);
-                } else {
-                    marker_location = marker.location();
-                }
+        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() : this._getMapCenter(true);
-                const next_marker =
-                    i < this._markers.length - 1
-                        ? this._markers[i + 1].location()
-                        : this._getMapCenter(true);
-
-                const prev_marker_zoom = this._calculateZoomChange(prev_marker, marker_location);
-                const next_marker_zoom = this._calculateZoomChange(next_marker, marker_location);
-
-                if (prev_marker_zoom && prev_marker_zoom < next_marker_zoom) {
-                    calculated_zoom = prev_marker_zoom;
-                } else if (next_marker_zoom) {
-                    calculated_zoom = next_marker_zoom;
-                } else {
-                    calculated_zoom = prev_marker_zoom;
-                }
+            // 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 (
-                    this.options.map_center_offset &&
-                    (this.options.map_center_offset.left !== 0 ||
-                        this.options.map_center_offset.top !== 0)
-                ) {
-                    calculated_zoom = calculated_zoom - 1;
-                }
+            if (calculated_zoom === undefined) {
+                continue;
+            }
 
-                marker.data.location.zoom = calculated_zoom;
+            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;
         }
     }
 
@@ -1149,25 +1645,32 @@ export default class OpenLayers extends Map {
         this._map.addLayer(line);
     }
 
-    _addToLine(line: VectorLayer, d: LinePoint): void {
+    _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;
+        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 && lon !== undefined) {
+        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: d.location.lat, lon }));
+        coords.push(this._toViewCoords({ lat, lon }));
         feature.getGeometry().setCoordinates(coords);
     }
 
@@ -1198,6 +1701,9 @@ export default class OpenLayers extends Map {
         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();
@@ -1267,7 +1773,7 @@ export default class OpenLayers extends Map {
         const suffix = grow_len >= 1 ? view_coords.slice(grow_len - 1) : null;
         const suffix_total = suffix ? this._pathLength(suffix) : 0;
 
-        const easing = this.options.ease as ((t: number) => number) | undefined;
+        const easing = this._easing;
         const start_time = performance.now();
         if (prefix) {
             // Seed the already-traveled prefix so it stays red from frame 0
@@ -1353,7 +1859,7 @@ export default class OpenLayers extends Map {
         this._map.getView().animate({
             center: this._toViewCoords(loc),
             duration: this.options.duration,
-            easing: this.options.ease as ((t: number) => number) | undefined,
+            easing: this._easing,
         });
     }
 
@@ -1361,15 +1867,33 @@ export default class OpenLayers extends Map {
         this._map.getView().animate({
             zoom: z,
             duration: this.options.duration,
-            easing: this.options.ease as ((t: number) => number) | undefined,
+            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 = { lat: loc.lat, lon: loc.lon };
+            _location: LatLngLiteral = start;
 
         // Show Active Line
         if (!this.options.map_as_image) {
@@ -1404,11 +1928,15 @@ export default class OpenLayers extends Map {
             center: this._toViewCoords(_location),
             zoom: _zoom,
             duration: _animate ? _duration : 0,
-            easing: this.options.ease as ((t: number) => number) | undefined,
+            easing: this._easing,
         });
 
         if (this._mini_map && this.options.width > this.options.skinny_size) {
-            if (_zoom - 1 <= this.zoom_min_max.min) {
+            // 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);
@@ -1416,6 +1944,36 @@ export default class OpenLayers extends Map {
         }
     }
 
+    /**
+     * 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];
@@ -1428,25 +1986,29 @@ export default class OpenLayers extends Map {
         return this._map.getView().getZoom() || 0;
     }
 
-    _getMapCenter(offset?: boolean): LatLngLiteral {
-        const center = toLonLat(
-            this._map.getView().getCenter(),
-            this._map.getView().getProjection(),
-        );
-        return { lat: center[1], lon: center[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
+        // 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] - this.options.map_center_offset.left * resolution,
-                center[1] + this.options.map_center_offset.top * resolution,
-            ],
+            [center[0] - offset.left * resolution, center[1] + offset.top * resolution],
             projection,
         );
     }
@@ -1459,13 +2021,48 @@ export default class OpenLayers extends Map {
         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 !== undefined ? origin.lon : origin.lng, origin.lat],
+            [origin.lon, origin.lat],
             [destination.lon, destination.lat],
         ];
         const view_coords = this._markerCoordsToViewCoords(coords);
@@ -1549,28 +2146,34 @@ export default class OpenLayers extends Map {
                     center: center_view,
                     zoom: view_zoom,
                     duration: duration ?? this._transition_duration,
-                    easing: this.options.ease as ((t: number) => number) | undefined,
+                    easing: this._easing,
                 });
             }
-        } else if (this.options.map_type === "iiif" && this.options.map_as_image) {
-            const source = this._tile_layer?.getSource();
+        } else if (this.isImageSpace()) {
+            const source = this._sourceOf(this._tile_layer);
             if (!source) {
                 return;
             }
             const fit = () => {
                 try {
-                    const grid = source.getTileGrid();
+                    // 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._map.getSize();
-                        const resolution_x = (extent[2] - extent[0]) / (size[0] || 1);
-                        const resolution_y = (extent[3] - extent[1]) / (size[1] || 1);
+                        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);
+                        const zoom = view.getZoomForResolution(resolution) ?? 0;
                         const overview_center = this.options.map_overview_center;
                         const center_px = overview_center
                             ? this._toViewCoords({
@@ -1585,7 +2188,7 @@ export default class OpenLayers extends Map {
                             center: this._toViewCoords(offset_location),
                             zoom: zoom,
                             duration: duration ?? this._transition_duration,
-                            easing: this.options.ease as ((t: number) => number) | undefined,
+                            easing: this._easing,
                         });
                     }
                 } catch (e) {
@@ -1609,14 +2212,14 @@ export default class OpenLayers extends Map {
             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._map.getSize();
+                const size = this._viewportSize();
                 const resolution = Math.max(
-                    (extent[2] - extent[0]) / (size[0] || 1),
-                    (extent[3] - extent[1]) / (size[1] || 1),
+                    (extent[2] - extent[0]) / size[0],
+                    (extent[3] - extent[1]) / size[1],
                 );
                 const zoom = Math.max(
                     0,
-                    Math.round(this._map.getView().getZoomForResolution(resolution)) - 1,
+                    Math.round(this._map.getView().getZoomForResolution(resolution) ?? 0) - 1,
                 );
                 const offset_location = this._getMapCenterOffset(
                     { lat: overview_center.lat, lon: overview_center.lon },
@@ -1626,7 +2229,7 @@ export default class OpenLayers extends Map {
                     center: this._toViewCoords(offset_location),
                     zoom: zoom,
                     duration: duration ?? this._transition_duration,
-                    easing: this.options.ease as ((t: number) => number) | undefined,
+                    easing: this._easing,
                 });
             } else if (
                 this.options.map_center_offset &&
@@ -1636,13 +2239,13 @@ export default class OpenLayers extends Map {
                 if (this.bounds_array && this.bounds_array.length) {
                     const view_coords = this._markerCoordsToViewCoords(this.bounds_array);
                     const extent = boundingExtent(view_coords);
-                    const size = this._map.getSize();
-                    const resolution_x = (extent[2] - extent[0]) / (size[0] || 1);
-                    const resolution_y = (extent[3] - extent[1]) / (size[1] || 1);
+                    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)) - 1,
+                        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();
@@ -1652,7 +2255,7 @@ export default class OpenLayers extends Map {
                         center: this._toViewCoords(offset_location),
                         zoom: zoom,
                         duration: duration ?? this._transition_duration,
-                        easing: this.options.ease as ((t: number) => number) | undefined,
+                        easing: this._easing,
                     });
                 }
             } else {
@@ -1664,13 +2267,16 @@ export default class OpenLayers extends Map {
                 const view = this._map.getView();
                 const zoom = view.getZoom();
                 if (zoom !== undefined) {
-                    const center = this._fromViewCoords(view.getCenter(), view.getProjection());
+                    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.options.ease as ((t: number) => number) | undefined,
+                        easing: this._easing,
                     });
                 }
             }
@@ -1690,14 +2296,7 @@ export default class OpenLayers extends Map {
         if (!this._mini_map) return;
         const overview = this._mini_map.getOverviewMap();
         overview.getLayers().clear();
-        const consent = consentManagerOf(this.options);
-        const tile_service = consentMessage("consent_service_tiles", "map tiles");
-        const tiles_allowed = !(
-            this.options.consent_required &&
-            consent &&
-            !consent.isGranted(tile_service)
-        );
-        if (!tiles_allowed) {
+        if (!this._tilesAllowed()) {
             this._tile_layer_mini = null;
             return;
         }
@@ -1707,13 +2306,12 @@ export default class OpenLayers extends Map {
         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];
+            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.options.map_type === "iiif" && this.options.map_as_image) {
+        if (this.isImageSpace()) {
             this._fitMiniMapToImage();
         }
     }
@@ -1733,13 +2331,7 @@ export default class OpenLayers extends Map {
                     if (this._tile_layer) {
                         this._map.removeLayer(this._tile_layer);
                     }
-                    const consent = consentManagerOf(this.options);
-                    const tile_service = consentMessage("consent_service_tiles", "map tiles");
-                    if (!(
-                        this.options.consent_required &&
-                        consent &&
-                        !consent.isGranted(tile_service)
-                    )) {
+                    if (this._tilesAllowed()) {
                         this._tile_layer = this._createTileLayer(this.options.map_type);
                         this._tile_layer.setZIndex(0);
                         this._map.addLayer(this._tile_layer);
@@ -1774,19 +2366,36 @@ export default class OpenLayers extends Map {
                     break;
                 case "map_bbox": {
                     // recreate the view so the new extent constraint applies,
-                    // preserving center and zoom
+                    // 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: view.getProjection(),
+                            projection: is_image_map ? "EPSG:4326" : "EPSG:3857",
                             center: center,
                             zoom: zoom,
                             minZoom: view.getMinZoom(),
                             maxZoom: view.getMaxZoom(),
-                            ...(extent ? { extent: extent } : {}),
+                            ...(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;
@@ -1865,7 +2474,11 @@ export default class OpenLayers extends Map {
      * stale positions after a size change.
      */
     _setViewInstant(loc: StorymapSlideLocation, zoom: number): void {
-        let _location: LatLngLiteral = { lat: loc.lat, lon: loc.lon };
+        const start = this._latLngOf(loc);
+        if (!start) {
+            return;
+        }
+        let _location: LatLngLiteral = start;
         if (this.options.map_center_offset) {
             _location = this._getMapCenterOffset(_location, zoom);
         }