@projektemacher/storymapjs 0.10.7 → 0.11.0

package/src/storymap/StoryMap.ts

@@ -1,43 +1,111 @@
-import { mergeData, slideTransitionDuration, updateData } from "../core/Util";
+import {
+    mergeData,
+    slideTransitionDuration,
+    updateData,
+    prefersReducedMotion,
+    REDUCED_MOTION_QUERY,
+} from "../core/Util";
 import { loadCSS } from "../core/Load";
 import { validateStorymapAndReport } from "./validate";
-import { isPresentation3Manifest, manifestToStorymapData } from "./iiif";
-import { ConsentManager, consentManagerOf, consentMessage } from "./Consent";
+import {
+    CONTENT_STATE_PARAM,
+    formatContentState,
+    parseContentState,
+    type ContentState,
+} from "./content-state";
+import {
+    isPresentation3Manifest,
+    isPresentation3Collection,
+    loadSeeAlso,
+    manifestToStorymapData,
+} from "./iiif";
+import {
+    followSlideshowPages,
+    formatSlideshowWarning,
+    isSlideshowCollection,
+    slideshowToStorymapData,
+    type SlideshowWarning,
+} from "./from-slideshow";
+import { asClampedNumber } from "./iiif-shared";
+import {
+    ConsentManager,
+    consentManagerOf,
+    fontService,
+    mediaService,
+    narrationService,
+    tileService,
+    type ConsentService,
+} from "./Consent";
 import Dom from "../dom/Dom";
 import { easeInOutQuint, easeOutStrong } from "../animation/easings";
-import { setLanguage, Language } from "../language/Language";
-import { Evented, type EventedInstance } from "../core/mixins";
+import {
+    setLanguage,
+    isRtl,
+    currentLanguageCode,
+    claimLanguage,
+    releaseLanguage,
+    isLanguageConflict,
+    Language,
+} from "../language/Language";
+import {
+    markInteraction,
+    ownsPageEvent,
+    registerParticipant,
+    unregisterParticipant,
+} from "../core/viewers";
+import MediaType from "../media/MediaType";
+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 "morpheus";
+import Animate from "../animation/tween";
 import type { Map as OlMap } from "ol";
-import type { AnimationHandle, StorymapData, StorymapDataWrapper, StorymapOptions } from "../types";
-
-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";
-        // 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;
-    }
-    if (!/^(http|https|\/\/)/.test(font)) {
-        return new URL(font, document.baseURI).href;
-    }
-    return font;
+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;
+
+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 };
 }
 
+type StoryMapListener<K extends keyof StoryMapEvents = keyof StoryMapEvents> = (
+    e: FiredEvent<StoryMapEvents, K>,
+) => void;
+
 /**
  * Interactive StoryMap viewer.
  *
@@ -46,7 +114,7 @@ export function resolveFontCssUrl(font: string): string {
  *
  * @example
  * ```ts
- * import { StoryMap } from "storymapjs";
+ * import { StoryMap } from "@projektemacher/storymapjs";
  * // from an inline data object
  * const map = new StoryMap("embed", { storymap: { ... } }, { start_at_slide: 2 });
  * // or straight from a source file (storymap JSON or IIIF manifest)
@@ -55,37 +123,104 @@ export function resolveFontCssUrl(font: string): string {
  */
 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": {
         container: HTMLElement;
         menubar: HTMLElement;
-        map: HTMLElement;
+        map: HTMLElement | null;
         storyslider: HTMLElement;
     };
     declare "_storyslider": StorySlider;
-    declare "_map": OpenLayersMap;
-    declare "map": OlMap;
+    declare "_map": OpenLayersMap | null;
+    /** `map_type: "none"`: the story is text-and-media, with no map at all. */
+    declare "_map_disabled": boolean;
+    /**
+     * The raw OpenLayers map. `null` until the map is built (the
+     * constructor assigns it during data load) — check it, or use the
+     * accessors, which return `null` until then.
+     */
+    declare "map": OlMap | null;
     declare "_menubar": MenuBar;
     declare "data": StorymapData;
     declare "options": StorymapOptions;
     declare "current_slide": number;
+    /**
+     * The manifest this viewer was built from, kept so `loadAnnotations()` can
+     * resolve its `seeAlso` targets. `null` for a storymap-JSON viewer, which
+     * has no `seeAlso`.
+     */
+    declare "_raw_manifest": unknown | null;
+    /**
+     * The deep link the page was opened with, captured before anything can
+     * rewrite the URL.
+     *
+     * This has to be read *early*. The slider's opening `goTo()` can reach
+     * `_navigate()` before `_onLoaded()` runs, and `_navigate()` calls
+     * `_syncHash()` — which would overwrite the incoming link with the current
+     * slide before `_onLoaded()` ever looked at it. Whether that happens
+     * depends on the order the slider and map finish loading, which is exactly
+     * the kind of race that makes a deep link work most of the time.
+     */
+    declare "_initial_deep_link": { state: ContentState | null; hash: string } | null;
     declare "animator_map": AnimationHandle | null;
     declare "animator_storyslider": AnimationHandle | null;
     declare "_autoplay_timer": ReturnType<typeof setTimeout> | null;
     declare "_transition_timer": ReturnType<typeof setTimeout> | null;
     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). */
+    declare "_narration_allowed": boolean;
+    /** True once the visitor has clicked/keyed: unmuted audio needs this. */
+    declare "_user_gestured": boolean;
+    /** The advance armed for the current slide (media-ended or the timer). */
+    declare "_autoplay_advance": (() => void) | null;
+    /** A narration that was skipped for want of a gesture, to retry later. */
+    declare "_replayNarrationAfterGesture": boolean;
     declare "_hash_initialized": boolean;
+    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 */
+    declare "_language_holder": symbol;
+    /** the locale the caller actually asked for, if any; see _loadLanguage */
+    declare "_language_requested": string | undefined;
+    /** bumped on interaction, so page-wide keys can pick one viewer */
+    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
 	================================================== */
@@ -105,41 +240,45 @@ 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",
+                    );
                 }
             }
         }
 
         // Version
-        this.version = "0.1.16";
+        // build-time constant from package.json (see vite.config.ts); the
+        // typeof guard keeps a dev-server run without the define working
+        this.version =
+            typeof __STORYMAP_VERSION__ === "string" ? __STORYMAP_VERSION__ : "0.0.0-dev";
 
         // Ready
         this.ready = false;
 
-        // DOM ELEMENTS
+        // DOM ELEMENTS. Only map may legitimately stay null: a mapless story
+        // never builds the pane, so unlike its siblings it gets a real null
+        // rather than a stub that would read truthy before _initLayout runs.
         this._el = {
             container: {} as HTMLElement,
             storyslider: {} as HTMLElement,
-            map: {} as HTMLElement,
+            map: null,
             menubar: {} as HTMLElement,
         };
 
@@ -147,15 +286,23 @@ class StoryMapBase {
         if (typeof elem === "object") {
             this._el.container = elem;
         } else {
-            this._el.container = Dom.get(elem);
+            const found = Dom.get(elem);
+            if (!found) {
+                throw new Error("StoryMapJS: no element with id " + elem);
+            }
+            this._el.container = found;
         }
 
         // Slider
         this._storyslider = {} as StorySlider;
 
-        // Map
-        this._map = {} as OpenLayersMap;
-        this.map = {} as OlMap; // direct access to the OpenLayers map
+        // Map. Genuinely null when the story has no map (map_type "none") or
+        // before the layout builds one: the accessor guards below read
+        // `!this._disposed && this._map`, which a `{}` stub would sail past
+        // and then call a method on.
+        this._map = null;
+        // direct access to the OpenLayers map; null until it is built
+        this.map = null;
 
         // Menu Bar
         this._menubar = {} as MenuBar;
@@ -169,6 +316,10 @@ class StoryMapBase {
 
         this.options = {
             script_path: StoryMap.SCRIPT_PATH,
+            // raw OpenLayers Map/View options passed through (see map_options
+            // in the README); empty by default, and the OL code reads it
+            // defensively because the option is also settable from JSON
+            map_options: {},
             height: this._el.container.offsetHeight,
             width: this._el.container.offsetWidth,
             layout: "landscape", // portrait or landscape
@@ -176,7 +327,6 @@ class StoryMapBase {
             default_bg_color: { r: 255, g: 255, b: 255 },
             map_size_sticky: 2.5, // Set as division 1/3 etc
             map_center_offset: null, // takes object {top:0,left:0}
-            less_bounce: false, // Less map bounce when calculating zoom, false is good when there are clusters of tightly grouped markers
             start_at_slide: 0,
             call_to_action: false,
             call_to_action_text: "",
@@ -188,20 +338,33 @@ class StoryMapBase {
             // animation
             duration: 1000,
             ease: easeInOutQuint,
-            // interaction
-            dragging: true,
             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,
             attribution: "",
             map_mini: true,
-            map_subdomains: "",
             map_as_image: false,
             // no bundled credentials: pass map_access_token in the options
             // if you use Mapbox/Stadia tiles, api_key_flickr for flickr API
@@ -210,6 +373,15 @@ class StoryMapBase {
             map_background_color: "#d9d9d9",
             map_area: "full", // "left" limits the map to the visible half (landscape)
             map_bbox: null,
+            // options the map also declares: updateData only copies keys
+            // 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,
             consent_required: false,
             zoomify: undefined,
             text_color: "",
@@ -225,9 +397,6 @@ class StoryMapBase {
             slide_padding_lr: 45, // padding on slide of slide
             slide_default_fade: "0%", // landscape fade
             menubar_default_y: 0,
-            path_gfx: "gfx",
-            map_popup: false,
-            zoom_distance: 100,
             calculate_zoom: true, // Allow map to determine best zoom level between markers (recommended)
             line_follows_path: true, // Map history path follows default line, if false it will connect previous and current only
             line_color: "#c34528", //"#DA0000",
@@ -247,16 +416,51 @@ class StoryMapBase {
         this.animator_map = null;
         this.animator_storyslider = null;
         this._resize_observer = null;
+        this._on_resize = null;
+        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;
+        this._language_holder = Symbol("storymap");
+        this._language_requested = undefined;
+        this._interaction = 0;
+        this._onInteraction = null;
         this._resize_timer = null;
         this._autoplay_timer = null;
         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;
+        this._replayNarrationAfterGesture = false;
+        this._autoplay_advance = null;
         this._hash_initialized = false;
+        this._collapsed = false;
+
+        // The caller's own `language`, read before the merge: afterwards
+        // options.language is always set (the default is "en"), so "asked for
+        // German" and "never mentioned a language" are indistinguishable.
+        this._language_requested =
+            typeof options?.language === "string" && options.language !== ""
+                ? options.language
+                : undefined;
 
         // Merge Options -- legacy, in case people still need to pass in
         mergeData(this.options, options);
 
-        // Current Slide (after the options merge so start_at_slide applies)
+        // Current Slide — the constructor options have been merged, but the
+        // storymap *data* has not (issue #305). _initData -> _initOptions
+        // merges the data in afterwards, and the data may carry a
+        // start_at_slide of its own, so re-read it there rather than
+        // freezing the constructor value here.
         this.current_slide = this.options.start_at_slide;
 
         this._initData(data);
@@ -270,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 =
@@ -278,9 +486,18 @@ class StoryMapBase {
                     : data;
             void this._loadDataFromUrl(url, data);
         } else if (typeof data === "object") {
-            if (isPresentation3Manifest(data)) {
+            // a Collection is a legitimate IIIF input too: its member
+            // Manifests' canvases concatenate into one linear story
+            if (isPresentation3Manifest(data) || isPresentation3Collection(data)) {
                 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);
@@ -299,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);
@@ -306,9 +573,39 @@ class StoryMapBase {
                 throw new Error("HTTP " + response.status + " " + response.statusText);
             }
             const result: unknown = await response.json();
-            if (isPresentation3Manifest(result)) {
+            // A teardown while the fetch was in flight must win: without
+            // this, a late-resolving response rebuilds the whole viewer into
+            // the container dispose() just emptied — menubar, slider, map,
+            // listeners, locale claim, autoplay — and sets ready = true.
+            if (this._disposed) {
+                return;
+            }
+            if (isPresentation3Manifest(result) || isPresentation3Collection(result)) {
                 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;
@@ -319,6 +616,14 @@ class StoryMapBase {
             }
             this._initOptions();
         } catch (err: unknown) {
+            if (isLanguageConflict(err)) {
+                // a second viewer on this page asked for another locale. This
+                // is a configuration error, not a failed fetch, and reporting
+                // it as one would send the host looking for a 404.
+                console.error((err as Error).message);
+                this.fire("error", { message: (err as Error).message, source, conflict: true });
+                return;
+            }
             console.error("StoryMapJS: could not load storymap data from " + source, err);
             this.fire("error", { message: String(err), source });
         }
@@ -326,10 +631,78 @@ 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 = {
+            state: parseContentState(
+                new URLSearchParams(window.location.search).get(CONTENT_STATE_PARAM),
+            ),
+            hash: window.location.hash,
+        };
+
+        // issue #305: the data may override start_at_slide. The constructor
+        // read it before this merge, and the slider's opening goTo() fires
+        // before _initEvents() attaches our change listener — so nothing
+        // else resynchronises the field, leaving the hash, the progress bar
+        // and current_slide disagreeing with the visible slide.
+        this.current_slide = this.options.start_at_slide;
+
         // legacy zoomify options only work with storymap JSON sources — a
         // IIIF Presentation manifest cannot carry them
         if (this._data_from_manifest) {
@@ -340,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 };
             }
@@ -373,6 +756,33 @@ class StoryMapBase {
             }
         }
 
+        // `map_type` is optional in the schema, and a hand-written document
+        // can carry an explicit null. Normalise rather than guard: leaving a
+        // null in place only moves the crash to the map's own
+        // `map_type.split(":")`. "" is the documented default and means OSM.
+        if (typeof this.options.map_type !== "string") {
+            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";
+
         // handle Stamen change
         if (this.options.map_type.startsWith("stamen")) {
             const old_type = this.options.map_type;
@@ -381,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();
@@ -391,24 +801,70 @@ class StoryMapBase {
 	================================================== */
 
     _loadLanguage() {
-        setLanguage(this.options.language);
-        // the resolved locale decides the layout direction (issues #211, #245)
-        this.options.language = Language as unknown as string;
+        // the locale chunk is fetched on demand, so the language is not
+        // available synchronously; layout proceeds with the English defaults
+        // and the labels are repainted once the locale arrives.
+        //
+        // The claim is what makes a second viewer on this page safe: the UI
+        // strings are one module-level binding, so a conflicting locale would
+        // otherwise repaint this viewer in the other viewer's language. It
+        // throws rather than warn, before any of this viewer's DOM exists.
+        //
+        // The document may carry its own `language` (updateData merges the
+        // document's keys into the options), so that counts as a request too.
+        const requested = this._requestedLanguage();
+        if (requested === undefined) {
+            // Nobody asked for a locale, so adopt whatever the page is already
+            // using. Claiming the "en" default instead would conflict with a
+            // sibling that did ask — a host that called setLanguage("de") and
+            // then built a viewer with no `language` option used to get
+            // English, silently repainting its German sibling's chrome.
+            claimLanguage(currentLanguageCode(), this._language_holder);
+        } else {
+            claimLanguage(requested, this._language_holder);
+            setLanguage(requested);
+        }
         this._onDataLoaded();
     }
 
+    /**
+     * The locale this viewer was actually asked for, or undefined when the
+     * caller and the document both stayed silent.
+     */
+    _requestedLanguage(): string | undefined {
+        // the document wins, because updateData merges it over the options, so
+        // a document-level `language` is what options.language ends up holding
+        const fromDocument = (this.data as { language?: unknown } | null | undefined)?.language;
+        if (typeof fromDocument === "string" && fromDocument !== "") {
+            return fromDocument;
+        }
+        return this._language_requested;
+    }
+
     /*  Switch the UI language at runtime, without a page reload.
     ================================================== */
 
     refreshLanguage(code: string): void {
+        if (this._disposed) return;
+        // throws if a sibling viewer is rendering in another language
+        claimLanguage(code, this._language_holder);
         this.options.language = code;
         setLanguage(code);
-        // the resolved locale decides the layout direction (issues #211, #245)
-        this.options.language = Language as unknown as string;
-        if (this._menubar && typeof this._menubar.refreshLabels === "function") {
-            this._menubar.refreshLabels();
-        }
-        this.updateDisplay();
+        this._applyLanguageLayout();
+    }
+
+    /**
+     * Repaint everything a runtime language switch affects: the menubar
+     * labels and the `vco-rtl` class.
+     *
+     * This deliberately does *not* call `updateDisplay()`. A full re-layout
+     * re-runs the slider's `goTo(current_slide)`, which goes through the
+     * navigation path that re-arms autoplay — so calling it here silently
+     * cancelled a pending autoplay tick and the story stopped advancing.
+     */
+    _applyLanguageLayout(): void {
+        this._menubar?.refreshLabels?.();
+        this._el.container.classList.toggle("vco-rtl", isRtl());
     }
 
     /*  Load the font theme stylesheet
@@ -416,19 +872,21 @@ 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) {
             // external font CSS is an external service — ask first
             const host = new URL(font.startsWith("//") ? "https:" + font : font).host;
             const container = this._el.map ?? (this._el.container as HTMLElement);
-            const allowed = await manager.request(
-                consentMessage("consent_service_fonts", "web fonts"),
-                host,
-                container,
-            );
+            const allowed = await manager.request(fontService(), host, container);
             if (!allowed) {
                 return;
             }
@@ -452,28 +910,72 @@ class StoryMapBase {
     /*	Navigation
 	================================================== */
     /**
-     * Navigate to a slide by index.
+     * Navigate to a slide by index. Out-of-range indices are ignored, as is
+     * the current index.
      *
      * @param n - Zero-based slide index; the map animates to the slide's
-     *   marker (or the overview when `n` is 0 for storymaps with one).
+     *   marker. The overview is selected by the slide's own
+     *   `type: "overview"`, not by its index.
      */
     goTo(n: number) {
+        if (this._disposed) return;
         // out-of-range indices are ignored: they would desync the slider and
         // map (no active slide) and write a broken #slide-N bookmark
         if (n >= 0 && n < (this.data?.slides?.length ?? 0) && n !== this.current_slide) {
-            const duration = slideTransitionDuration(this.current_slide, n);
-            this.current_slide = n;
+            this._navigate(n);
+        }
+    }
+
+    /**
+     * The single navigation path shared by programmatic navigation, the
+     * slider's `change` event, the map's `change` event and "back to start".
+     *
+     * `navigate` names the single component that the bubble source already
+     * moved; the other component follows. `navigated` says whether the caller
+     * has *not* already reported the change outward, so the outward `change`
+     * event fires exactly once per navigation (the bubble paths would
+     * otherwise re-enter through the other component's handler).
+     */
+    private _navigate(
+        n: number,
+        opts: {
+            navigate?: "slider" | "map";
+            navigated?: boolean;
+            animate?: boolean;
+        } = {},
+    ): void {
+        const { navigate, navigated = false, animate = true } = opts;
+        const duration = animate ? slideTransitionDuration(this.current_slide, n) : 0;
+
+        this.current_slide = n;
+        if (navigate !== "slider") {
             this._storyslider.goTo(this.current_slide);
-            this._map.goTo(this.current_slide);
-            this._beginTransition(duration);
+        }
+        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;
-            // the bubbled slider/map change events below are dropped by
-            // their equality guards, so this fires exactly once
-            this.fire("change", { current_slide: this.current_slide }, this);
-            this._syncHash();
-            this._scheduleAutoplay();
-            this._updateProgress();
+            // the bubbled slider/map change events are dropped by their
+            // equality guards, so this fires exactly once
+            // `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._syncHash();
+        this._playNarration(this.data.slides?.[this.current_slide]);
+        this._stopAmbientSlideMedia(this.data.slides?.[this.current_slide]);
+        this._scheduleAutoplay();
+        this._updateProgress();
     }
 
     /**
@@ -486,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);
     }
 
@@ -498,6 +1000,9 @@ class StoryMapBase {
      * Called automatically on resize (see the `trackResize` option).
      */
     updateDisplay() {
+        if (this._disposed) {
+            return;
+        }
         if (this.ready) {
             this._updateDisplay();
         }
@@ -506,8 +1011,10 @@ class StoryMapBase {
     /**
      * Change a single map option at runtime and apply its effect immediately.
      *
-     * Runtime-changeable options: `map_type` (rebuilds the main + minimap tile
-     * layers, keeping the overview fitted to the marker bounds), `overlays`
+     * Runtime-changeable options: `map_type` (swaps one basemap for another and
+     * rebuilds the main + minimap tile layers, keeping the overview fitted to
+     * the marker bounds; it cannot add or remove a map, and `"none"` and
+     * non-strings are declined), `overlays`
      * (rebuilds the stacked overlay layers), `show_lines`, `line_color`,
      * `line_color_inactive`, `line_weight`, `line_opacity`, `line_dash`,
      * `line_join`, `line_follows_path`, `show_history_line` (restyled
@@ -516,219 +1023,827 @@ class StoryMapBase {
      * options only take effect on the next navigation or require re-creating
      * the StoryMap.
      */
+    /**
+     * Sugar over {@link setMapOptions} — `setMapOption(name, value)` is the
+     * same call as `setMapOptions({ [name]: value })`.
+     */
     setMapOption(name: string, value: unknown) {
+        if (this._disposed) return;
         this.setMapOptions({ [name]: value } as Partial<StorymapOptions>);
     }
 
     /**
      * Show or hide a stacked overlay by index (see the `overlays` option).
+     * Prefer `getOverlayLayer(index).setVisible(v)` on the layer itself; this
+     * wrapper also re-syncs the attribution line and the overlay blend mode.
      */
     setOverlayVisible(index: number, visible: boolean): void {
-        this._map.setOverlayVisible(index, visible);
+        if (this._disposed) return;
+        this._map?.setOverlayVisible(index, visible);
     }
 
     /**
      * Set a stacked overlay's opacity by index (see the `overlays` option).
+     * Alias: `getOverlayLayer(index)?.setOpacity(opacity)`.
      */
     setOverlayOpacity(index: number, opacity: number): void {
-        this._map.setOverlayOpacity(index, opacity);
+        if (this._disposed) return;
+        this._map?.setOverlayOpacity(index, opacity);
     }
 
     /**
      * Change several map options at runtime (see setMapOption).
      */
     setMapOptions(options: Partial<StorymapOptions>) {
-        mergeData(this.options, options);
-        if (this._map && this._map.options) {
-            mergeData(this._map.options, options);
-            this._map.applyOptions(Object.keys(options));
-        } else {
-            for (const key of Object.keys(options)) {
-                (this.options as Record<string, unknown>)[key] = (
-                    options as Record<string, unknown>
-                )[key];
+        if (this._disposed) return;
+        // `map_type` decides at construction time whether a map exists. The
+        // engine can swap one basemap for another, but it can neither grow a
+        // map onto a mapless story nor remove a built one — "none" has no
+        // basemap branch and would silently install OpenStreetMap, the exact
+        // inverse of its meaning — and a non-string crashes the layer
+        // builder. So both are declined here, loudly, rather than half-applied.
+        let effective = options;
+        if (options.map_type !== undefined) {
+            if (typeof options.map_type !== "string") {
+                console.warn(
+                    `StoryMapJS: setMapOptions ignores a non-string map_type (${String(options.map_type)}); pass "" for the default basemap.`,
+                );
+                effective = { ...options, map_type: "" };
+            } else if (options.map_type === "none" || this._map_disabled) {
+                console.warn(
+                    "StoryMapJS: setMapOptions cannot add or remove a map after construction; map_type is load-time only.",
+                );
+                effective = { ...options };
+                delete effective.map_type;
             }
         }
+        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)
-            if (this.options.text_color) {
-                this._el.container.style.setProperty("--vco-color-text", this.options.text_color);
-            }
-            if (this.options.text_background_color) {
-                this._el.container.style.setProperty(
-                    "--vco-color-text-background",
-                    this.options.text_background_color,
-                );
-            }
+            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();
         }
     }
 
-    /*	Private Methods
-	================================================== */
+    /*	OpenLayers accessors
+	The map itself is public (`storymap.map`, the raw `ol/Map`). These hand
+	out the objects the viewer keeps private, so a consumer never has to reach
+	through an underscore field. `getBaseLayer()` returns `null` while the
+	base layer is deferred awaiting tile consent.
+	================================================= */
 
-    // Initialize the layout
-    _initLayout() {
-        this._el.container.className += " vco-storymap";
-        this.options.base_class = this._el.container.className;
+    /** The base tile layer, or `null` when deferred (tile consent not granted). */
+    getBaseLayer(): OlLayer | null {
+        return !this._disposed && this._map ? this._map.getBaseLayer() : null;
+    }
 
-        // Text color theming (issue #177): expose the text colors as CSS
-        // custom properties consumed by the slide typography
-        if (this.options.text_color) {
-            this._el.container.style.setProperty("--vco-color-text", this.options.text_color);
-        }
-        if (this.options.text_background_color) {
-            this._el.container.style.setProperty(
-                "--vco-color-text-background",
-                this.options.text_background_color,
-            );
-        }
+    /** The stacked `overlays[]` layers, in `overlays[]` order. */
+    getOverlayLayers(): OlLayer[] {
+        return !this._disposed && this._map ? this._map.getOverlayLayers() : [];
+    }
 
-        // Create Layout
-        this._el.menubar = Dom.create("div", "vco-menubar", this._el.container);
-        this._el.map = this._resolveMapElement();
-        if (!this._el.map) {
-            this._el.map = Dom.create("div", "vco-map", this._el.container);
-        }
-        this._el.storyslider = Dom.create("div", "vco-storyslider", this._el.container);
+    /** One stacked overlay layer by its `overlays[]` index, or `null`. */
+    getOverlayLayer(index: number): OlLayer | null {
+        return !this._disposed && this._map ? this._map.getOverlayLayer(index) : null;
+    }
 
-        // Initial Default Layout
-        this.options.width = this._el.container.offsetWidth;
-        this.options.height = this._el.container.offsetHeight;
-        this._el.map.style.height = "1px";
-        this._el.storyslider.style.top = "1px";
+    /** Number of stacked overlay layers (see the `overlays` option). */
+    getOverlayCount(): number {
+        return !this._disposed && this._map ? this._map.getOverlayCount() : 0;
+    }
 
-        // Create Map using preferred Map API
-        this._map = new OpenLayersMap(this._el.map, this.data, this.options);
-        this.map = this._map._map; // For access to the OpenLayers map.
-        this._map.on("loaded", this._onMapLoaded, this);
+    /** The minimap's OpenLayers map (the `OverviewMap` control's inner map). */
+    getMinimap(): OlMap | null {
+        return !this._disposed && this._map ? this._map.getMinimap() : null;
+    }
 
-        // Map Background Color
-        this._el.map.style.backgroundColor = this.options.map_background_color;
+    /** The full (inactive) route line layer. */
+    getLine(): OlLayer | null {
+        return !this._disposed && this._map ? this._map.getLine() : null;
+    }
 
-        // Create Menu Bar
-        this._menubar = new MenuBar(this._el.menubar, this._el.container, this.options);
+    /**
+     * True when the map shows a IIIF image as a picture of the world
+     * (`map_as_image`) rather than as a georeferenced map. In that mode the
+     * view is `EPSG:4326` image space: `map.getView().getCenter()` is in
+     * degrees, the resolution is in pixels per degree, and marker locations
+     * are pixel offsets into the image. Ask this instead of checking
+     * `map_type` — georeferenced IIIF (`map_bbox` without `map_as_image`)
+     * is an ordinary mercator map.
+     */
+    isImageSpace(): boolean {
+        return !this._disposed && this._map ? this._map.isImageSpace() : false;
+    }
 
-        // Create StorySlider
-        this._storyslider = new StorySlider(this._el.storyslider, this.data, this.options);
-        this._storyslider.on("loaded", this._onStorySliderLoaded, this);
-        this._storyslider.on("title", this._onTitle, this);
-        this._storyslider.init();
+    /**
+     * The `uniqueid` of a slide — the current one by default.
+     *
+     * A IIIF manifest supplies one per canvas (§2.3) and it is the only
+     * identity a link can be built on, since an index moves when a slide is
+     * inserted. A storymap-JSON slide usually has none, in which case this is
+     * `null` rather than a generated id: a random one would be stable to nobody.
+     */
+    getSlideId(index?: number): string | null {
+        if (this._disposed) return null;
+        const at = index ?? this.current_slide;
+        const id = this.data?.slides?.[at]?.uniqueid;
+        return typeof id === "string" && id !== "" ? id : null;
+    }
 
-        // LAYOUT
-        if (this.options.layout === "portrait") {
-            // Set Default Component Sizes
-            this.options.map_height = this.options.height / this.options.map_size_sticky;
-            this.options.storyslider_height =
-                this.options.height - this._el.menubar.offsetHeight - this.options.map_height - 1;
-            this._menubar.setSticky(0);
-        } else {
-            this.options.menubar_height = this._el.menubar.offsetHeight;
-            // Set Default Component Sizes
-            this.options.map_height = this.options.height;
-            this.options.storyslider_height =
-                this.options.height - this._el.menubar.offsetHeight - 1;
-            this._menubar.setSticky(this.options.menubar_height);
+    /**
+     * Read the annotation documents this manifest points at with `seeAlso` and
+     * add the tour stops they carry.
+     *
+     * Explicit and asynchronous on purpose (§5.2). The alternative — following
+     * `seeAlso` inside `manifestToStorymapData` — would mean one blocking
+     * network round trip per referenced document before the viewer could paint
+     * its first slide, against third-party servers the host may not want to
+     * contact at all. Here the story stands on its own immediately and the
+     * annotations arrive afterwards, behind a per-(id, type) cache, and
+     * `annotationsloaded` fires when they are in.
+     *
+     * The stops are **appended**, not placed after the canvas they annotate.
+     * A canvas's own annotations are inserted in position at parse time; doing
+     * the same to a live tour would mean rebuilding the slider and every piece
+     * of state that hangs off it, for an ordering nicety. A host that needs
+     * the stops placed exactly can read them off the resolved value and place
+     * them itself.
+     *
+     * @returns the stops that were added, keyed by canvas id, plus any
+     *   `SearchService1` endpoint seen and any document that failed to load.
+     */
+    async loadAnnotations(
+        options: { fetchImpl?: typeof fetch } = {},
+    ): Promise<{ stops: StorymapSlide[]; searchService: string | null; failed: string[] }> {
+        const added: StorymapSlide[] = [];
+        if (this._disposed || this._raw_manifest === null) {
+            return { stops: added, searchService: null, failed: [] };
         }
-
-        // Update Display
-        this._updateDisplay(this.options.map_height, true, 2000);
-
-        // Animate Menu Bar to Default Location
-        this._menubar.show(2000);
+        const loaded = await loadSeeAlso(this._raw_manifest, options);
+        if (this._disposed) {
+            // torn down while the requests were in flight
+            return { stops: added, searchService: loaded.searchService, failed: loaded.failed };
+        }
+        // canvas order, so the appended stops follow the story rather than the
+        // order the documents happened to resolve in
+        for (const slide of this.data.slides ?? []) {
+            const stops = loaded.stops.get(slide.uniqueid ?? "");
+            if (stops === undefined) continue;
+            for (const stop of stops) {
+                stop.uniqueid = `${slide.uniqueid ?? "slide"}#seealso-${added.length}`;
+                added.push(stop);
+                this.data.slides.push(stop);
+                this._storyslider.createSlide(stop);
+            }
+        }
+        if (added.length > 0) {
+            this._updateProgress();
+            this._updateDistance();
+        }
+        const result = { stops: added, searchService: loaded.searchService, failed: loaded.failed };
+        this.fire("annotationsloaded", result);
+        return result;
     }
 
-    _initEvents() {
-        // Sidebar Events
-        this._menubar.on("collapse", this._onMenuBarCollapse, this);
-        this._menubar.on("back_to_start", this._onBackToStart, this);
-        this._menubar.on("overview", this._onOverview, this);
-        this._menubar.on("fullscreen", this._onFullscreenToggle, this);
-
-        // StorySlider Events
-        this._storyslider.on("change", this._onSlideChange, this);
-        this._storyslider.on("colorchange", this._onColorChange, this);
-
-        // Map Events
-        this._map.on("change", this._onMapChange, this);
+    /**
+     * Release everything the viewer attached to the page: window/document
+     * listeners, timers, the resize observer, running Web Animations, the
+     * slider, the menubar, the map and the map markers. Use this when tearing
+     * a storymap down (SPA route change, modal close).
+     *
+     * Teardown is terminal: the host container is emptied, `map` becomes
+     * null, and the public methods (`goTo`, `setMapOptions`,
+     * `createMiniMap`, ...) become no-ops rather than throwing. There is no
+     * re-init path; build a new StoryMap on the same element instead.
+     * Calling `dispose()` twice is a no-op.
+     */
+    dispose(): void {
+        if (this._disposed) {
+            return;
+        }
+        this._disposed = true;
+        // `updateDisplay()` is gated on `ready`, not `_disposed`, so without
+        // this a post-teardown resize listener (or a stray host call) re-runs
+        // the whole layout — and reaches the map engine — against an emptied
+        // container and a disposed ol/Map.
+        this.ready = false;
 
-        // Global slide navigation (opt-in): the slider only listens on its
-        // own panel, which needs focus
-        if (this.options.keyboard) {
-            window.addEventListener("keydown", this._onKeyDownGlobal.bind(this));
+        for (const timer of [this._transition_timer, this._autoplay_timer, this._resize_timer]) {
+            if (timer !== null && timer !== undefined) {
+                clearTimeout(timer);
+            }
         }
+        this._transition_timer = null;
+        this._autoplay_timer = null;
+        this._resize_timer = null;
 
-        // Fullscreen state
-        document.addEventListener("fullscreenchange", this._onFullscreenChange.bind(this));
-    }
+        this._resize_observer?.disconnect();
+        this._resize_observer = null;
 
-    _onKeyDownGlobal(e: KeyboardEvent) {
-        if (e.defaultPrevented) {
-            return;
+        if (this._on_resize) {
+            window.removeEventListener("resize", this._on_resize);
+            this._on_resize = null;
         }
-        const target = e.target as HTMLElement | null;
-        const tag = target?.tagName?.toLowerCase();
-        if (tag === "input" || tag === "textarea" || tag === "select" || target?.isContentEditable) {
-            return;
+        if (this._on_keydown_global) {
+            window.removeEventListener("keydown", this._on_keydown_global);
+            this._on_keydown_global = null;
         }
-        // let OpenLayers keep arrow-key map panning when the map has focus
-        if (target instanceof Element && target.closest(".vco-map")) {
-            return;
+        if (this._on_fullscreen) {
+            document.removeEventListener("fullscreenchange", this._on_fullscreen);
+            this._on_fullscreen = null;
         }
-        if (e.key === "ArrowRight" || e.key === "ArrowDown") {
-            e.preventDefault();
-            this._storyslider.next();
-        } else if (e.key === "ArrowLeft" || e.key === "ArrowUp") {
-            e.preventDefault();
-            this._storyslider.previous();
+        if (this._on_hashchange) {
+            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;
         }
-    }
-
-    // Update View
-    _updateDisplay(map_height?: number, animate?: boolean, d?: number) {
-        let duration = this.options.duration,
-            display_class = this.options.base_class;
 
-        if (d) {
-            duration = d;
+        // slide transitions in flight (Web Animations API)
+        for (const el of [this._el?.container, this._el?.map]) {
+            el?.getAnimations?.().forEach((a) => a.cancel());
         }
 
-        // Update width and height
-        this.options.width = this._el.container.offsetWidth;
-        this.options.height = this._el.container.offsetHeight;
+        // an unanswered consent panel holds a promise that Media.loadMedia()
+        // is awaiting; settle it before the children go away
+        consentManagerOf(this.options)?.dispose();
 
-        // Check if skinny
-        if (this.options.width <= this.options.skinny_size) {
-            this.options.layout = "portrait";
-        } else {
-            this.options.layout = "landscape";
+        this._stopNarration();
+        this._stopAmbient();
+        if (this._narration_el) {
+            this._narration_el.src = "";
+            this._narration_el = null;
         }
-
-        // Map Height
-        if (map_height) {
-            this.options.map_height = map_height;
+        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?.();
+
+        // the public ol/Map handle. The viewer is terminal after dispose(), so
+        // this is null rather than a disposed instance; the public methods
+        // above are guarded and no-op instead of throwing.
+        this.map = null;
+
+        // empty the host element: the children owned their own listeners and
+        // players, but their nodes (and the ol canvas) would otherwise stay
+        // in the document after teardown
+        this._el?.container?.replaceChildren();
+
+        // let another viewer claim a different language, now that this one is
+        // no longer reading the shared strings (refcounted, so a sibling in
+        // the same language keeps its claim)
+        releaseLanguage(this._language_holder);
+
+        if (this._onInteraction) {
+            for (const type of ["pointerdown", "focusin", "wheel"] as const) {
+                this._el.container.removeEventListener(type, this._onInteraction);
+            }
+            this._onInteraction = null;
+        }
+        unregisterParticipant(this);
+    }
 
-        // Detect Mobile and Update Orientation on Touch devices
+    /**
+     * This viewer's root element. Satisfies the `Participant` shape the
+     * page-wide key registry (`src/core/viewers.ts`) arbitrates on.
+     *
+     * @internal
+     */
+    get element(): HTMLElement | null {
+        return this._el?.container ?? null;
+    }
+
+    /**
+     * Monotonic stamp of the last interaction with this viewer; the highest
+     * one owns a page-wide keypress when nothing is focused.
+     *
+     * @internal
+     */
+    get interaction(): number {
+        return this._interaction;
+    }
+
+    /** The highlighted route line drawn up to the current slide. */
+    getLineActive(): OlLayer | null {
+        return !this._disposed && this._map ? this._map.getLineActive() : null;
+    }
+
+    /** The map markers, indexed by slide. */
+    getMarkers(): OpenLayersMapMarker[] {
+        return !this._disposed && this._map ? this._map.getMarkers() : [];
+    }
+
+    /** One map marker by slide index, or `null`. */
+    getMarker(index: number): OpenLayersMapMarker | null {
+        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
+     * or a deferred tile-consent grant.
+     */
+    createMiniMap(): void {
+        if (this._disposed) return;
+        this._map?.createMiniMap();
+    }
+
+    /**
+     * Append attribution fragments and refresh the credit line (e.g. for a
+     * custom layer added through `tile_source_factory`).
+     */
+    setExtraAttributions(parts: string[]): void {
+        if (this._disposed) return;
+        this._map?.setExtraAttributions(parts);
+    }
+
+    /**
+     * Publish the text colour custom properties. Called from both the initial
+     * layout and every runtime option change (issue #177) so the two paths
+     * cannot drift.
+     */
+    _applyTextColors(): void {
+        if (this.options.text_color) {
+            this._el.container.style.setProperty("--vco-color-text", this.options.text_color);
+        }
+        if (this.options.text_background_color) {
+            this._el.container.style.setProperty(
+                "--vco-color-text-background",
+                this.options.text_background_color,
+            );
+        }
+    }
+
+    /**
+     * 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
+	================================================== */
+
+    // Initialize the layout
+    _initLayout() {
+        if (this._disposed) {
+            return;
+        }
+        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();
+
+        // Create Layout
+        this._el.menubar = Dom.create("div", "vco-menubar", this._el.container);
+        this._el.map = this._map_disabled
+            ? 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;
+        this.options.height = this._el.container.offsetHeight;
+        if (this._el.map) {
+            this._el.map.style.height = "1px";
+        }
+        this._el.storyslider.style.top = "1px";
+
+        if (this._map_disabled) {
+            // No map pane, so the map options have nothing to size. The
+            // slider takes the whole height below the menubar, and every
+            // map-derived option is set to something the layout code below
+            // does not need. Nothing is constructed - no ol/Map, no tile
+            // layer, no consent ask. storyslider_height is set by the
+            // _updateDisplay call below, so assigning it here would be dead.
+            this.options.map_height = 0;
+            // the overview control is a map control: with no map there is
+            // nothing for it to zoom out to, so it is hidden the same way
+            // `show_overview: false` hides it
+            this.options.show_overview = false;
+        } else {
+            // Create Map using preferred Map API
+            this._map = new OpenLayersMap(this._map_el(), this.data, this.options);
+            this.map = this._map._map; // For access to the OpenLayers map.
+            this._map.on("loaded", this._onMapLoaded, this);
+            // 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", this._onImageReady, this);
+
+            // Map Background Color
+            this._map_el().style.backgroundColor = this.options.map_background_color;
+        }
+
+        // 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);
+        this._storyslider.on("loaded", this._onStorySliderLoaded, this);
+        this._storyslider.on("title", this._onTitle, this);
+        this._storyslider.init();
+
+        // LAYOUT
+        if (this._map_disabled) {
+            // one branch, both orientations: nothing to split the height
+            // with, and the menubar is the only thing above the slider
+            this.options.menubar_height = this._el.menubar.offsetHeight;
+            this._menubar.setSticky(this.options.menubar_height);
+        } else if (this.options.layout === "portrait") {
+            // Set Default Component Sizes
+            this.options.map_height = this.options.height / this.options.map_size_sticky;
+            this.options.storyslider_height =
+                this.options.height - this._el.menubar.offsetHeight - this.options.map_height - 1;
+            this._menubar.setSticky(0);
+        } else {
+            this.options.menubar_height = this._el.menubar.offsetHeight;
+            // Set Default Component Sizes
+            this.options.map_height = this.options.height;
+            this.options.storyslider_height =
+                this.options.height - this._el.menubar.offsetHeight - 1;
+            this._menubar.setSticky(this.options.menubar_height);
+        }
+
+        // Update Display
+        this._updateDisplay(this.options.map_height, true, 2000);
+
+        // Animate Menu Bar to Default Location
+        this._menubar.show(2000);
+    }
+
+    _initEvents() {
+        // Sidebar Events
+        this._menubar.on("collapse", this._onMenuBarCollapse, this);
+        this._menubar.on("back_to_start", this._onBackToStart, this);
+        this._menubar.on("overview", this._onOverview, this);
+        this._menubar.on("fullscreen", this._onFullscreenToggle, this);
+
+        // StorySlider Events
+        this._storyslider.on("change", this._onSlideChange, this);
+        this._storyslider.on("colorchange", this._onColorChange, this);
+
+        // 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.
+        //
+        // With more than one viewer on the page, `window` is shared, and
+        // e.preventDefault() does not stop a sibling listener on the same
+        // target — so an arrow press used to advance every story at once. This
+        // viewer takes part in the registry and then answers whether it owns
+        // the event (focus first, then most-recently-interacted).
+        if (this.options.keyboard) {
+            this._onInteraction = () => {
+                this._interaction = markInteraction();
+            };
+            for (const type of ["pointerdown", "focusin", "wheel"] as const) {
+                this._el.container.addEventListener(type, this._onInteraction, {
+                    passive: true,
+                });
+            }
+            registerParticipant(this);
+            this._on_keydown_global = (e: KeyboardEvent) => this._onKeyDownGlobal(e);
+            window.addEventListener("keydown", this._on_keydown_global);
+        }
+
+        // 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) {
+        if (e.defaultPrevented) {
+            return;
+        }
+        const target = e.target as HTMLElement | null;
+        const tag = target?.tagName?.toLowerCase();
+        if (
+            tag === "input" ||
+            tag === "textarea" ||
+            tag === "select" ||
+            target?.isContentEditable
+        ) {
+            return;
+        }
+        // One viewer owns a page-wide keypress. This also covers the old
+        // "let OpenLayers pan the map" carve-out: the map is inside the
+        // viewer's own container, so a keypress aimed at another viewer (or at
+        // nothing the visitor has focused) no longer reaches this slider.
+        if (!ownsPageEvent(this)) {
+            return;
+        }
+        if (e.key === "ArrowRight" || e.key === "ArrowDown") {
+            e.preventDefault();
+            this._storyslider.next();
+        } else if (e.key === "ArrowLeft" || e.key === "ArrowUp") {
+            e.preventDefault();
+            this._storyslider.previous();
+        }
+    }
+
+    // View
+    _updateDisplay(map_height?: number, animate?: boolean, d?: number) {
+        // prefers-reduced-motion: glides collapse to instant size changes
+        if (animate && prefersReducedMotion()) {
+            animate = false;
+        }
+        let duration = this.options.duration,
+            display_class = this.options.base_class;
+
+        if (d) {
+            duration = d;
+        }
+
+        // Update width and height
+        this.options.width = this._el.container.offsetWidth;
+        this.options.height = this._el.container.offsetHeight;
+
+        // Check if skinny
+        if (this.options.width <= this.options.skinny_size) {
+            this.options.layout = "portrait";
+        } else {
+            this.options.layout = "landscape";
+        }
+
+        // Map Height
+        if (map_height) {
+            this.options.map_height = map_height;
+        }
+
+        // Detect Mobile and Update Orientation on Touch devices
         if (Browser.touch) {
             this.options.layout = Browser.orientation();
             display_class += " vco-mobile";
         }
 
         // LAYOUT
-        if (this.options.layout === "portrait") {
+        if (this._map_disabled) {
+            // The mapless layout: the menubar on top, the slider filling
+            // everything below it, in both orientations. No map element to
+            // size, offset, animate or fit, so none of that runs, and
+            // `map_area` has nothing to narrow.
+            display_class += " vco-layout-no-map";
+            // A narrow mapless story still needs the narrow-viewport slide
+            // layout: every rule that stacks the two-column slide (the
+            // 100px side padding, the floated 50% media block) keys on
+            // vco-skinny, and without it a phone-width story renders broken.
+            // The wide case needs nothing extra — the no-map rule already
+            // owns the full-width opaque panel.
+            if (this.options.layout === "portrait") {
+                display_class += " vco-skinny vco-layout-portrait";
+            }
+            // A narrow mapless story still needs the narrow-viewport slide
+            // layout: every rule that stacks the two-column slide (the
+            // 100px side padding, the floated 50% media block) keys on
+            // vco-skinny, and without it a phone-width story renders broken.
+            // The wide case needs nothing extra — the no-map rule already
+            // owns the full-width opaque panel.
+
+            this.options.menubar_height = this._el.menubar.offsetHeight;
+            this.options.map_height = 0;
+            this.options.storyslider_height = this.options.height - 1;
+            this._menubar.setSticky(this.options.menubar_height);
+
+            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._storyslider.updateDisplay(
+                this.options.width,
+                this.options.storyslider_height,
+                animate,
+                this.options.layout,
+            );
+        } else if (this.options.layout === "portrait") {
             display_class += " vco-skinny";
             // Map Offset
-            this._map.setMapOffset(0, 0);
-
-            this.options.map_height = this.options.height / this.options.map_size_sticky;
+            this._map_required().setMapOffset(0, 0);
+
+            // Portrait split. The collapse toggle is only offered in portrait
+            // (MenuBar hides it in landscape), so this branch used to
+            // unconditionally recompute map_height and discard the collapsed
+            // height it was handed — the button was a visual no-op. Honour
+            // the toggle state instead.
+            if (this._collapsed) {
+                this.options.map_height = COLLAPSED_MAP_HEIGHT;
+            } else {
+                this.options.map_height = this.options.height / this.options.map_size_sticky;
+            }
             this.options.storyslider_height = this.options.height - this.options.map_height - 1;
             this._menubar.setSticky(0);
 
             // Portrait: the map spans the full width again (a landscape
             // map_area "left" pass narrowed it)
             display_class += " vco-layout-portrait";
-            this._el.map.style.width = "100%";
+            this._map_el().style.width = "100%";
 
             if (animate) {
                 // Animate Map
@@ -736,12 +1851,12 @@ class StoryMapBase {
                     this.animator_map.stop();
                 }
 
-                this.animator_map = Animate(this._el.map, {
+                this.animator_map = Animate(this._map_el(), {
                     height: this.options.map_height + "px",
                     duration: duration,
                     easing: easeOutStrong,
                     complete: () => {
-                        this._map.updateDisplay(
+                        this._map_required().updateDisplay(
                             this.options.width,
                             this.options.map_height,
                             animate,
@@ -762,7 +1877,7 @@ class StoryMapBase {
                 });
             } else {
                 // Map
-                this._el.map.style.height = Math.ceil(this.options.map_height) + "px";
+                this._map_el().style.height = Math.ceil(this.options.map_height) + "px";
 
                 // StorySlider
                 this._el.storyslider.style.height = this.options.storyslider_height + "px";
@@ -770,7 +1885,7 @@ class StoryMapBase {
 
             // Update Component Displays
             this._menubar.updateDisplay(this.options.width, this.options.height, animate);
-            this._map.updateDisplay(this.options.width, this.options.height, false);
+            this._map_required().updateDisplay(this.options.width, this.options.height, false);
             this._storyslider.updateDisplay(
                 this.options.width,
                 this.options.storyslider_height,
@@ -786,12 +1901,11 @@ class StoryMapBase {
             // Set Default Component Sizes
             this.options.map_height = this.options.height;
             this.options.storyslider_height = this.options.height;
-            this._menubar.setSticky(this.options.menubar_height);
 
             // Set Sticky state of MenuBar
             this._menubar.setSticky(this.options.menubar_height);
 
-            this._el.map.style.height = this.options.height + "px";
+            this._map_el().style.height = this.options.height + "px";
 
             // map_area "left": the map element is limited to the left, visible
             // half (the slide panel is opaque) — no view offset needed;
@@ -799,39 +1913,79 @@ class StoryMapBase {
             // fading slide panel and the view is offset by a quarter width
             if (this.options.map_area === "left") {
                 display_class += " vco-map-area-left";
-                this._el.map.style.width = Math.floor(this.options.width / 2) + "px";
-                this._map.setMapOffset(0, 0);
+                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._el.map.style.width = "100%";
-                this._map.setMapOffset(-(this.options.width / 4), 0);
-            }
-
-            // StorySlider
-            this._el.storyslider.style.top = "0";
-            this._el.storyslider.style.height = this.options.storyslider_height + "px";
+                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";
 
-            this._menubar.updateDisplay(this.options.width, this.options.height, animate);
-            this._map.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,
+                );
+            }
         }
 
-        if ((this.options.language as unknown as { direction?: string }).direction === "rtl") {
+        // the resolved locale decides the layout direction (issues #211, #245)
+        if (isRtl()) {
             display_class += " vco-rtl";
         }
 
         // 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
 	================================================== */
 
     _onDataLoaded(e?: unknown) {
+        // Belt and braces with the _loadDataFromUrl guard: anything reaching
+        // this point after a teardown must not rebuild the layout.
+        if (this._disposed) {
+            return;
+        }
         // attach the consent manager BEFORE the layout is created, so the
         // slider/map/media options copies all share it
         (this.options as Record<string, unknown>).consent_manager = new ConsentManager();
@@ -845,19 +1999,332 @@ class StoryMapBase {
         this._initEvents();
         this._initResizeHandling();
         this.ready = true;
+        this._startConsentAsk();
         this._startAutoplay();
     }
 
+    /**
+     * Start-of-story consent (issue: allow all / individually / decline
+     * all): with `consent_required`, one dialog lists every external
+     * service the story uses — map tiles, external web fonts and the media
+     * services in the slides. Shown only while some service is unanswered;
+     * per-service slide asks remain the fallback.
+     */
+    _startConsentAsk(): void {
+        const manager = consentManagerOf(this.options);
+        if (!manager || !this.options.consent_required) {
+            return;
+        }
+        const services: ConsentService[] = [];
+        // map tiles — the same service the map's layer code keys off. A story
+        // with no map asks about its media and fonts only: there is no tile
+        // request to consent to, so asking would be noise the visitor cannot
+        // act on.
+        if (!this._map_disabled) {
+            services.push(tileService());
+        }
+        // media services with a real URL in the slides (a storymap is allowed
+        // to have no slides at all)
+        const seen = new Set<string>();
+        for (const slide of this.data.slides ?? []) {
+            // 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
+        // for it — without this the GDPR mode would have a hole.
+        const has_narration = (this.data.slides ?? []).some(
+            (slide) => !!(slide.narration as { url?: string } | null)?.url,
+        );
+        if (has_narration && !seen.has("narration")) {
+            services.push(narrationService());
+        }
+        // external web fonts (same-origin themes never ask). Compared by
+        // 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.
+        // 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
+    ================================================== */
+
+    /**
+     * Play the current slide's narration, if it has one.
+     *
+     * One `<audio>` element is reused for the whole story rather than a
+     * player per slide, so switching slides cannot leave a recording playing
+     * behind. Two things gate it:
+     *
+     * - **browser autoplay policy**: unmuted audio only plays after a user
+     *   gesture, so before the first interaction the element is left paused
+     *   and nothing is reported as broken. Re-arm on the first interaction.
+     * - **consent**: the `media:narration` service is requested at start-up
+     *   (see `_startConsentAsk`); a denied or unanswered service means no
+     *   playback, and the story still works.
+     */
+    _playNarration(slide: StorymapSlide | undefined, allow_without_gesture = false) {
+        // 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()) {
+            this._replayNarrationAfterGesture = true;
+            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;
+        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;
+        void el.play()?.catch?.(() => {
+            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");
+            this._narration_el.className = "vco-media-item vco-narration";
+            this._narration_el.preload = "none";
+            this._narration_el.setAttribute("aria-hidden", "true");
+        }
+        return this._narration_el;
+    }
+
+    _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;
+        this._narration_allowed = this._narration_allowed && true;
+        if (this._replayNarrationAfterGesture) {
+            this._replayNarrationAfterGesture = false;
+            this._playNarration(this.data.slides?.[this.current_slide], true);
+        }
+    }
+
+    _has_user_gesture(): boolean {
+        return this._user_gestured;
+    }
+
     _startAutoplay() {
         this._stopAutoplay();
         this._autoplay_stopped = false;
-        if (this.options.autoplay > 0) {
-            // any user interaction stops autoplay permanently
-            const stop = () => {
+        // a denied media:narration service means no narration for this story
+        const manager = consentManagerOf(this.options);
+        if (manager && this.options.consent_required) {
+            this._narration_allowed = !manager.isDenied(narrationService().key);
+        }
+        // browsers only allow unmuted audio after a user gesture; the first
+        // interaction arms narration for the rest of the story
+        if (!this._user_gestured) {
+            const on_gesture = () => {
+                this._user_gestured = true;
+                this._note_user_gesture_for_narration();
+                this._el.container.removeEventListener("pointerdown", on_gesture);
+                this._el.container.removeEventListener("keydown", on_gesture);
+            };
+            this._el.container.addEventListener("pointerdown", on_gesture, { once: true });
+            this._el.container.addEventListener("keydown", on_gesture, { once: true });
+        }
+        // prefers-reduced-motion: no autoplay (WCAG 2.2.2)
+        if (this.options.autoplay > 0 && !prefersReducedMotion()) {
+            // 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 });
@@ -866,17 +2333,101 @@ 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.
+     *
+     * With `autoplay_media` on and a slide whose media is playable audio or
+     * video, the advance waits for that media to end instead of using the
+     * `autoplay` millisecond timer. The timer is **kept as a fallback** in
+     * that case too: a media element that never fires `ended` (a stalled
+     * fetch, a codec the browser cannot play, or a slide whose media was
+     * never loaded because the visitor skipped past it) would otherwise stop
+     * the story dead. So both are armed, whichever fires first advances, and
+     * the other is cleared.
+     */
     _scheduleAutoplay() {
         this._stopAutoplay();
-        if (this.options.autoplay > 0 && !this._autoplay_stopped) {
-            this._autoplay_timer = setTimeout(() => {
-                this._autoplay_timer = null;
-                if (this.current_slide + 1 < this.data.slides.length) {
-                    this.goTo(this.current_slide + 1);
-                    this._scheduleAutoplay();
-                }
-            }, this.options.autoplay);
+        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();
+            if (this.current_slide + 1 < this.data.slides.length) {
+                this.goTo(this.current_slide + 1);
+                this._scheduleAutoplay();
+            }
+        };
+        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?.()) {
+                // 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, dwell);
     }
 
     _stopAutoplay() {
@@ -884,33 +2435,123 @@ class StoryMapBase {
             clearTimeout(this._autoplay_timer);
             this._autoplay_timer = null;
         }
+        this._autoplay_advance = null;
+    }
+
+    /**
+     * The current slide's `uniqueid`, or null when the data carries none.
+     *
+     * A storymap-JSON slide usually has no `uniqueid` — the slider generates
+     * one per slide for its own DOM ids, but that is not a shareable identity,
+     * so it is deliberately not used here. A IIIF manifest supplies one per
+     * canvas (§2.3), and that is what a deep link should name.
+     */
+    _currentSlideId(): string | null {
+        const id = this.data?.slides?.[this.current_slide]?.uniqueid;
+        return typeof id === "string" && id !== "" ? id : null;
     }
 
-    /** Keep the URL hash in sync with the current slide (#slide-N). */
+    /** The current slide as a Content State, or null when it has no id. */
+    _currentContentState(): ContentState | null {
+        const id = this._currentSlideId();
+        if (id === null) return null;
+        const region = this.data.slides[this.current_slide]?.location?.region;
+        return Array.isArray(region) && region.length === 4
+            ? { id, region: region as [number, number, number, number] }
+            : { id };
+    }
+
+    /**
+     * Keep the URL in sync with the current slide: the `#slide-…` hash and,
+     * when the slide has a shareable id, an `iiif-content` parameter (§5.1).
+     *
+     * The query string is rewritten rather than replaced, because pages like
+     * the embed player and the test harness carry their own configuration in
+     * it (`?url=…`, `?example=…`, `?manifest=…`).
+     */
     _syncHash() {
         try {
-            // preserve the query string: pages like the embed player carry
-            // their configuration in it (?url=..., ?example=...)
+            const state = this._currentContentState();
+            const params = new URLSearchParams(window.location.search);
+            if (state !== null) {
+                params.set(
+                    CONTENT_STATE_PARAM,
+                    formatContentState(
+                        state,
+                        (this.data as { uniqueid?: string }).uniqueid ?? null,
+                    ),
+                );
+            } else {
+                // a storymap-JSON slide with no id cannot be named, so the
+                // parameter would only ever point at the wrong stop
+                params.delete(CONTENT_STATE_PARAM);
+            }
+            const query = params.toString();
             history.replaceState(
                 null,
                 "",
-                window.location.pathname + window.location.search + "#slide-" + this.current_slide,
+                window.location.pathname +
+                    (query === "" ? "" : "?" + query) +
+                    "#slide-" +
+                    (state !== null ? encodeURI(state.id) : this.current_slide),
             );
         } catch {
             // non-browser or sandboxed contexts
         }
     }
 
-    /** A #slide-N hash deep-links the storymap (applied on load + hashchange). */
-    _applyHashSlide(): boolean {
-        const match = /^#slide-(\d+)$/.exec(window.location.hash);
-        if (!match) return false;
-        const n = parseInt(match[1], 10);
-        if (n >= 0 && n < this.data.slides.length && n !== this.current_slide) {
-            this.goTo(n);
-            return true;
+    /**
+     * A `#slide-…` hash or an `iiif-content` parameter deep-links the storymap
+     * (applied on load + hashchange).
+     *
+     * The hash token is an index when it is all digits and a `uniqueid`
+     * otherwise, which is unambiguous because an index never contains anything
+     * else. The index form stays supported, so links shared before ids were
+     * emitted keep working; they just stop being stable the moment a slide is
+     * inserted.
+     */
+    _applyHashSlide(captured?: { state: ContentState | null; hash: string } | null): boolean {
+        const link = captured ?? {
+            state: parseContentState(
+                new URLSearchParams(window.location.search).get(CONTENT_STATE_PARAM),
+            ),
+            hash: window.location.hash,
+        };
+        const target = this._resolveDeepLink(link.state, link.hash);
+        if (target === null || target === this.current_slide) return false;
+        this.goTo(target);
+        return true;
+    }
+
+    /**
+     * A content state or hash token as a slide index, or null when it names
+     * nothing. A content state wins over the hash, being the standard spelling.
+     */
+    _resolveDeepLink(state: ContentState | null, hash: string): number | null {
+        if (state !== null) {
+            const index = this._slideIndexById(state.id);
+            if (index !== null) return index;
+            console.warn(
+                `StoryMapJS: the content state names a canvas this storymap does not have: ${state.id}`,
+            );
         }
-        return false;
+        const match = /^#slide-(.+)$/.exec(hash);
+        if (match === null) return null;
+        const token = match[1];
+        if (/^\d+$/.test(token)) {
+            const n = parseInt(token, 10);
+            return n >= 0 && n < this.data.slides.length ? n : null;
+        }
+        return this._slideIndexById(decodeURIComponent(token));
+    }
+
+    /** A canvas id as a slide index, or null. */
+    _slideIndexById(id: string): number | null {
+        const slides = this.data?.slides ?? [];
+        for (let i = 0; i < slides.length; i++) {
+            if (slides[i]?.uniqueid === id) return i;
+        }
+        return null;
     }
 
     /*  Resize handling
@@ -938,6 +2579,7 @@ class StoryMapBase {
             this._resize_observer = new ResizeObserver(onResize);
             this._resize_observer.observe(this._el.container);
         }
+        this._on_resize = onResize;
         window.addEventListener("resize", onResize);
     }
 
@@ -947,6 +2589,34 @@ class StoryMapBase {
      * map container (given the vco-map class) and moved into place between
      * the menubar and the story slider.
      */
+    /**
+     * The map pane, for the code paths that only run when there is a map.
+     * `_el.map` is null exactly when the engine is; see `_map_required()`.
+     */
+    _map_el(): HTMLElement {
+        if (!this._el.map) {
+            throw new Error(
+                'StoryMapJS: this operation needs a map pane, but the story has none (map_type: "none").',
+            );
+        }
+        return this._el.map;
+    }
+
+    /**
+     * The map engine, for the code paths that only run when there is a map.
+     * Throws rather than returning null: reaching one of these from a mapless
+     * story is a bug in this class, and a loud one, rather than a layout that
+     * quietly misbehaves. Public entry points use `this._map?.` instead.
+     */
+    _map_required(): OpenLayersMap {
+        if (!this._map) {
+            throw new Error(
+                'StoryMapJS: this operation needs a map, but the story has none (map_type: "none").',
+            );
+        }
+        return this._map;
+    }
+
     _resolveMapElement(): HTMLElement | null {
         const element = this.options.map_options?.element;
         if (!element) {
@@ -962,7 +2632,7 @@ class StoryMapBase {
         return el;
     }
 
-    _onTitle(e: unknown) {
+    _onTitle(e: { title: string }) {
         this.fire("title", e);
     }
 
@@ -976,38 +2646,166 @@ class StoryMapBase {
 
     _onSlideChange(e: { current_slide: number }) {
         if (this.current_slide !== e.current_slide) {
-            const duration = slideTransitionDuration(this.current_slide, e.current_slide);
-            this.current_slide = e.current_slide;
-            this._map.goTo(this.current_slide);
-            this._beginTransition(duration);
-            this.fire("change", { current_slide: this.current_slide }, this);
-            this._syncHash();
-            this._scheduleAutoplay();
-            this._updateProgress();
+            // the slider already moved itself
+            this._navigate(e.current_slide, { navigate: "slider" });
         }
     }
 
     _onMapChange(e: { current_marker: number }) {
         if (this.current_slide !== e.current_marker) {
-            const duration = slideTransitionDuration(this.current_slide, e.current_marker);
-            this.current_slide = e.current_marker;
-            this._storyslider.goTo(this.current_slide);
-            this._beginTransition(duration);
-            this.fire("change", { current_slide: this.current_slide }, this);
-            this._syncHash();
+            // the map already moved itself
+            this._navigate(e.current_marker, { navigate: "map" });
+        }
+    }
+
+    _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();
-            this._updateProgress();
+        } 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);
         }
     }
 
     _onOverview(e?: unknown) {
-        this._map.markerOverview();
+        this._map?.markerOverview();
     }
 
     /**
@@ -1039,18 +2837,18 @@ class StoryMapBase {
     }
 
     _onBackToStart(e?: unknown) {
-        this.current_slide = 0;
-        this._map.goTo(this.current_slide);
-        this._storyslider.goTo(this.current_slide);
-        this.fire("change", { current_slide: this.current_slide }, this);
-        // keep hash, progress and autoplay in sync like the other paths
-        this._syncHash();
-        this._scheduleAutoplay();
-        this._updateProgress();
+        if (this.current_slide === 0) {
+            return;
+        }
+        this._navigate(0);
     }
 
-    _onMenuBarCollapse(e: { y: number }) {
-        this._updateDisplay(e.y, true);
+    _onMenuBarCollapse(e: { y?: number; collapsed?: boolean }) {
+        // `y` is the menubar position, not a map height; `collapsed` is the
+        // authoritative signal. Older menubars omit it, so infer it from a
+        // near-zero y for backwards compatibility.
+        this._collapsed = e.collapsed !== undefined ? e.collapsed : e.y !== undefined && e.y < 5;
+        this._updateDisplay(undefined, true);
     }
 
     _onMapLoaded() {
@@ -1071,34 +2869,59 @@ class StoryMapBase {
         if (!this.options.show_distance) {
             return;
         }
-        const km = this._map.getRouteDistance();
+        const km = this._map?.getRouteDistance();
         this._menubar.setDistance(km);
     }
 
+    /**
+     * The URL is ours to own as soon as the story is: the deep link is read
+     * and the hash is kept in step.
+     *
+     * This deliberately does **not** wait for the map. The map only reports
+     * itself loaded on OpenLayers' first `loadend`, which is the first paint of
+     * the base tiles — so a deep link used to be applied only once
+     * `tile.openstreetmap.org` answered, and on a slow or unreachable tile
+     * host it was never applied at all. Nothing about a URL depends on imagery:
+     * the data and the slider are what it needs, and both are ready before the
+     * map is. `_applyHashSlide` → `goTo` → `_navigate` already tolerates a map
+     * that has not reported loaded, and the map re-syncs when it does.
+     */
+    _initHash() {
+        if (this._hash_initialized || !this._loaded.storyslider) {
+            return;
+        }
+        this._hash_initialized = true;
+        // a #slide-N hash or an iiif-content parameter deep-links the initial
+        // slide (issue #146) and keeps working through the browser
+        // back/forward buttons
+        this._applyHashSlide(this._initial_deep_link);
+        // from here on the URL is ours to keep in sync, so a hashchange means
+        // the user moved and can be read live
+        this._on_hashchange = () => this._applyHashSlide();
+        window.addEventListener("hashchange", this._on_hashchange);
+        this._syncHash();
+    }
+
     _onLoaded() {
-        if (this._loaded.storyslider && this._loaded.map) {
+        this._initHash();
+        // the slider is always required; the map only if there is one, so a
+        // mapless story still fires `loaded` and gets its hash, progress and
+        // distance applied
+        if (this._loaded.storyslider && (this._map_disabled || this._loaded.map)) {
             this.fire("loaded", this.data);
-            if (!this._hash_initialized) {
-                this._hash_initialized = true;
-                // a #slide-N hash deep-links the initial slide (issue #146)
-                // and keeps working through the browser back/forward buttons
-                this._applyHashSlide();
-                window.addEventListener("hashchange", () => this._applyHashSlide());
-                this._syncHash();
-            }
             this._updateProgress();
             this._updateDistance();
         }
     }
 }
 
-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
      * (src/main.ts) and the built ESM bundle (js/storymap.js).
      */
-    static SCRIPT_PATH = new URL("../", import.meta.url).href;
+    static SCRIPT_PATH = new URL(/* @vite-ignore */ "../", import.meta.url).href;
 
     constructor(...args: ConstructorParameters<typeof StoryMapBase>) {
         super(...args);