@projektemacher/storymapjs 0.10.8 → 0.11.0

package/dist/js/storymap.d.ts

@@ -1,7 +1,9 @@
 import { default as default_2 } from 'ol/control/OverviewMap';
 import { default as default_3 } from 'ol/Overlay';
 import { default as default_4 } from 'ol/tilegrid/TileGrid';
+import { default as default_5 } from 'ol/source/ImageStatic';
 import { Extent } from 'ol/extent';
+import { Image as Image_2 } from 'ol/layer';
 import { Map as Map_3 } from 'ol';
 import { default as OlLayer } from 'ol/layer/Layer';
 import { default as OlMap } from 'ol/Map';
@@ -12,6 +14,7 @@ import { default as OlVectorLayer } from 'ol/layer/Vector';
 import { default as OlView } from 'ol/View';
 import { Style } from 'ol/style';
 import { Tile } from 'ol/layer';
+import { unByKey } from 'ol/Observable';
 import { Vector } from 'ol/layer';
 import { XYZ } from 'ol/source';
 
@@ -137,6 +140,9 @@ declare interface ConsentService {
     label: string;
 }
 
+/** Constructor shape accepted by the mixin functions. */
+declare type Constructor<T = object> = new (...args: any[]) => T;
+
 export declare type ContentState = {
     /** The canvas (or other resource) the state points at. */
     id: string;
@@ -150,7 +156,7 @@ export declare type ContentState = {
 
 declare interface DragData {
     sliding: boolean;
-    direction: string | null;
+    direction: SwipeDirection | null;
     pagex: {
         start: number;
         end: number;
@@ -193,13 +199,25 @@ declare interface DragEventNames {
 }
 
 /** Eventing members provided by the Evented mixin. */
-declare interface EventedInstance {
-    on: (type: string, fn: unknown, context?: unknown) => unknown;
-    off: (type: string, fn: unknown, context?: unknown) => unknown;
-    fire: (type: string, data?: unknown, target?: unknown) => unknown;
-    hasEventListeners: (type: string) => boolean;
+declare interface EventedInstance<M = Record<string, unknown>> {
+    on<K extends keyof M & string>(type: K, fn: (e: FiredEvent<M, K>) => void, context?: unknown): this;
+    off<K extends keyof M & string>(type: K, fn: (e: FiredEvent<M, K>) => void, context?: unknown): this;
+    fire<K extends keyof M & string>(type: K, data?: M[K]): this;
+    hasEventListeners<K extends keyof M & string>(type: K): boolean;
 }
 
+/** What a listener receives: the payload, plus the framework's own fields.
+ *
+ * Kept as an intersection because `fire` merges them into one object — that
+ * is what a handler gets. As a side effect it also fixes the `type`
+ * clobbering at the type level: intersecting `type: "loaded"` with
+ * `type?: string` yields `"loaded"`.
+ */
+export declare type FiredEvent<M, K extends keyof M & string> = M[K] & {
+    type: K;
+    target: unknown;
+};
+
 declare type IconSpec = {
     url: string;
     size: number[];
@@ -237,6 +255,14 @@ export declare function isPresentation3Collection(data: unknown): boolean;
  */
 export declare function isPresentation3Manifest(data: unknown): boolean;
 
+/**
+ * True for a slideshow tour document: a v2 `AnnotationCollection` or a v1
+ * `AnnotationPageSequence` carrying the matching extension context (never a
+ * P3 `Manifest`/`Collection`), with items shaped like tour annotations.
+ * Narrow by conjunction so P3 `seeAlso` collections never match.
+ */
+export declare function isSlideshowCollection(doc: unknown): boolean;
+
 /**
  * UI strings for the active locale.
  *
@@ -278,6 +304,84 @@ export declare interface LatLngLiteral {
     lng?: number;
 }
 
+declare interface LayersBasemapRow {
+    kind: "basemap";
+    map_type: string;
+    label: string;
+    checked: boolean;
+}
+
+declare class LayersControl extends LayersControl_base {
+    constructor(...args: ConstructorParameters<typeof LayersControlBase>);
+}
+
+declare const LayersControl_base: Constructor<EventedInstance<LayersControlEvents>> & typeof LayersControlBase;
+
+declare class LayersControlBase {
+    "_el": {
+        container: HTMLElement;
+        button: HTMLButtonElement;
+        panel: HTMLElement;
+    };
+    "_menubar": HTMLElement;
+    "_delegate": LayersControlDelegate | null;
+    "_rows": LayersRow[];
+    "_open": boolean;
+    "_panel_id": string;
+    "_onKeyDownBound": ((e: KeyboardEvent) => void) | null;
+    "_onPointerDownBound": ((e: Event) => void) | null;
+    "fire": EventedInstance<LayersControlEvents>["fire"];
+    constructor(menubar: HTMLElement);
+    /** Hand the control its state source (StoryMap wires this via MenuBar). */
+    setDelegate(delegate: LayersControlDelegate): void;
+    /** Re-pull rows from the delegate and sync the panel in place. */
+    refresh(): void;
+    /** Re-resolve row labels (function labels repaint on language change). */
+    refreshLabels(): void;
+    open(): void;
+    close(): void;
+    /**
+     * Release the document listeners and drop the nodes. Called by
+     * `MenuBar.dispose()`; the control must not be used afterwards.
+     */
+    dispose(): void;
+    _onButtonClick(): void;
+    _onRowChange(e: Event, row: LayersRow): void;
+    _onPanelKeyDown(e: KeyboardEvent): void;
+    _onDocumentPointerDown(e: Event): void;
+    _sameRows(rows: LayersRow[]): boolean;
+    _updateRows(rows: LayersRow[]): void;
+    _buildRows(rows: LayersRow[]): void;
+    _buildGroup(kind: "basemap" | "overlay", rows: LayersRow[]): HTMLElement;
+    _buildRow(row: LayersRow): HTMLElement;
+}
+
+declare interface LayersControlDelegate {
+    /** Current rows, basemaps first. Empty while there is nothing to switch. */
+    rows(): LayersRow[];
+}
+
+declare interface LayersControlEvents {
+    basemapchange: {
+        map_type: string;
+    };
+    overlaychange: {
+        index: number;
+        visible: boolean;
+    };
+}
+
+declare interface LayersOverlayRow {
+    kind: "overlay";
+    /** Built-layer index: malformed entries are skipped, like setOverlayVisible. */
+    index: number;
+    label: string;
+    checked: boolean;
+    locked: boolean;
+}
+
+declare type LayersRow = LayersOverlayRow | LayersBasemapRow;
+
 /** Legacy drag handlers historically mixed mouse and touch event surfaces. */
 declare type LegacyEvent = Event & {
     originalEvent?: TouchEvent;
@@ -333,23 +437,12 @@ declare const Map_base: {
         onRemove(): void;
         _el: Record<string, unknown>;
         data?: unknown;
-        on: (type: string, fn: unknown, context?: unknown) => unknown;
-        off: (type: string, fn: unknown, context?: unknown) => unknown;
-        fire: (type: string, data?: unknown, target?: unknown) => unknown;
-        hasEventListeners: (type: string) => boolean;
-    };
-} & {
-    new (...args: any[]): {
-        _vco_events?: Record<string, {
-            action: unknown;
-            context: unknown;
-        }[]> | undefined;
-        on(type: string, fn: unknown, context?: unknown): /*elided*/ any;
-        hasEventListeners(type: string): boolean;
-        off(type: string, fn: unknown, context?: unknown): /*elided*/ any;
-        fire(type: string, data?: unknown, target?: unknown): /*elided*/ any;
+        on<K extends "loaded" | "change" | "added" | "removed" | "markerclick" | "popupopen" | "popupclose" | "markerRemoved" | "markerAdded" | "imageready" | "tilesallowed">(type: K, fn: (e: FiredEvent<MapEvents, K>) => void, context?: unknown): /*elided*/ any;
+        off<K extends "loaded" | "change" | "added" | "removed" | "markerclick" | "popupopen" | "popupclose" | "markerRemoved" | "markerAdded" | "imageready" | "tilesallowed">(type: K, fn: (e: FiredEvent<MapEvents, K>) => void, context?: unknown): /*elided*/ any;
+        fire<K extends "loaded" | "change" | "added" | "removed" | "markerclick" | "popupopen" | "popupclose" | "markerRemoved" | "markerAdded" | "imageready" | "tilesallowed">(type: K, data?: MapEvents[K] | undefined): /*elided*/ any;
+        hasEventListeners<K extends "loaded" | "change" | "added" | "removed" | "markerclick" | "popupopen" | "popupclose" | "markerRemoved" | "markerAdded" | "imageready" | "tilesallowed">(type: K): boolean;
     };
-} & typeof MapBase;
+} & Constructor<EventedInstance<MapEvents>> & typeof MapBase;
 
 declare class MapBase {
     "_el": {
@@ -377,6 +470,8 @@ declare class MapBase {
     "_line": Vector | null;
     "_line_active": Vector | null;
     "current_marker": number;
+    /** The wheel handler on the map element, stored for dispose(). */
+    "_onWheelBound": ((e: WheelEvent) => void) | null;
     "bounds_array": number[][] | null;
     "_tile_layer": OlLayer | null;
     "_tile_layer_mini": OlLayer | null;
@@ -388,7 +483,7 @@ declare class MapBase {
     "timer": ReturnType<typeof setTimeout> | null;
     "touch_scale": number;
     "scroll": ScrollState;
-    "fire": EventedInstance["fire"];
+    "fire": EventedInstance<MapEvents>["fire"];
     constructor(elem: string | HTMLElement, data?: Partial<StorymapData>, options?: Partial<StorymapOptions>);
     updateDisplay(w: number, h: number, animate?: boolean, d?: number, offset?: unknown): void;
     goTo(n: number, change?: boolean): void;
@@ -523,6 +618,12 @@ declare class MapBase {
     _onMarkerClick(e: {
         marker_number: number;
     }): void;
+    _onMarkerPopupOpen(e: {
+        marker_number: number;
+    }): void;
+    _onMarkerPopupClose(e: {
+        marker_number: number;
+    }): void;
     _onMapLoaded(e?: unknown): void;
     _onWheel(e: WheelEvent): void;
     _scollZoom(e?: unknown): void;
@@ -538,22 +639,28 @@ declare class MapBase {
     _initEvents(): void;
 }
 
+export declare interface MapEvents {
+    change: {
+        current_marker: number;
+    };
+    loaded: StorymapData;
+    added: StorymapData;
+    removed: StorymapData;
+    markerAdded: MapMarker;
+    markerRemoved: MapMarker;
+    markerclick: MarkerEventPayload;
+    popupopen: MarkerEventPayload;
+    popupclose: MarkerEventPayload;
+    imageready: ImagereadyPayload;
+    /** Deferred tile layers attached after a tile consent grant. */
+    tilesallowed: undefined;
+}
+
 declare class MapMarker extends MapMarker_base {
     constructor(...args: ConstructorParameters<typeof MapMarkerBase>);
 }
 
-declare const MapMarker_base: {
-    new (...args: any[]): {
-        _vco_events?: Record<string, {
-            action: unknown;
-            context: unknown;
-        }[]> | undefined;
-        on(type: string, fn: unknown, context?: unknown): /*elided*/ any;
-        hasEventListeners(type: string): boolean;
-        off(type: string, fn: unknown, context?: unknown): /*elided*/ any;
-        fire(type: string, data?: unknown, target?: unknown): /*elided*/ any;
-    };
-} & typeof MapMarkerBase;
+declare const MapMarker_base: Constructor<EventedInstance<MapMarkerEvents>> & typeof MapMarkerBase;
 
 declare class MapMarkerBase {
     "_el": Record<string, HTMLElement>;
@@ -568,7 +675,7 @@ declare class MapMarkerBase {
     "data": MapMarkerData;
     "options": StorymapOptions;
     "animator": AnimationHandle | null;
-    "fire": EventedInstance["fire"];
+    "fire": EventedInstance<MapMarkerEvents>["fire"];
     constructor(data?: MapMarkerData, options?: Partial<StorymapOptions>);
     /**
      * @deprecated No-op since 0.9.x upstream (the original marker defined an
@@ -620,6 +727,17 @@ declare type MapMarkerData = StorymapSlide & {
     real_marker?: boolean;
 };
 
+export declare interface MapMarkerEvents {
+    markerclick: MarkerEventPayload;
+    popupopen: MarkerEventPayload;
+    popupclose: MarkerEventPayload;
+}
+
+/** A marker event payload: the marker by slide index. */
+export declare interface MarkerEventPayload {
+    marker_number: number;
+}
+
 /** The resolved marker presentation: `marker.*` over `location.*`. */
 declare interface MarkerPresentation {
     icon?: string;
@@ -631,18 +749,38 @@ declare interface MarkerPresentation {
     useCustomMarker?: boolean;
 }
 
+declare interface MediaData extends StorymapSlideMedia {
+    uniqueid?: string | null;
+    link?: string | null;
+    link_target?: string | null;
+    [key: string]: unknown;
+}
+
+export declare interface MediaEvents {
+    loaded: MediaData;
+    media_loaded: MediaData;
+    media_ended: MediaData;
+    added: MediaData;
+    removed: MediaData;
+}
+
 declare interface MediaInstance {
     addTo: (container: HTMLElement) => void;
     loadMedia: () => void;
     stopMedia: () => void;
     updateDisplay: (w?: number, h?: number, l?: string) => void;
     dispose?: () => void;
-    on?: EventedInstance["on"];
-    off?: EventedInstance["off"];
+    on?: EventedInstance<MediaEvents>["on"];
+    off?: EventedInstance<MediaEvents>["off"];
     _state?: {
         loaded?: boolean;
         eager?: boolean;
     };
+    /** Per-item consent identity: each item is built with its own
+     `media_name`/`media_type`, which `hasPlayableMedia` reads back (#358). */
+    options?: {
+        media_type?: string;
+    };
 }
 
 /**
@@ -679,31 +817,23 @@ declare const MenuBar_base: {
         onRemove(): void;
         _el: Record<string, unknown>;
         data?: unknown;
-        on: (type: string, fn: unknown, context?: unknown) => unknown;
-        off: (type: string, fn: unknown, context?: unknown) => unknown;
-        fire: (type: string, data?: unknown, target?: unknown) => unknown;
-        hasEventListeners: (type: string) => boolean;
-    };
-} & {
-    new (...args: any[]): {
-        _vco_events?: Record<string, {
-            action: unknown;
-            context: unknown;
-        }[]> | undefined;
-        on(type: string, fn: unknown, context?: unknown): /*elided*/ any;
-        hasEventListeners(type: string): boolean;
-        off(type: string, fn: unknown, context?: unknown): /*elided*/ any;
-        fire(type: string, data?: unknown, target?: unknown): /*elided*/ any;
+        on<K extends "fullscreen" | "loaded" | "added" | "removed" | "overview" | "overlaychange" | "basemapchange" | "back_to_start" | "autoplay_toggle" | "progress_go" | "collapse">(type: K, fn: (e: FiredEvent<MenuBarEvents, K>) => void, context?: unknown): /*elided*/ any;
+        off<K extends "fullscreen" | "loaded" | "added" | "removed" | "overview" | "overlaychange" | "basemapchange" | "back_to_start" | "autoplay_toggle" | "progress_go" | "collapse">(type: K, fn: (e: FiredEvent<MenuBarEvents, K>) => void, context?: unknown): /*elided*/ any;
+        fire<K extends "fullscreen" | "loaded" | "added" | "removed" | "overview" | "overlaychange" | "basemapchange" | "back_to_start" | "autoplay_toggle" | "progress_go" | "collapse">(type: K, data?: MenuBarEvents[K] | undefined): /*elided*/ any;
+        hasEventListeners<K extends "fullscreen" | "loaded" | "added" | "removed" | "overview" | "overlaychange" | "basemapchange" | "back_to_start" | "autoplay_toggle" | "progress_go" | "collapse">(type: K): boolean;
     };
-} & typeof MenuBarBase;
+} & Constructor<EventedInstance<MenuBarEvents>> & typeof MenuBarBase;
 
 declare class MenuBarBase {
     "_el": Record<string, HTMLElement>;
     "collapsed": boolean;
     "options": MenuBarOptions;
     "animator": Record<string, unknown>;
-    "fire": EventedInstance["fire"];
+    "fire": EventedInstance<MenuBarEvents>["fire"];
     _fullscreenActive: boolean;
+    _autoplayStopped: boolean;
+    /** The layer switcher, if `show_layers_control` is on. */
+    "_layersControl": LayersControl | null;
     constructor(elem: HTMLElement | string, parent_elem?: HTMLElement, options?: object);
     show(d?: number): void;
     hide(top: number): void;
@@ -715,7 +845,7 @@ declare class MenuBarBase {
     setFullscreenState(active: boolean): void;
     /**
      * Repaint the overview button label. An image map has no interactive
-     * overview, so it gets the shorter wording.
+     * overview, so it gets the shorter wording. Icon-only on mobile.
      */
     _renderOverviewLabel(): void;
     /**
@@ -726,15 +856,35 @@ declare class MenuBarBase {
      * Repaint the collapse/expand toggle. Icon-only on mobile.
      */
     _renderCollapseLabel(collapsed: boolean): void;
+    /**
+     * Reflect the autoplay state in the toggle label.
+     */
+    setAutoplayState(stopped: boolean): void;
     /**
      * Repaint every text label from the active language (see `setLanguage`).
-     * Icon-only mobile buttons carry no text and are left untouched.
+     * Icon-only mobile buttons carry text via aria-label instead.
      */
     refreshLabels(): void;
     /**
-     * Update the progress indicator (issue #247); no-op when disabled.
+     * Icon-only mobile buttons expose their labels to assistive tech since
+     * the visible text is icon glyphs.
+     */
+    _renderMobileLabels(): void;
+    /** Hand the layer switcher its state source (StoryMap wires this). */
+    setLayersDelegate(delegate: LayersControlDelegate): void;
+    /** Re-pull the switcher rows (overlays, basemaps, consent state). */
+    refreshLayers(): void;
+    /**
+     * Update the progress indicator; no-op when disabled. The `progressbar`
+     * option selects the style (slideshow `progressbar`): the classic fill
+     * `bar` (default), height variants `block`/`thinblock`, or per-slide
+     * `dots`/`squares` buttons that jump to their slide.
      */
     setProgress(current: number, total: number): void;
+    /** The resolved progress style: `progressbar` wins, `show_progress` decides the default. */
+    _progressStyle(): "off" | "bar" | "dots" | "squares" | "block" | "thinblock";
+    /** Per-slide progress buttons for the `dots`/`squares` styles. */
+    _renderProgressSteps(style: "dots" | "squares", current: number, total: number): void;
     /**
      * Update the route distance display (issue #341); no-op when disabled or
      * before the first reading.
@@ -744,6 +894,14 @@ declare class MenuBarBase {
     _onButtonOverview(e: Event): void;
     _onButtonBackToStart(e: Event): void;
     _onButtonFullscreen(e: Event): void;
+    _onButtonAutoplay(): void;
+    _onLayersBasemap(e: {
+        map_type: string;
+    }): void;
+    _onLayersOverlay(e: {
+        index: number;
+        visible: boolean;
+    }): void;
     _onButtonCollapseMap(e: Event): void;
     _initLayout(): void;
     _updateDisplay(width?: number, height?: number, animate?: boolean): void;
@@ -754,6 +912,30 @@ declare class MenuBarBase {
     dispose(): void;
 }
 
+export declare interface MenuBarEvents {
+    overview: Event;
+    back_to_start: Event;
+    fullscreen: Event;
+    autoplay_toggle: undefined;
+    progress_go: {
+        slide: number;
+    };
+    collapse: {
+        y: number;
+        collapsed: boolean;
+    };
+    basemapchange: {
+        map_type: string;
+    };
+    overlaychange: {
+        index: number;
+        visible: boolean;
+    };
+    loaded: undefined;
+    added: undefined;
+    removed: undefined;
+}
+
 declare interface MenuBarOptions {
     width: number;
     height: number;
@@ -780,43 +962,40 @@ declare const Message_base: {
         onRemove(): void;
         _el: Record<string, unknown>;
         data?: unknown;
-        on: (type: string, fn: unknown, context?: unknown) => unknown;
-        off: (type: string, fn: unknown, context?: unknown) => unknown;
-        fire: (type: string, data?: unknown, target?: unknown) => unknown;
-        hasEventListeners: (type: string) => boolean;
+        on<K extends "loaded" | "added" | "removed" | "clicked">(type: K, fn: (e: FiredEvent<MessageEvents, K>) => void, context?: unknown): /*elided*/ any;
+        off<K extends "loaded" | "added" | "removed" | "clicked">(type: K, fn: (e: FiredEvent<MessageEvents, K>) => void, context?: unknown): /*elided*/ any;
+        fire<K extends "loaded" | "added" | "removed" | "clicked">(type: K, data?: MessageEvents[K] | undefined): /*elided*/ any;
+        hasEventListeners<K extends "loaded" | "added" | "removed" | "clicked">(type: K): boolean;
     };
-} & {
-    new (...args: any[]): {
-        _vco_events?: Record<string, {
-            action: unknown;
-            context: unknown;
-        }[]> | undefined;
-        on(type: string, fn: unknown, context?: unknown): /*elided*/ any;
-        hasEventListeners(type: string): boolean;
-        off(type: string, fn: unknown, context?: unknown): /*elided*/ any;
-        fire(type: string, data?: unknown, target?: unknown): /*elided*/ any;
-    };
-} & typeof MessageBase;
+} & Constructor<EventedInstance<MessageEvents>> & typeof MessageBase;
 
 declare class MessageBase {
     "_el": Record<string, HTMLElement>;
     "options": MessageOptions;
     "data": Record<string, unknown>;
     "animator": Record<string, unknown>;
-    "fire": EventedInstance["fire"];
+    "fire": EventedInstance<MessageEvents>["fire"];
     constructor(data?: Record<string, unknown>, options?: Record<string, unknown>, add_to_container?: HTMLElement);
     updateMessage(t: string): void;
     _updateMessage(t?: string): void;
     _onMouseClick(): void;
+    _onKeyDown(e: Event): void;
     _initLayout(): void;
     _initEvents(): void;
     /**
-     * Release the click listener and drop the element. Called by
+     * Release the listeners and drop the element. Called by
      * `StorySlider.dispose()`; the message must not be used afterwards.
      */
     dispose(): void;
 }
 
+export declare interface MessageEvents {
+    clicked: MessageOptions;
+    loaded: Record<string, unknown>;
+    added: Record<string, unknown>;
+    removed: Record<string, unknown>;
+}
+
 declare interface MessageOptions {
     width: number;
     height: number;
@@ -846,7 +1025,7 @@ declare class OpenLayers extends Map_2 {
     "_line_active": Vector;
     "_tile_layer_mini": OlLayer | null;
     "_mini_map": default_2;
-    "_markers": OpenLayersMapMarker[];
+    "_markers": StoryMapMarker[];
     /** App-level stacked overlays (see the `overlays` option) */
     "_overlay_layers": OlLayer[];
     /**
@@ -859,6 +1038,36 @@ declare class OpenLayers extends Map_2 {
     "_line_animation": number | null;
     /** Sources `imageready` has already been fired for. */
     "_imageready_fired": WeakSet<object>;
+    /** The `loadend` subscription key, stored so dispose() can detach it. */
+    "_loadend_key": Parameters<typeof unByKey>[0] | null;
+    /**
+     * Per-slide basemap layers by key (multi-manifest tours): built on first
+     * use through the tile layer factory, then reused. Empty until a slide
+     * names a `location.basemap`.
+     */
+    "_basemap_cache": globalThis.Map<string, OlLayer>;
+    /**
+     * The active per-slide basemap key, or null when the story basemap is
+     * showing. Restored to the story basemap on slides without one.
+     */
+    "_slide_basemap": string | null;
+    /** Spotlight mask element (slideshow passepartout), or null when off. */
+    "_mask_el": HTMLDivElement | null;
+    /** Per-slide image overlay layer (slideshow imgoverlay), or null. */
+    "_imgoverlay_layer": OlLayer | null;
+    /** Guards stale static-fallback probes (see `_probeStaticFallback`). */
+    "_static_probe_token": number;
+    /**
+     * Set by `dispose()` so in-flight fetches and probes resolve into
+     * no-ops instead of touching a torn-down map.
+     */
+    "_disposed": boolean;
+    /**
+     * Per-URL probe tokens for static slide basemaps: concurrent probes for
+     * different slides must not cancel each other (see
+     * `_createStaticImageBasemap`).
+     */
+    "_slide_probe_tokens": globalThis.Map<string, number>;
     _createMap(): void;
     /** Extra attribution fragments (e.g. overlay credits), always listed last. */
     "_extra_attributions": string[];
@@ -880,15 +1089,37 @@ declare class OpenLayers extends Map_2 {
     /** The highlighted route line layer drawn up to the current slide. */
     getLineActive(): OlLayer | null;
     /** The markers, in slide order (the index matches the slide index). */
-    getMarkers(): OpenLayersMapMarker[];
+    getMarkers(): StoryMapMarker[];
     /** One marker by slide index, or `null`. */
-    getMarker(index: number): OpenLayersMapMarker | null;
+    getMarker(index: number): StoryMapMarker | null;
     /**
      * (Re)render the attribution line for the current map type. Called at
      * creation and on every `map_type` switch, which previously left the
      * initial text stale.
      */
     _updateAttribution(): void;
+    /**
+     * Provider credit for a `map_type`, in both renderings: the linked HTML
+     * for our own `.vco-map-attribution` line and the plain text for the
+     * OpenLayers source `attributions`. One table — the two previous
+     * functions repeated the same `osm/stadia/mapbox/esri` switch and could
+     * drift apart, leaving a provider credited in one place but not the other
+     * (which their terms of service require).
+     */
+    _providerCredit(map_type: string): {
+        html: string;
+        text: string;
+    };
+    /**
+     * The table row for an absolute tile template's host, or null when the
+     * template is relative (a host serving its own tiles credits itself via
+     * `attribution`) or unknown. Subdomains match their parent, so
+     * `a.tile.openstreetmap.org` credits OSM.
+     */
+    _hostCredit(map_type: string): {
+        html: string;
+        text: string;
+    } | null;
     _getAttribution(map_type: string): string[];
     /**
      * The provider credit for `map_type` as plain text (no HTML), for the
@@ -950,6 +1181,12 @@ declare class OpenLayers extends Map_2 {
      * `getOverlayLayers().length`.
      */
     getOverlayCount(): number;
+    /**
+     * The built overlay entries, parallel to `getOverlayLayers()`: malformed
+     * entries are skipped, so this is what a control must iterate to stay on
+     * the same index space as `setOverlayVisible()`.
+     */
+    getOverlayEntries(): StorymapOverlayLayer[];
     /**
      * Show or hide a stacked overlay by index (re-syncs attribution). The
      * index counts built layers, i.e. it skips malformed entries.
@@ -989,6 +1226,51 @@ declare class OpenLayers extends Map_2 {
         zoom: number;
         center: number[];
     } | null;
+    /**
+     * Paint the story's static image when its IIIF `info.json` cannot be
+     * used (unreachable, or missing dimensions): a single-resolution
+     * `ImageStatic` layer replaces the empty tile layer, so the tour still
+     * shows its picture instead of a blank basemap. Needs
+     * `iiif.fallbackUrl` (the full-size image) plus `iiif.width`/`height`
+     * (canvas size); without dimensions the natural size is probed, but
+     * only for slideshow tours — internal documents keep the existing
+     * error path. Returns false when nothing was (or will be) painted.
+     */
+    _useStaticFallback(empty_layer: Tile): boolean;
+    /**
+     * Resolve a fallback image's natural size, then paint it. Stale probes
+     * (a newer probe started, e.g. after a basemap switch) and unusable
+     * dimensions fall back to the logged IIIF error.
+     */
+    _probeStaticFallback(empty_layer: Tile, url: string): Promise<void>;
+    /**
+     * The natural size of an image URL. Separated for testability: unit
+     * tests stub the `Image` constructor rather than the network.
+     */
+    _probeStaticImage(url: string): Promise<{
+        width: number;
+        height: number;
+    }>;
+    /**
+     * One static image source: shared by the story fallback (known extent),
+     * per-slide static basemaps (probed extent) and per-slide overlays
+     * (view extent). Layer assembly stays per call site — base (z 0),
+     * pending-fill and overlay (z 5, opacity) have different lifecycles.
+     */
+    _newStaticSource(url: string, extent: Extent, projection: string | OlProjection, attributions?: string | string[]): default_5;
+    /**
+     * One static image layer: the constructor shared by the story fallback,
+     * per-slide static basemaps and per-slide overlays. Extent and
+     * projection are the caller's policy (canvas size, probed size, or view
+     * extent); presentation rides the options.
+     */
+    _newStaticLayer(url: string, extent: Extent, projection: string | OlProjection, presentation?: {
+        opacity?: number;
+        attributions?: string | string[];
+        zIndex?: number;
+    }): Image_2<default_5>;
+    /** Swap the empty tile layer for a static image of the given extent. */
+    _buildStaticLayer(empty_layer: Tile, url: string, width: number, height: number): void;
     _createTileLayer(map_type: string): OlLayer;
     /**
      * A layer's source, or null when it has none. Custom `Layer` subclasses
@@ -1069,15 +1351,15 @@ declare class OpenLayers extends Map_2 {
     _createMiniMap(): void;
     _fitMiniMapToImage(): void;
     _createMarker(d: StorymapSlide): void;
-    _addMarker(marker: OpenLayersMapMarker): void;
+    _addMarker(marker: StoryMapMarker): void;
     /**
      * Position marker overlays on the unwrapped longitude path so they sit on
      * the same world copy as the fitted view and the line (issue #381).
      * Image-space coordinates are not degrees and stay untouched.
      */
     _afterCreateMarkers(): void;
-    _removeMarker(marker: OpenLayersMapMarker): void;
-    _getAllMarkersBounds(markers_array: OpenLayersMapMarker[]): number[][];
+    _removeMarker(marker: StoryMapMarker): void;
+    _getAllMarkersBounds(markers_array: StoryMapMarker[]): number[][];
     /**
      * Normalize a longitude sequence so consecutive values differ by at most
      * 180 degrees: markers keep their raw coordinates (OpenLayers wraps the
@@ -1143,10 +1425,84 @@ declare class OpenLayers extends Map_2 {
     /**
      * Image region stop: fit the xywh bbox ([x, y, w, h] image pixels —
      * the EPSG:4326 image space) with the shared animation options, then
-     * keep the minimap collapse state in sync like `_viewTo`.
+     * keep the minimap collapse state in sync like `_viewTo`. A slide
+     * rotation follows the fit (fit() takes no rotation), plus the
+     * filter/mask tail when the location is passed.
      */
-    _fitRegion(region: [number, number, number, number], opts?: ViewToOptions): void;
+    _fitRegion(region: [number, number, number, number], opts?: ViewToOptions, loc?: StorymapSlideLocation): void;
     _toViewCoords(loc: LatLngLiteral): number[];
+    /**
+     * Swap the base layer for a slide `location.basemap` (multi-manifest
+     * tours): built on first use through the tile layer factory (custom
+     * factories apply), then cached. A slide without one restores the story
+     * basemap. No-op when the requested key is already showing, so resize
+     * and re-fit paths pass through untouched. Consent-denied tiles skip
+     * the switch entirely.
+     */
+    _switchSlideBasemap(loc: StorymapSlideLocation | null | undefined): void;
+    /**
+     * Build a per-slide basemap layer: IIIF `info.json` URLs (or bare
+     * service bases) become tile layers; plain image URLs become static
+     * image layers (dimensions probed); anything else goes through the
+     * regular tile layer factory, so keywords and templates keep working.
+     */
+    _createSlideBasemap(key: string): OlLayer;
+    /**
+     * A basemap from a plain image URL (no IIIF service): an `ImageLayer`
+     * filled in once the natural size probes. Used for per-slide basemaps
+     * pointing at static files, and as the fallback when an `info.json`
+     * turns out unreachable (some `.jpx`/`.jp2` bases serve one, some are
+     * plain files — only the fetch tells). Unusable dimensions keep the
+     * error logged and the layer empty, like the failed-service path.
+     */
+    _createStaticImageBasemap(url: string): OlLayer;
+    /**
+     * Replace a failed IIIF slide basemap with a probed static image under
+     * the same cache key, swapping it into the map when still current (the
+     * visitor may have moved on while the fetch was in flight, in which
+     * case the cache holds it for a return visit).
+     */
+    _replaceWithStaticBasemap(key: string, pending: Tile): void;
+    /**
+     * The story's own base layer (as opposed to a per-slide one): stashed
+     * on creation so a slide basemap can hand back to it without refetching.
+     */
+    "_story_basemap_layer": OlLayer | null;
+    /**
+     * Apply a slide's CSS filter grading to the map viewport
+     * (slideshow `filters`). Always assigned — "" clears — so grading never
+     * leaks onto the next slide.
+     */
+    _applySlideFilter(loc: StorymapSlideLocation | null | undefined): void;
+    /**
+     * Apply a slide's spotlight mask (slideshow `passepartout`): normalized
+     * viewport fractions stay visible while the rest is dimmed. Rendered as
+     * up to four percentage-positioned divs (or one for `invert`), so it
+     * needs no updates on pan/zoom/resize. `pointer-events: none` keeps
+     * markers clickable through the shade; the marker overlay container
+     * (z-index 1) paints above it. Absent/invalid clears the mask.
+     */
+    _applySlideMask(loc: StorymapSlideLocation | null | undefined): void;
+    /** Filter + mask together: the synchronous tail of every navigation. */
+    _applySlideFilterAndMask(loc: StorymapSlideLocation | null | undefined): void;
+    /**
+     * Rotate the view to a slide `rotation` (degrees clockwise). Merges into
+     * the caller's animation when one is running; on its own (region fits,
+     * location-less slides, overview reset) it animates alone, or sets
+     * synchronously when the navigation is instant. A no-op when neither
+     * the slide nor the view is rotated, so unrotated stories animate
+     * exactly as before.
+     */
+    _applySlideRotation(loc: StorymapSlideLocation | null | undefined, duration?: number, instant?: boolean): void;
+    /**
+     * Show a per-slide image overlay (slideshow `imgoverlay`) while its
+     * slide is active. `extent` pins it (`[west, south, east, north]` lon/lat,
+     * raw image pixels on image-space maps); otherwise it covers the current
+     * view, optionally scaled to `size` (fraction of the viewport). Painted
+     * above the base (z 5) below the route lines. Null/empty clears.
+     * Consent-denied tiles skip it like every other layer.
+     */
+    setSlideImageOverlay(overlay: StorymapImageOverlay | null | undefined): void;
     _getMapZoom(): number;
     _getMapCenter(): LatLngLiteral;
     _getMapCenterOffset(location: LatLngLiteral, zoom: number): LatLngLiteral;
@@ -1199,81 +1555,6 @@ declare class OpenLayers extends Map_2 {
     _setViewInstant(loc: StorymapSlideLocation, zoom: number): void;
 }
 
-declare class OpenLayersMapMarker extends MapMarker {
-    "_overlay": default_3;
-    "_onMarkerClickBound": ((e: Event) => void) | null;
-    /** marker.popup: the active marker opens its card when clicked. */
-    "_popup_enabled": boolean;
-    /** marker.audioBadge: flag a slide that has narration or audio media. */
-    "_audio_badge": boolean;
-    /**
-     * The popup card while it is open. `declare` fields are undefined until
-     * assigned, so every read below is a truthiness check, never `=== null`,
-     * and there is no constructor to initialise them: `MapMarker`'s own
-     * constructor already runs `_initLayout()` → `_createMarker()`, which
-     * assigns the flags, and initialising afterwards would wipe them.
-     */
-    "_popup_el": HTMLElement | null;
-    /** Escape-to-close, detached in dispose(). */
-    "_onPopupKeyBound": ((e: KeyboardEvent) => void) | null;
-    /** Mirrors `active()`, as a flag rather than a method reference. */
-    "_is_active": boolean;
-    /**
-     * The merged marker presentation: `marker.*` wins, `location.*` is the
-     * legacy spelling and still works (docs/plans/iiif-media-tours.md §2).
-     * `location` also stays the carrier of geography, so lat/lon are read
-     * from it alone — presentation never moves a marker.
-     */
-    _presentation(d?: MapMarkerData): MarkerPresentation;
-    _createMarker(d?: MapMarkerData, o?: StorymapOptions): void;
-    _createMarkerElement(d: MapMarkerData, o?: StorymapOptions): HTMLDivElement;
-    /**
-     * The marker's {lat, lon}, or null when it is a non-georeferenced marker
-     * (an overview slide, or a slide with only an image region). `_createMarker`
-     * already established this for a real marker, but returning it from one
-     * place means the type checker can see it too.
-     */
-    latLon(): LatLngLiteral | null;
-    _addTo(m: Map_3): void;
-    _removeFrom(m: Map_3): void;
-    /**
-     * Terminal teardown: detach the click listener and drop the overlay and
-     * element. Called by the map's dispose(); the marker must not be used
-     * afterwards.
-     */
-    /**
-     * Toggle the popup card for the *active* marker. Inactive markers keep
-     * their original behaviour — a click navigates — so a popup never
-     * swallows navigation on a map full of pins.
-     *
-     * The card is a DOM element parented to the marker element and positioned
-     * with CSS, which is how it survives a move to the vector renderer
-     * (docs/plans/issue-159-vector-markers.md): only the anchor is the
-     * marker's, and that is `latLon()`.
-     */
-    _togglePopup(): void;
-    _closePopup(): void;
-    get popupOpen(): boolean;
-    /**
-     * Headline, a sanitized excerpt, the media thumb and an audio control.
-     * Every piece of text goes through `sanitizeSlideText` — a slide's text
-     * is untrusted input and a marker card is no different (the stored-XSS
-     * audit made that lesson once; a label is attacker-controlled text like
-     * any other).
-     */
-    _createPopupElement(): HTMLElement | null;
-    /**
-     * A small indicator on markers whose slide has narration or audio media
-     * (the Micrio affordance). Recomputed on activation, because a slide's
-     * media may only be known once it is resolved.
-     */
-    _updateAudioBadge(): void;
-    dispose(): void;
-    _active(a: boolean): void;
-    _customIconAnchor(size?: number[]): number[];
-    _location(): LatLngLiteral | null;
-}
-
 /** Wheel/scroll zoom bookkeeping (handles cleared via clearTimeout). */
 declare interface ScrollState {
     start_time: number | null;
@@ -1307,34 +1588,31 @@ declare const Slide_base: {
         onRemove(): void;
         _el: Record<string, unknown>;
         data?: unknown;
-        on: (type: string, fn: unknown, context?: unknown) => unknown;
-        off: (type: string, fn: unknown, context?: unknown) => unknown;
-        fire: (type: string, data?: unknown, target?: unknown) => unknown;
-        hasEventListeners: (type: string) => boolean;
-    };
-} & {
-    new (...args: any[]): {
-        _vco_events?: Record<string, {
-            action: unknown;
-            context: unknown;
-        }[]> | undefined;
-        on(type: string, fn: unknown, context?: unknown): /*elided*/ any;
-        hasEventListeners(type: string): boolean;
-        off(type: string, fn: unknown, context?: unknown): /*elided*/ any;
-        fire(type: string, data?: unknown, target?: unknown): /*elided*/ any;
+        on<K extends "call_to_action" | "loaded" | "added" | "removed" | "background_change">(type: K, fn: (e: FiredEvent<SlideEvents, K>) => void, context?: unknown): /*elided*/ any;
+        off<K extends "call_to_action" | "loaded" | "added" | "removed" | "background_change">(type: K, fn: (e: FiredEvent<SlideEvents, K>) => void, context?: unknown): /*elided*/ any;
+        fire<K extends "call_to_action" | "loaded" | "added" | "removed" | "background_change">(type: K, data?: SlideEvents[K] | undefined): /*elided*/ any;
+        hasEventListeners<K extends "call_to_action" | "loaded" | "added" | "removed" | "background_change">(type: K): boolean;
     };
-} & typeof SlideBase;
+} & Constructor<EventedInstance<SlideEvents>> & typeof SlideBase;
 
 declare interface SlideBackgroundChange {
     color_value?: string;
     image?: boolean;
 }
 
+export declare interface SlideBackgroundState {
+    image: boolean;
+    color: boolean;
+    color_value: string;
+}
+
 declare class SlideBase {
     /** `call_to_action` is only created when the slide shows one. */
     "_el": SlideElements;
+    /** The primary media item; always `_medias[0]` when present (#358). */
     "_media": MediaInstance | null;
-    "_mediaclass": unknown;
+    /** Every media item: `[media, ...media_extra]` with a non-empty url. */
+    "_medias": MediaInstance[];
     "_text": Text_2;
     "_state": {
         loaded: boolean;
@@ -1342,15 +1620,24 @@ declare class SlideBase {
     "_scroll_hint": HTMLElement | null;
     "_scroll_hint_dismissed": boolean;
     "_onSlideScrollBound": EventListener;
-    /** Every `media_ended` handler registered via `onMediaEnded`, kept so `dispose()` can remove them. */
-    "_media_ended_fns": (() => void)[];
+    /** Every `media_ended` handler registered via `onMediaEnded`, with the
+     media it was attached to so `dispose()` can remove them. */
+    "_media_ended_fns": {
+        media: MediaInstance;
+        fn: () => void;
+    }[];
+    /** The `media_loaded` handlers below, kept for the same reason. */
+    "_media_loaded_fns": {
+        media: MediaInstance;
+        fn: () => void;
+    }[];
     "has": SlideHas;
     "title": string;
     "data": StorymapSlide;
     "options": SlideOptions;
     "active": boolean;
     "animator": unknown;
-    "fire": EventedInstance["fire"];
+    "fire": EventedInstance<SlideEvents>["fire"];
     "onLoaded": () => void;
     constructor(data: StorymapSlide, options: Record<string, unknown>, title_slide?: boolean);
     show(): void;
@@ -1365,11 +1652,13 @@ declare class SlideBase {
     loadMedia(): void;
     _eagerLoadImages(): void;
     stopMedia(): void;
-    getBackground(): {
-        image: boolean;
-        color: boolean;
-        color_value: string;
-    };
+    /**
+     * Stop this slide's ambient audio beds (`media.stopOnExit: false`) —
+     * called by the viewer when another slide claims the audio, not on every
+     * deactivation (see `stopMedia`, which skips them).
+     */
+    stopAmbientMedia(): void;
+    getBackground(): SlideBackgroundState;
     /**
      * True when this slide's media is a timed, playable one (audio or video).
      * `autoplay_media` waits for such a slide's media to end instead of using
@@ -1380,9 +1669,18 @@ declare class SlideBase {
      * Call `fn` when this slide's media finishes playing. A slide with no
      * media — or media that cannot end — never calls it, which is why
      * `autoplay_media` keeps its timer as a fallback rather than waiting on
-     * an event that may not arrive.
+     * an event that may not arrive. Multi-media slides never call it either:
+     * waiting for the last of several items to end would stall autoplay, so
+     * the timer stays the advance for those (#358).
      */
     onMediaEnded(fn: () => void): void;
+    /**
+     * Drop `media_ended` handlers armed by `onMediaEnded()` without waiting
+     * for dispose: re-arming (autoplay revisit) or navigating away must not
+     * accumulate stale advance closures — an ambient bed outliving its slide
+     * would otherwise fire a previous slide's advance on ending.
+     */
+    clearMediaEnded(): void;
     scrollToTop(): void;
     /**
      * Show a bouncing downward arrow when the slide content overflows
@@ -1413,16 +1711,20 @@ declare type SlideElements = {
     call_to_action: HTMLElement | null;
 };
 
+export declare interface SlideEvents {
+    background_change: SlideBackgroundState;
+    call_to_action: Event;
+    loaded: StorymapSlide;
+    added: StorymapSlide;
+    removed: StorymapSlide;
+}
+
 declare interface SlideHas {
     headline: boolean;
     text: boolean;
     media: boolean;
     title: boolean;
-    background: {
-        image: boolean;
-        color: boolean;
-        color_value: string;
-    };
+    background: SlideBackgroundState;
 }
 
 declare class SlideNav extends SlideNav_base {
@@ -1442,23 +1744,12 @@ declare const SlideNav_base: {
         onRemove(): void;
         _el: Record<string, unknown>;
         data?: unknown;
-        on: (type: string, fn: unknown, context?: unknown) => unknown;
-        off: (type: string, fn: unknown, context?: unknown) => unknown;
-        fire: (type: string, data?: unknown, target?: unknown) => unknown;
-        hasEventListeners: (type: string) => boolean;
-    };
-} & {
-    new (...args: any[]): {
-        _vco_events?: Record<string, {
-            action: unknown;
-            context: unknown;
-        }[]> | undefined;
-        on(type: string, fn: unknown, context?: unknown): /*elided*/ any;
-        hasEventListeners(type: string): boolean;
-        off(type: string, fn: unknown, context?: unknown): /*elided*/ any;
-        fire(type: string, data?: unknown, target?: unknown): /*elided*/ any;
+        on<K extends "loaded" | "added" | "removed" | "clicked">(type: K, fn: (e: FiredEvent<SlideNavEvents, K>) => void, context?: unknown): /*elided*/ any;
+        off<K extends "loaded" | "added" | "removed" | "clicked">(type: K, fn: (e: FiredEvent<SlideNavEvents, K>) => void, context?: unknown): /*elided*/ any;
+        fire<K extends "loaded" | "added" | "removed" | "clicked">(type: K, data?: SlideNavEvents[K] | undefined): /*elided*/ any;
+        hasEventListeners<K extends "loaded" | "added" | "removed" | "clicked">(type: K): boolean;
     };
-} & typeof SlideNavBase;
+} & Constructor<EventedInstance<SlideNavEvents>> & typeof SlideNavBase;
 
 declare class SlideNavBase {
     "_el": Record<string, HTMLElement>;
@@ -1467,7 +1758,7 @@ declare class SlideNavBase {
     "options": SlideNavOptions;
     "animator": AnimationHandle | null;
     "animator_position": AnimationHandle | null;
-    "fire": EventedInstance["fire"];
+    "fire": EventedInstance<SlideNavEvents>["fire"];
     constructor(data?: Partial<SlideNavData>, options?: Partial<SlideNavOptions>, add_to_container?: HTMLElement);
     update(d?: Partial<SlideNavData>): void;
     setColor(inverted: boolean): void;
@@ -1492,6 +1783,13 @@ declare interface SlideNavData {
     [key: string]: unknown;
 }
 
+export declare interface SlideNavEvents {
+    clicked: SlideNavOptions;
+    loaded: SlideNavData;
+    added: SlideNavData;
+    removed: SlideNavData;
+}
+
 declare interface SlideNavOptions {
     direction: string;
     [key: string]: unknown;
@@ -1509,6 +1807,64 @@ declare interface SlideOptions {
     [key: string]: unknown;
 }
 
+/** The embed `settings` JSON (string → web component), all fields optional. */
+export declare interface SlideshowPlayerSettings {
+    uri?: unknown;
+    mode?: unknown;
+    viewerheight?: unknown;
+    autoplay?: unknown;
+    slidetimeout?: unknown;
+    fxmode?: unknown;
+    shownav?: unknown;
+    showfullscreen?: unknown;
+    showinfo?: unknown;
+    showscrollbars?: unknown;
+    progressbar?: unknown;
+    textmode?: unknown;
+    textsize?: unknown;
+    imgoverlay?: unknown;
+    imgoverlayurl?: unknown;
+    imgoverlaysize?: unknown;
+    showheadings?: unknown;
+    bgcolor?: unknown;
+    hudbgcolor?: unknown;
+    hudcolor?: unknown;
+    hudopacity?: unknown;
+    [key: string]: unknown;
+}
+
+/**
+ * Translate one slideshow tour document (plus any following pages) into
+ * storymap data. Slideshow-only fields land verbatim; internal validation
+ * (`validateStorymap`) must still pass on the result.
+ */
+export declare function slideshowToStorymapData(doc: unknown, opts?: SlideshowTranslatorOptions): SlideshowToStorymapResult;
+
+export declare interface SlideshowToStorymapResult {
+    data: StorymapData;
+    warnings: SlideshowWarning[];
+}
+
+export declare interface SlideshowTranslatorOptions {
+    /** Parsed embed settings; option keys land on the storymap object. */
+    settings?: SlideshowPlayerSettings | null;
+    /**
+     * Following `AnnotationPage`s for `first.next` chains (fetched by the
+     * caller: CLI and viewer). Items append in order.
+     */
+    extraPages?: unknown[];
+}
+
+/** 2 for the `strollview` extension, 1 for the legacy context, else 0. */
+export declare function slideshowVersion(doc: unknown): 0 | 1 | 2;
+
+export declare interface SlideshowWarning {
+    kind: string;
+    count: number;
+    sampleIds: string[];
+    detail: string;
+}
+
 export declare class StoryMap extends StoryMap_base {
     /**
      * The library base path (the directory containing the module).
@@ -1519,18 +1875,7 @@ export declare class StoryMap extends StoryMap_base {
     constructor(...args: ConstructorParameters<typeof StoryMapBase>);
 }
 
-declare const StoryMap_base: {
-    new (...args: any[]): {
-        _vco_events?: Record<string, {
-            action: unknown;
-            context: unknown;
-        }[]> | undefined;
-        on(type: string, fn: unknown, context?: unknown): /*elided*/ any;
-        hasEventListeners(type: string): boolean;
-        off(type: string, fn: unknown, context?: unknown): /*elided*/ any;
-        fire(type: string, data?: unknown, target?: unknown): /*elided*/ any;
-    };
-} & typeof StoryMapBase;
+declare const StoryMap_base: Constructor<EventedInstance<StoryMapEvents>> & typeof StoryMapBase;
 
 /**
  * Interactive StoryMap viewer.
@@ -1552,7 +1897,7 @@ declare class StoryMapBase {
         storyslider: boolean;
         map: boolean;
     };
-    "on": EventedInstance["on"];
+    "on": EventedInstance<StoryMapEvents>["on"];
     "version": string;
     "ready": boolean;
     "_el": {
@@ -1603,6 +1948,26 @@ declare class StoryMapBase {
     "_autoplay_stopped": boolean;
     /** The narration player: one <audio> for the whole story, reused. */
     "_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.
+     */
+    "_ambient_el": HTMLAudioElement | null;
+    /** What each player is (or was) playing, so same-URL beds continue. */
+    "_narration_meta": {
+        url: string;
+        stopOnExit: boolean;
+    } | null;
+    "_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.
+     */
+    "_ambient_playing": boolean;
     /** Guards a stale play() from a slide change that already moved on. */
     "_narration_token": number;
     /** Whether narration consent was granted (asked once per story). */
@@ -1617,12 +1982,16 @@ declare class StoryMapBase {
     "_collapsed": boolean;
     /** the data source was a IIIF Presentation manifest (legacy zoomify options are ignored) */
     "_data_from_manifest": boolean;
+    /** the data source was a slideshow tour (slideshow-only features apply) */
+    "_data_from_slideshow": boolean;
     "_resize_observer": ResizeObserver | null;
     /** Stored so `dispose()` can remove them again (see AGENTS: no leaks) */
     "_on_resize": (() => void) | null;
     "_on_keydown_global": ((e: KeyboardEvent) => void) | null;
     "_on_fullscreen": (() => void) | null;
     "_on_hashchange": (() => void) | null;
+    /** Reduced-motion toggles mid-story stop the advance timer. */
+    "_on_reduced_motion": ((e: MediaQueryListEvent) => void) | null;
     /** Set by `dispose()` so a second call returns early. */
     "_disposed": boolean;
     /** identity of this viewer's claim on the page-wide locale */
@@ -1633,8 +2002,7 @@ declare class StoryMapBase {
     "_interaction": number;
     "_onInteraction": (() => void) | null;
     "_resize_timer": ReturnType<typeof setTimeout> | null;
-    "fire": EventedInstance["fire"];
-    "hasEventListeners": EventedInstance["hasEventListeners"];
+    "fire": EventedInstance<StoryMapEvents>["fire"];
     /**
      * Create a StoryMap inside the given element.
      *
@@ -1647,9 +2015,36 @@ declare class StoryMapBase {
      * @param listeners - Optional event listeners keyed by event name
      *   (`change`, `title`, `loaded`, ...) attached on creation.
      */
-    constructor(elem: string | HTMLElement, data: string | StorymapDataWrapper | Record<string, unknown>, options?: Partial<StorymapOptions>, listeners?: Record<string, StoryMapListener | StoryMapListener[]>);
+    constructor(elem: string | HTMLElement, data: string | StorymapDataWrapper | Record<string, unknown>, options?: Partial<StorymapOptions>, listeners?: {
+        [K in keyof StoryMapEvents]?: StoryMapListener<K> | StoryMapListener<K>[];
+    });
     _initData(data: string | StorymapDataWrapper | Record<string, unknown>): void;
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    _followSlideshowPages(doc: unknown, url: string): Promise<{
+        pages: unknown[];
+        complete: boolean;
+    }>;
     _loadDataFromUrl(url: string, source: string): Promise<void>;
+    /**
+     * 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): void;
     _initOptions(): void;
     _loadLanguage(): void;
     /**
@@ -1815,9 +2210,27 @@ declare class StoryMapBase {
     /** The highlighted route line drawn up to the current slide. */
     getLineActive(): OlLayer | null;
     /** The map markers, indexed by slide. */
-    getMarkers(): OpenLayersMapMarker[];
+    getMarkers(): StoryMapMarker[];
     /** One map marker by slide index, or `null`. */
-    getMarker(index: number): OpenLayersMapMarker | null;
+    getMarker(index: number): StoryMapMarker | 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;
+    /**
+     * 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;
+    /** Whether slide `n`'s marker card is currently open. */
+    isPopupOpen(n: number): boolean;
     /**
      * Rebuild the minimap (`OverviewMap` control). The constructor already
      * builds it; this is for hosts that recreate it after a `map_type` swap
@@ -1835,6 +2248,18 @@ declare class StoryMapBase {
      * cannot drift.
      */
     _applyTextColors(): void;
+    /**
+     * 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;
+    /**
+     * 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;
     _initLayout(): void;
     _initEvents(): void;
     _onKeyDownGlobal(e: KeyboardEvent): void;
@@ -1863,12 +2288,49 @@ declare class StoryMapBase {
      *   playback, and the story still works.
      */
     _playNarration(slide: StorymapSlide | undefined, allow_without_gesture?: boolean): void;
-    _narrationElement(): HTMLAudioElement;
-    _stopNarration(): void;
+    /**
+     * 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): void;
+    /**
+     * 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;
+    /**
+     * 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): void;
+    _narrationElement(): HTMLAudioElement;
+    _stopNarration(): void;
+    _ambientElement(): HTMLAudioElement;
+    _stopAmbient(): void;
     /** A gesture has happened, so unmuted audio is allowed from now on. */
     _note_user_gesture_for_narration(): void;
     _has_user_gesture(): boolean;
     _startAutoplay(): void;
+    /**
+     * 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): void;
+    /**
+     * True when the slide's media element exists and is currently playing
+     * (not paused, not ended, not merely loadable).
+     */
+    _isSlideMediaPlaying(index: number): boolean;
     /**
      * Arm autoplay for the current slide.
      *
@@ -1944,7 +2406,9 @@ declare class StoryMapBase {
      */
     _map_required(): OpenLayers;
     _resolveMapElement(): HTMLElement | null;
-    _onTitle(e: unknown): void;
+    _onTitle(e: {
+        title: string;
+    }): void;
     _onColorChange(e: {
         color?: unknown;
         image?: unknown;
@@ -1955,6 +2419,45 @@ declare class StoryMapBase {
     _onMapChange(e: {
         current_marker: number;
     }): void;
+    _onImageReady(e: ImagereadyPayload): void;
+    _onMarkerPopupOpen(e: {
+        marker_number: number;
+    }): void;
+    _onMarkerPopupClose(e: {
+        marker_number: number;
+    }): void;
+    _onMarkerClick(e: {
+        marker_number: number;
+    }): void;
+    _onLayersBasemap(e: {
+        map_type: string;
+    }): void;
+    _onLayersOverlay(e: {
+        index: number;
+        visible: boolean;
+    }): void;
+    _onAutoplayToggle(): void;
+    _onProgressGo(e: {
+        slide: number;
+    }): void;
+    _onTilesAllowed(): void;
+    /**
+     * 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[];
+    /**
+     * 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[];
+    /** Whether deferred tile layers may attach (no consent gate, or granted). */
+    _tilesAllowed(): boolean;
     _updateProgress(): void;
     _onOverview(e?: unknown): void;
     /**
@@ -1992,9 +2495,36 @@ declare class StoryMapBase {
     _onLoaded(): void;
 }
 
+/**
+ * A selectable base map for the layer switcher (`StorymapOptions.basemaps`).
+ */
+export declare interface StorymapBasemap {
+    /** Any `map_type` value. */
+    map_type: string;
+    /**
+     * Control row label. Defaults to `map_type`. A function is re-invoked
+     * on every `refreshLabels()` for host i18n (constructor options only —
+     * see `StorymapOverlayLayer.label`).
+     */
+    label?: string | (() => string);
+}
+
+/**
+ * Authorship and rights for the story as a whole (slideshow
+ * `creator`/`rights`). Rendered into the map attribution line for
+ * slideshow tours; the license URL stays data-only for hosts.
+ */
+declare interface StorymapCredit {
+    creator?: string;
+    rights?: string;
+    licenseUrl?: string;
+    [key: string]: unknown;
+}
+
 export declare interface StorymapData {
     uniqueid?: string;
     slides: StorymapSlide[];
+    credit?: StorymapCredit | null;
     [key: string]: unknown;
 }
 
@@ -2022,6 +2552,59 @@ export declare interface StorymapError {
     message: string;
 }
 
+export declare 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;
+    };
+}
+
 /**
  * A IIIF Georeference Extension annotation body plus the image it places
  * (`overlays[].georeference`). The `body` is the annotation payload of
@@ -2071,12 +2654,26 @@ export declare interface StorymapGroundControlPoint {
     };
 }
 
+/**
+ * A per-slide image overlay (slideshow `imgoverlay`). `url` is a full-size
+ * image; `extent` pins it to `[west, south, east, north]` (lon/lat, or raw
+ * image pixels on image-space maps) and defaults to the current view;
+ * `size` scales it as a fraction of the viewport width; `opacity` is 0..1.
+ */
+declare interface StorymapImageOverlay {
+    url: string;
+    size?: number;
+    opacity?: number;
+    extent?: [number, number, number, number];
+    [key: string]: unknown;
+}
+
 /** A IIIF Presentation 3 language map; only the neutral `none` tag is written. */
 export declare interface StorymapLanguageMap {
     none: string[];
 }
 
-declare type StoryMapListener = (e: unknown) => void;
+declare type StoryMapListener<K extends keyof StoryMapEvents = keyof StoryMapEvents> = (e: FiredEvent<StoryMapEvents, K>) => void;
 
 export declare interface StorymapManifest {
     "@context": string[];
@@ -2108,6 +2705,12 @@ export declare interface StorymapManifestAnnotation {
     accessibilitySummary?: StorymapLanguageMap;
     body: StorymapManifestContentResource;
     target: string | StorymapManifestSpecificResource;
+    /** Playback flags (slideshow audio terms); foreign members, absent when unset. */
+    "storymap:loop"?: boolean;
+    "storymap:offset"?: number;
+    "storymap:play"?: string;
+    "storymap:stopOnExit"?: boolean;
+    "storymap:stopAllPrevious"?: boolean;
 }
 
 /** A canvas `background`: a painting annotation of the slide's backdrop (§2.6). */
@@ -2139,6 +2742,16 @@ export declare interface StorymapManifestCanvas {
     "storymap:type"?: string;
     "storymap:mediaSrcset"?: unknown;
     "storymap:mediaSizes"?: unknown;
+    /** View directives (slideshow rotation/basemap/filter/mask); navPlace carries them when lat/lon exist. */
+    "storymap:rotation"?: number;
+    "storymap:basemap"?: string;
+    "storymap:filter"?: unknown;
+    "storymap:mask"?: unknown;
+    /** Per-slide autoplay dwell (slideshow slidetimeout) and image overlay. */
+    "storymap:slidetimeout"?: number;
+    "storymap:imgoverlay"?: unknown;
+    /** Provenance identifiers (slideshow manifest/canvas/image ids). */
+    "storymap:provenance"?: unknown;
     navPlace?: StorymapManifestFeatureCollection;
 }
 
@@ -2255,6 +2868,108 @@ export declare interface StorymapMapOptions {
     [key: string]: unknown;
 }
 
+export declare class StoryMapMarker extends MapMarker {
+    "_overlay": default_3;
+    "_onMarkerClickBound": ((e: Event) => void) | null;
+    /** Enter/Space activation for keyboard visitors, detached in dispose(). */
+    "_onMarkerKeyBound": ((e: KeyboardEvent) => void) | null;
+    /** Base accessible name (slide headline or label), without audio suffix. */
+    "_marker_label": string;
+    /** marker.popup: the active marker opens its card when clicked. */
+    "_popup_enabled": boolean;
+    /** marker.audioBadge: flag a slide that has narration or audio media. */
+    "_audio_badge": boolean;
+    /**
+     * The popup card while it is open. `declare` fields are undefined until
+     * assigned, so every read below is a truthiness check, never `=== null`,
+     * and there is no constructor to initialise them: `MapMarker`'s own
+     * constructor already runs `_initLayout()` → `_createMarker()`, which
+     * assigns the flags, and initialising afterwards would wipe them.
+     */
+    "_popup_el": HTMLElement | null;
+    /** Escape-to-close, detached in dispose(). */
+    "_onPopupKeyBound": ((e: KeyboardEvent) => void) | null;
+    /** Mirrors `active()`, as a flag rather than a method reference. */
+    "_is_active": boolean;
+    /**
+     * The merged marker presentation: `marker.*` wins, `location.*` is the
+     * legacy spelling and still works.
+     * `location` also stays the carrier of geography, so lat/lon are read
+     * from it alone — presentation never moves a marker.
+     */
+    _presentation(d?: MapMarkerData): MarkerPresentation;
+    _createMarker(d?: MapMarkerData, o?: StorymapOptions): void;
+    _createMarkerElement(d: MapMarkerData, o?: StorymapOptions): HTMLDivElement;
+    /**
+     * The marker's {lat, lon}, or null when it is a non-georeferenced marker
+     * (an overview slide, or a slide with only an image region). `_createMarker`
+     * already established this for a real marker, but returning it from one
+     * place means the type checker can see it too.
+     */
+    latLon(): LatLngLiteral | null;
+    _addTo(m: Map_3): void;
+    _removeFrom(m: Map_3): void;
+    /**
+     * Terminal teardown: detach the click listener and drop the overlay and
+     * element. Called by the map's dispose(); the marker must not be used
+     * afterwards.
+     */
+    /**
+     * Toggle the popup card for the *active* marker. Inactive markers keep
+     * their original behaviour — a click navigates — so a popup never
+     * swallows navigation on a map full of pins.
+     *
+     * The card is a DOM element parented to the marker element and positioned
+     * with CSS, which is how it survives a move to the vector renderer
+     * (docs/plans/issue-159-vector-markers.md): only the anchor is the
+     * marker's, and that is `latLon()`.
+     */
+    _togglePopup(): void;
+    _closePopup(): void;
+    /** True when this marker is configured to show a popup card. */
+    isPopupEnabled(): boolean;
+    /**
+     * Open the popup card for this marker.
+     *
+     * Returns false (and opens nothing) when popups are disabled for the
+     * marker or it is not a real map marker — e.g. an overview slide. A
+     * click on an inactive marker navigates instead of opening (see the
+     * click handler in `_createMarker`); programmatic callers that want the
+     * card on another stop should navigate first (`StoryMap.openMarkerPopup`
+     * does exactly that). Fires `popupopen` on success.
+     */
+    openPopup(): boolean;
+    /**
+     * Close the popup card if it is open. Fires `popupclose`. Also runs on
+     * Escape, the card's close button, deactivation and `dispose()`.
+     */
+    closePopup(): void;
+    /**
+     * Open the card when closed, close it when open. Returns whether the
+     * card is open afterwards (false when popups are disabled).
+     */
+    togglePopup(): boolean;
+    get popupOpen(): boolean;
+    /**
+     * Headline, a sanitized excerpt, the media thumb and an audio control.
+     * Every piece of text goes through `sanitizeSlideText` — a slide's text
+     * is untrusted input and a marker card is no different (the stored-XSS
+     * audit made that lesson once; a label is attacker-controlled text like
+     * any other).
+     */
+    _createPopupElement(): HTMLElement | null;
+    /**
+     * A small indicator on markers whose slide has narration or audio media
+     * (the Micrio affordance). Recomputed on activation, because a slide's
+     * media may only be known once it is resolved.
+     */
+    _updateAudioBadge(): void;
+    dispose(): void;
+    _active(a: boolean): void;
+    _customIconAnchor(size?: number[]): number[];
+    _location(): LatLngLiteral | null;
+}
+
 export declare interface StorymapOptions {
     width: number;
     height: number;
@@ -2303,10 +3018,33 @@ export declare interface StorymapOptions {
     autoplay_media: boolean;
     /** Show a progress bar in the menubar (issue #247) */
     show_progress: boolean;
-    /** Show the slide headline as a label on the active map marker (issue #243) */
+    /**
+     * Progress indicator style (slideshow `progressbar`): `false`/`"off"`
+     * hides it (same as `show_progress: false`), `true`/`"bar"` is the
+     * classic fill bar, `dots`/`squares` render one step per slide,
+     * `block`/`thinblock` are fill-bar height variants. Absent means the
+     * `show_progress` boolean decides and the style is `"bar"`. Honored
+     * only with `slideshow_source`.
+     */
+    progressbar?: boolean | "bar" | "dots" | "squares" | "block" | "thinblock" | "off"; /** Show the slide headline as a label on the active map marker (issue #243) */
     marker_labels: boolean;
     /** Default text alignment for slide text: left, center or right (issue #244) */
     text_align: "left" | "center" | "right";
+    /**
+     * Slide panel dock (slideshow `textmode`): which side the text panel
+     * occupies in landscape. `"right"` (default) is the current layout;
+     * `"left"` mirrors it; `"bottom"` docks the panel below the map.
+     * Portrait layouts always behave like `"bottom"`. Honored only with
+     * `slideshow_source`.
+     */
+    textmode?: "left" | "right" | "bottom";
+    /**
+     * Slide panel size as a percentage (slideshow `textsize`): percent of
+     * the width for side docks, of the height for the bottom dock.
+     * Range 10..80; absent keeps the built-in 50/50 split. Honored only
+     * with `slideshow_source`.
+     */
+    textsize?: number;
     /** Override the overview fit center (issues #107, #271) */
     map_overview_center: {
         lat: number;
@@ -2330,6 +3068,15 @@ export declare interface StorymapOptions {
      * (default) means base map only.
      */
     overlays: StorymapOverlayLayer[];
+    /** Show the basemap/overlay switcher in the menubar (default false) */
+    show_layers_control: boolean;
+    /**
+     * Selectable base maps for the layer switcher. Entry 0 is the initial
+     * basemap unless `map_type` says otherwise; omit for an overlays-only
+     * control. Constructor- and runtime-only when labels are functions
+     * (functions cannot ride storymap JSON — see `label`).
+     */
+    basemaps?: StorymapBasemap[];
     map_mini: boolean;
     map_as_image: boolean;
     map_access_token: string;
@@ -2380,6 +3127,77 @@ export declare interface StorymapOptions {
     text_background_color: string;
     /** Show the great-circle route distance in the menubar (issue #341) */
     show_distance: boolean;
+    /**
+     * Slide transition effect (slideshow `fxmode`): `"slide"` (default) is
+     * the current glide, `"fade"` cross-fades slides, `"none"` jumps without
+     * animation. `prefers-reduced-motion` still forces `"none"`. Honored
+     * only with `slideshow_source`.
+     */
+    fxmode?: "slide" | "fade" | "none";
+    /**
+     * Reading mode (slideshow `mode`): `"standard"` (default) is the
+     * slider; `"static"` stacks all slides in a scrollable list and follows
+     * the map to the slide in view. Honored only with `slideshow_source`.
+     */
+    mode?: "standard" | "static";
+    /**
+     * HUD foreground color override (slideshow `hudcolor`): sets the
+     * `--vco-hud-fg` CSS variable. Absent follows the theme. Honored only
+     * with `slideshow_source`.
+     */
+    hudcolor?: string;
+    /**
+     * HUD background color override (slideshow `hudbgcolor`): sets the
+     * `--vco-hud-bg` CSS variable. Absent follows the theme. Honored only
+     * with `slideshow_source`.
+     */
+    hudbgcolor?: string;
+    /**
+     * HUD opacity percent 0..100 (slideshow `hudopacity`): applied to the
+     * HUD background. Absent means fully opaque theme background. Honored
+     * only with `slideshow_source`.
+     */
+    hudopacity?: number;
+    /**
+     * Show the previous/next slide navigation (slideshow `shownav`).
+     * Default true; `false` hides the nav chrome (keyboard/AT navigation
+     * still works, like `show_progress: false` keeps the story usable).
+     * Honored only with `slideshow_source`.
+     */
+    shownav?: boolean;
+    /**
+     * Render slide headlines (slideshow `showheadings`). Default true;
+     * `false` hides headline elements via CSS. Honored only with
+     * `slideshow_source`.
+     */
+    show_headings?: boolean;
+    /**
+     * Show scrollbars in the slide panel (slideshow `showscrollbars`).
+     * Default true; `false` hides them via CSS (content still scrolls).
+     * Honored only with `slideshow_source`.
+     */
+    show_scrollbars?: boolean;
+    /**
+     * Fixed viewer height (slideshow `viewerheight`), e.g. `"400px"`:
+     * applied as a container height override when set. Absent keeps the
+     * measured-container behavior. Only `px`, `%` and `vh` units accepted.
+     * Honored only with `slideshow_source`.
+     */
+    viewerheight?: string;
+    /**
+     * Show media captions and credits (slideshow `showinfo`). Default true;
+     * `false` hides the caption/credit block. Honored only with
+     * `slideshow_source`.
+     */
+    show_info?: boolean;
+    /**
+     * Detect slideshow tours automatically (default `true`): an
+     * `AnnotationCollection` shaped like one loads through the translator.
+     * Set `false` to disable detection (such documents then fail validation
+     * as before).
+     */
+    slideshow?: boolean;
+    /* Excluded from this release type: slideshow_source */
     /**
      * Raw OpenLayers map configuration. `controls` replaces the StoryMapJS
      * defaults, `interactions` are *added to* the viewer's own pan/zoom
@@ -2399,14 +3217,24 @@ export declare interface StorymapOptions {
     show_lines: boolean;
     show_history_line: boolean;
     use_custom_markers: boolean;
+    /**
+     * IIIF image service for image maps. `url` is the `info.json`; `width`
+     * and `height` record the canvas size so region clamping and the static
+     * fallback work without another fetch; `fallbackUrl` is a full-size
+     * image used when `info.json` cannot be loaded (slideshow
+     * `image_static`).
+     */
     iiif: {
         url: string;
         attribution: string;
+        width?: number;
+        height?: number;
+        fallbackUrl?: string;
     };
     tilejson?: StorymapTilejson;
     /**
      * The `seeAlso` targets a IIIF manifest points at, recorded but not
-     * fetched — see `loadSeeAlso()` (§5.2 of docs/plans/iiif-interop.md).
+     * fetched — see `loadSeeAlso()`.
      */
     see_also?: {
         id: string;
@@ -2418,8 +3246,18 @@ export declare interface StorymapOptions {
     slide_default_fade: string;
     menubar_default_y: number;
     script_path: string;
-    font_css: string;
+    /**
+     * Font theme stylesheet: `stock:<name>`, a URL/path, or `false` for no
+     * injected stylesheet (the host bundles the theme itself).
+     */
+    font_css: string | false;
     language: string;
+    /**
+     * Colour theme: `"dark"` forces the dark palette, `"light"` pins the
+     * light one (overriding an OS dark preference), unset follows
+     * `prefers-color-scheme`. Construction-time only, like `map_type`.
+     */
+    theme?: "dark" | "light";
     api_key_flickr: string;
     [key: string]: unknown;
 }
@@ -2452,6 +3290,23 @@ export declare interface StorymapOverlayLayer {
     className?: string;
     /** CSS mix-blend-mode for the layer container (needs className) */
     blendMode?: string;
+    /**
+     * Control row label for the layer switcher (`show_layers_control`).
+     * Defaults to `map_type`. A function is re-invoked on every
+     * `refreshLabels()` for host i18n — but only when the entry comes from
+     * constructor options: `mergeData()` overwrites option keys with the
+     * storymap JSON, so a document carrying `overlays` replaces function
+     * labels with its own strings.
+     */
+    label?: string | (() => string);
+    /**
+     * Render the row checked and disabled: an overlay the visitor may add
+     * back but not remove (e.g. a georeferenced scan the story is built on).
+     * The control never toggles a locked entry.
+     */
+    locked?: boolean;
+    /** false hides the row from the control without removing the overlay. */
+    control?: boolean;
     /** Clip box `[west, south, east, north]` in lon/lat (mercator maps) */
     extent?: [number, number, number, number];
     /**
@@ -2475,8 +3330,7 @@ export declare interface StorymapSlide {
     date?: string | Record<string, unknown> | null;
     group?: string;
     /**
-     * The language tag this slide's text was read in (§3.4 of
-     * docs/plans/iiif-interop.md). A IIIF manifest states its text as a
+     * The language tag this slide's text was read in. A IIIF manifest states its text as a
      * language map; the reader picks the viewer's configured language and
      * reports which one it used, so a host can offer a language switch.
      * Absent for language-neutral (`none`) text, and for a single-language
@@ -2485,11 +3339,46 @@ export declare interface StorymapSlide {
     language?: string;
     location?: StorymapSlideLocation | null;
     media?: StorymapSlideMedia | null;
+    /**
+     * Additional visible media for this slide (#358), rendered after `media`
+     * in order. Items without a non-empty `url` are skipped, so a document
+     * without this field renders identically. In a IIIF manifest these are
+     * further `painting` annotations on the canvas; the slide layout
+     * (`media_layout`) has no IIIF term and stays viewer-side.
+     */
+    media_extra?: StorymapSlideMedia[] | null;
+    /**
+     * Layout of a multi-media slide (#358): `stack` piles the items
+     * vertically (the panel scrolls), `row` puts two items side by side.
+     * Defaults to `stack`; `row` with anything but two items falls back to
+     * `stack`. Ignored for a single media item.
+     */
+    media_layout?: "stack" | "row";
     marker?: StorymapSlideMarker | null;
     narration?: StorymapSlideNarration | null;
     text?: StorymapSlideText | null;
     background?: StorymapSlideBackground | string | null;
     uniqueid?: string | null;
+    /**
+     * Provenance identifiers for the slide's source (slideshow
+     * `manifest_id`/`canvas_id`/`image_id`): which manifest, canvas and
+     * image the stop was translated from. Data-only (deep links, export);
+     * never rendered.
+     */
+    provenance?: StorymapSlideProvenance | null;
+    /**
+     * Per-slide autoplay dwell in milliseconds (slideshow `slidetimeout`):
+     * overrides the global `autoplay` interval for this slide; `0` holds on
+     * this slide. Absent means the global interval. Honored only with
+     * `slideshow_source`.
+     */
+    slidetimeout?: number;
+    /**
+     * Per-slide image overlay on the map (slideshow `imgoverlay`): a placed
+     * image shown while this slide is active. Absent means no overlay.
+     * Honored only with `slideshow_source`.
+     */
+    imgoverlay?: StorymapImageOverlay | null;
     [key: string]: unknown;
 }
 
@@ -2499,16 +3388,58 @@ export declare interface StorymapSlideBackground {
     opacity?: number;
 }
 
+/**
+ * Declarative CSS filter grading for one slide (slideshow `filters`).
+ * Rendered by `buildSlideFilter()`; unknown keys never reach CSS.
+ */
+declare interface StorymapSlideFilter {
+    brightness?: number;
+    contrast?: number;
+    saturate?: number;
+    hueRotate?: number;
+    sepia?: number;
+    blur?: number;
+    [key: string]: unknown;
+}
+
 export declare interface StorymapSlideLocation {
     lat?: number;
     lon?: number;
     zoom?: number;
     /**
      * Image region `[x, y, w, h]` in image pixels (IIIF xywh convention,
-     * StrollView-style image stops): the view fits the region on
+     * slideshow-style image stops): the view fits the region on
      * navigation; image maps (`map_type: "iiif"` + `map_as_image`) only.
      */
     region?: [number, number, number, number];
+    /**
+     * View rotation in degrees clockwise (slideshow `rotation`). Applied to
+     * the map view on navigation; absent means north-up (0). Image and geo
+     * maps alike; purely presentational. Honored only with
+     * `slideshow_source`.
+     */
+    rotation?: number;
+    /**
+     * Per-slide image grading (slideshow `filters`): applied as a CSS
+     * `filter()` on the map viewport. All fields optional; absent means
+     * unfiltered. `hueRotate` is degrees (-180..180), `blur` is CSS pixels.
+     * Honored only with `slideshow_source`.
+     */
+    filter?: StorymapSlideFilter;
+    /**
+     * Spotlight mask (slideshow `passepartout`): normalized viewport
+     * fractions `{x, y, w, h}` (0..1) left visible while the rest is dimmed
+     * with `color`. `invert` dims the inside instead of the outside.
+     * Absent means no mask. Honored only with `slideshow_source`.
+     */
+    mask?: StorymapSlideMask;
+    /**
+     * Per-slide basemap override (multi-manifest slideshow tours): any
+     * `map_type` value or IIIF `info.json` URL. Absent keeps the story
+     * basemap. The layer is cached, so returning to a slide is free.
+     * Honored only with `slideshow_source`.
+     */
+    basemap?: string;
     line?: boolean;
     icon?: string;
     iconSize?: number[];
@@ -2517,17 +3448,9 @@ export declare interface StorymapSlideLocation {
     [key: string]: unknown;
 }
 
-/**
- * Optional spoken narration for one slide, played through a dedicated audio
- * element rather than the slide's media frame — a tour stop usually has a
- * picture and a recording, not one media item. Storymap JSON only: the
- * closest manifest spelling is a `Sound` body, which currently lands in
- * `media.url` rather than here.
- */
 /**
  * Per-slide marker presentation, consolidated. `location.*` keeps working as
- * the legacy spelling and `marker.*` wins when present — see
- * docs/plans/iiif-media-tours.md §2.
+ * the legacy spelling and `marker.*` wins when present.
  *
  * In a IIIF manifest none of this is a `storymap:` term: it all arrives in the
  * `navPlace` Feature's `properties` bag (`icon`, `iconSize`, `image`, `name`,
@@ -2547,6 +3470,21 @@ export declare interface StorymapSlideMarker {
     [key: string]: unknown;
 }
 
+/**
+ * Spotlight mask geometry (slideshow `passepartout`). Fractions of the
+ * visible map area; `color` is a `#rgb`/`#rrggbb`/`#rrggbbaa`/`rgb(a)` string.
+ */
+declare interface StorymapSlideMask {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    color?: string;
+    invert?: boolean;
+    opacity?: number;
+    [key: string]: unknown;
+}
+
 export declare interface StorymapSlideMedia {
     url?: string | null;
     caption?: string | null;
@@ -2566,11 +3504,83 @@ export declare interface StorymapSlideMedia {
      * `TextualBody` + `format: text/vtt` shape we also accept.
      */
     subtitles?: string | null;
+    /**
+     * Start offset in seconds for audio/video media (slideshow `audio.offset`).
+     * Applied once the media metadata is available; absent or negative means 0.
+     * Honored only with `slideshow_source`.
+     */
+    offset?: number;
+    /**
+     * Loop audio/video media (slideshow `audio.loop`). Absent means no loop.
+     * Honored only with `slideshow_source`.
+     */
+    loop?: boolean;
+    /**
+     * `auto` (default) plays on activation; `click` arms the media paused and
+     * lets the visitor start it (slideshow `audio.play`). Absent means `auto`.
+     * Honored only with `slideshow_source`.
+     */
+    play?: "auto" | "click";
+    /**
+     * Stop this media when leaving the slide (default true). `false` lets an
+     * audio bed continue across slides (slideshow ambient audio). Honored
+     * only with `slideshow_source`.
+     */
+    stopOnExit?: boolean;
     [key: string]: unknown;
 }
 
+/**
+ * Optional spoken narration for one slide, played through a dedicated audio
+ * element rather than the slide's media frame — a tour stop usually has a
+ * picture and a recording, not one media item. In a IIIF manifest this is a
+ * `motivation: "supplementing"` Sound/Video body, read and written alongside
+ * the painting annotation.
+ */
 export declare interface StorymapSlideNarration {
     url: string;
+    /**
+     * Loop the narration (slideshow `audio.loop`). Absent means no loop.
+     * Note: a looping narration never fires `ended`, so `autoplay_media`
+     * falls back to its millisecond timer for that slide. Honored only with
+     * `slideshow_source`.
+     */
+    loop?: boolean;
+    /**
+     * Start offset in seconds (slideshow `audio.offset`), applied once the
+     * audio metadata is available. Absent or negative means 0. Honored only
+     * with `slideshow_source`.
+     */
+    offset?: number;
+    /**
+     * `auto` (default) plays on navigation; `click` arms the narration
+     * paused and lets the visitor start it (slideshow `audio.play`).
+     * Honored only with `slideshow_source`.
+     */
+    play?: "auto" | "click";
+    /**
+     * Stop the narration when leaving the slide (default true). `false`
+     * keeps an audio bed playing across slides while the URL is unchanged
+     * (slideshow ambient audio). Honored only with `slideshow_source`.
+     */
+    stopOnExit?: boolean;
+    /**
+     * Stop any other playing narration/ambient track before starting this
+     * one (default true). `false` allows the ambient overlap of two tracks.
+     * Honored only with `slideshow_source`.
+     */
+    stopAllPrevious?: boolean;
+    [key: string]: unknown;
+}
+
+/**
+ * Provenance identifiers for one slide's source: the manifest, canvas and
+ * image a stop was translated from. Data-only.
+ */
+declare interface StorymapSlideProvenance {
+    manifest?: string;
+    canvas?: string;
+    image?: string;
     [key: string]: unknown;
 }
 
@@ -2582,7 +3592,7 @@ export declare interface StorymapSlideText {
 
 /**
  * TileJSON 2.1 tile source metadata, from a manifest's map configuration
- * service (§2.9 of docs/plans/iiif-interop.md).
+ * service.
  *
  * This is how a manifest states a tile source: `tiles` is the URL template and
  * the rest is the standard metadata around it, where a keyword basemap
@@ -2622,18 +3632,7 @@ declare class StorySlider extends StorySlider_base {
     constructor(...args: ConstructorParameters<typeof StorySliderBase>);
 }
 
-declare const StorySlider_base: {
-    new (...args: any[]): {
-        _vco_events?: Record<string, {
-            action: unknown;
-            context: unknown;
-        }[]> | undefined;
-        on(type: string, fn: unknown, context?: unknown): /*elided*/ any;
-        hasEventListeners(type: string): boolean;
-        off(type: string, fn: unknown, context?: unknown): /*elided*/ any;
-        fire(type: string, data?: unknown, target?: unknown): /*elided*/ any;
-    };
-} & typeof StorySliderBase;
+declare const StorySlider_base: Constructor<EventedInstance<StorySliderEvents>> & typeof StorySliderBase;
 
 declare class StorySliderBase {
     "_el": StorySliderElements;
@@ -2649,13 +3648,19 @@ declare class StorySliderBase {
     "_message": Message;
     "current_slide": number;
     "current_bg_color": string | null;
+    /** Layout the background gradient was built for; a portrait↔landscape
+     switch rebuilds it even when the color is unchanged. */
+    "current_bg_layout": string | null;
     "data": Partial<StorymapData>;
     "options": StorySliderOptions;
     "animator": AnimationHandle | null;
     "animator_background": AnimationHandle | null;
-    "fire": EventedInstance["fire"];
+    "fire": EventedInstance<StorySliderEvents>["fire"];
     "_loaded": boolean;
-    "hasEventListeners": EventedInstance["hasEventListeners"];
+    /** Scroll-spy observer for `mode: "static"`; null in standard mode. */
+    "_static_observer": IntersectionObserver | null;
+    /** True while a scroll-spy navigation is settling (suppresses echo scrolls). */
+    "_static_spying": boolean;
     constructor(elem: HTMLElement | string, data: Partial<StorymapData>, options?: Partial<StorySliderOptions>, init?: boolean);
     init(): void;
     updateDisplay(w?: number, h?: number, a?: unknown, l?: string): void;
@@ -2679,7 +3684,7 @@ declare class StorySliderBase {
      * `StoryMap.dispose()`; the slider must not be used afterwards.
      */
     dispose(): void;
-    goTo(n: number, fast?: boolean, displayupdate?: boolean): void;
+    goTo(n: number, fast?: boolean, displayupdate?: boolean, fromScroll?: boolean): void;
     preloadSlides(): void;
     getNavInfo(slide: Slide): {
         title: string;
@@ -2690,6 +3695,17 @@ declare class StorySliderBase {
     showNav(nav_obj: SlideNav, show: boolean): void;
     changeBackground(bg: SlideBackgroundChange): void;
     fadeInBackground(bg_css: string): void;
+    /** True in the stacked reading mode (`mode: "static"`): no strip translation. */
+    _isStatic(): boolean;
+    /**
+     * Scroll-spy for the static reading mode: the most visible stacked slide
+     * becomes current, so the map follows the reading position. Programmatic
+     * scrolls set `_static_spying` while settling and are ignored, or the
+     * observer would echo them back.
+     */
+    _initStaticSpy(): void;
+    /** Scroll a stacked slide into view without moving the host page. */
+    _scrollSlideIntoView(n: number): void;
     _updateDisplay(width?: number, height?: number, animate?: unknown, layout?: string): void;
     _introInterface(): void;
     _initLayout(): void;
@@ -2700,7 +3716,7 @@ declare class StorySliderBase {
     _onMessageClick(e?: unknown): void;
     _onSwipeNoDirection(e?: unknown): void;
     _onNavigation(e: {
-        direction: string;
+        direction: string | null;
     }): void;
     _onSlideAdded(e?: unknown): void;
     _onSlideChange(displayupdate?: boolean): void;
@@ -2708,8 +3724,7 @@ declare class StorySliderBase {
 }
 
 /**
- * The slider's element cache. `live_region` only exists when the slide
- * announcements are enabled (the `a11y` option), so it starts out null.
+ * The slider's element cache.
  */
 declare type StorySliderElements = {
     container: HTMLElement;
@@ -2721,6 +3736,23 @@ declare type StorySliderElements = {
     live_region: HTMLElement | null;
 };
 
+export declare interface StorySliderEvents {
+    colorchange: SlideBackgroundChange;
+    nav_next: Partial<StorymapData>;
+    nav_previous: Partial<StorymapData>;
+    nav_left: Partial<StorymapData>;
+    nav_right: Partial<StorymapData>;
+    slideAdded: Partial<StorymapData>;
+    change: {
+        current_slide: number;
+        uniqueid: string | null | undefined;
+    };
+    loaded: Partial<StorymapData>;
+    title: {
+        title: string;
+    };
+}
+
 declare interface StorySliderOptions {
     id?: string;
     layout: string;
@@ -2747,18 +3779,7 @@ declare class Swipable extends Swipable_base {
     constructor(...args: ConstructorParameters<typeof SwipableBase>);
 }
 
-declare const Swipable_base: {
-    new (...args: any[]): {
-        _vco_events?: Record<string, {
-            action: unknown;
-            context: unknown;
-        }[]> | undefined;
-        on(type: string, fn: unknown, context?: unknown): /*elided*/ any;
-        hasEventListeners(type: string): boolean;
-        off(type: string, fn: unknown, context?: unknown): /*elided*/ any;
-        fire(type: string, data?: unknown, target?: unknown): /*elided*/ any;
-    };
-} & typeof SwipableBase;
+declare const Swipable_base: Constructor<EventedInstance<SwipableEvents>> & typeof SwipableBase;
 
 declare class SwipableBase {
     "mousedrag": DragEventNames;
@@ -2768,7 +3789,7 @@ declare class SwipableBase {
     "animator": AnimationHandle | null;
     "dragevent": DragEventNames;
     "data": DragData;
-    "fire": EventedInstance["fire"];
+    "fire": EventedInstance<SwipableEvents>["fire"];
     constructor(drag_elem: HTMLElement, move_elem?: HTMLElement, options?: Record<string, unknown>);
     enable(e?: LegacyEvent): void;
     disable(): void;
@@ -2789,6 +3810,18 @@ declare class SwipableBase {
     _animateMomentum(): void;
 }
 
+export declare interface SwipableEvents {
+    dragstart: DragData;
+    dragend: DragData;
+    dragmove: DragData;
+    momentum: DragData;
+    swipe_left: DragData;
+    swipe_right: DragData;
+    swipe_up: DragData;
+    swipe_down: DragData;
+    swipe_nodirection: DragData;
+}
+
 declare interface SwipableOptions {
     snap: boolean;
     enable: {
@@ -2806,28 +3839,22 @@ declare interface SwipableOptions {
     ease: unknown;
 }
 
+/** The four swipe directions. `"none"` is not one: an undecided gesture
+ *  carries `null`, and the truthiness guard at the fire site treats it as
+ *  "no swipe" rather than a fifth direction. */
+export declare type SwipeDirection = "left" | "right" | "up" | "down";
+
 declare class Text_2 extends Text_base {
     constructor(...args: ConstructorParameters<typeof TextBase>);
 }
 
-declare const Text_base: {
-    new (...args: any[]): {
-        _vco_events?: Record<string, {
-            action: unknown;
-            context: unknown;
-        }[]> | undefined;
-        on(type: string, fn: unknown, context?: unknown): /*elided*/ any;
-        hasEventListeners(type: string): boolean;
-        off(type: string, fn: unknown, context?: unknown): /*elided*/ any;
-        fire(type: string, data?: unknown, target?: unknown): /*elided*/ any;
-    };
-} & typeof TextBase;
+declare const Text_base: Constructor<EventedInstance<TextEvents>> & typeof TextBase;
 
 declare class TextBase {
     "_el": Record<string, HTMLElement>;
     "data": TextData;
     "options": TextOptions;
-    "fire": EventedInstance["fire"];
+    "fire": EventedInstance<TextEvents>["fire"];
     constructor(data: TextData, options?: TextOptions, add_to_container?: HTMLElement);
     show(): void;
     hide(): void;
@@ -2852,9 +3879,17 @@ declare interface TextData {
     } | null;
 }
 
+export declare interface TextEvents {
+    loaded: TextData;
+    added: TextData;
+    removed: TextData;
+}
+
 declare interface TextOptions {
     title?: boolean;
     text_align?: string;
+    /** BCP 47 tag for the slide text (from `StorymapSlide.language`). */
+    language?: string;
 }
 
 /**
@@ -2883,6 +3918,8 @@ declare interface ViewToOptions {
     calculate_zoom?: boolean;
     duration?: number;
     zoom?: number;
+    /** View rotation in degrees clockwise; absent leaves rotation unchanged. */
+    rotation?: number;
 }
 
 export { }