@projektemacher/storymapjs 0.10.8 → 0.11.0

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

@@ -3,6 +3,7 @@ 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";
 
@@ -27,6 +28,10 @@ interface MarkerPresentation {
 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. */
@@ -48,7 +53,7 @@ export default class OpenLayersMapMarker extends MapMarker {
     ================================================== */
     /**
      * The merged marker presentation: `marker.*` wins, `location.*` is the
-     * legacy spelling and still works (docs/plans/iiif-media-tours.md §2).
+     * 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.
      */
@@ -88,6 +93,15 @@ export default class OpenLayersMapMarker extends MapMarker {
             }
 
             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) => {
@@ -102,6 +116,23 @@ export default class OpenLayersMapMarker extends MapMarker {
                 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) => {
@@ -122,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);
@@ -131,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);
@@ -210,23 +244,69 @@ export default class OpenLayersMapMarker extends MapMarker {
      * marker's, and that is `latLon()`.
      */
     _togglePopup(): void {
-        if (!this._popup_enabled) return;
-        if (this._popup_el) {
-            this._closePopup();
-            return;
-        }
+        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;
+        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;
     }
 
-    _closePopup(): void {
+    /**
+     * 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 {
@@ -244,6 +324,7 @@ export default class OpenLayersMapMarker extends MapMarker {
         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";
@@ -262,11 +343,13 @@ export default class OpenLayersMapMarker extends MapMarker {
         });
         card.appendChild(close);
 
-        if (data.media?.thumb) {
+        // 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 = data.media.thumb;
-            img.alt = data.media.caption ?? "";
+            img.src = thumb_item.thumb;
+            img.alt = thumb_item.caption ?? "";
             img.loading = "lazy";
             card.appendChild(img);
         }
@@ -297,9 +380,22 @@ export default class OpenLayersMapMarker extends MapMarker {
     _updateAudioBadge(): void {
         if (!this._audio_badge) return;
         const media = (this.data as unknown as { media?: { mediatype?: { type?: string } } }).media;
-        const kind = media?.mediatype?.type;
-        const audible = kind === "audio" || kind === "video" || !!this.data.narration;
+        // 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 {
@@ -313,6 +409,10 @@ export default class OpenLayersMapMarker extends MapMarker {
             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;

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. */

package/src/media/EmbedUtil.ts

@@ -9,6 +9,8 @@
 	in a storymap's JSON can never execute code in a viewer's browser.
 ================================================== */
 
+import { Language } from "../language/Language";
+
 // Attributes copied from a pasted <iframe> onto the rebuilt element.
 // src is handled separately (validated); everything else is dropped.
 const IFRAME_ATTRIBUTES = [
@@ -99,6 +101,11 @@ const SLIDE_TEXT_DROP_TAGS = DROP_TAGS.filter((tag) => tag !== "IFRAME");
  *
  * This list covers prose and media embeds. Anything else is unwrapped (its
  * text is kept) rather than dropped with its contents.
+ *
+ * Note on `style` (trusted authors): inline declarations pass through
+ * verbatim — there is no script execution from declarations in modern
+ * engines, `url()` tracking is at parity with allowlisted `<img>`, and the
+ * slide root is positioned and isolated so nothing escapes the slide box.
  */
 const SLIDE_TEXT_TAGS = [
     // structure / text
@@ -165,13 +172,16 @@ const SLIDE_TEXT_TAGS = [
 
 /**
  * Attributes allowed on slide-text elements. `id`/`name` are deliberately
- * absent: they enable DOM clobbering of host-page globals. `style` is
- * deliberately absent (see above). `class` is kept — the story fixtures and
+ * absent: they enable DOM clobbering of host-page globals. `style` passes
+ * through verbatim — tour authors are trusted; the slide root is positioned
+ * and isolated, so declarations cannot escape it (see VCO.Slide.scss).
+ * `class` is kept — the story fixtures and
  * the migrated site content style slides through it, and a class name cannot
  * execute anything.
  */
 const SLIDE_TEXT_ATTRIBUTES = [
     "class",
+    "style",
     "title",
     "lang",
     "dir",
@@ -276,6 +286,21 @@ export function buildIframe(html: string): HTMLIFrameElement | null {
         iframe.setAttribute("frameborder", "0");
         iframe.setAttribute("allowfullscreen", "");
     }
+    if (!iframe.hasAttribute("title")) {
+        const localeMedia = (Language as unknown as { media?: { iframe_title?: unknown } }).media;
+        const localeTitle =
+            typeof localeMedia?.iframe_title === "string" && localeMedia.iframe_title !== ""
+                ? localeMedia.iframe_title
+                : undefined;
+        const messagesTitle = Language.messages["media.iframe_title"];
+        iframe.setAttribute(
+            "title",
+            localeTitle ??
+                (typeof messagesTitle === "string" && messagesTitle !== ""
+                    ? messagesTitle
+                    : "Embedded media"),
+        );
+    }
     return iframe;
 }
 

package/src/media/Media.ts

@@ -50,6 +50,16 @@ export function loadErrorIcon(media_type: unknown): string {
     return LOAD_ERROR_ICONS[type] ?? GENERIC_LOAD_ERROR_ICON;
 }
 
+/**
+ * Whether media captions/credits render: `show_info: false` hides them, but
+ * only for slideshow tours (`slideshow_source`) — internal documents always
+ * show their captions. Pure for testability.
+ */
+export function shouldShowInfo(options: MediaOptions): boolean {
+    if (options.slideshow_source !== true) return true;
+    return options.show_info !== false;
+}
+
 /*	Options for Media and its subclasses: the fields Media itself sets
 	or reads. Everything else merged in via mergeData is absorbed by the
 	index signature. */
@@ -74,6 +84,14 @@ export interface MediaData extends StorymapSlideMedia {
     [key: string]: unknown;
 }
 
+export interface MediaEvents {
+    loaded: MediaData;
+    media_loaded: MediaData;
+    media_ended: MediaData;
+    added: MediaData;
+    removed: MediaData;
+}
+
 /**
  * The media element cache.
  *
@@ -110,7 +128,7 @@ export class MediaBase {
     declare "options": MediaOptions;
     declare "animator": unknown;
     declare "_media": unknown;
-    declare "fire": EventedInstance["fire"];
+    declare "fire": EventedInstance<MediaEvents>["fire"];
 
     /*	Constructor
 	================================================== */
@@ -230,8 +248,7 @@ export class MediaBase {
                 this._state.loaded = true;
                 this._updateDisplay();
             } catch (e) {
-                console.log("Error loading media for ", this._media);
-                console.log(e);
+                console.warn("StoryMapJS: error loading media.", e);
                 this.loadErrorDisplay("Error loading media.");
             }
         }, 1200);
@@ -441,6 +458,9 @@ export class MediaBase {
         const text = Dom.create("p", "");
         text.appendChild(document.createTextNode(message));
         this._el.content_item.appendChild(text);
+        // announced, not just shown: load failures otherwise pass silently
+        // for screen-reader visitors
+        this._el.content_item.setAttribute("role", "alert");
 
         // After Loaded
         this.onLoaded(true);
@@ -474,6 +494,9 @@ export class MediaBase {
 
     /** Render the media credit and caption, if the slide has them. */
     showMeta(): void {
+        // slideshow tours may hide the info block (show_info: false);
+        // internal documents always render it
+        if (!shouldShowInfo(this.options)) return;
         this._state.show_meta = true;
         // Credit and caption are author-supplied strings that may legitimately
         // contain formatting (they are documented as HTML), so they go through
@@ -590,7 +613,7 @@ export class MediaBase {
     _stopMedia() {}
 }
 
-export class Media extends Evented(MediaBase) {
+export class Media extends Evented<MediaEvents, typeof MediaBase>(MediaBase) {
     constructor(...args: ConstructorParameters<typeof MediaBase>) {
         super(...args);
     }

package/src/media/embedId.ts

@@ -102,3 +102,9 @@ export function flickrId(url: string): string | null {
 export function tweetId(url: string): string | null {
     return segmentAfter(url, /\/status(?:es)?\//i);
 }
+
+/** Tweet author (the profile segment before `/status/<id>`), or null. */
+export function tweetAuthor(url: string): string | null {
+    const match = /(?:twitter\.com|x\.com)\/([^\s/?#]+)\/status(?:es)?\//i.exec(url);
+    return match ? match[1] : null;
+}

package/src/media/types/Flickr.ts

@@ -8,6 +8,8 @@ import Dom from "../../dom/Dom";
 
 export default class Flickr extends Media {
     declare "media_id": string;
+    /** The `load` handler on the image, stored so dispose() can detach it. */
+    declare "_onLoad": (() => void) | null;
 
     /*	Load the media
 	================================================== */
@@ -22,10 +24,12 @@ export default class Flickr extends Media {
             this._el.content,
         );
 
-        // Media Loaded Event
-        this._el.content_item.addEventListener("load", (e) => {
+        // Media Loaded Event. The reference is kept so dispose() can detach
+        // it: an inline arrow function has no other handle.
+        this._onLoad = () => {
             this.onMediaLoaded();
-        });
+        };
+        this._el.content_item.addEventListener("load", this._onLoad);
 
         // Get Media ID
         this.establishMediaID();
@@ -112,4 +116,11 @@ export default class Flickr extends Media {
 
         return _size;
     }
+
+    _disposeMedia(): void {
+        if (this._onLoad) {
+            this._el.content_item?.removeEventListener("load", this._onLoad);
+            this._onLoad = null;
+        }
+    }
 }

package/src/media/types/HtmlMedia.ts

@@ -51,6 +51,19 @@ export class HtmlMediaBase extends Media {
         ) as HTMLMediaElement;
         this._el.content_item = media_item;
         media_item.controls = true;
+        const captionText =
+            typeof this.data.caption === "string"
+                ? this.data.caption
+                      .replace(/<[^>]*>/g, " ")
+                      .replace(/\s+/g, " ")
+                      .trim()
+                : "";
+        const mediaName =
+            typeof this.options.media_name === "string" ? this.options.media_name : "";
+        media_item.setAttribute(
+            "aria-label",
+            captionText || mediaName || (spec.kind === "audio" ? "Audio" : "Video"),
+        );
 
         const source_item = Dom.create("source", "", media_item) as HTMLSourceElement;
         this._el.source_item = source_item;
@@ -58,9 +71,62 @@ export class HtmlMediaBase extends Media {
         // Media Loaded Event. The references are kept so dispose() can detach
         // them: an inline arrow function has no other handle.
         this._onEnded = null;
+        // Playback flags (slideshow audio terms): loop repeats, offset seeks
+        // once the metadata is available, play:"auto" starts on load
+        // (absent stays click-to-play with controls, as before). Slideshow
+        // tours only — internal documents ignore the bag even when present.
+        const sourced = (this.options as { slideshow_source?: unknown }).slideshow_source === true;
+        const bag = (
+            sourced
+                ? this.data
+                : ({} as {
+                      loop?: boolean;
+                      offset?: number;
+                      play?: string;
+                  })
+        ) as {
+            loop?: boolean;
+            offset?: number;
+            play?: string;
+        };
+        media_item.loop = bag.loop === true;
+        const offset =
+            typeof bag.offset === "number" && Number.isFinite(bag.offset) && bag.offset > 0
+                ? bag.offset
+                : 0;
+        const seek = () => {
+            if (offset <= 0) return;
+            try {
+                media_item.currentTime = offset;
+            } catch {
+                // pre-metadata seek throws in some browsers; canplay retries
+            }
+        };
+        const autoplay = bag.play === "auto";
         this._onCanPlay = () => {
+            seek();
+            if (autoplay) {
+                void media_item.play()?.catch?.(() => {
+                    // autoplay policy or missing gesture: controls stay for
+                    // the visitor, like a click-armed slide
+                });
+            }
             this.onLoaded();
         };
+        // offset with metadata already present (cached media): seek now too
+        if (offset > 0) {
+            if (media_item.readyState >= 1) {
+                seek();
+            } else {
+                media_item.addEventListener(
+                    "loadedmetadata",
+                    () => {
+                        seek();
+                    },
+                    { once: true },
+                );
+            }
+        }
         media_item.addEventListener("canplay", this._onCanPlay);
 
         // Load Error Event (the source element fires it, not the media element)