@projektemacher/storymapjs 0.10.7 → 0.11.0

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

@@ -2,6 +2,9 @@ import Overlay from "ol/Overlay";
 import { fromLonLat } from "ol/proj";
 import type { Map as OlMap } from "ol";
 import MapMarker from "../MapMarker";
+import { clearTimer } from "../../core/Util";
+import { Language } from "../../language/Language";
+import { sanitizeSlideText } from "../../media/EmbedUtil";
 import type { LatLngLiteral, MapMarkerData, StorymapOptions } from "../../types";
 
 /*	MapMarker.OpenLayers
@@ -11,30 +14,131 @@ import type { LatLngLiteral, MapMarkerData, StorymapOptions } from "../../types"
 	existing .vco-mapmarker styles apply unchanged.
 ================================================= */
 
+/** The resolved marker presentation: `marker.*` over `location.*`. */
+interface MarkerPresentation {
+    icon?: string;
+    iconSize?: number[];
+    image?: string;
+    label?: string;
+    popup: boolean;
+    audioBadge: boolean;
+    useCustomMarker?: boolean;
+}
+
 export default class OpenLayersMapMarker extends MapMarker {
     declare "_overlay": Overlay;
+    declare "_onMarkerClickBound": ((e: Event) => void) | null;
+    /** Enter/Space activation for keyboard visitors, detached in dispose(). */
+    declare "_onMarkerKeyBound": ((e: KeyboardEvent) => void) | null;
+    /** Base accessible name (slide headline or label), without audio suffix. */
+    declare "_marker_label": string;
+    /** marker.popup: the active marker opens its card when clicked. */
+    declare "_popup_enabled": boolean;
+    /** marker.audioBadge: flag a slide that has narration or audio media. */
+    declare "_audio_badge": boolean;
+    /**
+     * The popup card while it is open. `declare` fields are undefined until
+     * assigned, so every read below is a truthiness check, never `=== null`,
+     * and there is no constructor to initialise them: `MapMarker`'s own
+     * constructor already runs `_initLayout()` → `_createMarker()`, which
+     * assigns the flags, and initialising afterwards would wipe them.
+     */
+    declare "_popup_el": HTMLElement | null;
+    /** Escape-to-close, detached in dispose(). */
+    declare "_onPopupKeyBound": ((e: KeyboardEvent) => void) | null;
+    /** Mirrors `active()`, as a flag rather than a method reference. */
+    declare "_is_active": boolean;
 
     /*	Create Marker
     ================================================== */
+    /**
+     * The merged marker presentation: `marker.*` wins, `location.*` is the
+     * legacy spelling and still works.
+     * `location` also stays the carrier of geography, so lat/lon are read
+     * from it alone — presentation never moves a marker.
+     */
+    _presentation(d?: MapMarkerData): MarkerPresentation {
+        const location = (d?.location ?? {}) as Record<string, unknown>;
+        const marker = (d?.marker ?? {}) as Record<string, unknown>;
+        return {
+            icon: (marker.icon as string | undefined) ?? (location.icon as string | undefined),
+            iconSize:
+                (marker.iconSize as number[] | undefined) ??
+                (location.iconSize as number[] | undefined),
+            image: (marker.image as string | undefined) ?? (location.image as string | undefined),
+            // in a manifest the label arrives as the navPlace property `name`
+            label: (marker.label as string | undefined) ?? (location.name as string | undefined),
+            popup: Boolean(marker.popup ?? location.popup),
+            audioBadge: Boolean(marker.audioBadge ?? location.audioBadge),
+            useCustomMarker: location.use_custom_marker as boolean | undefined,
+        };
+    }
+
     _createMarker(d?: MapMarkerData, o?: StorymapOptions): void {
-        if (d.location && typeof d.location.lat == "number" && typeof d.location.lon == "number") {
+        const location = d?.location;
+        if (location && typeof location.lat == "number" && typeof location.lon == "number") {
             this.data.real_marker = true;
-            const use_custom_marker = o.use_custom_markers || d.location.use_custom_marker;
-            if (use_custom_marker && d.location.icon) {
+            const presentation = this._presentation(d);
+            this._popup_enabled = presentation.popup;
+            this._audio_badge = presentation.audioBadge;
+            const use_custom_marker = o?.use_custom_markers || presentation.useCustomMarker;
+            if (use_custom_marker && presentation.icon) {
                 this._custom_icon = {
-                    url: d.location.icon,
-                    size: d.location.iconSize || [48, 48],
-                    anchor: this._customIconAnchor(d.location.iconSize),
+                    url: presentation.icon,
+                    size: presentation.iconSize || [48, 48],
+                    anchor: this._customIconAnchor(presentation.iconSize),
                 };
-            } else if (use_custom_marker && d.location.image) {
-                this._custom_image_icon = d.location.image;
+            } else if (use_custom_marker && presentation.image) {
+                this._custom_image_icon = presentation.image;
             }
 
-            this._marker = this._createMarkerElement(d, o);
-            this._marker.addEventListener("click", (e) => {
+            this._marker = this._createMarkerElement(d as MapMarkerData, o);
+            // keyboard route to the same behaviour as a click: focusable,
+            // announced as a button, Enter/Space activate
+            const text = (d as MapMarkerData)?.text;
+            const headline =
+                typeof text?.headline === "string" && text.headline !== "" ? text.headline : null;
+            this._marker_label = presentation.label ?? headline ?? "Marker";
+            this._marker.setAttribute("tabindex", "0");
+            this._marker.setAttribute("role", "button");
+            this._marker.setAttribute("aria-label", this._marker_label);
+            // kept as a field so dispose() can detach it; the inline arrow
+            // had no other handle
+            this._onMarkerClickBound = (e: Event) => {
                 e.stopPropagation();
+                // the active marker's card toggles instead of navigating:
+                // the slide is already showing, and a popup that also moved
+                // the story would be impossible to dismiss
+                if (this._popup_enabled && this._is_active) {
+                    this._togglePopup();
+                    return;
+                }
                 this._onMarkerClick(e);
-            });
+            };
+            this._marker.addEventListener("click", this._onMarkerClickBound);
+            // Keyboard visitors get the click behaviour: Enter/Space
+            // activates, and an opened card takes focus so its close button
+            // is reachable without a pointer.
+            this._onMarkerKeyBound = (e: KeyboardEvent) => {
+                if (e.key !== "Enter" && e.key !== " " && e.key !== "Spacebar") return;
+                e.preventDefault();
+                const wasOpen = this.popupOpen;
+                this._onMarkerClickBound?.(e);
+                if (!wasOpen && this.popupOpen) {
+                    (
+                        this._popup_el?.querySelector(
+                            ".vco-marker-popup-close",
+                        ) as HTMLElement | null
+                    )?.focus();
+                }
+            };
+            this._marker.addEventListener("keydown", this._onMarkerKeyBound);
+            // Escape closes the card; the listener is on the document and is
+            // detached in dispose(), so a torn-down map leaves nothing behind
+            this._onPopupKeyBound = (e: KeyboardEvent) => {
+                if (e.key === "Escape") this._closePopup();
+            };
+            document.addEventListener("keydown", this._onPopupKeyBound);
         }
     }
 
@@ -49,6 +153,8 @@ export default class OpenLayersMapMarker extends MapMarker {
             el.className = "vco-mapmarker-custom";
             const img = document.createElement("img");
             img.src = this._custom_icon.url;
+            // decorative: the parent div carries the marker's title
+            img.alt = "";
             img.style.width = this._custom_icon.size[0] + "px";
             img.style.height = "auto";
             el.appendChild(img);
@@ -58,6 +164,7 @@ export default class OpenLayersMapMarker extends MapMarker {
             el.className = "vco-mapmarker-image-icon";
             const img = document.createElement("img");
             img.src = this._custom_image_icon;
+            img.alt = "";
             img.style.width = "48px";
             img.style.height = "auto";
             el.appendChild(img);
@@ -69,14 +176,31 @@ export default class OpenLayersMapMarker extends MapMarker {
         return el;
     }
 
+    /**
+     * The marker's {lat, lon}, or null when it is a non-georeferenced marker
+     * (an overview slide, or a slide with only an image region). `_createMarker`
+     * already established this for a real marker, but returning it from one
+     * place means the type checker can see it too.
+     */
+    latLon(): LatLngLiteral | null {
+        const location = this.data.location;
+        if (!this.data.real_marker || !location) {
+            return null;
+        }
+        if (typeof location.lat !== "number" || typeof location.lon !== "number") {
+            return null;
+        }
+        return { lat: location.lat, lon: location.lon };
+    }
+
     _addTo(m: OlMap): void {
-        if (this.data.real_marker) {
-            const d = this.data;
+        const latlon = this.latLon();
+        if (latlon && this._marker) {
             // Image-space maps (IIIF) use EPSG:4326 with raw image pixel coordinates
             const is_image_space = m.getView().getProjection().getCode() === "EPSG:4326";
             const position = is_image_space
-                ? [d.location.lon, d.location.lat]
-                : fromLonLat([d.location.lon, d.location.lat]);
+                ? [latlon.lon, latlon.lat]
+                : fromLonLat([latlon.lon, latlon.lat]);
 
             // Default pins anchor on their tip: OL's inline styles override
             // any CSS top/left, so the alignment is done here — bottom-center
@@ -101,7 +225,211 @@ export default class OpenLayersMapMarker extends MapMarker {
         }
     }
 
+    /**
+     * Terminal teardown: detach the click listener and drop the overlay and
+     * element. Called by the map's dispose(); the marker must not be used
+     * afterwards.
+     */
+    /*  Marker popup and audio badge
+    ================================================== */
+
+    /**
+     * Toggle the popup card for the *active* marker. Inactive markers keep
+     * their original behaviour — a click navigates — so a popup never
+     * swallows navigation on a map full of pins.
+     *
+     * The card is a DOM element parented to the marker element and positioned
+     * with CSS, which is how it survives a move to the vector renderer
+     * (docs/plans/issue-159-vector-markers.md): only the anchor is the
+     * marker's, and that is `latLon()`.
+     */
+    _togglePopup(): void {
+        this.togglePopup();
+    }
+
+    _closePopup(): void {
+        this.closePopup();
+    }
+
+    /** True when this marker is configured to show a popup card. */
+    isPopupEnabled(): boolean {
+        return this._popup_enabled === true;
+    }
+
+    /**
+     * Open the popup card for this marker.
+     *
+     * Returns false (and opens nothing) when popups are disabled for the
+     * marker or it is not a real map marker — e.g. an overview slide. A
+     * click on an inactive marker navigates instead of opening (see the
+     * click handler in `_createMarker`); programmatic callers that want the
+     * card on another stop should navigate first (`StoryMap.openMarkerPopup`
+     * does exactly that). Fires `popupopen` on success.
+     */
+    openPopup(): boolean {
+        if (!this._popup_enabled) return false;
+        if (!this.data.real_marker) return false;
+        if (this._popup_el) return true;
+        const el = this._createPopupElement();
+        if (el === null) return false;
+        this._marker.appendChild(el);
+        this._popup_el = el;
+        this._marker.classList.add("vco-mapmarker-popup-open");
+        this.fire("popupopen", { marker_number: this.marker_number });
+        return true;
+    }
+
+    /**
+     * Close the popup card if it is open. Fires `popupclose`. Also runs on
+     * Escape, the card's close button, deactivation and `dispose()`.
+     */
+    closePopup(): void {
+        if (!this._popup_el) return;
+        // keyboard visitors may be inside the card (its close button is
+        // focusable): hand focus back to the marker instead of dropping it
+        // on the page body. Mouse visitors never had focus here, so theirs
+        // is untouched.
+        const hadFocus = this._popup_el.contains(document.activeElement);
+        this._popup_el.parentNode?.removeChild(this._popup_el);
+        this._popup_el = null;
+        this._marker?.classList?.remove("vco-mapmarker-popup-open");
+        if (hadFocus) this._marker?.focus();
+        this.fire("popupclose", { marker_number: this.marker_number });
+    }
+
+    /**
+     * Open the card when closed, close it when open. Returns whether the
+     * card is open afterwards (false when popups are disabled).
+     */
+    togglePopup(): boolean {
+        if (this._popup_el) {
+            this.closePopup();
+            return false;
+        }
+        return this.openPopup();
+    }
+
+    get popupOpen(): boolean {
+        return Boolean(this._popup_el);
+    }
+
+    /**
+     * Headline, a sanitized excerpt, the media thumb and an audio control.
+     * Every piece of text goes through `sanitizeSlideText` — a slide's text
+     * is untrusted input and a marker card is no different (the stored-XSS
+     * audit made that lesson once; a label is attacker-controlled text like
+     * any other).
+     */
+    _createPopupElement(): HTMLElement | null {
+        const data = this.data as unknown as {
+            text?: { headline?: string; text?: string };
+            media?: { thumb?: string | null; url?: string | null; caption?: string | null };
+            media_extra?: { thumb?: string | null; url?: string | null; caption?: string | null }[];
+        };
+        const card = document.createElement("div");
+        card.className = "vco-marker-popup";
+        // a dialog-ish card, not a modal: no focus trap, Escape closes
+        card.setAttribute("role", "group");
+        card.setAttribute("aria-label", data.text?.headline ?? "Slide details");
+
+        const close = document.createElement("button");
+        close.type = "button";
+        close.className = "vco-marker-popup-close";
+        close.setAttribute("aria-label", "Close");
+        close.textContent = "\u00d7";
+        close.addEventListener("click", (e) => {
+            e.stopPropagation();
+            this._closePopup();
+        });
+        card.appendChild(close);
+
+        // first item with a thumb across the primary and the extras (#358)
+        const thumb_item = [data.media, ...(data.media_extra ?? [])].find((item) => !!item?.thumb);
+        if (thumb_item?.thumb) {
+            const img = document.createElement("img");
+            img.className = "vco-marker-popup-thumb";
+            img.src = thumb_item.thumb;
+            img.alt = thumb_item.caption ?? "";
+            img.loading = "lazy";
+            card.appendChild(img);
+        }
+
+        const body = document.createElement("div");
+        body.className = "vco-marker-popup-body";
+        if (data.text?.headline) {
+            const h = document.createElement("h3");
+            h.className = "vco-marker-popup-headline";
+            h.appendChild(sanitizeSlideText(data.text.headline));
+            body.appendChild(h);
+        }
+        if (data.text?.text) {
+            const p = document.createElement("p");
+            p.className = "vco-marker-popup-excerpt";
+            p.appendChild(sanitizeSlideText(data.text.text));
+            body.appendChild(p);
+        }
+        card.appendChild(body);
+        return card;
+    }
+
+    /**
+     * A small indicator on markers whose slide has narration or audio media
+     * (the Micrio affordance). Recomputed on activation, because a slide's
+     * media may only be known once it is resolved.
+     */
+    _updateAudioBadge(): void {
+        if (!this._audio_badge) return;
+        const media = (this.data as unknown as { media?: { mediatype?: { type?: string } } }).media;
+        // any audible item badges the marker, not just item 0: an
+        // image-first/audio-second slide is still an audible stop (#358)
+        const extra =
+            (this.data as unknown as { media_extra?: { mediatype?: { type?: string } }[] })
+                .media_extra ?? [];
+        const audible =
+            [media, ...extra].some((item) => {
+                const kind = item?.mediatype?.type;
+                return kind === "audio" || kind === "video";
+            }) || !!this.data.narration;
+        this._marker.classList.toggle("vco-mapmarker-has-audio", audible);
+        const suffix =
+            audible && typeof Language.buttons.audio_badge === "string"
+                ? `, ${Language.buttons.audio_badge}`
+                : "";
+        this._marker.setAttribute("aria-label", `${this._marker_label}${suffix}`);
+    }
+
+    dispose(): void {
+        const marker = this._marker as unknown as HTMLElement | null;
+        this._closePopup();
+        if (this._onPopupKeyBound) {
+            document.removeEventListener("keydown", this._onPopupKeyBound);
+            this._onPopupKeyBound = null;
+        }
+        if (this._onMarkerClickBound) {
+            marker?.removeEventListener?.("click", this._onMarkerClickBound);
+            this._onMarkerClickBound = null;
+        }
+        if (this._onMarkerKeyBound) {
+            marker?.removeEventListener?.("keydown", this._onMarkerKeyBound);
+            this._onMarkerKeyBound = null;
+        }
+        if (this._overlay) {
+            this._overlay.setElement(undefined);
+            this._overlay = null as unknown as Overlay;
+        }
+        // via the parent so a non-DOM stand-in (a test double) is tolerated
+        marker?.parentNode?.removeChild(marker);
+        this._marker = null as unknown as HTMLDivElement;
+    }
+
     _active(a: boolean): void {
+        this._is_active = a;
+        if (!a) {
+            // navigating away closes the card: a popup belongs to its stop
+            this._closePopup();
+        } else {
+            this._updateAudioBadge();
+        }
         if (this.data.media && this.data.media.mediatype) {
             this.media_icon_class = "vco-mapmarker-icon vco-icon-" + this.data.media.mediatype.type;
         } else {
@@ -112,7 +440,7 @@ export default class OpenLayersMapMarker extends MapMarker {
                 // custom icons look the same active or not (as in the
                 // original Leaflet version): only the stacking changes
                 if (!a) {
-                    clearTimeout(this.timer);
+                    clearTimer(this.timer);
                 }
                 this._marker.style.zIndex = a ? "1000" : "";
             } else if (this._custom_image_icon) {
@@ -121,7 +449,7 @@ export default class OpenLayersMapMarker extends MapMarker {
                     this._marker.classList.add("vco-mapmarker-image-icon-active");
                     this._marker.style.zIndex = "1000";
                 } else {
-                    clearTimeout(this.timer);
+                    clearTimer(this.timer);
                     this._marker.classList.remove("vco-mapmarker-image-icon-active");
                     this._marker.classList.add("vco-mapmarker-image-icon");
                     this._marker.style.zIndex = "";
@@ -131,7 +459,7 @@ export default class OpenLayersMapMarker extends MapMarker {
                 this._marker.classList.add("vco-mapmarker-active");
                 this._marker.style.zIndex = "1000";
             } else {
-                clearTimeout(this.timer);
+                clearTimer(this.timer);
                 this._marker.classList.remove("vco-mapmarker-active");
                 this._marker.classList.add("vco-mapmarker");
                 this._marker.style.zIndex = "";
@@ -166,11 +494,7 @@ export default class OpenLayersMapMarker extends MapMarker {
         }
     }
 
-    _location(): LatLngLiteral {
-        if (this.data.real_marker) {
-            return { lat: this.data.location.lat, lon: this.data.location.lon };
-        } else {
-            return {} as LatLngLiteral;
-        }
+    _location(): LatLngLiteral | null {
+        return this.latLon();
     }
 }

package/src/map/openlayers/zoomifyTiles.ts

@@ -15,10 +15,7 @@ export const ZOOMIFY_TILE_SIZE = 256;
  * Full-size tiles are left untouched for OpenLayers' own load handling.
  */
 export function padCroppedZoomifyTile(tile: ImageTile, image: HTMLImageElement): void {
-    if (
-        image.naturalWidth !== ZOOMIFY_TILE_SIZE ||
-        image.naturalHeight !== ZOOMIFY_TILE_SIZE
-    ) {
+    if (image.naturalWidth !== ZOOMIFY_TILE_SIZE || image.naturalHeight !== ZOOMIFY_TILE_SIZE) {
         const canvas = document.createElement("canvas");
         canvas.width = ZOOMIFY_TILE_SIZE;
         canvas.height = ZOOMIFY_TILE_SIZE;

package/src/map/slideView.ts

@@ -0,0 +1,149 @@
+/**
+ * Pure view helpers for slideshow-driven slide presentation: rotation,
+ * CSS filter grading, spotlight masks and per-slide basemaps.
+ *
+ * DOM- and OpenLayers-free so the CLI and unit tests can use them; the map
+ * engine (`Map.OpenLayers`) applies their output. Every helper treats
+ * absent/mistyped input as "feature off", so stories that never mention the
+ * new fields render exactly as before.
+ */
+
+import type { StorymapSlideFilter, StorymapSlideLocation, StorymapSlideMask } from "../types";
+import { asClampedNumber } from "../storymap/iiif-shared.ts";
+
+/**
+ * Valid ranges for filter grading, shared by the translator (which reads
+ * them) and the renderer (which enforces them again — hand-written JSON
+ * reaches the renderer directly, so read-time clamping alone is not enough).
+ */
+export const FILTER_RANGES = {
+    brightness: { min: 0, max: 200, def: 100 },
+    contrast: { min: 0, max: 200, def: 100 },
+    saturate: { min: 0, max: 200, def: 100 },
+    hueRotate: { min: -180, max: 180, def: 0 },
+    sepia: { min: 0, max: 100, def: 0 },
+    blur: { min: 0, max: 20, def: 0 },
+} as const;
+
+/** View rotation in radians, or null when the slide states none. */
+export function slideRotationRad(
+    location: StorymapSlideLocation | null | undefined,
+): number | null {
+    const rotation = location?.rotation;
+    if (typeof rotation !== "number" || !Number.isFinite(rotation) || rotation === 0) {
+        return null;
+    }
+    return (rotation * Math.PI) / 180;
+}
+
+/**
+ * A `filter()` CSS value for the map viewport from a slide `filter` bag
+ * (slideshow `filters`): brightness/contrast/saturate in percent,
+ * hue-rotate in degrees, sepia in percent, blur in pixels. Unknown keys
+ * never reach CSS. Returns "" when nothing is graded.
+ */
+export function buildSlideFilter(filter: StorymapSlideFilter | null | undefined): string {
+    if (!filter || typeof filter !== "object") return "";
+    const parts: string[] = [];
+    const percent = (value: unknown, name: "brightness" | "contrast" | "saturate" | "sepia") => {
+        if (typeof value !== "number" || !Number.isFinite(value)) return;
+        const { min, max, def } = FILTER_RANGES[name];
+        if (value === def) return;
+        parts.push(`${name}(${asClampedNumber(value, min, max)}%)`);
+    };
+    percent(filter.brightness, "brightness");
+    percent(filter.contrast, "contrast");
+    percent(filter.saturate, "saturate");
+    const hue = asClampedNumber(filter.hueRotate, ...filterRange("hueRotate"));
+    if (hue !== null && hue !== FILTER_RANGES.hueRotate.def) {
+        parts.push(`hue-rotate(${hue}deg)`);
+    }
+    percent(filter.sepia, "sepia");
+    const blur = asClampedNumber(filter.blur, ...filterRange("blur"));
+    if (blur !== null && blur !== FILTER_RANGES.blur.def) {
+        parts.push(`blur(${blur}px)`);
+    }
+    return parts.join(" ");
+}
+
+/** The `[min, max]` pair for a filter range (spread into `asClampedNumber`). */
+function filterRange(key: keyof typeof FILTER_RANGES): [number, number] {
+    return [FILTER_RANGES[key].min, FILTER_RANGES[key].max];
+}
+
+const MASK_COLOR = /^(#[0-9a-f]{3}([0-9a-f]{3}([0-9a-f]{2})?)?|rgba?\([^)]*\))$/i;
+
+export interface NormalizedMask {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    color: string;
+    invert: boolean;
+    opacity: number;
+}
+
+/**
+ * A validated spotlight mask (slideshow `passepartout`): normalized
+ * viewport fractions plus presentation. Returns null for anything that is
+ * not a usable `{x, y, w, h}` shape; out-of-range fractions are clamped,
+ * an unparsable color falls back to translucent black.
+ */
+export function normalizeMask(mask: StorymapSlideMask | null | undefined): NormalizedMask | null {
+    if (!mask || typeof mask !== "object") return null;
+    const { x, y, w, h } = mask;
+    if (
+        typeof x !== "number" ||
+        typeof y !== "number" ||
+        typeof w !== "number" ||
+        typeof h !== "number" ||
+        ![x, y, w, h].every(Number.isFinite)
+    ) {
+        return null;
+    }
+    const clamp01 = (n: number) => Math.min(1, Math.max(0, n));
+    const nx = clamp01(x);
+    const ny = clamp01(y);
+    // shrink the far edge with a clamped origin (like clampRegion): a mask
+    // fully outside the viewport resolves to nothing, not a full mask
+    const nw = Math.min(1 - nx, Math.max(0, w + Math.min(0, x)));
+    const nh = Math.min(1 - ny, Math.max(0, h + Math.min(0, y)));
+    if (!(nw > 0) || !(nh > 0)) return null;
+    const rawColor = typeof mask.color === "string" ? mask.color.trim() : "";
+    const color = rawColor !== "" && MASK_COLOR.test(rawColor) ? rawColor : "rgba(0,0,0,0.5)";
+    const opacity =
+        typeof mask.opacity === "number" && Number.isFinite(mask.opacity)
+            ? Math.min(1, Math.max(0, mask.opacity))
+            : 1;
+    return { x: nx, y: ny, w: nw, h: nh, color, invert: mask.invert === true, opacity };
+}
+
+/** The per-slide basemap key, or null when the slide keeps the story basemap. */
+export function slideBasemapKey(location: StorymapSlideLocation | null | undefined): string | null {
+    const basemap = location?.basemap;
+    return typeof basemap === "string" && basemap !== "" ? basemap : null;
+}
+
+/**
+ * True for plain image-file URLs (no IIIF service, `{z}` template or
+ * keyword). Only unambiguous raster extensions: `.jpx`/`.jp2` can be IIIF
+ * bases too (Leipzig serves `info.json` off `.jpx`), so those go through
+ * the service attempt with a static fallback instead. Relative URLs
+ * (same-origin static files) count; templates never match (no extension).
+ */
+export function isStaticImageUrl(url: string): boolean {
+    if (url.includes("{z}")) return false;
+    if (!/\.(jpe?g|png|gif|webp|tif?f|bmp|avif)(\?.*)?$/i.test(url)) return false;
+    if (/^https?:\/\//i.test(url)) return true;
+    // same-origin relative file without any other scheme (mapbox:, osm:, …)
+    return !/^[a-z][a-z0-9+.-]*:/i.test(url);
+}
+
+/**
+ * An image service base as its `info.json` URL (idempotent for URLs that
+ * already name it). Shared by the slideshow translator (story default) and
+ * the per-slide basemap builder so the suffix rule cannot drift.
+ */
+export function serviceToInfoJson(service: string): string {
+    return /info\.json$/i.test(service) ? service : `${service.replace(/\/$/, "")}/info.json`;
+}

package/src/map/types.ts

@@ -7,6 +7,8 @@ export interface ViewToOptions {
     calculate_zoom?: boolean;
     duration?: number;
     zoom?: number;
+    /** View rotation in degrees clockwise; absent leaves rotation unchanged. */
+    rotation?: number;
 }
 
 /** A point of the connection line: either a slide or a raw lat/lon pair. */