@projektemacher/storymapjs 0.10.8 → 0.11.0

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

@@ -1,11 +1,13 @@
 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";
@@ -27,15 +29,26 @@ 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,
+    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,
@@ -50,6 +63,16 @@ import { sanitizeSlideText } from "../../media/EmbedUtil";
 
 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";
 
@@ -92,12 +115,50 @@ export default class OpenLayers extends Map {
     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.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
@@ -161,7 +222,7 @@ export default class OpenLayers extends Map {
             }),
         });
 
-        this._map.on("loadend", () => {
+        this._loadend_key = this._map.on("loadend", () => {
             this._onMapLoaded(undefined);
         });
 
@@ -315,6 +376,120 @@ export default class OpenLayers extends Map {
         }
     }
 
+    /**
+     * 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[] {
         const parts = [
             "<a href='https://storymap.knightlab.com/' target='_blank' class='vco-knightlab-brand'><span>&#x25a0;</span> StoryMapJS</a>",
@@ -324,29 +499,7 @@ export default class OpenLayers extends Map {
         // what the visitor sees. Sources additionally carry the plain-text
         // credit from `_sourceAttributions`, so `source.getAttributions()`
         // and a consumer's own Attribution control are not left empty.
-        // Emitting provider credit
-        // only for OSM left Stadia, Mapbox and the OL XYZ template providers
-        // uncredited, which their terms of service require. The credit is
-        // keyed off the resolved map_type, so a custom `{z}` template gets
-        // the generic "map data" line and the author can still override it
-        // with the `attribution` option.
-        if (map_type === "" || map_type.startsWith("osm")) {
-            parts.push(
-                "© <a target='_blank' href='https://www.openstreetmap.org/copyright'>OpenStreetMap</a> contributors",
-            );
-        } else if (map_type.startsWith("stadia") || map_type === "stamen") {
-            parts.push(
-                '© <a target="_blank" rel="noopener noreferrer" href="https://stadiamaps.com/">Stadia Maps</a>, ' +
-                    '© <a target="_blank" rel="noopener noreferrer" href="https://openmaptiles.org/">OpenMapTiles</a> ' +
-                    '© <a target="_blank" rel="noopener noreferrer" href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors',
-            );
-        } else if (map_type.startsWith("mapbox://")) {
-            parts.push('© <a target="_blank" href="https://www.mapbox.com/about/maps/">Mapbox</a>');
-        } else if (map_type.startsWith("ch-") || map_type.startsWith("esri")) {
-            parts.push('Map data © <a target="_blank" href="https://www.esri.com/">Esri</a>');
-        } else {
-            parts.push("Map data");
-        }
+        parts.push(this._providerCredit(map_type).html);
         if (this.options.attribution) {
             parts.push(this.options.attribution);
         }
@@ -361,18 +514,7 @@ export default class OpenLayers extends Map {
      * `ol/control/Attribution`) work instead of returning nothing.
      */
     _sourceAttributions(map_type: string): string[] {
-        const parts: string[] = [];
-        if (map_type === "" || map_type.startsWith("osm")) {
-            parts.push("© OpenStreetMap contributors");
-        } else if (map_type.startsWith("stadia") || map_type === "stamen") {
-            parts.push("© Stadia Maps, © OpenMapTiles © OpenStreetMap contributors");
-        } else if (map_type.startsWith("mapbox://")) {
-            parts.push("© Mapbox");
-        } else if (map_type.startsWith("ch-") || map_type.startsWith("esri")) {
-            parts.push("Map data © Esri");
-        } else {
-            parts.push("Map data");
-        }
+        const parts: string[] = [this._providerCredit(map_type).text];
         if (this.options.attribution) {
             parts.push(this.options.attribution);
         }
@@ -392,6 +534,10 @@ 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;
+        }
     }
 
     /**
@@ -601,6 +747,15 @@ export default class OpenLayers extends Map {
         return this._overlay_layers.length;
     }
 
+    /**
+     * 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.
@@ -637,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);
         }
@@ -655,6 +811,9 @@ export default class OpenLayers extends Map {
                 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);
             }
         }
     }
@@ -738,6 +897,154 @@ export default class OpenLayers extends Map {
         return { zoom, center };
     }
 
+    /**
+     * 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
@@ -828,16 +1135,35 @@ export default class OpenLayers extends Map {
      * 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);
@@ -999,6 +1325,17 @@ export default class OpenLayers extends Map {
 
             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) => {
@@ -1013,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({
@@ -1039,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;
             }
@@ -1381,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;
@@ -1515,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);
@@ -1549,7 +1902,7 @@ export default class OpenLayers extends Map {
             size: ol_map.getSize(),
             padding: this._opaquePanelPadding(),
             maxZoom: 12,
-            duration: duration,
+            duration: prefersReducedMotion() ? 0 : duration,
             easing: this._easing,
         });
     }
@@ -1712,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;
@@ -1858,7 +2212,7 @@ export default class OpenLayers extends Map {
     _panTo(loc: LatLngLiteral, animate?: boolean): void {
         this._map.getView().animate({
             center: this._toViewCoords(loc),
-            duration: this.options.duration,
+            duration: prefersReducedMotion() ? 0 : this.options.duration,
             easing: this._easing,
         });
     }
@@ -1866,13 +2220,20 @@ export default class OpenLayers extends Map {
     _zoomTo(z: number, animate?: boolean): void {
         this._map.getView().animate({
             zoom: z,
-            duration: this.options.duration,
+            duration: prefersReducedMotion() ? 0 : this.options.duration,
             easing: this._easing,
         });
     }
 
     _viewTo(loc: StorymapSlideLocation, opts?: ViewToOptions): void {
-        // Image region stops (StrollView-style): in image mode the view is
+        // 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.
@@ -1882,12 +2243,15 @@ export default class OpenLayers extends Map {
                 ? loc.region
                 : null;
         if (region) {
-            this._fitRegion(region, opts);
+            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,
@@ -1924,10 +2288,16 @@ 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,
+            ...(_rotation !== null || _current_rotation !== 0 ? { rotation: _rotation ?? 0 } : {}),
+            duration: _animate && !prefersReducedMotion() ? _duration : 0,
             easing: this._easing,
         });
 
@@ -1947,9 +2317,15 @@ 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`.
+     * 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): void {
+    _fitRegion(
+        region: [number, number, number, number],
+        opts?: ViewToOptions,
+        loc?: StorymapSlideLocation,
+    ): void {
         const [x, y, w, h] = region;
         if (!(w > 0) || !(h > 0)) {
             return;
@@ -1966,9 +2342,13 @@ export default class OpenLayers extends Map {
         this._map.getView().fit([x, y, x + w, y + h], {
             size: this._map.getSize(),
             padding: this._opaquePanelPadding(),
-            duration: _animate ? _duration : 0,
+            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);
         }
@@ -1980,6 +2360,295 @@ export default class OpenLayers extends Map {
         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
@@ -2115,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()) {
@@ -2145,7 +2833,7 @@ export default class OpenLayers extends Map {
                 this._map.getView().animate({
                     center: center_view,
                     zoom: view_zoom,
-                    duration: duration ?? this._transition_duration,
+                    duration: prefersReducedMotion() ? 0 : (duration ?? this._transition_duration),
                     easing: this._easing,
                 });
             }
@@ -2156,6 +2844,22 @@ export default class OpenLayers extends Map {
             }
             const fit = () => {
                 try {
+                    // 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 = (
@@ -2187,7 +2891,9 @@ export default class OpenLayers extends Map {
                         view.animate({
                             center: this._toViewCoords(offset_location),
                             zoom: zoom,
-                            duration: duration ?? this._transition_duration,
+                            duration: prefersReducedMotion()
+                                ? 0
+                                : (duration ?? this._transition_duration),
                             easing: this._easing,
                         });
                     }
@@ -2228,7 +2934,7 @@ export default class OpenLayers extends Map {
                 this._map.getView().animate({
                     center: this._toViewCoords(offset_location),
                     zoom: zoom,
-                    duration: duration ?? this._transition_duration,
+                    duration: prefersReducedMotion() ? 0 : (duration ?? this._transition_duration),
                     easing: this._easing,
                 });
             } else if (
@@ -2254,7 +2960,9 @@ export default class OpenLayers extends Map {
                     this._map.getView().animate({
                         center: this._toViewCoords(offset_location),
                         zoom: zoom,
-                        duration: duration ?? this._transition_duration,
+                        duration: prefersReducedMotion()
+                            ? 0
+                            : (duration ?? this._transition_duration),
                         easing: this._easing,
                     });
                 }
@@ -2275,7 +2983,9 @@ export default class OpenLayers extends Map {
                     view.animate({
                         center: this._toViewCoords(offset_location),
                         zoom: zoom,
-                        duration: duration ?? this._transition_duration,
+                        duration: prefersReducedMotion()
+                            ? 0
+                            : (duration ?? this._transition_duration),
                         easing: this._easing,
                     });
                 }
@@ -2336,6 +3046,11 @@ export default class OpenLayers extends Map {
                         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;
@@ -2485,6 +3200,16 @@ export default class OpenLayers extends Map {
         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();
     }
 }