@projektemacher/storymapjs 0.10.8 → 0.11.0

package/src/storymap/StoryMap.ts

@@ -1,4 +1,10 @@
-import { mergeData, slideTransitionDuration, updateData, prefersReducedMotion } from "../core/Util";
+import {
+    mergeData,
+    slideTransitionDuration,
+    updateData,
+    prefersReducedMotion,
+    REDUCED_MOTION_QUERY,
+} from "../core/Util";
 import { loadCSS } from "../core/Load";
 import { validateStorymapAndReport } from "./validate";
 import {
@@ -13,6 +19,14 @@ import {
     loadSeeAlso,
     manifestToStorymapData,
 } from "./iiif";
+import {
+    followSlideshowPages,
+    formatSlideshowWarning,
+    isSlideshowCollection,
+    slideshowToStorymapData,
+    type SlideshowWarning,
+} from "./from-slideshow";
+import { asClampedNumber } from "./iiif-shared";
 import {
     ConsentManager,
     consentManagerOf,
@@ -31,6 +45,7 @@ import {
     claimLanguage,
     releaseLanguage,
     isLanguageConflict,
+    Language,
 } from "../language/Language";
 import {
     markInteraction,
@@ -39,78 +54,57 @@ import {
     unregisterParticipant,
 } from "../core/viewers";
 import MediaType from "../media/MediaType";
-import { Evented, type EventedInstance } from "../core/mixins";
+import { Evented, type EventedInstance, type FiredEvent } from "../core/mixins";
 import OpenLayersMap from "../map/openlayers/Map.OpenLayers";
+import type { ImagereadyPayload } from "../map/openlayers/Map.OpenLayers";
 import MenuBar from "../ui/MenuBar";
+import type { LayersRow } from "../ui/LayersControl";
 import StorySlider from "../slider/StorySlider";
 import { Browser } from "../core/Browser";
 import Animate from "../animation/tween";
 import type { Map as OlMap } from "ol";
 import type OlLayer from "ol/layer/Layer";
 import type OpenLayersMapMarker from "../map/openlayers/MapMarker.OpenLayers";
+export { resolveFontCssUrl, isExternalUrl, fontCssOriginal } from "./font-css";
+import { resolveFontCssUrl, isExternalUrl, fontCssOriginal } from "./font-css";
 import type {
     AnimationHandle,
+    StorymapBasemap,
     StorymapData,
     StorymapDataWrapper,
     StorymapOptions,
     StorymapSlide,
+    StorymapSlideNarration,
 } from "../types";
 
 /** Map height in pixels while the menubar has collapsed the map (portrait only). */
 const COLLAPSED_MAP_HEIGHT = 1;
 
-type StoryMapListener = (e: unknown) => void;
-
-/**
- * Resolve a `font_css` value to an absolute stylesheet URL.
- *
- * - `stock:<name>` resolves against the library location.
- * - Absolute URLs pass through untouched.
- * - Anything else resolves against the page URL, so hosts can reference
- *   themes vendored into their own public dir (e.g. "fonts/font.css").
- */
-export function resolveFontCssUrl(font: string): string {
-    if (font.startsWith("stock:")) {
-        const font_name = font.split(":")[1] || "default";
-        // A crafted name ("stock:../../secret") would otherwise resolve to an
-        // arbitrary same-origin file next to the bundle, because the name is
-        // concatenated into a URL path. Only accept a bare theme name.
-        if (!/^[a-z0-9-]+$/i.test(font_name)) {
-            console.warn(
-                "StoryMapJS: ignoring font_css with an invalid stock theme name",
-                font_name,
-            );
-            return new URL(/* @vite-ignore */ "../css/fonts/font.default.css", import.meta.url)
-                .href;
-        }
-        // resolved against the library location: one directory up from
-        // src/main.ts (dev) and js/storymap.js (build) in both cases
-        return new URL("../css/fonts/font." + font_name + ".css", import.meta.url).href;
-    }
-    // Absolute URL, protocol-relative, or a data: URL. Note this must be a
-    // real URL test, not a `/^(http|https|\/\/)/` prefix check: the old prefix
-    // test false-positived on a relative path that merely *starts* with those
-    // letters (e.g. "httpfonts.css"), which raised a spurious consent prompt
-    // for a same-origin file.
-    if (/^[a-z][a-z0-9+.-]*:/i.test(font) || font.startsWith("//")) {
-        return font;
-    }
-    return new URL(font, document.baseURI).href;
+export interface StoryMapEvents {
+    change: { current_slide: number; current_id: string | null };
+    loaded: StorymapData;
+    title: { title: string };
+    dataloaded: undefined;
+    fontLoaded: { font: string };
+    transitionstart: { current_slide: number; duration: number };
+    transitionend: { current_slide: number };
+    error: { message: string; source: string; conflict?: boolean };
+    imageready: ImagereadyPayload;
+    annotationsloaded: {
+        stops: StorymapSlide[];
+        searchService: string | null;
+        failed: string[];
+    };
+    markerclick: { marker_number: number; current_slide: number };
+    popupopen: { marker_number: number; current_slide: number };
+    popupclose: { marker_number: number; current_slide: number };
+    basemapchange: { map_type: string; previous: string };
+    overlaychange: { index: number; visible: boolean };
 }
 
-/** True when `url` points off-origin (or at a data: URL) and needs a consent ask. */
-export function isExternalUrl(url: string): boolean {
-    // data:/blob: are not off-origin but are not a theme stylesheet either
-    if (/^(data|blob):/i.test(url)) {
-        return true;
-    }
-    try {
-        return new URL(url, document.baseURI).origin !== window.location.origin;
-    } catch {
-        // unparseable: treat as external, so we err towards asking
-        return true;
-    }
-}
+type StoryMapListener<K extends keyof StoryMapEvents = keyof StoryMapEvents> = (
+    e: FiredEvent<StoryMapEvents, K>,
+) => void;
 
 /**
  * Interactive StoryMap viewer.
@@ -129,7 +123,7 @@ export function isExternalUrl(url: string): boolean {
  */
 class StoryMapBase {
     declare "_loaded": { storyslider: boolean; map: boolean };
-    declare "on": EventedInstance["on"];
+    declare "on": EventedInstance<StoryMapEvents>["on"];
     declare "version": string;
     declare "ready": boolean;
     declare "_el": {
@@ -177,6 +171,21 @@ class StoryMapBase {
     declare "_autoplay_stopped": boolean;
     /** The narration player: one <audio> for the whole story, reused. */
     declare "_narration_el": HTMLAudioElement | null;
+    /**
+     * The ambient player: a second <audio> for a narration bed that outlives
+     * its slide (`narration.stopOnExit: false`, slideshow ambient audio).
+     * At most one ambient track plays; a new one replaces it.
+     */
+    declare "_ambient_el": HTMLAudioElement | null;
+    /** What each player is (or was) playing, so same-URL beds continue. */
+    declare "_narration_meta": { url: string; stopOnExit: boolean } | null;
+    declare "_ambient_meta": { url: string } | null;
+    /**
+     * Whether the ambient bed is actually playing: `HTMLMediaElement.paused`
+     * cannot be trusted here (test doubles and pre-gesture elements report
+     * stale state), so the viewer tracks it explicitly.
+     */
+    declare "_ambient_playing": boolean;
     /** Guards a stale play() from a slide change that already moved on. */
     declare "_narration_token": number;
     /** Whether narration consent was granted (asked once per story). */
@@ -191,12 +200,16 @@ class StoryMapBase {
     declare "_collapsed": boolean;
     /** the data source was a IIIF Presentation manifest (legacy zoomify options are ignored) */
     declare "_data_from_manifest": boolean;
+    /** the data source was a slideshow tour (slideshow-only features apply) */
+    declare "_data_from_slideshow": boolean;
     declare "_resize_observer": ResizeObserver | null;
     /** Stored so `dispose()` can remove them again (see AGENTS: no leaks) */
     declare "_on_resize": (() => void) | null;
     declare "_on_keydown_global": ((e: KeyboardEvent) => void) | null;
     declare "_on_fullscreen": (() => void) | null;
     declare "_on_hashchange": (() => void) | null;
+    /** Reduced-motion toggles mid-story stop the advance timer. */
+    declare "_on_reduced_motion": ((e: MediaQueryListEvent) => void) | null;
     /** Set by `dispose()` so a second call returns early. */
     declare "_disposed": boolean;
     /** identity of this viewer's claim on the page-wide locale */
@@ -207,11 +220,7 @@ class StoryMapBase {
     declare "_interaction": number;
     declare "_onInteraction": (() => void) | null;
     declare "_resize_timer": ReturnType<typeof setTimeout> | null;
-    declare "fire": EventedInstance["fire"];
-    declare "hasEventListeners": EventedInstance["hasEventListeners"];
-
-    // TODO: mixin
-    // includes: VCO.Events,
+    declare "fire": EventedInstance<StoryMapEvents>["fire"];
 
     /*	Private Methods
 	================================================== */
@@ -231,26 +240,25 @@ class StoryMapBase {
         elem: string | HTMLElement,
         data: string | StorymapDataWrapper | Record<string, unknown>,
         options?: Partial<StorymapOptions>,
-        listeners?: Record<string, StoryMapListener | StoryMapListener[]>,
+        listeners?: { [K in keyof StoryMapEvents]?: StoryMapListener<K> | StoryMapListener<K>[] },
     ) {
         for (const key in listeners) {
-            const callbacks = listeners[key];
-            if (typeof callbacks == "function") {
-                this.on(key, callbacks);
-            } else {
-                for (const idx in callbacks) {
-                    if (typeof callbacks[idx] == "function") {
-                        this.on(key, callbacks[idx]);
-                    } else {
-                        console.log(
-                            "WARNING: Ignoring invalid callback '" +
-                                callbacks[idx] +
-                                "' defined for " +
-                                "listener '" +
-                                key +
-                                "' in StoryMap constructor",
-                        );
-                    }
+            const type = key as keyof StoryMapEvents;
+            const callbacks = listeners[type];
+            if (callbacks === undefined) continue;
+            const list = typeof callbacks == "function" ? [callbacks] : callbacks;
+            for (const callback of list) {
+                if (typeof callback == "function") {
+                    this.on(type, callback as StoryMapListener);
+                } else {
+                    console.warn(
+                        "WARNING: Ignoring invalid callback '" +
+                            callback +
+                            "' defined for " +
+                            "listener '" +
+                            key +
+                            "' in StoryMap constructor",
+                    );
                 }
             }
         }
@@ -333,11 +341,25 @@ class StoryMapBase {
             trackResize: true,
             keyboard: false,
             nocache: false,
+            slideshow: true,
             autoplay: 0,
             autoplay_media: false,
             show_progress: false,
+            progressbar: undefined,
             marker_labels: false,
             text_align: "left",
+            textmode: "right",
+            textsize: undefined,
+            fxmode: "slide",
+            mode: "standard",
+            hudcolor: "",
+            hudbgcolor: "",
+            hudopacity: undefined,
+            shownav: true,
+            show_headings: true,
+            show_scrollbars: true,
+            viewerheight: "",
+            show_info: true,
             map_overview_center: null,
             map_type: "", // "osm:standard",
             tile_source_factory: null,
@@ -355,6 +377,8 @@ class StoryMapBase {
             // that already exist here, so storymap JSON could not reach them
             overview_extent: null,
             overlays: [],
+            show_layers_control: false,
+            basemaps: undefined,
             // TileJSON 2.1 metadata for a tile-source basemap; a keyword
             // basemap has none (interop §2.9)
             tilejson: undefined,
@@ -396,6 +420,7 @@ class StoryMapBase {
         this._on_keydown_global = null;
         this._on_fullscreen = null;
         this._on_hashchange = null;
+        this._on_reduced_motion = null;
         this._raw_manifest = null;
         this._initial_deep_link = null;
         this._disposed = false;
@@ -408,6 +433,10 @@ class StoryMapBase {
         this._transition_timer = null;
         this._autoplay_stopped = false;
         this._narration_el = null;
+        this._ambient_el = null;
+        this._narration_meta = null;
+        this._ambient_meta = null;
+        this._ambient_playing = false;
         this._narration_token = 0;
         this._narration_allowed = true;
         this._user_gestured = false;
@@ -445,6 +474,10 @@ class StoryMapBase {
         // legacy zoomify options are only honored for storymap JSON sources —
         // a IIIF Presentation manifest cannot carry them
         this._data_from_manifest = false;
+        // slideshow tours unlock the slideshow-only presentation fields; the
+        // translator branch that sets this lives with the translator phase —
+        // until then only an explicit host flag (see slideshow_source) sets it
+        this._data_from_slideshow = false;
         if (typeof data === "string") {
             // issue #417: optional cache-busting re-fetch of the source file
             const url =
@@ -459,6 +492,12 @@ class StoryMapBase {
                 this._data_from_manifest = true;
                 this._raw_manifest = data;
                 this.data = manifestToStorymapData(data);
+            } else if (this.options.slideshow !== false && isSlideshowCollection(data)) {
+                this._data_from_slideshow = true;
+                const { data: storymap, warnings } = slideshowToStorymapData(data);
+                this._warnSlideshow(warnings);
+                validateStorymapAndReport({ storymap }, "slideshow");
+                this.data = storymap;
             } else {
                 const wrapper = data as StorymapDataWrapper;
                 validateStorymapAndReport(wrapper);
@@ -477,6 +516,56 @@ class StoryMapBase {
 
     /* Load storymap data from a URL
 	================================================== */
+    /**
+     * One `console.warn` per warning kind: count, detail and sample ids.
+     * Translation losses are loud exactly once, never per slide. Shared
+     * formatting with the CLI (see `formatSlideshowWarning`).
+     */
+    _warnSlideshow(warnings: SlideshowWarning[]): void {
+        for (const warning of warnings) {
+            console.warn(`StoryMapJS: ${formatSlideshowWarning(warning)}`);
+        }
+    }
+
+    /**
+     * Follow a tour's `first.next` page chain, returning the following pages
+     * for the translator. Bounded (20) and cycle-guarded; a broken chain
+     * reports incompletely so the caller warns instead of truncating
+     * silently. Relative links resolve against the tour URL.
+     */
+    async _followSlideshowPages(
+        doc: unknown,
+        url: string,
+    ): Promise<{ pages: unknown[]; complete: boolean }> {
+        // relative tour URLs (harness, subpath deploys) resolve against the
+        // page; an unresolvable base still lets absolute links through
+        let base = url;
+        try {
+            base = new URL(url, window.location.href).href;
+        } catch {
+            // keep the raw url
+        }
+        const first = (doc as Record<string, unknown> | null)?.first;
+        return followSlideshowPages({
+            first,
+            base,
+            resolve: (link, current) => {
+                try {
+                    return new URL(link, current).href;
+                } catch {
+                    return null;
+                }
+            },
+            load: async (absolute: string) => {
+                const response = await fetch(absolute);
+                if (!response.ok) {
+                    throw new Error(`HTTP ${response.status} ${response.statusText}`);
+                }
+                return response.json() as Promise<unknown>;
+            },
+        });
+    }
+
     async _loadDataFromUrl(url: string, source: string) {
         try {
             const response = await fetch(url);
@@ -495,6 +584,28 @@ class StoryMapBase {
                 this._data_from_manifest = true;
                 this._raw_manifest = result;
                 this.data = manifestToStorymapData(result);
+            } else if (this.options.slideshow !== false && isSlideshowCollection(result)) {
+                this._data_from_slideshow = true;
+                const followed = await this._followSlideshowPages(result, url);
+                if (this._disposed) {
+                    return;
+                }
+                const { data: storymap, warnings } = slideshowToStorymapData(result, {
+                    extraPages: followed.pages,
+                });
+                this._warnSlideshow(warnings);
+                if (!followed.complete) {
+                    this._warnSlideshow([
+                        {
+                            kind: "slideshow.paging",
+                            count: 1,
+                            sampleIds: [],
+                            detail: "page chain broke, tour may be truncated",
+                        },
+                    ]);
+                }
+                validateStorymapAndReport({ storymap }, source);
+                this.data = storymap;
             } else {
                 validateStorymapAndReport(result, source);
                 const wrapper = result as StorymapDataWrapper;
@@ -520,10 +631,62 @@ class StoryMapBase {
 
     /* Initialize the options
 	================================================== */
+    /**
+     * Reset every slideshow-only option to its long-standing default unless
+     * the loaded tour came from a slideshow source. Internal documents keep
+     * the pre-existing rendering even when they (or a host, via
+     * setMapOptions) name the new keys; slideshow tours keep what the
+     * translator emitted. Runs on every load and every runtime option change,
+     * over the viewer options and (at runtime) the map's own options copy.
+     */
+    _normalizeNonSlideshowOptions(options: StorymapOptions = this.options): void {
+        if (options.slideshow_source === true) return;
+        options.textmode = "right";
+        options.textsize = undefined;
+        options.fxmode = "slide";
+        options.mode = "standard";
+        options.hudcolor = "";
+        options.hudbgcolor = "";
+        options.hudopacity = undefined;
+        options.shownav = true;
+        options.show_headings = true;
+        options.show_scrollbars = true;
+        options.viewerheight = "";
+        options.show_info = true;
+        options.progressbar = undefined;
+    }
+
     _initOptions() {
         // Grab options from storymap data
         updateData(this.options, this.data);
 
+        // Source marker for the slideshow-only presentation fields: set
+        // programmatically from the load path, never from data (the key is
+        // absent from defaults and schema, so updateData above cannot inject
+        // it — a host may still pass it explicitly as an escape hatch).
+        if (this._data_from_slideshow) {
+            this.options.slideshow_source = true;
+        }
+        // Slideshow-only chrome stays inert for internal documents: reset
+        // every such option to its default unless the tour came from a
+        // slideshow source. this.data itself is never touched (it is the
+        // host's object — see data-immutable.test.ts).
+        this._normalizeNonSlideshowOptions();
+        // Story credit (slideshow `creator`/`rights`) joins the map
+        // attribution line for slideshow tours only; the line re-sanitizes
+        // its input, so author strings render as text. Internal documents
+        // keep their own attribution untouched.
+        if (this._data_from_slideshow && this.data.credit) {
+            const credit = [this.data.credit.creator, this.data.credit.rights].filter(
+                (part): part is string => typeof part === "string" && part !== "",
+            );
+            if (credit.length > 0) {
+                this.options.attribution = [this.options.attribution, ...credit]
+                    .filter((part) => part !== "")
+                    .join(" · ");
+            }
+        }
+
         // Capture the deep link now, before the slider and map exist and can
         // navigate — and so rewrite the URL we would read it from later.
         this._initial_deep_link = {
@@ -550,9 +713,19 @@ class StoryMapBase {
             // map_area "left": the map is limited to the visible half with an
             // opaque slide panel — no offset needed (the view center is the
             // visible center already); "full" (default) offsets the view so
-            // markers clear the panel that fades in over the map
+            // markers clear the panel that fades in over the map. A left
+            // text panel (textmode "left") mirrors the offset.
             if (this.options.map_area !== "left") {
-                this.options.map_center_offset = { left: -200, top: 0 };
+                // side docks offset the view past the panel (mirrored for a
+                // left panel); a bottom dock recenters slightly upward so
+                // point stops clear the panel (fits use measured padding)
+                if (this.options.textmode === "left") {
+                    this.options.map_center_offset = { left: 200, top: 0 };
+                } else if (this.options.textmode === "bottom") {
+                    this.options.map_center_offset = { left: 0, top: -120 };
+                } else {
+                    this.options.map_center_offset = { left: -200, top: 0 };
+                }
             } else {
                 this.options.map_center_offset = { left: 0, top: 0 };
             }
@@ -591,6 +764,21 @@ class StoryMapBase {
             this.options.map_type = "";
         }
 
+        // Entry 0 of `basemaps` is the initial basemap unless `map_type` says
+        // otherwise ("" counts as "not saying": it is the default, not a
+        // choice). Omit `basemaps` for an overlays-only control.
+        const basemaps = this.options.basemaps;
+        if (
+            this.options.map_type === "" &&
+            Array.isArray(basemaps) &&
+            basemaps.length > 0 &&
+            typeof basemaps[0]?.map_type === "string" &&
+            basemaps[0].map_type !== "" &&
+            basemaps[0].map_type !== "none"
+        ) {
+            this.options.map_type = basemaps[0].map_type;
+        }
+
         // "none" is the only way to say there is no map. An absent key or ""
         // keeps meaning OSM, so no existing document changes meaning.
         this._map_disabled = this.options.map_type === "none";
@@ -603,7 +791,7 @@ class StoryMapBase {
             } else {
                 this.options.map_type = "osm:standard";
             }
-            console.log(`Deprecated map_type ${old_type}; using ${this.options.map_type}`);
+            console.warn(`Deprecated map_type ${old_type}; using ${this.options.map_type}`);
         }
 
         this._loadLanguage();
@@ -684,8 +872,14 @@ class StoryMapBase {
     async _loadFontCss() {
         // only genuinely external URLs ask for consent: stock: themes and
         // relative paths resolve to same-origin / library assets
-        const original = this.options.font_css || "stock:default";
+        const original = fontCssOriginal(this.options.font_css);
+        if (original === null) {
+            // the theme ships in the host bundle (font_css: false): nothing
+            // to inject and no consent row for it
+            return;
+        }
         const font = resolveFontCssUrl(original);
+        if (font === null) return; // only "none" maps to null, handled above
         const manager = consentManagerOf(this.options);
         const external = /^(http|https|\/\/)/.test(original);
         if (external && this.options.consent_required && manager) {
@@ -760,6 +954,10 @@ class StoryMapBase {
         if (navigate !== "map") {
             this._map?.goTo(this.current_slide);
         }
+        // Per-slide image overlay (slideshow imgoverlay): shown while its
+        // slide is active, cleared otherwise. Null-safe: mapless stories
+        // have no map, slides without one clear a previous overlay.
+        this._map?.setSlideImageOverlay(this.data.slides?.[this.current_slide]?.imgoverlay ?? null);
         this._beginTransition(duration);
         if (!navigated) {
             // programmatic navigation reports outward like interaction does;
@@ -768,17 +966,14 @@ class StoryMapBase {
             // `current_id` so a host can tell *which stop* it is on, not just
             // how far along it is: an index moves when a slide is inserted, an
             // id does not (§5.1)
-            this.fire(
-                "change",
-                {
-                    current_slide: this.current_slide,
-                    current_id: this._currentSlideId(),
-                },
-                this,
-            );
+            this.fire("change", {
+                current_slide: this.current_slide,
+                current_id: this._currentSlideId(),
+            });
         }
         this._syncHash();
         this._playNarration(this.data.slides?.[this.current_slide]);
+        this._stopAmbientSlideMedia(this.data.slides?.[this.current_slide]);
         this._scheduleAutoplay();
         this._updateProgress();
     }
@@ -793,10 +988,10 @@ class StoryMapBase {
         if (this._transition_timer) {
             clearTimeout(this._transition_timer);
         }
-        this.fire("transitionstart", { current_slide: this.current_slide, duration }, this);
+        this.fire("transitionstart", { current_slide: this.current_slide, duration });
         this._transition_timer = setTimeout(() => {
             this._transition_timer = null;
-            this.fire("transitionend", { current_slide: this.current_slide }, this);
+            this.fire("transitionend", { current_slide: this.current_slide });
         }, duration);
     }
 
@@ -883,13 +1078,21 @@ class StoryMapBase {
             }
         }
         mergeData(this.options, effective);
+        // slideshow-only keys stay inert for internal documents at runtime too
+        this._normalizeNonSlideshowOptions();
         if (this._map && this._map.options) {
             mergeData(this._map.options, effective);
+            this._normalizeNonSlideshowOptions(this._map.options);
             this._map.applyOptions(Object.keys(effective));
         }
         if (this.ready) {
             // text color theming follows runtime option changes (issue #177)
             this._applyTextColors();
+            // slideshow chrome that maps onto container state does too;
+            // layout modes (textmode, mode) need a display pass to take effect
+            this._applyChrome();
+            // layers may have been added, removed or re-projected
+            this._menubar.refreshLayers();
             this.updateDisplay();
         }
     }
@@ -1010,7 +1213,7 @@ class StoryMapBase {
             this._updateDistance();
         }
         const result = { stops: added, searchService: loaded.searchService, failed: loaded.failed };
-        this.fire("annotationsloaded", result, this);
+        this.fire("annotationsloaded", result);
         return result;
     }
 
@@ -1065,6 +1268,12 @@ class StoryMapBase {
             window.removeEventListener("hashchange", this._on_hashchange);
             this._on_hashchange = null;
         }
+        if (this._on_reduced_motion && typeof window.matchMedia === "function") {
+            window
+                .matchMedia(REDUCED_MOTION_QUERY)
+                .removeEventListener("change", this._on_reduced_motion);
+            this._on_reduced_motion = null;
+        }
 
         // slide transitions in flight (Web Animations API)
         for (const el of [this._el?.container, this._el?.map]) {
@@ -1076,10 +1285,39 @@ class StoryMapBase {
         consentManagerOf(this.options)?.dispose();
 
         this._stopNarration();
+        this._stopAmbient();
         if (this._narration_el) {
             this._narration_el.src = "";
             this._narration_el = null;
         }
+        if (this._ambient_el) {
+            this._ambient_el.src = "";
+            this._ambient_el = null;
+        }
+        this._narration_meta = null;
+        this._ambient_meta = null;
+        // detach the child subscriptions so a host holding a documented
+        // child handle (storymap._map) cannot keep this viewer alive
+        // through the listener contexts
+        this._map?.off("loaded", this._onMapLoaded, this);
+        this._map?.off("change", this._onMapChange, this);
+        this._map?.off("imageready", this._onImageReady, this);
+        this._map?.off("popupopen", this._onMarkerPopupOpen, this);
+        this._map?.off("popupclose", this._onMarkerPopupClose, this);
+        this._map?.off("markerclick", this._onMarkerClick, this);
+        this._map?.off("tilesallowed", this._onTilesAllowed, this);
+        this._storyslider?.off("loaded", this._onStorySliderLoaded, this);
+        this._storyslider?.off("title", this._onTitle, this);
+        this._storyslider?.off("change", this._onSlideChange, this);
+        this._storyslider?.off("colorchange", this._onColorChange, this);
+        this._menubar?.off("collapse", this._onMenuBarCollapse, this);
+        this._menubar?.off("back_to_start", this._onBackToStart, this);
+        this._menubar?.off("overview", this._onOverview, this);
+        this._menubar?.off("fullscreen", this._onFullscreenToggle, this);
+        this._menubar?.off("basemapchange", this._onLayersBasemap, this);
+        this._menubar?.off("overlaychange", this._onLayersOverlay, this);
+        this._menubar?.off("autoplay_toggle", this._onAutoplayToggle, this);
+        this._menubar?.off("progress_go", this._onProgressGo, this);
         this._storyslider?.dispose?.();
         this._menubar?.dispose?.();
         this._map?.dispose?.();
@@ -1143,6 +1381,53 @@ class StoryMapBase {
         return !this._disposed && this._map ? this._map.getMarker(index) : null;
     }
 
+    /**
+     * Open the popup card for slide `n`'s marker, navigating there first
+     * when it is not the current slide.
+     *
+     * Returns false (and changes nothing) when the viewer is disposed,
+     * has no map (`map_type: "none"`), `n` is out of range, or the marker
+     * has popups disabled. Navigating fires the usual `change` (and
+     * transition) events; a successful open fires `popupopen`.
+     */
+    openMarkerPopup(n: number): boolean {
+        if (this._disposed) return false;
+        if (!Number.isInteger(n) || n < 0 || n >= (this.data?.slides?.length ?? 0)) {
+            return false;
+        }
+        if (this._map === null || this._map === undefined) return false;
+        const marker = this._map.getMarker(n);
+        if (!marker || !marker.isPopupEnabled()) return false;
+        if (n !== this.current_slide) {
+            this.goTo(n);
+        }
+        return marker.openPopup();
+    }
+
+    /**
+     * Close one marker's popup card (`n` given) or every open card
+     * (omitted). No-op when the viewer is disposed or mapless. Fires
+     * `popupclose` per card actually closed.
+     */
+    closeMarkerPopup(n?: number): void {
+        if (this._disposed) return;
+        if (this._map === null || this._map === undefined) return;
+        if (n === undefined) {
+            for (const marker of this._map.getMarkers()) {
+                marker.closePopup();
+            }
+            return;
+        }
+        this._map.getMarker(n)?.closePopup();
+    }
+
+    /** Whether slide `n`'s marker card is currently open. */
+    isPopupOpen(n: number): boolean {
+        if (this._disposed) return false;
+        if (this._map === null || this._map === undefined) return false;
+        return this._map.getMarker(n)?.popupOpen ?? false;
+    }
+
     /**
      * Rebuild the minimap (`OverviewMap` control). The constructor already
      * builds it; this is for hosts that recreate it after a `map_type` swap
@@ -1179,6 +1464,78 @@ class StoryMapBase {
         }
     }
 
+    /**
+     * Publish the slideshow-driven player chrome as container state.
+     * Everything here is opt-in: unset options leave the container exactly
+     * as the long-standing layout does, so existing stories are unaffected.
+     */
+    _applyChrome(): void {
+        const options = this.options;
+        const container = this._el.container;
+        // idempotent: runtime option changes re-run this, so previous state
+        // is cleared first (unset means the long-standing layout)
+        container.classList.remove(
+            "vco-textmode-left",
+            "vco-textmode-bottom",
+            "vco-no-headings",
+            "vco-no-scrollbars",
+            "vco-mode-static",
+        );
+        if (options.hudcolor) {
+            container.style.setProperty("--vco-hud-fg", options.hudcolor);
+        } else {
+            container.style.removeProperty("--vco-hud-fg");
+        }
+        if (options.hudbgcolor) {
+            const opacity = asClampedNumber(options.hudopacity, 0, 100);
+            container.style.setProperty(
+                "--vco-hud-bg",
+                opacity === null
+                    ? options.hudbgcolor
+                    : `color-mix(in srgb, ${options.hudbgcolor} ${Math.round(opacity)}%, transparent)`,
+            );
+        } else {
+            container.style.removeProperty("--vco-hud-bg");
+        }
+        if (typeof options.viewerheight === "string" && options.viewerheight !== "") {
+            container.style.height = options.viewerheight;
+        } else {
+            container.style.removeProperty("height");
+        }
+        if (options.textmode === "left" || options.textmode === "bottom") {
+            container.classList.add(`vco-textmode-${options.textmode}`);
+        }
+        if (options.show_headings === false) {
+            container.classList.add("vco-no-headings");
+        }
+        if (options.show_scrollbars === false) {
+            container.classList.add("vco-no-scrollbars");
+        }
+        if (options.mode === "static") {
+            container.classList.add("vco-mode-static");
+        }
+        const textsize = options.textsize;
+        if (typeof textsize === "number" && Number.isFinite(textsize)) {
+            const clamped = asClampedNumber(textsize, 10, 80) ?? 50;
+            container.style.setProperty("--vco-panel-size", `${clamped}%`);
+        } else {
+            container.style.removeProperty("--vco-panel-size");
+        }
+    }
+
+    /**
+     * The slide panel share of the width (side docks) or height (bottom
+     * dock) as a fraction: `textsize` percent when valid (10..80), else the
+     * built-in split (half for sides, 40% height for the bottom dock).
+     */
+    _panelShare(): number {
+        const textsize = this.options.textsize;
+        if (typeof textsize === "number" && Number.isFinite(textsize)) {
+            return (asClampedNumber(textsize, 10, 80) ?? 50) / 100;
+        }
+        return this.options.textmode === "bottom" ? 0.4 : 0.5;
+    }
+
     /*	Private Methods
 	================================================== */
 
@@ -1190,6 +1547,18 @@ class StoryMapBase {
         this._el.container.className += " vco-storymap";
         this.options.base_class = this._el.container.className;
 
+        // slideshow-driven player chrome first: viewerheight is an inline
+        // height that the measurement below must see (classes are re-applied
+        // in _updateDisplay, which rebuilds className from base_class)
+        this._applyChrome();
+
+        // Colour theme (dark theme plan): an explicit option pins the
+        // palette via data-vco-theme; unset, the CSS falls back to
+        // prefers-color-scheme. Construction-time only.
+        if (this.options.theme === "dark" || this.options.theme === "light") {
+            this._el.container.setAttribute("data-vco-theme", this.options.theme);
+        }
+
         // Text color theming (issue #177): expose the text colors as CSS
         // custom properties consumed by the slide typography
         this._applyTextColors();
@@ -1200,6 +1569,17 @@ class StoryMapBase {
             ? null
             : (this._resolveMapElement() ?? Dom.create("div", "vco-map", this._el.container));
         this._el.storyslider = Dom.create("div", "vco-storyslider", this._el.container);
+        // Skip link (a11y): first tab stop inside the widget, jumping to
+        // the slide content. Only when the host container has an id to
+        // anchor both ends to (multi-viewer pages need unique targets).
+        if (this._el.container.id !== "") {
+            this._el.storyslider.id = `${this._el.container.id}-slides`;
+            const skip = Dom.create("a", "vco-skip-link", this._el.container);
+            skip.setAttribute("href", `#${this._el.storyslider.id}`);
+            skip.textContent =
+                (Language.messages.skip_link as string | undefined) ?? "Skip to story content";
+            this._el.container.prepend(skip);
+        }
 
         // Initial Default Layout
         this.options.width = this._el.container.offsetWidth;
@@ -1229,9 +1609,7 @@ class StoryMapBase {
             // image readiness (IIIF/zoomify sources attach asynchronously) is
             // re-fired on the StoryMap, the coordination point for hosts that
             // overlay or measure their own layers
-            this._map.on("imageready", (e: unknown) => {
-                this.fire("imageready", e);
-            });
+            this._map.on("imageready", this._onImageReady, this);
 
             // Map Background Color
             this._map_el().style.backgroundColor = this.options.map_background_color;
@@ -1239,6 +1617,10 @@ class StoryMapBase {
 
         // Create Menu Bar
         this._menubar = new MenuBar(this._el.menubar, this._el.container, this.options);
+        // the progress chrome carries its initial state from construction,
+        // not from the first map/slider load event — otherwise the bar (and
+        // its ARIA) sits uninitialized until tiles arrive (issue #247)
+        this._updateProgress();
 
         // Create StorySlider
         this._storyslider = new StorySlider(this._el.storyslider, this.data, this.options);
@@ -1287,6 +1669,16 @@ class StoryMapBase {
 
         // Map Events
         this._map?.on("change", this._onMapChange, this);
+        this._map?.on("popupopen", this._onMarkerPopupOpen, this);
+        this._map?.on("popupclose", this._onMarkerPopupClose, this);
+        this._map?.on("markerclick", this._onMarkerClick, this);
+        this._map?.on("tilesallowed", this._onTilesAllowed, this);
+        this._menubar.on("basemapchange", this._onLayersBasemap, this);
+        this._menubar.on("overlaychange", this._onLayersOverlay, this);
+        this._menubar.on("autoplay_toggle", this._onAutoplayToggle, this);
+        this._menubar.on("progress_go", this._onProgressGo, this);
+        this._menubar.setLayersDelegate({ rows: () => this._layersRows() });
+        this._menubar.refreshLayers();
 
         // Global slide navigation (opt-in): the slider only listens on its
         // own panel, which needs focus.
@@ -1313,6 +1705,18 @@ class StoryMapBase {
         // Fullscreen state
         this._on_fullscreen = () => this._onFullscreenChange();
         document.addEventListener("fullscreenchange", this._on_fullscreen);
+
+        // An OS reduced-motion toggle mid-story stops automatic advancement;
+        // the next navigation's _scheduleAutoplay re-checks anyway, but an
+        // armed timer would otherwise fire once more first.
+        if (typeof window.matchMedia === "function") {
+            this._on_reduced_motion = (e: MediaQueryListEvent) => {
+                if (e.matches) this._stopAutoplay();
+            };
+            window
+                .matchMedia(REDUCED_MOTION_QUERY)
+                .addEventListener("change", this._on_reduced_motion);
+        }
     }
 
     _onKeyDownGlobal(e: KeyboardEvent) {
@@ -1511,23 +1915,53 @@ class StoryMapBase {
                 display_class += " vco-map-area-left";
                 this._map_el().style.width = Math.floor(this.options.width / 2) + "px";
                 this._map_required().setMapOffset(0, 0);
+            } else if (this.options.textmode === "bottom") {
+                // bottom dock: the map takes the top share, the slider the
+                // bottom share (like the portrait split, but keeping the
+                // landscape slide styling)
+                display_class += " vco-textmode-bottom";
+                const share = this._panelShare();
+                this.options.map_height = Math.floor(this.options.height * (1 - share));
+                this.options.storyslider_height = this.options.height - this.options.map_height - 1;
+                this._map_el().style.width = "100%";
+                this._map_el().style.height = this.options.map_height + "px";
+                this._map_required().setMapOffset(0, 0);
+                this._el.storyslider.style.top = this.options.map_height + "px";
+                this._el.storyslider.style.height = this.options.storyslider_height + "px";
+                this._menubar.updateDisplay(this.options.width, this.options.height, animate);
+                this._map_required().updateDisplay(
+                    this.options.width,
+                    this.options.height,
+                    animate,
+                    d,
+                );
+                this._storyslider.updateDisplay(
+                    this.options.width,
+                    this.options.storyslider_height,
+                    animate,
+                    this.options.layout,
+                );
             } else {
                 this._map_el().style.width = "100%";
                 this._map_required().setMapOffset(-(this.options.width / 4), 0);
-            }
-
-            // StorySlider
-            this._el.storyslider.style.top = "0";
-            this._el.storyslider.style.height = this.options.storyslider_height + "px";
+                // StorySlider
+                this._el.storyslider.style.top = "0";
+                this._el.storyslider.style.height = this.options.storyslider_height + "px";
 
-            this._menubar.updateDisplay(this.options.width, this.options.height, animate);
-            this._map_required().updateDisplay(this.options.width, this.options.height, animate, d);
-            this._storyslider.updateDisplay(
-                this.options.width / 2,
-                this.options.storyslider_height,
-                animate,
-                this.options.layout,
-            );
+                this._menubar.updateDisplay(this.options.width, this.options.height, animate);
+                this._map_required().updateDisplay(
+                    this.options.width,
+                    this.options.height,
+                    animate,
+                    d,
+                );
+                this._storyslider.updateDisplay(
+                    this.options.width * this._panelShare(),
+                    this.options.storyslider_height,
+                    animate,
+                    this.options.layout,
+                );
+            }
         }
 
         // the resolved locale decides the layout direction (issues #211, #245)
@@ -1537,6 +1971,10 @@ class StoryMapBase {
 
         // Apply class
         this._el.container.className = display_class;
+        // _updateDisplay rebuilds the container class from base_class, which
+        // wipes the opt-in chrome state _initLayout applied — re-apply it
+        // after every layout pass (init, resize, runtime option changes)
+        this._applyChrome();
     }
 
     /*	Events
@@ -1589,14 +2027,18 @@ class StoryMapBase {
         // to have no slides at all)
         const seen = new Set<string>();
         for (const slide of this.data.slides ?? []) {
-            const url = (slide.media as { url?: string | null } | null)?.url;
-            if (!url) continue;
-            const match = MediaType({ url } as never) as { type: string; name: string } | false;
-            if (!match || seen.has(match.type)) continue;
-            seen.add(match.type);
-            // same registry the per-slide panel uses, so the two dialogs can
-            // never disagree about a service's name
-            services.push(mediaService(match.type, match.name));
+            // every visible media item is its own service (#358)
+            const items = [slide.media, ...(slide.media_extra ?? [])];
+            for (const item of items) {
+                const url = (item as { url?: string | null } | null)?.url;
+                if (!url) continue;
+                const match = MediaType({ url } as never) as { type: string; name: string } | false;
+                if (!match || seen.has(match.type)) continue;
+                seen.add(match.type);
+                // same registry the per-slide panel uses, so the two dialogs can
+                // never disagree about a service's name
+                services.push(mediaService(match.type, match.name));
+            }
         }
         // Slide narration is its own service: the recording plays through a
         // dedicated audio element, not through Media, so nothing else asks
@@ -1611,16 +2053,21 @@ class StoryMapBase {
         // origin, not by a prefix test on the resolved URL: resolveFontCssUrl
         // has already turned a relative path into an absolute one, so testing
         // that for "http" made every relative font_css look external.
-        const font = resolveFontCssUrl(this.options.font_css || "stock:default");
-        if (isExternalUrl(font)) {
-            services.push(fontService());
+        // A host-bundled theme (font_css: false) loads no stylesheet, so it
+        // contributes no font service either.
+        const originalFontCss = fontCssOriginal(this.options.font_css);
+        if (originalFontCss !== null) {
+            const font = resolveFontCssUrl(originalFontCss);
+            if (font !== null && isExternalUrl(font)) {
+                services.push(fontService());
+            }
         }
         manager.requestAll(services, this._el.container);
     }
 
     /*  Autoplay (issue #380) and hash bookmarks (issue #146)
     ================================================== */
-    /*  Narration (docs/plans/iiif-media-tours.md §2)
+    /*  Narration
     ================================================== */
 
     /**
@@ -1638,7 +2085,49 @@ class StoryMapBase {
      *   playback, and the story still works.
      */
     _playNarration(slide: StorymapSlide | undefined, allow_without_gesture = false) {
-        const url = (slide?.narration as { url?: string } | null)?.url;
+        // Slideshow-only playback flags render only for slideshow tours;
+        // internal documents play the bare URL exactly as before (no data is
+        // mutated — the bag is reduced to a local).
+        const raw = slide?.narration ?? null;
+        const bag =
+            this.options.slideshow_source === true
+                ? raw
+                : raw && typeof raw.url === "string"
+                  ? { url: raw.url }
+                  : null;
+        const url = typeof bag?.url === "string" && bag.url !== "" ? bag.url : null;
+        const persistent = bag?.stopOnExit === false;
+        if (url !== null && persistent) {
+            // An audio bed that outlives its slide (slideshow ambient
+            // audio): already playing this bed → keep it, dropping any
+            // foreground left over from the slide we came from. At most one
+            // ambient track plays; a new one replaces the old.
+            if (this._ambient_meta?.url === url && this._ambient_playing) {
+                this._stopNarration();
+                return;
+            }
+            this._stopNarration();
+            if (bag?.stopAllPrevious !== false) this._stopAmbient();
+            if (this._disposed || !this._narration_allowed) return;
+            if (!allow_without_gesture && !this._has_user_gesture()) {
+                this._replayNarrationAfterGesture = true;
+                return;
+            }
+            const el = this._ambientElement();
+            this._ambient_meta = { url };
+            this._startTrack(el, url, bag, allow_without_gesture);
+            return;
+        }
+        // An ephemeral track (or none): a newcomer that does not opt out of
+        // stopping replaces any ambient bed; a silent slide keeps a playing
+        // bed (it belongs to the tour, not to the slide we left).
+        if (url === null || bag?.stopAllPrevious !== false) {
+            if (url === null && this._ambient_playing) {
+                this._stopNarration();
+                return;
+            }
+            this._stopAmbient();
+        }
         this._stopNarration();
         if (!url || this._disposed || !this._narration_allowed) return;
         if (!allow_without_gesture && !this._has_user_gesture()) {
@@ -1646,16 +2135,111 @@ class StoryMapBase {
             return;
         }
         const el = this._narrationElement();
+        this._narration_meta = { url, stopOnExit: bag?.stopOnExit !== false };
+        this._startTrack(el, url, bag, allow_without_gesture);
+    }
+
+    /**
+     * Start (or arm) a narration track: loop flag, start offset once the
+     * metadata is available, and `play: "click"` arms paused for the
+     * visitor instead of playing (see `playNarration()`). A rejected play()
+     * (policy, network) must not surface as an unhandled rejection.
+     */
+    _startTrack(
+        el: HTMLAudioElement,
+        url: string,
+        bag: StorymapSlideNarration | null,
+        allow_without_gesture: boolean,
+    ) {
+        el.loop = bag?.loop === true;
         el.src = url;
-        el.currentTime = 0;
+        this._seekAudio(el, bag?.offset);
+        if (bag?.play === "click") return;
+        if (!allow_without_gesture && !this._has_user_gesture()) {
+            this._replayNarrationAfterGesture = true;
+            return;
+        }
+        if (el === this._ambient_el) {
+            this._ambient_playing = true;
+        }
+        const token = ++this._narration_token;
+        void el.play()?.catch?.(() => {
+            if (token !== this._narration_token) return;
+            // a failed start is not playing: the gesture retry must attempt
+            // it again rather than take the same-URL fast path
+            if (el === this._ambient_el) {
+                this._ambient_playing = false;
+            }
+            this._replayNarrationAfterGesture = true;
+        });
+    }
+
+    /**
+     * Start the current slide's click-armed narration (`narration.play:
+     * "click"`): the control for visitors (or hosts) to start a track that
+     * waits for them. Auto-armed tracks play on their own. No-op when
+     * nothing is armed. Prefers the current slide's own track: with an
+     * ambient bed running, the foreground it armed is the one to start.
+     */
+    playNarration(): void {
+        const bag = this.data.slides?.[this.current_slide]?.narration ?? null;
+        const persistent = bag?.stopOnExit === false && typeof bag?.url === "string";
+        const el =
+            persistent && this._ambient_meta?.url === bag?.url
+                ? this._ambient_el
+                : this._narration_el;
+        if (!el || !el.getAttribute("src")) return;
+        if (this._disposed || !this._narration_allowed || this._has_user_gesture() === false) {
+            this._replayNarrationAfterGesture = true;
+            return;
+        }
+        if (el === this._ambient_el) {
+            this._ambient_playing = true;
+        }
         const token = ++this._narration_token;
-        // a rejected play() (policy, network) must not surface as an
-        // unhandled rejection
         void el.play()?.catch?.(() => {
-            if (token === this._narration_token) this._replayNarrationAfterGesture = true;
+            if (token !== this._narration_token) return;
+            if (el === this._ambient_el) {
+                this._ambient_playing = false;
+            }
+            this._replayNarrationAfterGesture = true;
         });
     }
 
+    /**
+     * Seek to a start offset in seconds (slideshow `audio.offset`):
+     * immediately when the metadata is already there, otherwise once on
+     * `loadedmetadata`. Guarded by the narration token, so a quick
+     * pass-through cannot seek a newer track.
+     */
+    _seekAudio(el: HTMLAudioElement, offset: number | null | undefined) {
+        const target =
+            typeof offset === "number" && Number.isFinite(offset) && offset > 0 ? offset : 0;
+        const token = this._narration_token;
+        const apply = () => {
+            if (token !== this._narration_token || this._disposed) return;
+            try {
+                el.currentTime = target;
+            } catch {
+                // metadata not ready yet; the listener below retries
+            }
+        };
+        if (el.readyState >= 1) {
+            apply();
+            return;
+        }
+        const on_metadata = () => {
+            el.removeEventListener("loadedmetadata", on_metadata);
+            apply();
+        };
+        el.addEventListener("loadedmetadata", on_metadata);
+        try {
+            el.currentTime = target;
+        } catch {
+            // pre-metadata seek throws in some browsers; the listener covers it
+        }
+    }
+
     _narrationElement(): HTMLAudioElement {
         if (this._narration_el === null) {
             this._narration_el = document.createElement("audio");
@@ -1668,12 +2252,33 @@ class StoryMapBase {
 
     _stopNarration() {
         this._narration_token++;
+        this._narration_meta = null;
         const el = this._narration_el;
         if (!el) return;
         el.pause();
         el.removeAttribute("src");
     }
 
+    _ambientElement(): HTMLAudioElement {
+        if (this._ambient_el === null) {
+            this._ambient_el = document.createElement("audio");
+            this._ambient_el.className = "vco-media-item vco-ambient";
+            this._ambient_el.preload = "none";
+            this._ambient_el.setAttribute("aria-hidden", "true");
+        }
+        return this._ambient_el;
+    }
+
+    _stopAmbient() {
+        this._narration_token++;
+        this._ambient_meta = null;
+        this._ambient_playing = false;
+        const el = this._ambient_el;
+        if (!el) return;
+        el.pause();
+        el.removeAttribute("src");
+    }
+
     /** A gesture has happened, so unmuted audio is allowed from now on. */
     _note_user_gesture_for_narration() {
         if (this._disposed) return;
@@ -1710,10 +2315,16 @@ class StoryMapBase {
         }
         // prefers-reduced-motion: no autoplay (WCAG 2.2.2)
         if (this.options.autoplay > 0 && !prefersReducedMotion()) {
-            // any user interaction stops autoplay permanently
-            const stop = () => {
+            // any user interaction stops autoplay permanently — except on
+            // the pause/resume toggle itself, whose click would otherwise
+            // stop and immediately restart (net no-op instead of pause)
+            const stop = (e: Event) => {
+                if ((e.target as HTMLElement | null)?.closest?.(".vco-menubar-autoplay")) {
+                    return;
+                }
                 this._autoplay_stopped = true;
                 this._stopAutoplay();
+                this._menubar.setAutoplayState(true);
             };
             this._el.container.addEventListener("pointerdown", stop, { once: true });
             this._el.container.addEventListener("keydown", stop, { once: true });
@@ -1722,6 +2333,45 @@ class StoryMapBase {
         }
     }
 
+    /**
+     * Stop other slides' ambient audio beds when the new slide claims the
+     * audio: its narration (unless opted out via `stopAllPrevious: false`),
+     * or playable media that is actually playing (a paused click-to-play
+     * bed must not kill an inherited ambient track it never starts).
+     * A silent slide inherits a playing bed.
+     */
+    _stopAmbientSlideMedia(slide: StorymapSlide | undefined) {
+        const claimsNarration =
+            typeof slide?.narration?.url === "string" &&
+            slide.narration.url !== "" &&
+            slide.narration.stopAllPrevious !== false;
+        const claimsMedia =
+            (slide?.media as { stopAllPrevious?: boolean } | null | undefined)?.stopAllPrevious !==
+                false && this._isSlideMediaPlaying(this.current_slide);
+        if (!claimsNarration && !claimsMedia) return;
+        const slides = this._storyslider?._slides;
+        if (!slides) return;
+        slides.forEach((entry, index) => {
+            if (index !== this.current_slide) entry.stopAmbientMedia?.();
+        });
+    }
+
+    /**
+     * True when the slide's media element exists and is currently playing
+     * (not paused, not ended, not merely loadable).
+     */
+    _isSlideMediaPlaying(index: number): boolean {
+        const slide = this._storyslider?._slides?.[index];
+        const medias = (
+            slide as unknown as { _medias?: { player_element?: HTMLMediaElement | null }[] }
+        )?._medias;
+        if (!Array.isArray(medias)) return false;
+        return medias.some((media) => {
+            const el = media?.player_element;
+            return !!el && typeof el.paused === "boolean" && !el.paused && !el.ended;
+        });
+    }
+
     /**
      * Arm autoplay for the current slide.
      *
@@ -1737,6 +2387,10 @@ class StoryMapBase {
     _scheduleAutoplay() {
         this._stopAutoplay();
         if (!(this.options.autoplay > 0) || this._autoplay_stopped) return;
+        // the OS setting may have flipped mid-story: re-check on every arm
+        // so a reduced-motion switch stops future advances (the in-flight
+        // timer is cleared by the next navigation's _scheduleAutoplay)
+        if (prefersReducedMotion()) return;
 
         const advance = () => {
             this._stopAutoplay();
@@ -1747,14 +2401,33 @@ class StoryMapBase {
         };
         this._autoplay_advance = advance;
 
+        // Per-slide dwell (slideshow slidetimeout): overrides the global
+        // interval for this slide; 0 holds here even with autoplay on.
+        // Internal documents always use the global interval.
+        const rawTimeout = this.data.slides?.[this.current_slide]?.slidetimeout;
+        const slideTimeout = this.options.slideshow_source === true ? rawTimeout : undefined;
+        const dwell =
+            typeof slideTimeout === "number" && Number.isFinite(slideTimeout) && slideTimeout >= 0
+                ? slideTimeout
+                : this.options.autoplay;
+        if (!(dwell > 0)) return;
+
         if (this.options.autoplay_media) {
             const slide = this._storyslider?._slides?.[this.current_slide];
             if (slide?.hasPlayableMedia?.()) {
-                slide.onMediaEnded(advance);
+                // re-arming clears the previous advance: without this,
+                // revisits accumulate listeners and a stale ended (e.g. an
+                // ambient bed outliving its slide) advances the wrong slide.
+                // The index guard covers the race between clearing and firing.
+                slide.clearMediaEnded();
+                const armed = this.current_slide;
+                slide.onMediaEnded(() => {
+                    if (this.current_slide === armed) advance();
+                });
             }
         }
 
-        this._autoplay_timer = setTimeout(advance, this.options.autoplay);
+        this._autoplay_timer = setTimeout(advance, dwell);
     }
 
     _stopAutoplay() {
@@ -1959,7 +2632,7 @@ class StoryMapBase {
         return el;
     }
 
-    _onTitle(e: unknown) {
+    _onTitle(e: { title: string }) {
         this.fire("title", e);
     }
 
@@ -1985,8 +2658,148 @@ class StoryMapBase {
         }
     }
 
+    _onImageReady(e: ImagereadyPayload) {
+        this.fire("imageready", e);
+    }
+
+    _onMarkerPopupOpen(e: { marker_number: number }) {
+        this.fire("popupopen", {
+            marker_number: e.marker_number,
+            current_slide: this.current_slide,
+        });
+    }
+
+    _onMarkerPopupClose(e: { marker_number: number }) {
+        this.fire("popupclose", {
+            marker_number: e.marker_number,
+            current_slide: this.current_slide,
+        });
+    }
+
+    _onMarkerClick(e: { marker_number: number }) {
+        // Re-fired from the map surface so a host listening on the viewer
+        // sees marker clicks; the map already navigated itself.
+        this.fire("markerclick", {
+            marker_number: e.marker_number,
+            current_slide: this.current_slide,
+        });
+    }
+
+    _onLayersBasemap(e: { map_type: string }) {
+        const previous = this.options.map_type;
+        this.setMapOption("map_type", e.map_type);
+        this._menubar.refreshLayers();
+        this.fire("basemapchange", { map_type: e.map_type, previous });
+    }
+
+    _onLayersOverlay(e: { index: number; visible: boolean }) {
+        // setOverlayVisible re-syncs the attribution line; the checkbox
+        // already shows the new state, so no refresh (which would steal
+        // keyboard focus from the row just toggled)
+        this.setOverlayVisible(e.index, e.visible);
+        this.fire("overlaychange", { index: e.index, visible: e.visible });
+    }
+
+    _onAutoplayToggle() {
+        if (this._autoplay_stopped) {
+            this._autoplay_stopped = false;
+            this._scheduleAutoplay();
+        } else {
+            this._autoplay_stopped = true;
+            this._stopAutoplay();
+        }
+        this._menubar.setAutoplayState(this._autoplay_stopped);
+    }
+
+    _onProgressGo(e: { slide: number }) {
+        this.goTo(e.slide);
+    }
+
+    _onTilesAllowed() {
+        this._menubar.refreshLayers();
+    }
+
+    /**
+     * The layer switcher rows: allowed basemaps first, then built overlays.
+     * Empty while there is nothing to switch (mapless story, consent-denied
+     * tiles), in which case the control hides itself.
+     */
+    _layersRows(): LayersRow[] {
+        if (this._map_disabled || !this._map || !this._tilesAllowed()) {
+            return [];
+        }
+        const rows: LayersRow[] = [];
+        for (const basemap of this._allowedBasemaps()) {
+            const label = basemap.label;
+            rows.push({
+                kind: "basemap",
+                map_type: basemap.map_type,
+                label: typeof label === "function" ? label() : (label ?? basemap.map_type),
+                checked: basemap.map_type === this.options.map_type,
+            });
+        }
+        const entries = this._map.getOverlayEntries();
+        const layers = this._map.getOverlayLayers();
+        entries.forEach((entry, index) => {
+            if (entry.control === false) return;
+            const label = entry.label;
+            rows.push({
+                kind: "overlay",
+                index,
+                label: typeof label === "function" ? label() : (label ?? entry.map_type ?? ""),
+                checked: layers[index]?.getVisible() ?? entry.visible ?? true,
+                locked: entry.locked === true,
+            });
+        });
+        return rows;
+    }
+
+    /**
+     * Basemap candidates compatible with the live view. A runtime basemap
+     * swap rebuilds layers but never the view, so an image-space candidate
+     * (`iiif` with `map_as_image`) on a mercator view — or the reverse —
+     * would wrap the wrong projection around the tiles: markers land in the
+     * wrong place and zoom is meaningless. Refused candidates are dropped
+     * with a warning, like the existing `setMapOptions` declines.
+     */
+    _allowedBasemaps(): StorymapBasemap[] {
+        const basemaps = this.options.basemaps;
+        if (!Array.isArray(basemaps)) return [];
+        const live = this.map?.getView()?.getProjection()?.getCode() ?? null;
+        return basemaps.filter((entry) => {
+            const map_type = entry?.map_type;
+            if (typeof map_type !== "string" || map_type === "" || map_type === "none") {
+                console.warn(
+                    `StoryMapJS: ignoring basemaps entry without a usable map_type: ${String(map_type)}`,
+                );
+                return false;
+            }
+            // the same rule `_createMap` builds the view by: image-space is
+            // `iiif` with `map_as_image`, everything else is mercator
+            const candidate =
+                map_type === "iiif" && this.options.map_as_image ? "EPSG:4326" : "EPSG:3857";
+            if (live !== null && candidate !== live) {
+                console.warn(
+                    `StoryMapJS: ignoring basemap ${map_type}: it needs a ${candidate} view but the live view is ${live}`,
+                );
+                return false;
+            }
+            return true;
+        });
+    }
+
+    /** Whether deferred tile layers may attach (no consent gate, or granted). */
+    _tilesAllowed(): boolean {
+        if (!this.options.consent_required) return true;
+        const manager = consentManagerOf(this.options);
+        return manager ? manager.isGranted(tileService().key) : true;
+    }
+
     _updateProgress() {
-        if (this.options.show_progress && this._menubar) {
+        // any enabled style updates (the classic bar via show_progress, the
+        // variants via progressbar); a disabled indicator stays untouched so
+        // its ARIA never goes stale
+        if (this._menubar && this._menubar._progressStyle() !== "off") {
             this._menubar.setProgress(this.current_slide, this.data.slides.length);
         }
     }
@@ -2102,7 +2915,7 @@ class StoryMapBase {
     }
 }
 
-export default class StoryMap extends Evented(StoryMapBase) {
+export default class StoryMap extends Evented<StoryMapEvents, typeof StoryMapBase>(StoryMapBase) {
     /**
      * The library base path (the directory containing the module).
      * Derived from `import.meta.url`, which works both for the source module