@projektemacher/storymapjs 0.10.8 → 0.11.0

package/dist/docs/iiif.html

@@ -37,6 +37,7 @@
                 <li><a class="button" href="./migration.html">Migration guide</a></li>
                 <li><a class="button" href="./iiif.html">IIIF docs</a></li>
                 <li><a class="button" href="./authoring.html">Authoring</a></li>
+                <li><a class="button" href="./events.html">Events</a></li>
                 <li><a class="button" href="./api/index.html">API docs</a></li>
                 <li><a class="button" href="../index.html#help">Help</a></li>
             </ul>
@@ -53,7 +54,11 @@ the fixtures in <a href="../examples/"><code>public/examples/</code></a> are rea
 (<a href="../examples-iiif/"><code>public/examples-iiif/</code></a>), and
 <code>scripts/validate-iiif.mjs</code> checks every converted manifest against the
 <a href="https://presentation-validator.iiif.io/">official IIIF presentation validator</a>
-(<code>npm run validate:iiif</code>). All converted fixtures pass the official validator.</p>
+(<code>npm run validate:iiif</code>). All converted fixtures pass the official validator,
+except the two hand-authored georeferenced-layer fixtures, which the base
+validator schema cannot accept by design (see &quot;Geo-referenced layers&quot; below);
+<code>npm run validate:iiif</code> reports those two as <em>not covered</em> rather than as
+failures.</p>
 <h2>Contexts</h2>
 <p>A manifest declares four context URLs, in this order: the official
 <a href="https://iiif.io/api/extension/navplace/">navPlace extension</a> context (which
@@ -67,7 +72,6 @@ reference; a manifest must reference it by URL, not paste it in (see the
         &quot;@version&quot;: 1.1,
         &quot;storymap&quot;: &quot;https://christianmahnke.de/iiif/storymap#&quot;,
         &quot;mapAsImage&quot;: &quot;storymap:mapAsImage&quot;,
-        &quot;basemap&quot;: &quot;storymap:basemap&quot;,
         &quot;tilejson&quot;: &quot;storymap:tilejson&quot;,
         &quot;mapAccessToken&quot;: &quot;storymap:mapAccessToken&quot;,
         &quot;mapBackgroundColor&quot;: &quot;storymap:mapBackgroundColor&quot;,
@@ -97,7 +101,19 @@ reference; a manifest must reference it by URL, not paste it in (see the
             &quot;@type&quot;: &quot;@id&quot;
         },
         &quot;mediaSrcset&quot;: &quot;storymap:mediaSrcset&quot;,
-        &quot;mediaSizes&quot;: &quot;storymap:mediaSizes&quot;
+        &quot;mediaSizes&quot;: &quot;storymap:mediaSizes&quot;,
+        &quot;rotation&quot;: &quot;storymap:rotation&quot;,
+        &quot;basemap&quot;: &quot;storymap:basemap&quot;,
+        &quot;filter&quot;: &quot;storymap:filter&quot;,
+        &quot;mask&quot;: &quot;storymap:mask&quot;,
+        &quot;slidetimeout&quot;: &quot;storymap:slidetimeout&quot;,
+        &quot;imgoverlay&quot;: &quot;storymap:imgoverlay&quot;,
+        &quot;loop&quot;: &quot;storymap:loop&quot;,
+        &quot;offset&quot;: &quot;storymap:offset&quot;,
+        &quot;play&quot;: &quot;storymap:play&quot;,
+        &quot;stopOnExit&quot;: &quot;storymap:stopOnExit&quot;,
+        &quot;stopAllPrevious&quot;: &quot;storymap:stopAllPrevious&quot;,
+        &quot;provenance&quot;: &quot;storymap:provenance&quot;
     }
 }
 </code></pre>
@@ -125,7 +141,6 @@ what the fixtures reference. Content:</p>
     &quot;@context&quot;: {
         &quot;@version&quot;: 1.1,
         &quot;storymap&quot;: &quot;https://christianmahnke.de/iiif/storymap#&quot;,
-        &quot;basemap&quot;: &quot;storymap:basemap&quot;,
         &quot;tilejson&quot;: &quot;storymap:tilejson&quot;,
         &quot;mapAsImage&quot;: &quot;storymap:mapAsImage&quot;,
         &quot;mapAccessToken&quot;: &quot;storymap:mapAccessToken&quot;,
@@ -153,7 +168,19 @@ what the fixtures reference. Content:</p>
         &quot;overlays&quot;: &quot;storymap:overlays&quot;,
         &quot;type&quot;: { &quot;@id&quot;: &quot;storymap:type&quot;, &quot;@type&quot;: &quot;@id&quot; },
         &quot;mediaSrcset&quot;: &quot;storymap:mediaSrcset&quot;,
-        &quot;mediaSizes&quot;: &quot;storymap:mediaSizes&quot;
+        &quot;mediaSizes&quot;: &quot;storymap:mediaSizes&quot;,
+        &quot;rotation&quot;: &quot;storymap:rotation&quot;,
+        &quot;basemap&quot;: &quot;storymap:basemap&quot;,
+        &quot;filter&quot;: &quot;storymap:filter&quot;,
+        &quot;mask&quot;: &quot;storymap:mask&quot;,
+        &quot;slidetimeout&quot;: &quot;storymap:slidetimeout&quot;,
+        &quot;imgoverlay&quot;: &quot;storymap:imgoverlay&quot;,
+        &quot;loop&quot;: &quot;storymap:loop&quot;,
+        &quot;offset&quot;: &quot;storymap:offset&quot;,
+        &quot;play&quot;: &quot;storymap:play&quot;,
+        &quot;stopOnExit&quot;: &quot;storymap:stopOnExit&quot;,
+        &quot;stopAllPrevious&quot;: &quot;storymap:stopAllPrevious&quot;,
+        &quot;provenance&quot;: &quot;storymap:provenance&quot;
     }
 }
 </code></pre>
@@ -301,9 +328,16 @@ with one GeoJSON Feature:</p>
 verbatim. For image-map storymaps (<code>storymap:mapAsImage: true</code>) the values are
 image coordinates rather than WGS84 degrees; consumers can detect this via
 <code>storymap:mapAsImage</code>.</li>
-<li><code>properties</code>: marker data — <code>name</code>, <code>zoom</code>, <code>line</code>, <code>icon</code>, <code>iconSize</code>,
-<code>image</code>, <code>use_custom_marker</code>, plus the presentation-only <code>popup</code> and
-<code>audioBadge</code> (only present keys).</li>
+<li><code>properties</code>: marker data — <code>name</code>, <code>zoom</code>, <code>rotation</code> (view rotation in
+degrees clockwise), <code>basemap</code> (a per-slide basemap override: any <code>map_type</code>
+value or IIIF <code>info.json</code> URL), <code>filter</code> (per-slide image grading:
+<code>brightness</code>/<code>contrast</code>/<code>saturate</code> in percent, <code>hueRotate</code> in degrees,
+<code>sepia</code> in percent, <code>blur</code> in CSS pixels), <code>mask</code> (a spotlight mask:
+normalized <code>{x, y, w, h}</code> viewport fractions plus <code>color</code>/<code>invert</code>), <code>line</code>,
+<code>icon</code>, <code>iconSize</code>, <code>image</code>, <code>use_custom_marker</code>, plus the
+presentation-only <code>popup</code> and <code>audioBadge</code> (only present keys). Slides
+without <code>lat</code>/<code>lon</code> carry <code>rotation</code>/<code>basemap</code>/<code>filter</code>/<code>mask</code> as the
+canvas <code>storymap:</code> terms below instead.</li>
 <li><code>location.use_custom_marker</code> / <code>use_custom_markers</code> (manifest) opt into
 custom marker rendering; see the storymap terms below.</li>
 </ul>
@@ -315,8 +349,7 @@ context, and a client that meets a property it does not understand must ignore
 it. There is no IIIF extension for marker presentation — navPlace defines
 exactly one term, <code>navPlace</code> itself — so the local context is the only option.
 It is why <code>popup</code> and <code>audioBadge</code> need no <code>storymap:</code> term of their own, and
-the same mechanism is what <code>docs/plans/iiif-media-tours.md</code> §2 wants for its
-marker config. The nine local names hang off this project&#39;s existing namespace
+the same mechanism serves marker config. The thirteen local names hang off this project&#39;s existing namespace
 (<code>https://christianmahnke.de/iiif/storymap#</code>), not a new one.</p>
 <h3>Context order matters</h3>
 <p>The navPlace extension&#39;s context <strong>must be listed before</strong> the Presentation 3
@@ -408,7 +441,9 @@ properties):</p>
 <p>A keyword basemap and a tile URL template are different kinds of thing, and
 <code>mapType</code> used to be both. They are now separate: <code>storymap:basemap</code> names a
 source the viewer knows how to configure, and an <strong>unprefixed</strong> <code>tilejson</code>
-object describes any other tile service in the standard&#39;s own terms. Only
+object describes any other tile service in the standard&#39;s own terms (the
+<code>tilejson</code> context entry stays prefixed by JSON-LD convention; only the
+unprefixed wire form is read). Only
 <code>tiles</code> is required:</p>
 <pre><code class="language-json">{
     &quot;service&quot;: [
@@ -432,7 +467,9 @@ object describes any other tile service in the standard&#39;s own terms. Only
 </code></pre>
 <p><code>tiles</code> becomes <code>map_type</code>, so everything that dispatches on a template (the
 <code>tile_source_factory</code> option, attribution, the minimap) works unchanged. The
-rest is honoured where the map can act on it:</p>
+rest is honoured where the map can act on it when <em>reading</em> a manifest; note
+the converter only writes <code>{tiles}</code> back out, so a manifest → storymap →
+manifest cycle drops <code>minzoom</code>/<code>maxzoom</code>/<code>bounds</code>/<code>scheme</code>/<code>center</code>:</p>
 <table>
 <thead>
 <tr>
@@ -507,9 +544,9 @@ offset, the same reason <code>map_bbox</code> works the way it does.</p>
 <td><code>{left, top}</code></td>
 </tr>
 <tr>
-<td><code>mapSubdomains</code></td>
+<td><em>(none — removed)</em></td>
 <td><code>map_subdomains</code></td>
-<td>Tile URL subdomains</td>
+<td><em>dropped</em> (inert, no reader; see the full mapping table)</td>
 </tr>
 <tr>
 <td><em>(none)</em></td>
@@ -519,7 +556,7 @@ offset, the same reason <code>map_bbox</code> works the way it does.</p>
 <tr>
 <td><code>fontCss</code></td>
 <td><code>font_css</code></td>
-<td>e.g. <code>stock:dancing-ledger</code></td>
+<td>e.g. <code>stock:dancing-ledger</code>, or <code>false</code> for no injected theme</td>
 </tr>
 <tr>
 <td><code>callToAction</code></td>
@@ -547,9 +584,9 @@ offset, the same reason <code>map_bbox</code> works the way it does.</p>
 <td>boolean</td>
 </tr>
 <tr>
-<td><code>lessBounce</code></td>
+<td><em>(none — removed)</em></td>
 <td><code>less_bounce</code></td>
-<td>boolean</td>
+<td><em>dropped</em> (inert, no reader; see the full mapping table)</td>
 </tr>
 <tr>
 <td><code>lineFollowsPath</code></td>
@@ -626,12 +663,24 @@ offset, the same reason <code>map_bbox</code> works the way it does.</p>
 <td><code>overlays[]</code> (georeference entries)</td>
 <td>IIIF images placed from ground control points — see &quot;Geo-referenced layers&quot;</td>
 </tr>
+<tr>
+<td><em>(viewer option)</em></td>
+<td><code>show_layers_control</code>, <code>basemaps</code></td>
+<td>the layer switcher and its basemap list: viewer-side only, never read from a manifest; <code>label</code> functions likewise never cross the JSON boundary</td>
+</tr>
 </tbody></table>
 <h3>Canvas level — direct properties</h3>
 <p>Canvas objects are open for extension terms, so slide-specific StoryMap data is
 carried directly on the Canvas: <code>storymap:type</code>, plus the two terms with no
 standard home, <code>storymap:mediaSrcset</code> and <code>storymap:mediaSizes</code> (see the
-Canvas table above). A slide&#39;s date is the standard <code>navDate</code> and its
+Canvas table above), plus the view directives <code>storymap:rotation</code>,
+<code>storymap:basemap</code>, <code>storymap:filter</code> and <code>storymap:mask</code> (the fallback for
+slides without <code>lat</code>/<code>lon</code>, which have no <code>navPlace</code> to carry them — the
+reader prefers <code>navPlace</code> when both spell a key), the per-slide autoplay
+dwell <code>storymap:slidetimeout</code> (milliseconds, <code>0</code> holds), the per-slide
+image overlay <code>storymap:imgoverlay</code> (<code>{url, size?, opacity?, extent?}</code>) and
+the provenance identifiers <code>storymap:provenance</code>
+(<code>{manifest?, canvas?, image?}</code>, data-only). A slide&#39;s date is the standard <code>navDate</code> and its
 background is the standard <code>background</code> annotation. The media caption, credit and alt
 text are <strong>not</strong> terms any more: they are the painting annotation&#39;s own <code>label</code>,
 <code>requiredStatement</code> and <code>accessibilitySummary</code>, which is where Presentation 3
@@ -640,6 +689,19 @@ are simply no longer read.</p>
 <p>Readers must use the prefixed term for the slide type (<code>storymap:type</code>): the
 bare <code>type</code> key of a Canvas is the IIIF class type (<code>&quot;Canvas&quot;</code>) and can never
 carry the StoryMap slide type.</p>
+<p><strong>Gating.</strong> The slideshow-motivated fields above (<code>rotation</code>, <code>basemap</code>,
+<code>filter</code>, <code>mask</code>, <code>slidetimeout</code>, <code>imgoverlay</code>, <code>provenance</code>) are read
+data-preservingly from any manifest, but they render <strong>only for slideshow
+tours</strong> (the viewer&#39;s internal <code>slideshow_source</code> marker, set when a
+document arrives through the slideshow translator). Hand-written manifests
+and storymap JSON keep the long-standing rendering; see the README&#39;s
+slideshow section. The playback flags (<code>storymap:loop/offset/play/ stopOnExit/stopAllPrevious</code>) are gated the same way.</p>
+<p><strong>Placement.</strong> The view directives live on the <strong>Canvas</strong> (direct
+properties); the playback flags live as <strong>Annotation</strong> foreign members —
+<code>storymap:loop/offset/play/stopOnExit</code> on the painting annotation (for
+audio/video media) and the full set including <code>storymap:stopAllPrevious</code>
+on the <code>supplementing</code> narration annotation. When a key is spelled both on
+the Canvas and in <code>navPlace</code> properties, <code>navPlace</code> wins.</p>
 <h2>Annotation-driven tour stops</h2>
 <p>A Canvas annotation whose <code>motivation</code> is <code>commenting</code>, <code>tagging</code>,
 <code>classifying</code> or <code>describing</code> and whose target resolves to a region becomes
@@ -698,8 +760,8 @@ and the standard properties are the only source:</p>
 <td>time-anchored stops</td>
 </tr>
 <tr>
-<td>a sibling <code>TextualBody</code> with <code>format: text/vtt</code></td>
-<td><code>subtitles</code></td>
+<td>a sibling <code>TextualBody</code> with <code>format: text/vtt</code> <strong>and an <code>id</code></strong></td>
+<td><code>subtitles</code> (both required — the <code>id</code> is the subtitle file URL)</td>
 </tr>
 </tbody></table>
 <h2>Native IIIF vs. the StoryMap extension</h2>
@@ -1245,7 +1307,7 @@ photo, and a slide with a YouTube video — full manifest:</p>
 </tr>
 <tr>
 <td><code>iiif.url</code></td>
-<td>Canvas Image annotation <code>service[0].id</code> + <code>/info.json</code></td>
+<td>Canvas Image annotation <code>service[0].id</code> + <code>/info.json</code> (only when the story uses <code>map_type: &quot;iiif&quot;</code>)</td>
 </tr>
 <tr>
 <td><code>iiif.attribution</code></td>
@@ -1257,7 +1319,7 @@ photo, and a slide with a YouTube video — full manifest:</p>
 </tr>
 <tr>
 <td><code>font_css</code></td>
-<td><code>service[0].storymap:fontCss</code></td>
+<td><code>service[0].storymap:fontCss</code> (<code>false</code> disables the injected theme)</td>
 </tr>
 <tr>
 <td><code>call_to_action</code></td>
@@ -1279,6 +1341,18 @@ photo, and a slide with a YouTube video — full manifest:</p>
 <td><em>(root) <code>width</code>, <code>height</code></em></td>
 <td><em>dropped</em> (viewer embed size)</td>
 </tr>
+<tr>
+<td><em>(slideshow tours) player chrome (<code>textmode</code>, <code>textsize</code>, <code>progressbar</code>, <code>fxmode</code>, <code>mode</code>, <code>hud*</code>, <code>shownav</code>, <code>show_*</code>, <code>viewerheight</code>, <code>autoplay</code>)</em></td>
+<td><em>dropped</em> (no IIIF vocabulary; translator-only, see docs/slideshow.md)</td>
+</tr>
+<tr>
+<td><code>credit.creator</code> / <code>credit.rights</code></td>
+<td>Manifest <code>metadata</code> entries (&quot;Creator&quot; / &quot;Rights&quot;) — one way: the reader keeps all metadata in <code>data.metadata[]</code> and never reconstructs <code>credit</code>, and <code>credit.licenseUrl</code> is not written at all</td>
+</tr>
+<tr>
+<td><code>iiif.fallbackUrl</code></td>
+<td><em>dropped</em> (runtime fallback; tour documents carry <code>image_static</code> per stop)</td>
+</tr>
 </tbody></table>
 <table>
 <thead>
@@ -1336,6 +1410,46 @@ photo, and a slide with a YouTube video — full manifest:</p>
 <td>Canvas <code>navPlace</code> Feature <code>properties.use_custom_marker</code></td>
 </tr>
 <tr>
+<td><code>location.rotation</code></td>
+<td>Canvas <code>navPlace</code> Feature <code>properties.rotation</code>, else Canvas <code>storymap:rotation</code></td>
+</tr>
+<tr>
+<td><code>location.basemap</code></td>
+<td>Canvas <code>navPlace</code> Feature <code>properties.basemap</code>, else Canvas <code>storymap:basemap</code></td>
+</tr>
+<tr>
+<td><code>location.filter</code></td>
+<td>Canvas <code>navPlace</code> Feature <code>properties.filter</code>, else Canvas <code>storymap:filter</code></td>
+</tr>
+<tr>
+<td><code>location.mask</code></td>
+<td>Canvas <code>navPlace</code> Feature <code>properties.mask</code>, else Canvas <code>storymap:mask</code></td>
+</tr>
+<tr>
+<td><code>slidetimeout</code></td>
+<td>Canvas <code>storymap:slidetimeout</code> (milliseconds, <code>0</code> holds)</td>
+</tr>
+<tr>
+<td><code>imgoverlay</code></td>
+<td>Canvas <code>storymap:imgoverlay</code></td>
+</tr>
+<tr>
+<td><code>provenance</code></td>
+<td>Canvas <code>storymap:provenance</code> (data-only identifiers)</td>
+</tr>
+<tr>
+<td><code>narration.url</code></td>
+<td>Supplementing annotation body <code>{type: &quot;Sound&quot;}</code></td>
+</tr>
+<tr>
+<td><code>narration.loop/offset/play/stopOnExit/stopAllPrevious</code></td>
+<td>Supplementing annotation <code>storymap:</code> members (foreign members, only when set)</td>
+</tr>
+<tr>
+<td><code>media.offset/loop/play/stopOnExit</code></td>
+<td>Painting annotation <code>storymap:</code> members (foreign members, only when set)</td>
+</tr>
+<tr>
 <td><code>media.url</code> (image)</td>
 <td>Annotation body <code>{type: &quot;Image&quot;, format: ...}</code></td>
 </tr>

package/dist/docs/migration.html

@@ -37,6 +37,7 @@
                 <li><a class="button" href="./migration.html">Migration guide</a></li>
                 <li><a class="button" href="./iiif.html">IIIF docs</a></li>
                 <li><a class="button" href="./authoring.html">Authoring</a></li>
+                <li><a class="button" href="./events.html">Events</a></li>
                 <li><a class="button" href="./api/index.html">API docs</a></li>
                 <li><a class="button" href="../index.html#help">Help</a></li>
             </ul>
@@ -154,6 +155,10 @@ are rendered wider with a visible track for contrast.</li>
 <td><code>font_css: &quot;stock:&lt;name&gt;&quot;</code> (or a path)</td>
 <td>paths now resolve against the page URL (not the library location), plus the font files ship via <code>@fontsource-utils/scss</code>; no separate font CSS link needed</td>
 </tr>
+<tr>
+<td><code>font_css: false</code> (bundler consumers)</td>
+<td><code>stock:&lt;name&gt;</code> resolves via <code>import.meta.url</code>, which only survives when this package is <em>not</em> processed by a bundler — bundling inlines <code>dist/js/storymap.js</code> into a chunk and the theme URL breaks. Instead <code>import &quot;@projektemacher/storymapjs/css/fonts/font.default.css&quot;</code> (fingerprinted, <code>files/</code> rebased by the bundler) and pass <code>font_css: false</code> for no injected <code>&lt;link&gt;</code>. <code>&quot;none&quot;</code> works too for JSON. A failing theme only warns</td>
+</tr>
 </tbody></table>
 <h2>A story with no map</h2>
 <p><code>map_type: &quot;none&quot;</code> runs the storymap as text and media only. Nothing is
@@ -241,11 +246,12 @@ their neutral values, and the map setters are no-ops.</p>
 <td>service no longer available (won&#39;t fix) — paste the provider&#39;s <code>&lt;iframe&gt;</code> snippet into the slide text if the service returns</td>
 </tr>
 </tbody></table>
-<p>Extra media per slide (#358, partial): each slide still has one primary
-<code>media</code> item, but an <code>&lt;iframe&gt;</code> embed snippet pasted into the slide <code>text</code>
-field now renders sanitized (scripts, event handlers and non-https sources
-dropped) — use this for a second video/map/embed or as the migration path
-for removed media types:</p>
+<p>Extra media per slide (#358, partial): a slide takes <code>media_extra</code> (a list of
+further media items, rendered after the primary one) plus <code>media_layout</code>
+(<code>stack</code>, the default, or <code>row</code> for two side-by-side items). An <code>&lt;iframe&gt;</code>
+embed snippet pasted into the slide <code>text</code> field still renders sanitized
+(scripts, event handlers and non-https sources dropped) — keep that as the
+migration path for removed media types:</p>
 <pre><code class="language-html">&lt;p&gt;Extra footage:&lt;/p&gt;
 &lt;iframe
     src=&quot;https://example.com/embed/123&quot;
@@ -272,9 +278,10 @@ below). It is <code>null</code> until the map has been built.</li>
 before; the mini map is an OpenLayers <code>OverviewMap</code> control.</li>
 <li>New basemap options: vector styles via <code>map_type: &quot;osm:&lt;style&gt;&quot;</code> (OpenFreeMap)
 or a Mapbox style JSON URL.</li>
-<li>All OL types (<code>Map</code>, <code>View</code>, <code>Layer</code>, <code>Source</code>, <code>Feature</code>, ...) are
-re-exported, so a consumer can type its own overlays without depending on
-<code>ol</code> directly.</li>
+<li>The <code>Ol*</code> aliases re-exported from <code>src/main.ts</code> (<code>OlMap</code>, <code>OlView</code>,
+<code>OlLayer</code>, <code>OlTileLayer</code>, <code>OlVectorLayer</code>, <code>OlSource</code>, <code>OlProjection</code>) let
+a consumer type the map and layers without depending on <code>ol</code> directly;
+anything beyond those (features, geometries, coordinates) still needs <code>ol</code>.</li>
 </ul>
 <h3>Direct Leaflet calls → OpenLayers</h3>
 <p>Both maps are reachable from the same place (<code>storymap.map</code>), so only the
@@ -384,12 +391,20 @@ deprecated no-ops and one is gone:</p>
 </tr>
 <tr>
 <td><code>marker.createPopup()</code></td>
-<td><strong>deprecated no-op</strong> — it never did anything upstream either (empty base body, commented-out Leaflet body), so the <code>map_popup</code> option that called it had no effect. Still accepted, still inert</td>
+<td><strong>deprecated no-op</strong> — it never did anything upstream either (empty base body, commented-out Leaflet body), so the <code>map_popup</code> option that called it had no effect. Still accepted, still inert. Use <code>marker.openPopup()</code> / <code>storymap.openMarkerPopup(n)</code> instead</td>
 </tr>
 <tr>
 <td><code>marker.addTo()</code>, <code>marker.removeFrom()</code>, <code>marker.updateDisplay()</code>, <code>marker.active()</code>, <code>marker.location()</code></td>
 <td>unchanged</td>
 </tr>
+<tr>
+<td><code>marker.openPopup()</code> / <code>closePopup()</code> / <code>togglePopup()</code> / <code>isPopupEnabled()</code> / <code>popupOpen</code></td>
+<td><strong>new</strong> — programmatic control of the popup card (<code>marker: { popup: true }</code>); <code>openPopup()</code> returns false when disabled or not a real marker, <code>popupOpen</code> reports the state</td>
+</tr>
+<tr>
+<td><code>storymap.openMarkerPopup(n)</code> / <code>closeMarkerPopup(n?)</code> / <code>isPopupOpen(n)</code></td>
+<td><strong>new</strong> — open/close/query a stop&#39;s card from the viewer; <code>openMarkerPopup</code> navigates to <code>n</code> first and returns false (changing nothing) when disabled, out of range, disposed or mapless</td>
+</tr>
 </tbody></table>
 <p>Marker helpers that Leaflet provided on the marker object (<code>getLatLng</code>,
 <code>setIcon</code>, <code>bindPopup</code>) are gone; use <code>marker.latLon()</code>, the
@@ -424,7 +439,7 @@ viewer keeps internally is available through accessors on <code>storymap</code>
 </tr>
 <tr>
 <td><code>getMinimap()</code></td>
-<td>the <code>OverviewMap</code> control, or its inner map via <code>getOverviewMap()</code></td>
+<td>the inner overview <code>ol/Map</code> (<code>OlMap | null</code>), not the <code>OverviewMap</code> control itself — there is no accessor for the control object</td>
 </tr>
 <tr>
 <td><code>getLine()</code> / <code>getLineActive()</code></td>
@@ -454,6 +469,20 @@ entries in order, and <strong>10/11</strong> for the full and travelled route li
 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.</p>
+<h3>Layer switcher</h3>
+<p><code>show_layers_control: true</code> adds a disclosure button to the menubar with
+basemap radios and overlay checkboxes. Basemap candidates come from
+<code>basemaps[]</code> (entry 0 is the initial basemap unless <code>map_type</code> says
+otherwise; omit for an overlays-only control); overlay rows come from the
+built <code>overlays[]</code> entries, so a malformed entry never gets a row and row
+<em>i</em> is always layer <em>i</em>. <code>label</code> may be a function for host i18n (re-invoked
+on <code>refreshLabels()</code>), <code>locked: true</code> renders a row checked and disabled,
+<code>control: false</code> hides a row without removing the overlay — but function
+labels survive only in constructor options, because <code>mergeData()</code> 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 <code>basemapchange</code> /
+<code>overlaychange</code>, and the visitor&#39;s choice is never persisted.</p>
 <h3>Image space vs. georeferenced</h3>
 <p><code>map_type: &quot;iiif&quot;</code> is a mercator map by default. With <code>map_as_image: true</code> the
 image <em>is</em> the map: the view projection becomes <code>EPSG:4326</code>, the view is
@@ -490,14 +519,15 @@ viewer&#39;s own pan/zoom set, <code>view</code> merges over the computed defaul
 <p>For source classes the templates cannot express (WMS, authenticated or
 gridded sources), use the <code>tile_source_factory</code> option. It is consulted
 for every base, overlay and minimap layer before the built-in
-<code>map_type</code> handling — return a <code>TileLayer</code> (or a bare <code>Source</code>, which
-is wrapped in one), or <code>null</code>/<code>undefined</code> to fall through:</p>
+<code>map_type</code> handling — return any <code>ol/layer/Layer</code> (used as-is) or a bare
+<code>Source</code> (which is wrapped in a <code>TileLayer</code>), or <code>null</code>/<code>undefined</code> to fall
+through:</p>
 <pre><code class="language-js">import TileLayer from &quot;ol/layer/Tile&quot;;
 import TileWMS from &quot;ol/source/TileWMS&quot;;
 
 new StoryMap(&quot;embed&quot;, data, {
     map_type: &quot;wms:flood&quot;,
-    tile_source_factory: (map_type, { createDefault }) =&gt;
+    tile_source_factory: (map_type, { options, createDefault }) =&gt;
         map_type.startsWith(&quot;wms:&quot;)
             ? new TileLayer({
                   source: new TileWMS({
@@ -509,6 +539,11 @@ new StoryMap(&quot;embed&quot;, data, {
             : createDefault(),
 });
 </code></pre>
+<p>The second factory argument also carries the resolved <code>options</code>
+(<code>{ options, createDefault }</code>). A factory may return any <code>ol/layer/Layer</code>
+(used as-is — including sourceless layers such as Allmaps&#39;
+<code>WarpedMapLayer</code>), a bare <code>Source</code> (wrapped in a <code>TileLayer</code>), or
+<code>null</code>/<code>undefined</code> to fall through to the default <code>map_type</code> handling.</p>
 <p>Custom sources must carry their own attributions (via the returned
 source or the <code>attribution</code> option) — only the built-in <code>osm*</code> types
 are credited automatically. <code>tile_source_factory</code> is constructor- and
@@ -531,13 +566,25 @@ manifest-only (the legacy format cannot express ground control points); see
 <a href="./iiif.html#geo-referenced-layers">docs/storymap-as-iiif-manifest.md</a>.</li>
 <li>The editor, staging/backend infrastructure, AWS/GitHub hosting scripts and the
 Python authoring server are gone — this is a viewer-only library.</li>
+<li><strong>Slideshow tours</strong> are a third input format: W3C <code>AnnotationCollection</code>
+documents (the format of slideshow-style guided image tours) load
+directly by object, file or URL, auto-detected after the IIIF branch
+(<code>slideshow: false</code> 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
+<code>slideshow_source</code> marker; other documents are unaffected). Convert
+offline with <code>npm run convert:slideshow</code>; the full mapping is in
+<a href="slideshow.md">docs/slideshow.md</a>.</li>
 </ul>
-<h2>Events (unchanged, plus two new ones)</h2>
-<p><code>change</code> (with <code>current_slide</code>, and now also <code>current_id</code> — the slide&#39;s
-<code>uniqueid</code>, for deep-linking), <code>loaded</code>, <code>title</code>, <code>dataloaded</code>,
-<code>fontLoaded</code>, plus the listener map in the constructor — all work as before.
-<code>markerAdded</code>/<code>markerRemoved</code> still fire on the map object, and <code>imageready</code>
-is new (see above).</p>
+<h2>Events (unchanged, plus new ones)</h2>
+<p>The canonical reference is <a href="./events.html">docs/events.md</a> — one table per
+emitter, with payloads. What changed in migration terms: <code>change</code> gains
+<code>current_id</code>, <code>loaded</code>, <code>title</code>, <code>dataloaded</code>, <code>fontLoaded</code>,
+<code>transitionstart</code>/<code>transitionend</code>, <code>error</code> and the constructor listener map
+all work as before; <code>markerAdded</code>/<code>markerRemoved</code> still fire on the map
+object; <code>imageready</code>, <code>markerclick</code> and <code>popupopen</code>/<code>popupclose</code> are new
+(see above).</p>
 <p>Two additions for IIIF tours: <code>await storymap.loadAnnotations()</code> fetches a
 manifest&#39;s externally referenced annotation pages and appends them as stops,
 then fires <code>annotationsloaded</code> with <code>{ stops, searchService, failed }</code>. A