@projektemacher/storymapjs 0.10.7 → 0.11.0

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

@@ -1,10 +1,14 @@
 import OlMap from "ol/Map";
 import View from "ol/View";
+import { unByKey } from "ol/Observable";
 import type { Control } from "ol/control";
 import type { Interaction } from "ol/interaction";
-import { Tile as TileLayer, Vector as VectorLayer } from "ol/layer";
+import { Image as ImageLayer, 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 Static from "ol/source/ImageStatic";
+import type Source from "ol/source/Source";
 import VectorSource from "ol/source/Vector";
 import LineString from "ol/geom/LineString";
 import Feature from "ol/Feature";
@@ -25,9 +29,33 @@ import "ol/ol.css";
 import Map from "../Map";
 import OpenLayersMapMarker from "./MapMarker.OpenLayers";
 import { padCroppedZoomifyTile } from "./zoomifyTiles";
+import { prefersReducedMotion } from "../../core/Util";
 import type { LinePoint, ViewToOptions } from "../types";
-import type { LatLngLiteral, StorymapSlide, StorymapSlideLocation } from "../../types";
-import { consentManagerOf, consentMessage, type ConsentManager } from "../../storymap/Consent";
+import type {
+    LatLngLiteral,
+    StorymapImageOverlay,
+    StorymapOverlayLayer,
+    StorymapTilejson,
+    StorymapSlide,
+    StorymapSlideLocation,
+} from "../../types";
+import { fitGeoreference, resolveInfoJsonUrl } from "../georeference";
+import {
+    buildSlideFilter,
+    isStaticImageUrl,
+    normalizeMask,
+    serviceToInfoJson,
+    slideBasemapKey,
+    slideRotationRad,
+    type NormalizedMask,
+} from "../slideView";
+import {
+    consentManagerOf,
+    tileService,
+    type ConsentManager,
+    type ConsentService,
+} from "../../storymap/Consent";
+import { sanitizeSlideText } from "../../media/EmbedUtil";
 
 /*	Map.OpenLayers
 	Creates a Map using OpenLayers
@@ -35,6 +63,30 @@ import { consentManagerOf, consentMessage, type ConsentManager } from "../../sto
 
 const MAX_ZOOM = 19;
 
+/**
+ * Natural-size probe timeout for the static fallback: how long the viewer
+ * waits for the fallback image's dimensions before giving up and logging
+ * the IIIF error. A named constant (rather than an inline literal) so hosts
+ * and tests can find the single knob. There is no shared network-timeout
+ * option to reuse — `options.duration` is animation timing and the 1200ms
+ * media delay is a load deferral, not a watchdog.
+ */
+const STATIC_PROBE_TIMEOUT_MS = 15000;
+
+/** 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 +97,73 @@ 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>;
+    /** The `loadend` subscription key, stored so dispose() can detach it. */
+    declare "_loadend_key": Parameters<typeof unByKey>[0] | null;
+    /**
+     * Per-slide basemap layers by key (multi-manifest tours): built on first
+     * use through the tile layer factory, then reused. Empty until a slide
+     * names a `location.basemap`.
+     */
+    declare "_basemap_cache": globalThis.Map<string, Layer>;
+    /**
+     * The active per-slide basemap key, or null when the story basemap is
+     * showing. Restored to the story basemap on slides without one.
+     */
+    declare "_slide_basemap": string | null;
+    /** Spotlight mask element (slideshow passepartout), or null when off. */
+    declare "_mask_el": HTMLDivElement | null;
+    /** Per-slide image overlay layer (slideshow imgoverlay), or null. */
+    declare "_imgoverlay_layer": Layer | null;
+    /** Guards stale static-fallback probes (see `_probeStaticFallback`). */
+    declare "_static_probe_token": number;
+    /**
+     * Set by `dispose()` so in-flight fetches and probes resolve into
+     * no-ops instead of touching a torn-down map.
+     */
+    declare "_disposed": boolean;
+    /**
+     * Per-URL probe tokens for static slide basemaps: concurrent probes for
+     * different slides must not cancel each other (see
+     * `_createStaticImageBasemap`).
+     */
+    declare "_slide_probe_tokens": globalThis.Map<string, number>;
 
     /*	Create the Map
 	================================================== */
     _createMap(): void {
-        const is_image_map = this.options.map_type === "iiif" && this.options.map_as_image;
-
-        // Caller-supplied OpenLayers options: controls/interactions replace the
-        // defaults, view merges over the computed default, other options pass through
+        const is_image_map = this.isImageSpace();
+        this._imageready_fired = new WeakSet();
+        this._disposed = false;
+        this._basemap_cache = new globalThis.Map();
+        this._slide_basemap = null;
+        this._story_basemap_layer = null;
+        this._mask_el = null;
+        this._imgoverlay_layer = null;
+        this._static_probe_token = 0;
+        this._slide_probe_tokens = new globalThis.Map();
+
+        // 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 +177,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 +194,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
@@ -102,7 +222,7 @@ export default class OpenLayers extends Map {
             }),
         });
 
-        this._map.on("loadend", () => {
+        this._loadend_key = this._map.on("loadend", () => {
             this._onMapLoaded(undefined);
         });
 
@@ -119,11 +239,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 +251,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 +273,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 +296,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 +354,171 @@ 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));
+        }
+    }
+
+    /**
+     * Provider credit for a `map_type`, in both renderings: the linked HTML
+     * for our own `.vco-map-attribution` line and the plain text for the
+     * OpenLayers source `attributions`. One table — the two previous
+     * functions repeated the same `osm/stadia/mapbox/esri` switch and could
+     * drift apart, leaving a provider credited in one place but not the other
+     * (which their terms of service require).
+     */
+    _providerCredit(map_type: string): { html: string; text: string } {
+        // A full XYZ template naming a known provider
+        // (https://tile.openstreetmap.org/{z}/{x}/{y}.png) is not the `osm`
+        // map type, so match its host as well as the type prefix — otherwise
+        // both renderings fall through to the generic "Map data" line.
+        const byHost = this._hostCredit(map_type);
+        if (byHost) return byHost;
+        // 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.
+        const table: { test: (t: string) => boolean; html: string; text: string }[] = [
+            {
+                test: (t) => t === "" || t.startsWith("osm"),
+                html: "© <a target='_blank' href='https://www.openstreetmap.org/copyright'>OpenStreetMap</a> contributors",
+                text: "© OpenStreetMap contributors",
+            },
+            {
+                test: (t) => t.startsWith("stadia") || t === "stamen",
+                html:
+                    '© <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',
+                text: "© Stadia Maps, © OpenMapTiles © OpenStreetMap contributors",
+            },
+            {
+                test: (t) => t.startsWith("mapbox://"),
+                html: '© <a target="_blank" href="https://www.mapbox.com/about/maps/">Mapbox</a>',
+                text: "© Mapbox",
+            },
+            {
+                test: (t) => t.startsWith("ch-") || t.startsWith("esri"),
+                html: 'Map data © <a target="_blank" href="https://www.esri.com/">Esri</a>',
+                text: "Map data © Esri",
+            },
+            {
+                test: () => true,
+                html: "Map data",
+                text: "Map data",
+            },
+        ];
+        const entry = table.find((row) => row.test(map_type)) ?? table[table.length - 1];
+        return { html: entry.html, text: entry.text };
+    }
+
+    /**
+     * The table row for an absolute tile template's host, or null when the
+     * template is relative (a host serving its own tiles credits itself via
+     * `attribution`) or unknown. Subdomains match their parent, so
+     * `a.tile.openstreetmap.org` credits OSM.
+     */
+    _hostCredit(map_type: string): { html: string; text: string } | null {
+        let host: string | null = null;
+        try {
+            host = new URL(map_type).hostname;
+        } catch {
+            // Not absolute: only a protocol-relative template (`//host/...`)
+            // still names a host. A relative template resolves against the
+            // dummy base below and is rejected by the host check.
+            try {
+                const resolved = new URL(map_type, "https://storymap.invalid").hostname;
+                host = resolved === "storymap.invalid" ? null : resolved;
+            } catch {
+                host = null;
+            }
         }
+        if (!host) return null;
+        const rows: { hosts: string[]; html: string; text: string }[] = [
+            {
+                hosts: ["openstreetmap.org", "osm.org"],
+                html: "© <a target='_blank' href='https://www.openstreetmap.org/copyright'>OpenStreetMap</a> contributors",
+                text: "© OpenStreetMap contributors",
+            },
+            {
+                hosts: ["stadiamaps.com", "openmaptiles.org"],
+                html:
+                    '© <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',
+                text: "© Stadia Maps, © OpenMapTiles © OpenStreetMap contributors",
+            },
+            {
+                hosts: ["mapbox.com"],
+                html: '© <a target="_blank" href="https://www.mapbox.com/about/maps/">Mapbox</a>',
+                text: "© Mapbox",
+            },
+            {
+                hosts: ["arcgisonline.com", "esri.com"],
+                html: 'Map data © <a target="_blank" href="https://www.esri.com/">Esri</a>',
+                text: "Map data © Esri",
+            },
+            {
+                hosts: ["carto.com", "basemaps.cartocdn.com"],
+                html:
+                    "© <a target='_blank' href='https://www.openstreetmap.org/copyright'>OpenStreetMap</a> contributors © " +
+                    '<a target="_blank" href="https://carto.com/">CARTO</a>',
+                text: "© OpenStreetMap contributors © CARTO",
+            },
+        ];
+        const row = rows.find(({ hosts }) =>
+            hosts.some((h) => host === h || host.endsWith(`.${h}`)),
+        );
+        return row ? { html: row.html, text: row.text } : null;
     }
 
-    _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")) {
-            parts.push(
-                "© <a target='_blank' href='https://www.openstreetmap.org/copyright'>OpenStreetMap</a> contributors",
-            );
+        // 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.
+        parts.push(this._providerCredit(map_type).html);
+        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[] = [this._providerCredit(map_type).text];
         if (this.options.attribution) {
             parts.push(this.options.attribution);
         }
-        return parts.join(" | ");
+        return parts;
     }
 
     /*	Create Tile Layer
@@ -222,12 +534,16 @@ export default class OpenLayers extends Map {
         // to bury the route lines under fresh tiles
         this._tile_layer.setZIndex(0);
         this._map.addLayer(this._tile_layer);
+        // the story's own base layer: per-slide basemaps hand back to it
+        if (!this._story_basemap_layer) {
+            this._story_basemap_layer = this._tile_layer;
+        }
     }
 
     /**
      * 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 +556,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 +608,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 +705,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 +729,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 +739,38 @@ 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). */
+    /**
+     * The built overlay entries, parallel to `getOverlayLayers()`: malformed
+     * entries are skipped, so this is what a control must iterate to stay on
+     * the same index space as `setOverlayVisible()`.
+     */
+    getOverlayEntries(): StorymapOverlayLayer[] {
+        return [...this._overlay_entries];
+    }
+
+    /**
+     * 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 +778,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);
     }
@@ -379,6 +792,7 @@ export default class OpenLayers extends Map {
     _onTilesAllowed(): void {
         this._addTileLayer();
         this._buildOverlays();
+        this.fire("tilesallowed");
         if (!this._tile_layer_mini) {
             this._tile_layer_mini = this._createTileLayer(this.options.map_type);
         }
@@ -392,8 +806,14 @@ 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);
+                }
+                // consent arrived after markers: the current slide may name
+                // a per-slide basemap
+                this._switchSlideBasemap(marker.data.location ?? null);
             }
         }
     }
@@ -477,7 +897,373 @@ export default class OpenLayers extends Map {
         return { zoom, center };
     }
 
-    _createTileLayer(map_type: string): TileLayer {
+    /**
+     * Paint the story's static image when its IIIF `info.json` cannot be
+     * used (unreachable, or missing dimensions): a single-resolution
+     * `ImageStatic` layer replaces the empty tile layer, so the tour still
+     * shows its picture instead of a blank basemap. Needs
+     * `iiif.fallbackUrl` (the full-size image) plus `iiif.width`/`height`
+     * (canvas size); without dimensions the natural size is probed, but
+     * only for slideshow tours — internal documents keep the existing
+     * error path. Returns false when nothing was (or will be) painted.
+     */
+    _useStaticFallback(empty_layer: TileLayer): boolean {
+        const width = this.options.iiif.width;
+        const height = this.options.iiif.height;
+        const url = this.options.iiif.fallbackUrl;
+        if (typeof url !== "string" || url === "") {
+            return false;
+        }
+        if (typeof width === "number" && width > 0 && typeof height === "number" && height > 0) {
+            this._buildStaticLayer(empty_layer, url, width, height);
+            return true;
+        }
+        if (this.options.slideshow_source !== true) {
+            return false;
+        }
+        void this._probeStaticFallback(empty_layer, url);
+        return true;
+    }
+
+    /**
+     * Resolve a fallback image's natural size, then paint it. Stale probes
+     * (a newer probe started, e.g. after a basemap switch) and unusable
+     * dimensions fall back to the logged IIIF error.
+     */
+    async _probeStaticFallback(empty_layer: TileLayer, url: string): Promise<void> {
+        const token = ++this._static_probe_token;
+        try {
+            const dims = await this._probeStaticImage(url);
+            if (this._disposed || token !== this._static_probe_token) return;
+            if (!dims || !(dims.width > 0) || !(dims.height > 0)) {
+                console.error("Static fallback image has no usable dimensions:", url);
+                return;
+            }
+            this._buildStaticLayer(empty_layer, url, dims.width, dims.height);
+        } catch (err) {
+            if (this._disposed || token !== this._static_probe_token) return;
+            console.error(
+                "Static fallback image could not be probed:",
+                url,
+                (err as Error)?.stack || err,
+            );
+        }
+    }
+
+    /**
+     * The natural size of an image URL. Separated for testability: unit
+     * tests stub the `Image` constructor rather than the network.
+     */
+    _probeStaticImage(url: string): Promise<{ width: number; height: number }> {
+        return new Promise((resolve, reject) => {
+            const img = new Image();
+            const timer = setTimeout(() => {
+                reject(new Error(`timed out after ${STATIC_PROBE_TIMEOUT_MS}ms`));
+            }, STATIC_PROBE_TIMEOUT_MS);
+            img.onload = () => {
+                clearTimeout(timer);
+                resolve({ width: img.naturalWidth, height: img.naturalHeight });
+            };
+            img.onerror = () => {
+                clearTimeout(timer);
+                reject(new Error("load error"));
+            };
+            img.crossOrigin = "anonymous";
+            img.src = url;
+        });
+    }
+
+    /**
+     * One static image source: shared by the story fallback (known extent),
+     * per-slide static basemaps (probed extent) and per-slide overlays
+     * (view extent). Layer assembly stays per call site — base (z 0),
+     * pending-fill and overlay (z 5, opacity) have different lifecycles.
+     */
+    _newStaticSource(
+        url: string,
+        extent: Extent,
+        projection: string | Projection,
+        attributions?: string | string[],
+    ): Static {
+        return new Static({
+            url,
+            imageExtent: extent,
+            projection,
+            crossOrigin: "anonymous",
+            ...(attributions !== undefined ? { attributions } : {}),
+        });
+    }
+
+    /**
+     * One static image layer: the constructor shared by the story fallback,
+     * per-slide static basemaps and per-slide overlays. Extent and
+     * projection are the caller's policy (canvas size, probed size, or view
+     * extent); presentation rides the options.
+     */
+    _newStaticLayer(
+        url: string,
+        extent: Extent,
+        projection: string | Projection,
+        presentation: { opacity?: number; attributions?: string | string[]; zIndex?: number } = {},
+    ): ImageLayer<Static> {
+        const layer = new ImageLayer({
+            source: this._newStaticSource(url, extent, projection, presentation.attributions),
+            ...(presentation.opacity !== undefined ? { opacity: presentation.opacity } : {}),
+        });
+        layer.setZIndex(presentation.zIndex ?? 0);
+        return layer;
+    }
+
+    /** Swap the empty tile layer for a static image of the given extent. */
+    _buildStaticLayer(empty_layer: TileLayer, url: string, width: number, height: number): void {
+        if (this._disposed) return;
+        const layer = this._newStaticLayer(url, [0, 0, width, height], "EPSG:4326", {
+            attributions: this.options.iiif.attribution || [],
+        });
+        if (this._tile_layer === (empty_layer as unknown as Layer)) {
+            this._map.removeLayer(empty_layer);
+            this._tile_layer = layer;
+            this._map.addLayer(layer);
+        } else {
+            // superseded while resolving (basemap switch, dispose): announce
+            // nothing and fit nothing for a layer that never shows
+            return;
+        }
+        const source = this._sourceOf(layer);
+        if (!source) return;
+        this._fireImageready(source, "iiif", layer);
+        if (typeof source.getState === "function" && source.getState() === "ready") {
+            this._markerOverview();
+        } else if (typeof (source as { once?: unknown }).once === "function") {
+            (source as unknown as { once(e: string, fn: () => void): void }).once("change", () => {
+                if (source.getState() === "ready") {
+                    this._markerOverview();
+                }
+            });
+        } else {
+            this._markerOverview();
+        }
+    }
+
+    _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 {
+        this._disposed = true;
+        // invalidate in-flight static probes and info.json fetches: their
+        // continuations check the flag or their token and resolve quietly
+        this._static_probe_token++;
+        if (this._line_animation !== null) {
+            cancelAnimationFrame(this._line_animation);
+            this._line_animation = null;
+        }
+        if (this._loadend_key) {
+            unByKey(this._loadend_key);
+            this._loadend_key = null;
+        }
+        if (this._onWheelBound) {
+            this._el.map?.removeEventListener("wheel", this._onWheelBound);
+            this._onWheelBound = null;
+        }
+        // markers own their click listener and an overlay; disposing the
+        // collection releases both
+        for (const marker of this._markers) {
+            marker.dispose?.();
+        }
+        this._markers = [];
+        this._mask_el?.remove();
+        this._mask_el = null;
+        this._basemap_cache.clear();
+        this._slide_probe_tokens.clear();
+        this._slide_basemap = null;
+        this._story_basemap_layer = null;
+        this._imgoverlay_layer = null;
+        // 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 +1280,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 +1288,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 +1308,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,12 +1319,23 @@ 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),
                     }),
                 });
 
             case "iiif": {
                 const iiif_layer: TileLayer = new TileLayer();
+                // a static-image tour states no info.json at all: skip the
+                // fetch and go straight to the fallback (which probes when
+                // no dimensions are stated either)
+                if (typeof this.options.iiif.url !== "string" || this.options.iiif.url === "") {
+                    if (!this._useStaticFallback(iiif_layer)) {
+                        console.error(
+                            "IIIF info.json URL is missing and no static fallback is stated.",
+                        );
+                    }
+                    return iiif_layer;
+                }
                 fetch(this.options.iiif.url)
                     .then((r) => r.json())
                     .then((info: unknown) => {
@@ -546,10 +1350,15 @@ export default class OpenLayers extends Map {
                             typeof fallback.width !== "number" ||
                             typeof fallback.height !== "number"
                         ) {
-                            console.error(
-                                "IIIF info.json is missing width/height:",
-                                this.options.iiif.url,
-                            );
+                            // without dimensions there is no grid to build;
+                            // fall back to the static image when the story
+                            // states dimensions of its own
+                            if (!this._useStaticFallback(iiif_layer)) {
+                                console.error(
+                                    "IIIF info.json is missing width/height:",
+                                    this.options.iiif.url,
+                                );
+                            }
                             return;
                         }
                         const source = new IIIF({
@@ -560,6 +1369,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 {
@@ -571,11 +1381,18 @@ export default class OpenLayers extends Map {
                         }
                     })
                     .catch((err) =>
-                        console.error(
-                            "IIIF info.json could not be loaded:",
-                            this.options.iiif.url,
-                            err?.stack || err,
-                        ),
+                        // the tile pyramid is unreachable: paint the static
+                        // image instead when the story states one, so the
+                        // tour still shows its picture
+                        {
+                            if (!this._useStaticFallback(iiif_layer)) {
+                                console.error(
+                                    "IIIF info.json could not be loaded:",
+                                    this.options.iiif.url,
+                                    err?.stack || err,
+                                );
+                            }
+                        },
                     );
                 return iiif_layer;
             }
@@ -587,15 +1404,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 +1426,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 +1488,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 +1501,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 +1537,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 +1642,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 +1654,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 +1673,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 +1691,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 +1712,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();
@@ -904,6 +1730,10 @@ export default class OpenLayers extends Map {
     _createMarker(d: StorymapSlide): void {
         const marker = new OpenLayersMapMarker(d, this.options);
         marker.on("markerclick", this._onMarkerClick, this);
+        // Forward popup cards to the map surface (fresh payloads, so the
+        // marker stays the event target of the original, not the re-fire).
+        marker.on("popupopen", this._onMarkerPopupOpen, this);
+        marker.on("popupclose", this._onMarkerPopupClose, this);
         this._addMarker(marker);
         this._markers.push(marker);
         marker.marker_number = this._markers.length - 1;
@@ -923,12 +1753,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 +1775,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 +1818,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 +1835,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);
@@ -1027,7 +1868,7 @@ export default class OpenLayers extends Map {
             panel_rect.bottom > map_rect.top;
         if (!overlaps) return padding;
         const layout = this.options.layout;
-        if (layout === "portrait") {
+        if (layout === "portrait" || this.options.textmode === "bottom") {
             padding[2] += Math.max(0, map_rect.bottom - panel_rect.top);
         } else {
             padding[1] += Math.max(0, panel_rect.right - map_rect.left);
@@ -1061,53 +1902,61 @@ export default class OpenLayers extends Map {
             size: ol_map.getSize(),
             padding: this._opaquePanelPadding(),
             maxZoom: 12,
-            duration: duration,
-            easing: this.options.ease as ((t: number) => number) | undefined,
+            duration: prefersReducedMotion() ? 0 : duration,
+            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 +1998,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 +2054,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();
@@ -1206,7 +2065,8 @@ export default class OpenLayers extends Map {
 
         this._cancelLineAnimation();
 
-        const duration = animate?.duration ?? 0;
+        // Reduced motion draws the full path at once instead of tracing it.
+        const duration = prefersReducedMotion() ? 0 : (animate?.duration ?? 0);
         if (duration <= 0 || view_coords.length < 2) {
             setGeometry(view_coords);
             return;
@@ -1267,7 +2127,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
@@ -1352,24 +2212,52 @@ export default class OpenLayers extends Map {
     _panTo(loc: LatLngLiteral, animate?: boolean): void {
         this._map.getView().animate({
             center: this._toViewCoords(loc),
-            duration: this.options.duration,
-            easing: this.options.ease as ((t: number) => number) | undefined,
+            duration: prefersReducedMotion() ? 0 : this.options.duration,
+            easing: this._easing,
         });
     }
 
     _zoomTo(z: number, animate?: boolean): void {
         this._map.getView().animate({
             zoom: z,
-            duration: this.options.duration,
-            easing: this.options.ease as ((t: number) => number) | undefined,
+            duration: prefersReducedMotion() ? 0 : this.options.duration,
+            easing: this._easing,
         });
     }
 
     _viewTo(loc: StorymapSlideLocation, opts?: ViewToOptions): void {
+        // Per-slide presentation first: basemap swap, filter grading and
+        // spotlight mask are synchronous state, independent of movement.
+        // Rotation joins the movement animation below (or _fitRegion's).
+        // Slideshow tours only: internal documents move exactly as before.
+        const feat = this.options.slideshow_source === true ? loc : undefined;
+        this._switchSlideBasemap(feat);
+        this._applySlideFilterAndMask(feat);
+        // Image region stops (slideshow-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, feat);
+            return;
+        }
+
+        const start = this._latLngOf(loc);
+        if (!start) {
+            // location-less slide (region-only on a geo map): nothing to
+            // fly to, but an explicit rotation still applies
+            this._applySlideRotation(feat, opts?.duration, opts?.duration === 0);
+            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) {
@@ -1400,15 +2288,25 @@ export default class OpenLayers extends Map {
             _location = this._getMapCenterOffset(_location, _zoom);
         }
 
+        // A slide rotation joins the glide; the animation arg is only added
+        // when the slide or the view is rotated, so unrotated stories
+        // animate exactly as before.
+        const _rotation = slideRotationRad(feat);
+        const _current_rotation = this._map.getView().getRotation();
         this._map.getView().animate({
             center: this._toViewCoords(_location),
             zoom: _zoom,
-            duration: _animate ? _duration : 0,
-            easing: this.options.ease as ((t: number) => number) | undefined,
+            ...(_rotation !== null || _current_rotation !== 0 ? { rotation: _rotation ?? 0 } : {}),
+            duration: _animate && !prefersReducedMotion() ? _duration : 0,
+            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,37 +2314,370 @@ 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`. A slide
+     * rotation follows the fit (fit() takes no rotation), plus the
+     * filter/mask tail when the location is passed.
+     */
+    _fitRegion(
+        region: [number, number, number, number],
+        opts?: ViewToOptions,
+        loc?: StorymapSlideLocation,
+    ): 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 && !prefersReducedMotion() ? _duration : 0,
+            easing: this._easing,
+        });
+        if (loc) {
+            this._applySlideRotation(loc, _duration, !_animate);
+            this._applySlideFilterAndMask(loc);
+        }
+        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]);
     }
 
+    /*	Per-slide view presentation (slideshow rotation/filter/mask/basemap)
+	================================================== */
+    /**
+     * Swap the base layer for a slide `location.basemap` (multi-manifest
+     * tours): built on first use through the tile layer factory (custom
+     * factories apply), then cached. A slide without one restores the story
+     * basemap. No-op when the requested key is already showing, so resize
+     * and re-fit paths pass through untouched. Consent-denied tiles skip
+     * the switch entirely.
+     */
+    _switchSlideBasemap(loc: StorymapSlideLocation | null | undefined): void {
+        // slideshow tours only: internal documents keep the story basemap
+        if (this.options.slideshow_source !== true) return;
+        if (!this._tilesAllowed()) return;
+        const key = slideBasemapKey(loc);
+        if (key === this._slide_basemap) return;
+        if (this._tile_layer) {
+            this._map.removeLayer(this._tile_layer);
+        }
+        if (key === null) {
+            this._tile_layer =
+                this._story_basemap_layer ?? this._createTileLayer(this.options.map_type);
+            this._story_basemap_layer = this._tile_layer;
+        } else {
+            let layer = this._basemap_cache.get(key);
+            if (!layer) {
+                layer = this._createSlideBasemap(key);
+                layer.setZIndex(0);
+                this._basemap_cache.set(key, layer);
+            }
+            this._tile_layer = layer;
+        }
+        this._tile_layer.setZIndex(0);
+        this._map.addLayer(this._tile_layer);
+        this._slide_basemap = key;
+        this._updateAttribution();
+    }
+
+    /**
+     * Build a per-slide basemap layer: IIIF `info.json` URLs (or bare
+     * service bases) become tile layers; plain image URLs become static
+     * image layers (dimensions probed); anything else goes through the
+     * regular tile layer factory, so keywords and templates keep working.
+     */
+    _createSlideBasemap(key: string): Layer {
+        // plain image files (absolute or same-origin relative) skip the
+        // doomed info.json fetch; services and keywords flow on
+        if (isStaticImageUrl(key)) {
+            return this._createStaticImageBasemap(key);
+        }
+        if (/^https?:\/\//i.test(key) && !key.includes("{z}")) {
+            const info_url = serviceToInfoJson(key);
+            const pending: TileLayer = new TileLayer();
+            fetch(info_url)
+                .then((r) => r.json())
+                .then((info: unknown) => {
+                    if (this._disposed) return;
+                    const parsed = new IIIFInfo(
+                        info as ImageInformationResponse,
+                    ).getTileSourceOptions();
+                    const dims = info as { width?: number; height?: number };
+                    if (typeof dims.width !== "number" || typeof dims.height !== "number") {
+                        this._replaceWithStaticBasemap(key, pending);
+                        return;
+                    }
+                    const source = new IIIF({
+                        ...(parsed ?? {}),
+                        projection: "EPSG:4326",
+                        size: [dims.width, dims.height],
+                        crossOrigin: "anonymous",
+                    });
+                    pending.setSource(source);
+                    this._fireImageready(source, "iiif", pending);
+                })
+                .catch(() => {
+                    // not an image service after all (a plain file, e.g. a
+                    // `.jpx` that serves no info.json): probe it as one
+                    this._replaceWithStaticBasemap(key, pending);
+                });
+            return pending;
+        }
+        return this._createTileLayer(key);
+    }
+
+    /**
+     * A basemap from a plain image URL (no IIIF service): an `ImageLayer`
+     * filled in once the natural size probes. Used for per-slide basemaps
+     * pointing at static files, and as the fallback when an `info.json`
+     * turns out unreachable (some `.jpx`/`.jp2` bases serve one, some are
+     * plain files — only the fetch tells). Unusable dimensions keep the
+     * error logged and the layer empty, like the failed-service path.
+     */
+    _createStaticImageBasemap(url: string): Layer {
+        const pending = new ImageLayer();
+        pending.setZIndex(0);
+        const token = (this._slide_probe_tokens.get(url) ?? 0) + 1;
+        this._slide_probe_tokens.set(url, token);
+        void this._probeStaticImage(url).then(
+            (dims) => {
+                if (this._disposed || this._slide_probe_tokens.get(url) !== token) return;
+                if (!dims || !(dims.width > 0) || !(dims.height > 0)) {
+                    console.error("Slide basemap image has no usable dimensions:", url);
+                    return;
+                }
+                pending.setSource(
+                    this._newStaticSource(url, [0, 0, dims.width, dims.height], "EPSG:4326"),
+                );
+                this._fireImageready(
+                    pending.getSource() as { getState?(): string },
+                    "iiif",
+                    pending,
+                );
+            },
+            (err) =>
+                console.error(
+                    "Slide basemap image could not be probed:",
+                    url,
+                    (err as Error)?.stack || err,
+                ),
+        );
+        return pending;
+    }
+
+    /**
+     * Replace a failed IIIF slide basemap with a probed static image under
+     * the same cache key, swapping it into the map when still current (the
+     * visitor may have moved on while the fetch was in flight, in which
+     * case the cache holds it for a return visit).
+     */
+    _replaceWithStaticBasemap(key: string, pending: TileLayer): void {
+        if (this._disposed) return;
+        const staticLayer = this._createStaticImageBasemap(key);
+        this._basemap_cache.set(key, staticLayer);
+        if (this._tile_layer === (pending as unknown as Layer)) {
+            this._map.removeLayer(pending);
+            this._tile_layer = staticLayer;
+            this._map.addLayer(staticLayer);
+        }
+    }
+
+    /**
+     * The story's own base layer (as opposed to a per-slide one): stashed
+     * on creation so a slide basemap can hand back to it without refetching.
+     */
+    declare "_story_basemap_layer": Layer | null;
+
+    /**
+     * Apply a slide's CSS filter grading to the map viewport
+     * (slideshow `filters`). Always assigned — "" clears — so grading never
+     * leaks onto the next slide.
+     */
+    _applySlideFilter(loc: StorymapSlideLocation | null | undefined): void {
+        this._map.getViewport().style.filter = buildSlideFilter(loc?.filter);
+    }
+
+    /**
+     * Apply a slide's spotlight mask (slideshow `passepartout`): normalized
+     * viewport fractions stay visible while the rest is dimmed. Rendered as
+     * up to four percentage-positioned divs (or one for `invert`), so it
+     * needs no updates on pan/zoom/resize. `pointer-events: none` keeps
+     * markers clickable through the shade; the marker overlay container
+     * (z-index 1) paints above it. Absent/invalid clears the mask.
+     */
+    _applySlideMask(loc: StorymapSlideLocation | null | undefined): void {
+        const mask: NormalizedMask | null = normalizeMask(loc?.mask);
+        if (!mask) {
+            this._mask_el?.remove();
+            this._mask_el = null;
+            return;
+        }
+        const viewport = this._map.getViewport();
+        if (!this._mask_el) {
+            const el = document.createElement("div");
+            el.className = "vco-map-mask";
+            el.setAttribute("aria-hidden", "true");
+            el.style.position = "absolute";
+            el.style.inset = "0";
+            el.style.zIndex = "0";
+            el.style.pointerEvents = "none";
+            el.style.overflow = "hidden";
+            viewport.appendChild(el);
+            this._mask_el = el;
+        }
+        const pct = (n: number) => `${n * 100}%`;
+        const shade = (left: string, top: string, width: string, height: string) =>
+            `<div style="position:absolute;left:${left};top:${top};width:${width};height:${height};background:${mask.color};opacity:${mask.opacity}"></div>`;
+        this._mask_el.innerHTML = mask.invert
+            ? shade(pct(mask.x), pct(mask.y), pct(mask.w), pct(mask.h))
+            : shade("0", "0", "100%", pct(mask.y)) +
+              shade("0", pct(mask.y + mask.h), "100%", pct(1 - mask.y - mask.h)) +
+              shade("0", pct(mask.y), pct(mask.x), pct(mask.h)) +
+              shade(pct(mask.x + mask.w), pct(mask.y), pct(1 - mask.x - mask.w), pct(mask.h));
+    }
+
+    /** Filter + mask together: the synchronous tail of every navigation. */
+    _applySlideFilterAndMask(loc: StorymapSlideLocation | null | undefined): void {
+        this._applySlideFilter(loc);
+        this._applySlideMask(loc);
+    }
+
+    /**
+     * Rotate the view to a slide `rotation` (degrees clockwise). Merges into
+     * the caller's animation when one is running; on its own (region fits,
+     * location-less slides, overview reset) it animates alone, or sets
+     * synchronously when the navigation is instant. A no-op when neither
+     * the slide nor the view is rotated, so unrotated stories animate
+     * exactly as before.
+     */
+    _applySlideRotation(
+        loc: StorymapSlideLocation | null | undefined,
+        duration?: number,
+        instant = false,
+    ): void {
+        const rotation = slideRotationRad(loc);
+        const view = this._map.getView();
+        if (rotation === null && view.getRotation() === 0) return;
+        const target = rotation ?? 0;
+        if (instant || prefersReducedMotion()) {
+            view.setRotation(target);
+            return;
+        }
+        view.animate({
+            rotation: target,
+            duration: duration ?? this.options.duration,
+            easing: this._easing,
+        });
+    }
+
+    /**
+     * Show a per-slide image overlay (slideshow `imgoverlay`) while its
+     * slide is active. `extent` pins it (`[west, south, east, north]` lon/lat,
+     * raw image pixels on image-space maps); otherwise it covers the current
+     * view, optionally scaled to `size` (fraction of the viewport). Painted
+     * above the base (z 5) below the route lines. Null/empty clears.
+     * Consent-denied tiles skip it like every other layer.
+     */
+    setSlideImageOverlay(overlay: StorymapImageOverlay | null | undefined): void {
+        if (this._imgoverlay_layer) {
+            this._map.removeLayer(this._imgoverlay_layer);
+            this._imgoverlay_layer = null;
+        }
+        if (!overlay || typeof overlay.url !== "string" || overlay.url === "") return;
+        if (!this._tilesAllowed()) return;
+        // slideshow tours only: internal documents never paint overlays
+        if (this.options.slideshow_source !== true) return;
+        const given = overlay.extent;
+        let extent: Extent;
+        if (
+            Array.isArray(given) &&
+            given.length === 4 &&
+            given.every((n) => typeof n === "number" && Number.isFinite(n))
+        ) {
+            const raw = (
+                this.isImageSpace()
+                    ? [given[0], given[1], given[2], given[3]]
+                    : [...fromLonLat([given[0], given[1]]), ...fromLonLat([given[2], given[3]])]
+            ) as Extent;
+            // lon/lat corners can arrive swapped; the view fit needs min/max
+            extent = [
+                Math.min(raw[0], raw[2]),
+                Math.min(raw[1], raw[3]),
+                Math.max(raw[0], raw[2]),
+                Math.max(raw[1], raw[3]),
+            ];
+        } else {
+            extent = this._map.getView().calculateExtent(this._viewportSize());
+            if (typeof overlay.size === "number" && Number.isFinite(overlay.size)) {
+                const scale = Math.min(1, Math.max(0.05, overlay.size));
+                const cx = (extent[0] + extent[2]) / 2;
+                const cy = (extent[1] + extent[3]) / 2;
+                const hw = ((extent[2] - extent[0]) * scale) / 2;
+                const hh = ((extent[3] - extent[1]) * scale) / 2;
+                extent = [cx - hw, cy - hh, cx + hw, cy + hh];
+            }
+        }
+        const opacity =
+            typeof overlay.opacity === "number" && Number.isFinite(overlay.opacity)
+                ? Math.min(1, Math.max(0, overlay.opacity))
+                : 1;
+        const layer = this._newStaticLayer(
+            overlay.url,
+            extent,
+            this._map.getView().getProjection(),
+            { opacity, zIndex: 5 },
+        );
+        this._map.addLayer(layer);
+        this._imgoverlay_layer = layer;
+    }
+
     _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;
     }
 
-    _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 +2690,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);
@@ -1518,6 +2784,25 @@ export default class OpenLayers extends Map {
         this._cancelLineAnimation();
         this._line_active.setVisible(false);
 
+        // The overview shows the whole story: per-slide grading, mask and
+        // rotation do not apply. Each reset is guarded so the common path
+        // (nothing set) touches nothing.
+        if (this._map.getView().getRotation() !== 0) {
+            this._map.getView().animate({
+                rotation: 0,
+                duration: prefersReducedMotion() ? 0 : (duration ?? this._transition_duration),
+                easing: this._easing,
+            });
+        }
+        if (this._map.getViewport().style.filter !== "") {
+            this._map.getViewport().style.filter = "";
+        }
+        if (this._mask_el) {
+            this._mask_el.remove();
+            this._mask_el = null;
+        }
+        this._switchSlideBasemap(null);
+
         // repeated presses while an overview animation is running snap
         // instantly instead of restarting the ~1s animation
         if (duration && this._map.getView().getAnimating()) {
@@ -1548,29 +2833,51 @@ export default class OpenLayers extends Map {
                 this._map.getView().animate({
                     center: center_view,
                     zoom: view_zoom,
-                    duration: duration ?? this._transition_duration,
-                    easing: this.options.ease as ((t: number) => number) | undefined,
+                    duration: prefersReducedMotion() ? 0 : (duration ?? this._transition_duration),
+                    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();
+                    // static fallback (no tile grid): fit the single image
+                    // extent directly so the overview still frames the picture
+                    const static_extent = (
+                        source as { getImageExtent?: () => Extent | null }
+                    ).getImageExtent?.();
+                    if (static_extent) {
+                        this._map.getView().fit(static_extent, {
+                            size: this._viewportSize(),
+                            padding: this._opaquePanelPadding(),
+                            duration: prefersReducedMotion()
+                                ? 0
+                                : (duration ?? this._transition_duration),
+                            easing: this._easing,
+                        });
+                        return;
+                    }
+                    // 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({
@@ -1584,8 +2891,10 @@ export default class OpenLayers extends Map {
                         view.animate({
                             center: this._toViewCoords(offset_location),
                             zoom: zoom,
-                            duration: duration ?? this._transition_duration,
-                            easing: this.options.ease as ((t: number) => number) | undefined,
+                            duration: prefersReducedMotion()
+                                ? 0
+                                : (duration ?? this._transition_duration),
+                            easing: this._easing,
                         });
                     }
                 } catch (e) {
@@ -1609,14 +2918,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 },
@@ -1625,8 +2934,8 @@ export default class OpenLayers extends Map {
                 this._map.getView().animate({
                     center: this._toViewCoords(offset_location),
                     zoom: zoom,
-                    duration: duration ?? this._transition_duration,
-                    easing: this.options.ease as ((t: number) => number) | undefined,
+                    duration: prefersReducedMotion() ? 0 : (duration ?? this._transition_duration),
+                    easing: this._easing,
                 });
             } else if (
                 this.options.map_center_offset &&
@@ -1636,13 +2945,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();
@@ -1651,8 +2960,10 @@ export default class OpenLayers extends Map {
                     this._map.getView().animate({
                         center: this._toViewCoords(offset_location),
                         zoom: zoom,
-                        duration: duration ?? this._transition_duration,
-                        easing: this.options.ease as ((t: number) => number) | undefined,
+                        duration: prefersReducedMotion()
+                            ? 0
+                            : (duration ?? this._transition_duration),
+                        easing: this._easing,
                     });
                 }
             } else {
@@ -1664,13 +2975,18 @@ 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,
+                        duration: prefersReducedMotion()
+                            ? 0
+                            : (duration ?? this._transition_duration),
+                        easing: this._easing,
                     });
                 }
             }
@@ -1690,14 +3006,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 +3016,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,17 +3041,16 @@ 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);
                     }
+                    // the story basemap changed: per-slide layers stay cached
+                    // (their keys are unchanged) but the active one is rebuilt
+                    // by the re-fit below through _switchSlideBasemap
+                    this._story_basemap_layer = this._tile_layer ?? null;
+                    this._slide_basemap = null;
                     this._refreshMiniMapLayer();
                     this._updateAttribution();
                     this._el.map.style.backgroundColor = this.options.map_background_color;
@@ -1774,19 +3081,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,13 +3189,27 @@ 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);
         }
         const view = this._map.getView();
         view.setZoom(zoom);
         view.setCenter(this._toViewCoords(_location));
+        // instant path (resize): rotation sets synchronously, filter and
+        // mask re-apply idempotently — slideshow tours only, so the resize
+        // path for internal documents touches nothing new
+        if (this.options.slideshow_source === true) {
+            const rotation = slideRotationRad(loc);
+            if (rotation !== null || view.getRotation() !== 0) {
+                view.setRotation(rotation ?? 0);
+            }
+            this._applySlideFilterAndMask(loc);
+        }
         this._map.renderSync();
     }
 }