@projektemacher/storymapjs 0.10.7 → 0.11.0

package/dist/navplace-properties.json

@@ -0,0 +1,54 @@
+{
+    "@context": {
+        "@version": 1.1,
+        "xsd": "http://www.w3.org/2001/XMLSchema#",
+        "storymap_navplace": "https://christianmahnke.de/iiif/storymap#",
+        "name": "storymap_navplace:navplaceName",
+        "zoom": {
+            "@id": "storymap_navplace:navplaceZoom",
+            "@type": "xsd:integer"
+        },
+        "line": {
+            "@id": "storymap_navplace:navplaceLine",
+            "@type": "xsd:boolean"
+        },
+        "icon": {
+            "@id": "storymap_navplace:navplaceIcon",
+            "@type": "@id"
+        },
+        "iconSize": {
+            "@id": "storymap_navplace:navplaceIconSize",
+            "@container": "@list"
+        },
+        "image": {
+            "@id": "storymap_navplace:navplaceImage",
+            "@type": "@id"
+        },
+        "use_custom_marker": {
+            "@id": "storymap_navplace:navplaceUseCustomMarker",
+            "@type": "xsd:boolean"
+        },
+        "popup": {
+            "@id": "storymap_navplace:navplacePopup",
+            "@type": "xsd:boolean"
+        },
+        "audioBadge": {
+            "@id": "storymap_navplace:navplaceAudioBadge",
+            "@type": "xsd:boolean"
+        },
+        "rotation": {
+            "@id": "storymap_navplace:navplaceRotation",
+            "@type": "xsd:decimal"
+        },
+        "basemap": {
+            "@id": "storymap_navplace:navplaceBasemap",
+            "@type": "@id"
+        },
+        "filter": {
+            "@id": "storymap_navplace:navplaceFilter"
+        },
+        "mask": {
+            "@id": "storymap_navplace:navplaceMask"
+        }
+    }
+}

package/dist/site.css

@@ -1,3 +1,4 @@
+@charset "UTF-8";
 /*
  * Site chrome for the landing/docs pages (index.html, demo.html, docs/*).
  *
@@ -12,8 +13,8 @@
   font-family: georgia, "Times New Roman", times, serif;
   font-size: 18px;
   line-height: 1.618;
-  color: #222;
-  background-color: #fff;
+  color: var(--sm-color-text, #222);
+  background-color: var(--sm-color-page, #fff);
 }
 .sm-site *,
 .sm-site *::before,
@@ -30,7 +31,7 @@
 .sm-site pre {
   font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
   font-size: 0.85em;
-  background-color: #f0f0f0;
+  background-color: var(--sm-color-light, #f0f0f0);
   border-radius: 3px;
 }
 .sm-site code {
@@ -68,7 +69,7 @@
   font-style: italic;
   font-weight: normal;
   font-size: 3.82rem;
-  color: #222;
+  color: var(--sm-color-text, #222);
   margin: 0;
 }
 @media (width <= 767px) {
@@ -105,10 +106,10 @@
   position: relative;
   overflow: hidden;
   padding: 0.89rem 1.78rem 0.94rem;
-  border: 1px solid #d4d4d4;
+  border: 1px solid var(--sm-color-border-light, #d4d4d4);
   border-radius: 4px;
   background-color: transparent;
-  color: #646464;
+  color: var(--sm-color-grey, #646464);
   font-family: "Helvetica Neue", helvetica, arial, "Segoe UI", system-ui, sans-serif;
   font-size: 0.89rem;
   text-align: center;
@@ -122,7 +123,7 @@
 .sm-site .button:hover {
   background-color: #fdfdfd;
   border-color: #d7d7d7;
-  color: #646464;
+  color: var(--sm-color-grey, #646464);
   text-decoration: none;
 }
 .sm-site .button:focus-visible {
@@ -216,11 +217,11 @@
   border-color: rgba(255, 255, 255, 0.1);
 }
 .sm-site .navbar .button-active {
-  background-color: #d4d4d4;
-  color: #222;
+  background-color: var(--sm-color-border-light, #d4d4d4);
+  color: var(--sm-color-text, #222);
 }
 .sm-site .navbar .button-active:hover {
-  background-color: #d4d4d4;
+  background-color: var(--sm-color-border-light, #d4d4d4);
 }
 .sm-site .navbar-dark {
   background-color: #484848;
@@ -233,8 +234,8 @@
 .sm-site .header-product {
   padding: 2rem 2rem 0;
   margin-bottom: 0;
-  border-bottom: 1px solid #b8b8b8;
-  background-color: #f0f0f0;
+  border-bottom: 1px solid var(--sm-color-border, #b8b8b8);
+  background-color: var(--sm-color-light, #f0f0f0);
   text-align: center;
 }
 .sm-site .header-product .product-tagline {
@@ -251,7 +252,7 @@
 }
 .sm-site .navbar-subnav {
   margin-top: 1rem;
-  background-color: #f0f0f0;
+  background-color: var(--sm-color-light, #f0f0f0);
 }
 @media (width <= 767px) {
   .sm-site .navbar-subnav {
@@ -259,12 +260,12 @@
   }
 }
 .sm-site .navbar-subnav .button {
-  border-color: #d4d4d4;
+  border-color: var(--sm-color-border-light, #d4d4d4);
   box-shadow: none;
-  color: #646464;
+  color: var(--sm-color-grey, #646464);
 }
 .sm-site .navbar-subnav .button:hover {
-  color: #222;
+  color: var(--sm-color-text, #222);
   background-color: rgba(255, 255, 255, 0.6);
 }
 .sm-site .container {
@@ -307,12 +308,12 @@
   margin-bottom: 0;
 }
 .sm-site .fill-color-grey {
-  background-color: #f0f0f0;
+  background-color: var(--sm-color-light, #f0f0f0);
 }
 .sm-site .note {
-  background-color: #f0f0f0;
+  background-color: var(--sm-color-light, #f0f0f0);
   border-radius: 8px;
-  color: #9c9c9c;
+  color: var(--sm-color-muted, #9c9c9c);
   font-family: "Helvetica Neue", helvetica, arial, "Segoe UI", system-ui, sans-serif;
   font-size: 0.9em;
   font-style: italic;
@@ -328,7 +329,7 @@
   display: block;
   width: 100%;
   border: 0;
-  background-color: #f0f0f0;
+  background-color: var(--sm-color-light, #f0f0f0);
 }
 .sm-site .cards {
   display: grid;
@@ -356,7 +357,7 @@
 }
 .sm-site .cards .card {
   padding: 0;
-  border: 1px solid #d4d4d4;
+  border: 1px solid var(--sm-color-border-light, #d4d4d4);
   border-radius: 4px;
   background-color: #fff;
   overflow: hidden;
@@ -379,7 +380,7 @@
   height: 100%;
   background-position: center;
   background-size: cover;
-  background-color: #646464;
+  background-color: var(--sm-color-grey, #646464);
   transition: filter 0.3s ease;
 }
 .sm-site .cards .card .header-image-background.bw {
@@ -391,17 +392,17 @@
 .sm-site .cards .card article.card-content h3 {
   font-size: 1rem;
   margin: 0;
-  color: #222;
+  color: var(--sm-color-text, #222);
 }
 .sm-site .cards .card footer {
   margin-top: auto;
   padding: 0.6rem 1rem 0.8rem;
   font-family: "Helvetica Neue", helvetica, arial, "Segoe UI", system-ui, sans-serif;
   font-size: 0.75em;
-  color: #9c9c9c;
+  color: var(--sm-color-muted, #9c9c9c);
 }
 .sm-site .cards .card:hover {
-  border-color: #222;
+  border-color: var(--sm-color-text, #222);
 }
 .sm-site .cards .card:hover .header-image-background.bw {
   filter: grayscale(0%);
@@ -417,15 +418,15 @@
   position: relative;
   padding: 0.5rem;
   margin-bottom: 0.5rem;
-  background-color: #f8f8f8;
-  border: 1px solid #d4d4d4;
+  background-color: var(--sm-color-lighter, #f8f8f8);
+  border: 1px solid var(--sm-color-border-light, #d4d4d4);
   border-radius: 8px;
 }
 .sm-site ul.accordion li:hover {
   border-color: #484848;
 }
 .sm-site ul.accordion li:hover h3 {
-  color: #222;
+  color: var(--sm-color-text, #222);
 }
 .sm-site ul.accordion li input[type=checkbox] {
   position: absolute;
@@ -461,7 +462,7 @@
   font-size: 1.2rem;
   font-weight: 700;
   margin: 0.4rem 1.5rem 0.4rem 0.6rem;
-  color: #222;
+  color: var(--sm-color-text, #222);
 }
 .sm-site ul.accordion li .accordion-content {
   position: relative;
@@ -511,12 +512,12 @@
 .sm-site .sm-docs table th,
 .sm-site .sm-docs table td {
   padding: 0.5rem 0.75rem;
-  border: 1px solid #d4d4d4;
+  border: 1px solid var(--sm-color-border-light, #d4d4d4);
   text-align: left;
   vertical-align: top;
 }
 .sm-site .sm-docs table th {
-  background-color: #f0f0f0;
+  background-color: var(--sm-color-light, #f0f0f0);
 }
 .sm-site .sm-docs table code {
   background: none;
@@ -525,8 +526,8 @@
 .sm-site .sm-docs blockquote {
   margin: 1rem 0;
   padding: 0.25rem 1rem;
-  border-left: 4px solid #d4d4d4;
-  color: #646464;
+  border-left: 4px solid var(--sm-color-border-light, #d4d4d4);
+  color: var(--sm-color-grey, #646464);
 }
 .sm-site .sm-docs img {
   max-width: 100%;
@@ -538,8 +539,8 @@
   padding: 60px 80px 30px;
   font-family: "Helvetica Neue", helvetica, arial, "Segoe UI", system-ui, sans-serif;
   font-size: 0.85em;
-  background-color: #f0f0f0;
-  border-top: 1px solid #b8b8b8;
+  background-color: var(--sm-color-light, #f0f0f0);
+  border-top: 1px solid var(--sm-color-border, #b8b8b8);
 }
 .sm-site .footer-knightlab .footer-grid {
   display: flex;
@@ -583,10 +584,27 @@
   list-style: none;
 }
 .sm-site .footer-knightlab ul.list-social a {
-  color: #646464;
+  color: var(--sm-color-grey, #646464);
   font-size: 1.1em;
   font-weight: 700;
 }
 .sm-site .footer-knightlab ul.list-social a:hover {
   color: #df4e13;
+}
+
+/* Dark landing (dark theme plan): the surfaces above redeclared. Brand
+   accents (badge, green, navbar, orange links) keep their light values —
+   they read on both. Follows the OS setting; the widget additionally
+   honours an explicit `theme` option. */
+@media (prefers-color-scheme: dark) {
+  .sm-site {
+    --sm-color-page: #1a1a1a;
+    --sm-color-text: #e0e0e0;
+    --sm-color-grey: #a8a8a8;
+    --sm-color-light: #262626;
+    --sm-color-lighter: #2e2e2e;
+    --sm-color-border: #555;
+    --sm-color-border-light: #444;
+    --sm-color-muted: #b0b0b0;
+  }
 }

package/docs/migration-from-knightlab.md

@@ -72,15 +72,36 @@ element, ... }` to configure the underlying OpenLayers map; `element`
 
 ## Changed options and map types
 
-| Old                                           | New                                                                                                                                                              |
-| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `map_type: "zoomify"` (+ `options.zoomify`)   | preferred: `map_type: "iiif"` with `options.iiif = { url, attribution }` (IIIF Image API 2/3); zoomify still works as a legacy image-pyramid basemap (see below) |
-| `map_type: "stamen:toner"` etc.               | `"stamen:*"` types are deprecated and remapped: `stamen:watercolor` → `ch-watercolor`, others → `osm:standard`                                                   |
-| Stadia Maps paid tiles via `map_access_token` | Recommended: free OpenStreetMap vector styles, e.g. `map_type: "osm:bright"` (OpenFreeMap), or any style JSON URL                                                |
-| Bundled `map_access_token`                    | removed — pass `map_access_token` in the options if you use Mapbox/Stadia tiles                                                                                  |
-| Bundled Flickr API key                        | removed — pass `api_key_flickr` in the options if you use `flickr.com/photos` API URLs                                                                           |
-| `relative_date: true` (moment.js)             | removed — format dates in the story text                                                                                                                         |
-| `font_css: "stock:<name>"` (or a path)        | paths now resolve against the page URL (not the library location), plus the font files ship via `@fontsource-utils/scss`; no separate font CSS link needed       |
+| Old                                           | New                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `map_type: "zoomify"` (+ `options.zoomify`)   | preferred: `map_type: "iiif"` with `options.iiif = { url, attribution }` (IIIF Image API 2/3); zoomify still works as a legacy image-pyramid basemap (see below)                                                                                                                                                                                                                                                                            |
+| `map_type: "stamen:toner"` etc.               | `"stamen:*"` types are deprecated and remapped: `stamen:watercolor` → `ch-watercolor`, others → `osm:standard`                                                                                                                                                                                                                                                                                                                              |
+| Stadia Maps paid tiles via `map_access_token` | Recommended: free OpenStreetMap vector styles, e.g. `map_type: "osm:bright"` (OpenFreeMap), or any style JSON URL                                                                                                                                                                                                                                                                                                                           |
+| Bundled `map_access_token`                    | removed — pass `map_access_token` in the options if you use Mapbox/Stadia tiles                                                                                                                                                                                                                                                                                                                                                             |
+| Bundled Flickr API key                        | removed — pass `api_key_flickr` in the options if you use `flickr.com/photos` API URLs                                                                                                                                                                                                                                                                                                                                                      |
+| `relative_date: true` (moment.js)             | removed — format dates in the story text                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `font_css: "stock:<name>"` (or a path)        | paths now resolve against the page URL (not the library location), plus the font files ship via `@fontsource-utils/scss`; no separate font CSS link needed                                                                                                                                                                                                                                                                                  |
+| `font_css: false` (bundler consumers)         | `stock:<name>` resolves via `import.meta.url`, which only survives when this package is _not_ processed by a bundler — bundling inlines `dist/js/storymap.js` into a chunk and the theme URL breaks. Instead `import "@projektemacher/storymapjs/css/fonts/font.default.css"` (fingerprinted, `files/` rebased by the bundler) and pass `font_css: false` for no injected `<link>`. `"none"` works too for JSON. A failing theme only warns |
+
+## A story with no map
+
+`map_type: "none"` runs the storymap as text and media only. Nothing is
+constructed: no `ol/Map`, no tile layer, no tile consent row, and the overview
+control is hidden. The slider panel takes the full width, because there is no
+map behind it to fade over.
+
+This is the shape a photo essay or a transcript-led story wants, and it is the
+one the map engine's unconditional construction used to make impossible. Note
+that `map_type: ""` and an absent `map_type` both still mean OpenStreetMap, and
+`map_type: null` now falls back to that default instead of throwing out of the
+constructor — absence is not reinterpreted, so no existing document changes
+meaning. Map-derived accessors (`getBaseLayer()`, `getMarkers()`, …) return
+their neutral values, and the map setters are no-ops.
+
+| Old                                        | New                                   |
+| ------------------------------------------ | ------------------------------------- |
+| a text-only story with a dummy `map_type`  | `map_type: "none"`                    |
+| `map_type: null` (crashed the constructor) | normalised to the default, `""` → OSM |
 
 ## Removed globals and exports
 
@@ -97,9 +118,28 @@ element, ... }` to configure the underlying OpenLayers map; `element`
 
 | Removed                               | Replacement                                                                                                                                                                                                                  |
 | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `vine` media type (service shut down) | vine URLs fall back to the `website` iframe — use another media source for those slides                                                                                                                                      |
+| `vine` media type (service shut down) | vine URLs fall back to the `website` iframe — or paste the provider's `<iframe>` snippet into the slide text (sanitized, https-only); use another media source for those slides                                              |
 | Juxtapose `frame/?uid=` embed URLs    | the `juxtapose.knightlab.com/frame/?uid=` host is dead — use the published format `https://cdn.knightlab.com/libs/juxtapose/latest/embed/index.html?uid=...` (note: this keeps a Knight Lab CDN dependency for those slides) |
 | Twitter `@nickname` rendering         | tweets from `x.com` URLs are now parsed too (fixes `@undefined` nicknames); no migration needed                                                                                                                              |
+| Ricoh360/theta360 embeds (#391)       | service no longer available (won't fix) — paste the provider's `<iframe>` snippet into the slide text if the service returns                                                                                                 |
+
+Extra media per slide (#358, partial): a slide takes `media_extra` (a list of
+further media items, rendered after the primary one) plus `media_layout`
+(`stack`, the default, or `row` for two side-by-side items). An `<iframe>`
+embed snippet pasted into the slide `text` field still renders sanitized
+(scripts, event handlers and non-https sources dropped) — keep that as the
+migration path for removed media types:
+
+```html
+<p>Extra footage:</p>
+<iframe
+    src="https://example.com/embed/123"
+    width="560"
+    height="315"
+    frameborder="0"
+    allowfullscreen
+></iframe>
+```
 
 `map_type: "zoomify"` is supported again (legacy): the image pyramid renders
 via the storymap data's `zoomify` options (`path`, `width`, `height`), using a
@@ -113,12 +153,206 @@ storymap JSON sources.
 ## Map engine: Leaflet → OpenLayers
 
 - `storymap.map` now exposes the **OpenLayers `Map`** instance instead of a
-  Leaflet map. Port any direct Leaflet calls (e.g. `setView`, `flyTo`) to the
-  OpenLayers API (`getView().animate(...)`, ...).
+  Leaflet map. Port any direct Leaflet calls to the OpenLayers API (table
+  below). It is `null` until the map has been built.
 - Markers are DOM overlays (`.vco-mapmarker` / `.vco-mapmarker-active`) like
   before; the mini map is an OpenLayers `OverviewMap` control.
 - New basemap options: vector styles via `map_type: "osm:<style>"` (OpenFreeMap)
   or a Mapbox style JSON URL.
+- The `Ol*` aliases re-exported from `src/main.ts` (`OlMap`, `OlView`,
+  `OlLayer`, `OlTileLayer`, `OlVectorLayer`, `OlSource`, `OlProjection`) let
+  a consumer type the map and layers without depending on `ol` directly;
+  anything beyond those (features, geometries, coordinates) still needs `ol`.
+
+### Direct Leaflet calls → OpenLayers
+
+Both maps are reachable from the same place (`storymap.map`), so only the
+call syntax changes:
+
+| Leaflet                                    | OpenLayers                                                                |
+| ------------------------------------------ | ------------------------------------------------------------------------- |
+| `map.getCenter()`                          | `map.getView().getCenter()` — panel-shifted, see below                    |
+| `map.getZoom()`                            | `map.getView().getZoom()`                                                 |
+| `map.setView(c, z)` / `map.fitBounds(b)`   | `map.getView().fit(extent, { size: map.getSize() })`                      |
+| `map.panTo(c)` / `map.flyTo(c, z)`         | `map.getView().animate({ center: c, duration: 300 })`                     |
+| `map.setZoom(z)`                           | `map.getView().setZoom(z)` (or `.animate({ zoom: z })`)                   |
+| `map.getSize()` / `map.getBounds()`        | `map.getSize()` / `map.getView().calculateExtent(map.getSize())`          |
+| `map.on("moveend", fn)`                    | `map.on("moveend", fn)` (same event names; `movestart`/`move` also exist) |
+| `L.tileLayer(url, opts).addTo(map)`        | `new TileLayer({ source: new XYZ({ url, attributions }) }).setMap(map)`   |
+| `L.control.attribution` / `L.control.zoom` | OL `Attribution` / `Zoom` controls (pass them via `map_options.controls`) |
+| `map.getPane("overlayPane")`               | `map.getOverlayContainer()` (markers are DOM siblings, not OL features)   |
+| `map.invalidateSize()`                     | `map.updateSize()`                                                        |
+| `map.remove()`                             | `map.setTarget(undefined); map.dispose();` (or `storymap.dispose()`)      |
+
+The exposed center is deliberately panel-shifted: in landscape the view is
+offset so the visible map sits left of the slide panel, which means
+`getView().getCenter()` does **not** equal the current slide's location.
+That is a display concern, not a data one — read the location from the
+slide, not from the view. There is intentionally no offset-aware getter;
+an earlier `_getMapCenter(offset)` parameter promised that correction and
+never applied it, so it was removed rather than left to mislead.
+| `map.options.crs` / `map.getPixelOrigin()` | `map.getView().getProjection()` / `map.getPixelFromCoordinate(coord)` |
+
+Marker positions are still DOM elements, so `marker.getLatLng()` has no
+equivalent — read the slide data (`storymap.data.stlides[n].location`) or use
+`storymap._map.getMarker(n).latLon()`.
+
+### Map and marker methods
+
+The map/marker methods of the original viewer are still there with the same
+names and behaviour (`storymap._map.<method>()`, `marker.<method>()`); the OL
+engine implements them as thin wrappers over `storymap.map`. Two methods are
+deprecated no-ops and one is gone:
+
+| Original method                                                                                           | Status                                                                                                                                                                                                                                                            |
+| --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `updateDisplay`, `goTo`, `panTo`, `zoomTo`, `viewTo`                                                      | unchanged                                                                                                                                                                                                                                                         |
+| `getBoundsZoom`, `markerOverview`, `calculateMarkerZooms`                                                 | unchanged (`getBoundsZoom()` now returns `number \| undefined` instead of a falsy value)                                                                                                                                                                          |
+| `createMiniMap`, `createMarkers`, `createMarker`                                                          | unchanged                                                                                                                                                                                                                                                         |
+| `setMapOffset`, `calculateMinMaxZoom`, `updateMinMaxZoom`, `initialMapLocation`                           | unchanged                                                                                                                                                                                                                                                         |
+| `show()` / `hide()` (map and marker)                                                                      | **deprecated no-ops** — they were already empty in the original viewer. Style `.vco-mapmarker` or use `marker.active(false)`                                                                                                                                      |
+| `map.addTo(container)` / `map.removeFrom(container)`                                                      | unchanged — inherited from the `DomMixed` mixin: append/remove the map container and fire `added`/`removed`. The engine override re-targets and re-measures the OpenLayers viewport, so a move into a differently sized parent works                              |
+| `marker.createPopup()`                                                                                    | **deprecated no-op** — it never did anything upstream either (empty base body, commented-out Leaflet body), so the `map_popup` option that called it had no effect. Still accepted, still inert. Use `marker.openPopup()` / `storymap.openMarkerPopup(n)` instead |
+| `marker.addTo()`, `marker.removeFrom()`, `marker.updateDisplay()`, `marker.active()`, `marker.location()` | unchanged                                                                                                                                                                                                                                                         |
+| `marker.openPopup()` / `closePopup()` / `togglePopup()` / `isPopupEnabled()` / `popupOpen`                | **new** — programmatic control of the popup card (`marker: { popup: true }`); `openPopup()` returns false when disabled or not a real marker, `popupOpen` reports the state                                                                                       |
+| `storymap.openMarkerPopup(n)` / `closeMarkerPopup(n?)` / `isPopupOpen(n)`                                 | **new** — open/close/query a stop's card from the viewer; `openMarkerPopup` navigates to `n` first and returns false (changing nothing) when disabled, out of range, disposed or mapless                                                                          |
+
+Marker helpers that Leaflet provided on the marker object (`getLatLng`,
+`setIcon`, `bindPopup`) are gone; use `marker.latLon()`, the
+`.vco-mapmarker` element and your own DOM/CSS.
+
+## Reaching the map, layers and markers
+
+`storymap.map` is the raw `ol/Map` (typed as `OlMap | null` — it is set during
+construction, so check it before first use in an async setup). Everything the
+viewer keeps internally is available through accessors on `storymap` (and on
+`storymap._map` for the engine methods):
+
+| Accessor                                                     | Returns                                                                                                                           |
+| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| `getBaseLayer()`                                             | the base tile/vector layer                                                                                                        |
+| `getOverlayLayers()` / `getOverlayLayer(i)`                  | overlay layers / one by index (`null` if out of range)                                                                            |
+| `getOverlayCount()`                                          | number of overlays                                                                                                                |
+| `setOverlayVisible(i, on)` / `setOverlayOpacity(i, opacity)` | show/hide and fade one overlay                                                                                                    |
+| `getMinimap()`                                               | the inner overview `ol/Map` (`OlMap \| null`), not the `OverviewMap` control itself — there is no accessor for the control object |
+| `getLine()` / `getLineActive()`                              | the full and the travelled route `VectorLayer`                                                                                    |
+| `getMarker(n)` / `getMarkers()`                              | one marker or all of them, in slide order                                                                                         |
+| `setExtraAttributions(html)`                                 | extra attribution HTML, listed after the source credits                                                                           |
+| `isImageSpace()`                                             | whether the map is a IIIF image in image space (see below)                                                                        |
+
+`tile_source_factory` may return a full `ol/layer/Layer` (not just a source)
+anywhere a layer is built, so custom layers can carry their own opacity,
+z-index and events. A custom layer without a source (Allmaps'
+`WarpedMapLayer`) passes through untouched; source reads go through a
+capability check, so it simply skips the tile-grid fits.
+
+The viewer reserves three z-index ranges and custom layers should stay out
+of them: **0** for the base tiles, **1..n** for the stacked `overlays[]`
+entries in order, and **10/11** for the full and travelled route lines. A
+custom layer with no explicit z-index lands wherever OpenLayers puts it,
+which is above the lines — set one explicitly if the layer must sit inside
+the stack.
+
+### Layer switcher
+
+`show_layers_control: true` adds a disclosure button to the menubar with
+basemap radios and overlay checkboxes. Basemap candidates come from
+`basemaps[]` (entry 0 is the initial basemap unless `map_type` says
+otherwise; omit for an overlays-only control); overlay rows come from the
+built `overlays[]` entries, so a malformed entry never gets a row and row
+_i_ is always layer _i_. `label` may be a function for host i18n (re-invoked
+on `refreshLabels()`), `locked: true` renders a row checked and disabled,
+`control: false` hides a row without removing the overlay — but function
+labels survive only in constructor options, because `mergeData()` lets
+storymap JSON overwrite same-named option keys. A runtime basemap swap
+rebuilds layers but never the view, so candidates needing another
+projection are refused with a warning; switching fires `basemapchange` /
+`overlaychange`, and the visitor's choice is never persisted.
+
+### Image space vs. georeferenced
+
+`map_type: "iiif"` is a mercator map by default. With `map_as_image: true` the
+image _is_ the map: the view projection becomes `EPSG:4326`, the view is
+fitted to the image extent and marker locations are pixel offsets into the
+image rather than lat/lon. Ask `storymap.isImageSpace()` instead of testing
+`map_type` — georeferenced IIIF (a manifest with `navPlace` regions) is an
+ordinary mercator map, and `map_bbox` with a georeferenced layer is one too.
+
+### Knowing when the imagery is there
+
+Tile and image sources attach asynchronously, so `loaded` can fire before the
+imagery exists. Listen for `imageready`, which fires once a source is ready and
+carries `{ source, kind, layer }` (`kind` is `"iiif"`, `"zoomify"` or
+`"tiles"`); it is re-fired on the `storymap` as well:
+
+```js
+storymap.on("imageready", ({ kind, source }) => {
+    console.log("imagery ready", kind, source);
+});
+```
+
+### Tearing a storymap down
+
+Call `storymap.dispose()` when the embedding view goes away (SPA route change,
+dialog close). It clears the timers and the resize observer, removes the
+`window`/`document` listeners, cancels running slide animations, disposes the
+slider and the OpenLayers map, and sets `storymap.map` to `null`. Calling it
+twice is safe; the instance is unusable afterwards.
+
+## Custom map providers
+
+Any slippy-map tile URL works as `map_type` — pass the template verbatim
+(including `{z}/{x}/{y}`), relative or absolute:
+
+```js
+new StoryMap("embed", data, {
+    map_type: "https://tiles.example.org/base/{z}/{x}/{y}.png",
+});
+```
+
+Mapbox style JSON URLs render as vector tile layers; OpenLayers
+`Map`/`View` pass-through stays available via `options.map_options`
+(`controls` replaces the defaults, `interactions` are added to the
+viewer's own pan/zoom set, `view` merges over the computed default).
+
+For source classes the templates cannot express (WMS, authenticated or
+gridded sources), use the `tile_source_factory` option. It is consulted
+for every base, overlay and minimap layer before the built-in
+`map_type` handling — return any `ol/layer/Layer` (used as-is) or a bare
+`Source` (which is wrapped in a `TileLayer`), or `null`/`undefined` to fall
+through:
+
+```js
+import TileLayer from "ol/layer/Tile";
+import TileWMS from "ol/source/TileWMS";
+
+new StoryMap("embed", data, {
+    map_type: "wms:flood",
+    tile_source_factory: (map_type, { options, createDefault }) =>
+        map_type.startsWith("wms:")
+            ? new TileLayer({
+                  source: new TileWMS({
+                      url: "https://geoserver.example.org/wms",
+                      params: { LAYERS: map_type.slice(4) },
+                      crossOrigin: "anonymous",
+                  }),
+              })
+            : createDefault(),
+});
+```
+
+The second factory argument also carries the resolved `options`
+(`{ options, createDefault }`). A factory may return any `ol/layer/Layer`
+(used as-is — including sourceless layers such as Allmaps'
+`WarpedMapLayer`), a bare `Source` (wrapped in a `TileLayer`), or
+`null`/`undefined` to fall through to the default `map_type` handling.
+
+Custom sources must carry their own attributions (via the returned
+source or the `attribution` option) — only the built-in `osm*` types
+are credited automatically. `tile_source_factory` is constructor- and
+runtime-only (functions cannot ride storymap JSON) and also applies to
+`overlays[]` entries, whose `map_type` values go through the same
+factory.
 
 ## Data and tooling
 
@@ -126,14 +360,40 @@ storymap JSON sources.
   (`schema/storymap.schema.json`); invalid documents are reported to the
   console at load time.
 - IIIF Presentation 3 manifests are accepted directly as storymap sources.
-- The StoryMap IIIF extension context changed to
-  `https://christianmahnke.de/iiif/storymap` — manifests produced with the old
-  `https://example.org/ns/storymap/v1` context need re-converting
-  (`scripts/convert-to-iiif.mjs`).
+  The map settings map onto `storymap:` terms of a map configuration service
+  (IIIF has no basemap or tile-layer vocabulary of its own), and the
+  geospatial parts use the native extensions where they exist: `navPlace`
+  Points for slide locations, a `navPlace` Polygon for the story extent
+  (`map_bbox`), an IIIF Image API Selector for `location.region`, and the
+  Georeference Extension for placed rasters. A georeferenced layer is
+  manifest-only (the legacy format cannot express ground control points); see
+  [docs/storymap-as-iiif-manifest.md](storymap-as-iiif-manifest.md#geo-referenced-layers).
 - The editor, staging/backend infrastructure, AWS/GitHub hosting scripts and the
   Python authoring server are gone — this is a viewer-only library.
+- **Slideshow tours** are a third input format: W3C `AnnotationCollection`
+  documents (the format of slideshow-style guided image tours) load
+  directly by object, file or URL, auto-detected after the IIIF branch
+  (`slideshow: false` opts out). A pure translator converts them to
+  storymap data — per-slide image regions, rotation, filter grading,
+  spotlight masks, per-slide basemaps, narration with playback flags and
+  player chrome — which renders only for slideshow tours (the internal
+  `slideshow_source` marker; other documents are unaffected). Convert
+  offline with `npm run convert:slideshow`; the full mapping is in
+  [docs/slideshow.md](slideshow.md).
+
+## Events (unchanged, plus new ones)
 
-## Events (unchanged)
+The canonical reference is [docs/events.md](events.md) — one table per
+emitter, with payloads. What changed in migration terms: `change` gains
+`current_id`, `loaded`, `title`, `dataloaded`, `fontLoaded`,
+`transitionstart`/`transitionend`, `error` and the constructor listener map
+all work as before; `markerAdded`/`markerRemoved` still fire on the map
+object; `imageready`, `markerclick` and `popupopen`/`popupclose` are new
+(see above).
 
-`change` (with `current_slide`), `loaded`, `title`, `dataloaded`,
-`fontLoaded`, plus the listener map in the constructor — all work as before.
+Two additions for IIIF tours: `await storymap.loadAnnotations()` fetches a
+manifest's externally referenced annotation pages and appends them as stops,
+then fires `annotationsloaded` with `{ stops, searchService, failed }`. A
+slide's stable identity is available as `storymap.getSlideId(index)`, which
+is what the `#slide-N` hash and the `iiif-content` deep link resolve
+through.