@projektemacher/storymapjs 0.10.6 → 0.10.8

package/dist/docs/migration.html

@@ -36,6 +36,7 @@
                 <li><a class="button" href="./readme.html">README</a></li>
                 <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="./api/index.html">API docs</a></li>
                 <li><a class="button" href="../index.html#help">Help</a></li>
             </ul>
@@ -151,7 +152,35 @@ are rendered wider with a visible track for contrast.</li>
 </tr>
 <tr>
 <td><code>font_css: &quot;stock:&lt;name&gt;&quot;</code> (or a path)</td>
-<td>unchanged, plus the font files ship via <code>@fontsource-utils/scss</code>; no separate font CSS link needed</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>
+</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
+constructed: no <code>ol/Map</code>, 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.</p>
+<p>This is the shape a photo essay or a transcript-led story wants, and it is the
+one the map engine&#39;s unconditional construction used to make impossible. Note
+that <code>map_type: &quot;&quot;</code> and an absent <code>map_type</code> both still mean OpenStreetMap, and
+<code>map_type: null</code> 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 (<code>getBaseLayer()</code>, <code>getMarkers()</code>, …) return
+their neutral values, and the map setters are no-ops.</p>
+<table>
+<thead>
+<tr>
+<th>Old</th>
+<th>New</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>a text-only story with a dummy <code>map_type</code></td>
+<td><code>map_type: &quot;none&quot;</code></td>
+</tr>
+<tr>
+<td><code>map_type: null</code> (crashed the constructor)</td>
+<td>normalised to the default, <code>&quot;&quot;</code> → OSM</td>
 </tr>
 </tbody></table>
 <h2>Removed globals and exports</h2>
@@ -197,7 +226,7 @@ are rendered wider with a visible track for contrast.</li>
 </thead>
 <tbody><tr>
 <td><code>vine</code> media type (service shut down)</td>
-<td>vine URLs fall back to the <code>website</code> iframe — use another media source for those slides</td>
+<td>vine URLs fall back to the <code>website</code> iframe — or paste the provider&#39;s <code>&lt;iframe&gt;</code> snippet into the slide text (sanitized, https-only); use another media source for those slides</td>
 </tr>
 <tr>
 <td>Juxtapose <code>frame/?uid=</code> embed URLs</td>
@@ -207,7 +236,25 @@ are rendered wider with a visible track for contrast.</li>
 <td>Twitter <code>@nickname</code> rendering</td>
 <td>tweets from <code>x.com</code> URLs are now parsed too (fixes <code>@undefined</code> nicknames); no migration needed</td>
 </tr>
+<tr>
+<td>Ricoh360/theta360 embeds (#391)</td>
+<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>
+<pre><code class="language-html">&lt;p&gt;Extra footage:&lt;/p&gt;
+&lt;iframe
+    src=&quot;https://example.com/embed/123&quot;
+    width=&quot;560&quot;
+    height=&quot;315&quot;
+    frameborder=&quot;0&quot;
+    allowfullscreen
+&gt;&lt;/iframe&gt;
+</code></pre>
 <p><code>map_type: &quot;zoomify&quot;</code> is supported again (legacy): the image pyramid renders
 via the storymap data&#39;s <code>zoomify</code> options (<code>path</code>, <code>width</code>, <code>height</code>), using a
 JS warning instead of the previous removal error. Cropped edge/remainder tiles
@@ -219,29 +266,284 @@ storymap JSON sources.</p>
 <h2>Map engine: Leaflet → OpenLayers</h2>
 <ul>
 <li><code>storymap.map</code> now exposes the <strong>OpenLayers <code>Map</code></strong> instance instead of a
-Leaflet map. Port any direct Leaflet calls (e.g. <code>setView</code>, <code>flyTo</code>) to the
-OpenLayers API (<code>getView().animate(...)</code>, ...).</li>
+Leaflet map. Port any direct Leaflet calls to the OpenLayers API (table
+below). It is <code>null</code> until the map has been built.</li>
 <li>Markers are DOM overlays (<code>.vco-mapmarker</code> / <code>.vco-mapmarker-active</code>) like
 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>
 </ul>
+<h3>Direct Leaflet calls → OpenLayers</h3>
+<p>Both maps are reachable from the same place (<code>storymap.map</code>), so only the
+call syntax changes:</p>
+<table>
+<thead>
+<tr>
+<th>Leaflet</th>
+<th>OpenLayers</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>map.getCenter()</code></td>
+<td><code>map.getView().getCenter()</code> — panel-shifted, see below</td>
+</tr>
+<tr>
+<td><code>map.getZoom()</code></td>
+<td><code>map.getView().getZoom()</code></td>
+</tr>
+<tr>
+<td><code>map.setView(c, z)</code> / <code>map.fitBounds(b)</code></td>
+<td><code>map.getView().fit(extent, { size: map.getSize() })</code></td>
+</tr>
+<tr>
+<td><code>map.panTo(c)</code> / <code>map.flyTo(c, z)</code></td>
+<td><code>map.getView().animate({ center: c, duration: 300 })</code></td>
+</tr>
+<tr>
+<td><code>map.setZoom(z)</code></td>
+<td><code>map.getView().setZoom(z)</code> (or <code>.animate({ zoom: z })</code>)</td>
+</tr>
+<tr>
+<td><code>map.getSize()</code> / <code>map.getBounds()</code></td>
+<td><code>map.getSize()</code> / <code>map.getView().calculateExtent(map.getSize())</code></td>
+</tr>
+<tr>
+<td><code>map.on(&quot;moveend&quot;, fn)</code></td>
+<td><code>map.on(&quot;moveend&quot;, fn)</code> (same event names; <code>movestart</code>/<code>move</code> also exist)</td>
+</tr>
+<tr>
+<td><code>L.tileLayer(url, opts).addTo(map)</code></td>
+<td><code>new TileLayer({ source: new XYZ({ url, attributions }) }).setMap(map)</code></td>
+</tr>
+<tr>
+<td><code>L.control.attribution</code> / <code>L.control.zoom</code></td>
+<td>OL <code>Attribution</code> / <code>Zoom</code> controls (pass them via <code>map_options.controls</code>)</td>
+</tr>
+<tr>
+<td><code>map.getPane(&quot;overlayPane&quot;)</code></td>
+<td><code>map.getOverlayContainer()</code> (markers are DOM siblings, not OL features)</td>
+</tr>
+<tr>
+<td><code>map.invalidateSize()</code></td>
+<td><code>map.updateSize()</code></td>
+</tr>
+<tr>
+<td><code>map.remove()</code></td>
+<td><code>map.setTarget(undefined); map.dispose();</code> (or <code>storymap.dispose()</code>)</td>
+</tr>
+</tbody></table>
+<p>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
+<code>getView().getCenter()</code> does <strong>not</strong> equal the current slide&#39;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 <code>_getMapCenter(offset)</code> parameter promised that correction and
+never applied it, so it was removed rather than left to mislead.
+| <code>map.options.crs</code> / <code>map.getPixelOrigin()</code> | <code>map.getView().getProjection()</code> / <code>map.getPixelFromCoordinate(coord)</code> |</p>
+<p>Marker positions are still DOM elements, so <code>marker.getLatLng()</code> has no
+equivalent — read the slide data (<code>storymap.data.stlides[n].location</code>) or use
+<code>storymap._map.getMarker(n).latLon()</code>.</p>
+<h3>Map and marker methods</h3>
+<p>The map/marker methods of the original viewer are still there with the same
+names and behaviour (<code>storymap._map.&lt;method&gt;()</code>, <code>marker.&lt;method&gt;()</code>); the OL
+engine implements them as thin wrappers over <code>storymap.map</code>. Two methods are
+deprecated no-ops and one is gone:</p>
+<table>
+<thead>
+<tr>
+<th>Original method</th>
+<th>Status</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>updateDisplay</code>, <code>goTo</code>, <code>panTo</code>, <code>zoomTo</code>, <code>viewTo</code></td>
+<td>unchanged</td>
+</tr>
+<tr>
+<td><code>getBoundsZoom</code>, <code>markerOverview</code>, <code>calculateMarkerZooms</code></td>
+<td>unchanged (<code>getBoundsZoom()</code> now returns <code>number | undefined</code> instead of a falsy value)</td>
+</tr>
+<tr>
+<td><code>createMiniMap</code>, <code>createMarkers</code>, <code>createMarker</code></td>
+<td>unchanged</td>
+</tr>
+<tr>
+<td><code>setMapOffset</code>, <code>calculateMinMaxZoom</code>, <code>updateMinMaxZoom</code>, <code>initialMapLocation</code></td>
+<td>unchanged</td>
+</tr>
+<tr>
+<td><code>show()</code> / <code>hide()</code> (map and marker)</td>
+<td><strong>deprecated no-ops</strong> — they were already empty in the original viewer. Style <code>.vco-mapmarker</code> or use <code>marker.active(false)</code></td>
+</tr>
+<tr>
+<td><code>map.addTo(container)</code> / <code>map.removeFrom(container)</code></td>
+<td>unchanged — inherited from the <code>DomMixed</code> mixin: append/remove the map container and fire <code>added</code>/<code>removed</code>. The engine override re-targets and re-measures the OpenLayers viewport, so a move into a differently sized parent works</td>
+</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>
+</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>
+</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
+<code>.vco-mapmarker</code> element and your own DOM/CSS.</p>
+<h2>Reaching the map, layers and markers</h2>
+<p><code>storymap.map</code> is the raw <code>ol/Map</code> (typed as <code>OlMap | null</code> — 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 <code>storymap</code> (and on
+<code>storymap._map</code> for the engine methods):</p>
+<table>
+<thead>
+<tr>
+<th>Accessor</th>
+<th>Returns</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>getBaseLayer()</code></td>
+<td>the base tile/vector layer</td>
+</tr>
+<tr>
+<td><code>getOverlayLayers()</code> / <code>getOverlayLayer(i)</code></td>
+<td>overlay layers / one by index (<code>null</code> if out of range)</td>
+</tr>
+<tr>
+<td><code>getOverlayCount()</code></td>
+<td>number of overlays</td>
+</tr>
+<tr>
+<td><code>setOverlayVisible(i, on)</code> / <code>setOverlayOpacity(i, opacity)</code></td>
+<td>show/hide and fade one overlay</td>
+</tr>
+<tr>
+<td><code>getMinimap()</code></td>
+<td>the <code>OverviewMap</code> control, or its inner map via <code>getOverviewMap()</code></td>
+</tr>
+<tr>
+<td><code>getLine()</code> / <code>getLineActive()</code></td>
+<td>the full and the travelled route <code>VectorLayer</code></td>
+</tr>
+<tr>
+<td><code>getMarker(n)</code> / <code>getMarkers()</code></td>
+<td>one marker or all of them, in slide order</td>
+</tr>
+<tr>
+<td><code>setExtraAttributions(html)</code></td>
+<td>extra attribution HTML, listed after the source credits</td>
+</tr>
+<tr>
+<td><code>isImageSpace()</code></td>
+<td>whether the map is a IIIF image in image space (see below)</td>
+</tr>
+</tbody></table>
+<p><code>tile_source_factory</code> may return a full <code>ol/layer/Layer</code> (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&#39;
+<code>WarpedMapLayer</code>) passes through untouched; source reads go through a
+capability check, so it simply skips the tile-grid fits.</p>
+<p>The viewer reserves three z-index ranges and custom layers should stay out
+of them: <strong>0</strong> for the base tiles, <strong>1..n</strong> for the stacked <code>overlays[]</code>
+entries in order, and <strong>10/11</strong> 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.</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
+fitted to the image extent and marker locations are pixel offsets into the
+image rather than lat/lon. Ask <code>storymap.isImageSpace()</code> instead of testing
+<code>map_type</code> — georeferenced IIIF (a manifest with <code>navPlace</code> regions) is an
+ordinary mercator map, and <code>map_bbox</code> with a georeferenced layer is one too.</p>
+<h3>Knowing when the imagery is there</h3>
+<p>Tile and image sources attach asynchronously, so <code>loaded</code> can fire before the
+imagery exists. Listen for <code>imageready</code>, which fires once a source is ready and
+carries <code>{ source, kind, layer }</code> (<code>kind</code> is <code>&quot;iiif&quot;</code>, <code>&quot;zoomify&quot;</code> or
+<code>&quot;tiles&quot;</code>); it is re-fired on the <code>storymap</code> as well:</p>
+<pre><code class="language-js">storymap.on(&quot;imageready&quot;, ({ kind, source }) =&gt; {
+    console.log(&quot;imagery ready&quot;, kind, source);
+});
+</code></pre>
+<h3>Tearing a storymap down</h3>
+<p>Call <code>storymap.dispose()</code> when the embedding view goes away (SPA route change,
+dialog close). It clears the timers and the resize observer, removes the
+<code>window</code>/<code>document</code> listeners, cancels running slide animations, disposes the
+slider and the OpenLayers map, and sets <code>storymap.map</code> to <code>null</code>. Calling it
+twice is safe; the instance is unusable afterwards.</p>
+<h2>Custom map providers</h2>
+<p>Any slippy-map tile URL works as <code>map_type</code> — pass the template verbatim
+(including <code>{z}/{x}/{y}</code>), relative or absolute:</p>
+<pre><code class="language-js">new StoryMap(&quot;embed&quot;, data, {
+    map_type: &quot;https://tiles.example.org/base/{z}/{x}/{y}.png&quot;,
+});
+</code></pre>
+<p>Mapbox style JSON URLs render as vector tile layers; OpenLayers
+<code>Map</code>/<code>View</code> pass-through stays available via <code>options.map_options</code>
+(<code>controls</code> replaces the defaults, <code>interactions</code> are added to the
+viewer&#39;s own pan/zoom set, <code>view</code> merges over the computed default).</p>
+<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>
+<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;
+        map_type.startsWith(&quot;wms:&quot;)
+            ? new TileLayer({
+                  source: new TileWMS({
+                      url: &quot;https://geoserver.example.org/wms&quot;,
+                      params: { LAYERS: map_type.slice(4) },
+                      crossOrigin: &quot;anonymous&quot;,
+                  }),
+              })
+            : createDefault(),
+});
+</code></pre>
+<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
+runtime-only (functions cannot ride storymap JSON) and also applies to
+<code>overlays[]</code> entries, whose <code>map_type</code> values go through the same
+factory.</p>
 <h2>Data and tooling</h2>
 <ul>
 <li>Storymap JSON is now validated against a JSON Schema
 (<code>schema/storymap.schema.json</code>); invalid documents are reported to the
 console at load time.</li>
-<li>IIIF Presentation 3 manifests are accepted directly as storymap sources.</li>
-<li>The StoryMap IIIF extension context changed to
-<code>https://christianmahnke.de/iiif/storymap</code> — manifests produced with the old
-<code>https://example.org/ns/storymap/v1</code> context need re-converting
-(<code>scripts/convert-to-iiif.mjs</code>).</li>
+<li>IIIF Presentation 3 manifests are accepted directly as storymap sources.
+The map settings map onto <code>storymap:</code> 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: <code>navPlace</code>
+Points for slide locations, a <code>navPlace</code> Polygon for the story extent
+(<code>map_bbox</code>), an IIIF Image API Selector for <code>location.region</code>, and the
+Georeference Extension for placed rasters. A georeferenced layer is
+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>
 </ul>
-<h2>Events (unchanged)</h2>
-<p><code>change</code> (with <code>current_slide</code>), <code>loaded</code>, <code>title</code>, <code>dataloaded</code>,
-<code>fontLoaded</code>, plus the listener map in the constructor — all work as before.</p>
+<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>
+<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
+slide&#39;s stable identity is available as <code>storymap.getSlideId(index)</code>, which
+is what the <code>#slide-N</code> hash and the <code>iiif-content</code> deep link resolve
+through.</p>
 
         </main>
         

package/dist/docs/readme.html

@@ -36,6 +36,7 @@
                 <li><a class="button" href="./readme.html">README</a></li>
                 <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="./api/index.html">API docs</a></li>
                 <li><a class="button" href="../index.html#help">Help</a></li>
             </ul>
@@ -54,7 +55,9 @@ affiliated with, or supported by Northwestern University Knight Lab.</p>
 files (or IIIF Presentation manifests) with TypeScript + Vite + OpenLayers.
 There is no authoring tool — create your storymap JSON by hand or with your
 own code, and see <code>docs/</code> for the migration notes from the original
-Knight Lab release.</p>
+Knight Lab release. The library also exports <code>storymapToManifest()</code>, which
+produces a IIIF manifest from a storymap document (<code>npm run convert:iiif</code>
+does the same from the command line; see <code>docs/storymap-as-iiif-manifest.md</code>).</p>
 <h2>Development</h2>
 <p>See docs/DEVELOPMENT.md to get setup for local development of StoryMapJS. This
 repository is the viewer library only (TypeScript + Vite + OpenLayers);
@@ -74,6 +77,13 @@ value of the storymap&#39;s <code>language</code> option must match the file nam
 <h2>Map Options</h2>
 <p>To disable connecting lines on maps set <code>map_as_image: true</code> in the storymap
 options (the default <code>false</code> renders cartography).</p>
+<p><code>storymap.map</code> is the raw OpenLayers map, typed with the re-exported <code>ol</code>
+types, and <code>getBaseLayer()</code>, <code>getOverlayLayers()</code>, <code>getMinimap()</code>,
+<code>getMarkers()</code> and friends hand out the layers the viewer built. Listen for
+<code>imageready</code> to run code against the real imagery, and call
+<code>storymap.dispose()</code> when the embedding view goes away — see
+<a href="./migration.html#reaching-the-map-layers-and-markers">docs/migration-from-knightlab.md</a>
+for the full surface.</p>
 <p>The menubar buttons can be disabled individually:</p>
 <pre><code>show_overview:       false,   // map overview button
 show_back_to_start:  false,   // back to the beginning button
@@ -115,7 +125,8 @@ map_type: &quot;https://tiles.openfreemap.org/styles/bright&quot;,  // vector st
 </code></pre>
 <p>Any value containing <code>{z}</code> renders as a raster XYZ layer; a path without <code>{z}</code>
 that looks like a URL/path renders as a vector style layer; anything else falls
-back to classic OSM raster.</p>
+back to classic OSM raster — except <code>&quot;none&quot;</code>, which builds no map at all and
+runs the story as text and media only.</p>
 <h3>Switching the basemap at runtime</h3>
 <p><code>storymap.setMapOption(&quot;map_type&quot;, next)</code> / <code>setMapOptions({...})</code> rebuilds the
 main tile layer <strong>and</strong> the minimap (<code>ol/control/OverviewMap</code>) layer, keeping
@@ -138,23 +149,43 @@ images, lists, emphasis and spans in your slides, e.g.:</p>
 }
 </code></pre>
 <p>The <code>vco-note</code> span renders as a small grey note, like the built-in credits.</p>
-<p><strong>Caution:</strong> the text is rendered raw — it is not sanitized. Only load
-storymaps from sources you trust.</p>
+<p><strong>Caution:</strong> the text is sanitized, but sanitizing is a mitigation rather
+than a guarantee. Prose and media formatting survive (<code>class</code>, <code>alt</code>, <code>width</code>,
+table attributes, and so on), scripts and other executable tags are dropped
+with their contents, event-handler attributes are stripped, every URL
+attribute is checked to be <code>http(s)</code>, and <code>&lt;iframe&gt;</code> embeds are rebuilt into
+a sandboxed, <code>no-referrer</code> element. <code>style</code>, <code>id</code> and <code>name</code> are <em>not</em> allowed,
+and a link&#39;s <code>target</code> is always forced to <code>_blank</code>. The same sanitizer covers
+media credit, media caption, the navigation headline and the map attribution
+line. Still: only load storymaps from sources you trust.</p>
 <h2>GDPR consent for external services</h2>
 <p>Set the <code>consent_required</code> option to <code>true</code> to ask for permission before
 anything is loaded from external services (media embeds such as YouTube,
-Twitter or SoundCloud, map tiles, and external font CSS):</p>
+Twitter or SoundCloud, slide narration audio, map tiles, and external font
+CSS):</p>
 <pre><code>{
     &quot;consent_required&quot;: true,
     ...
 }
 </code></pre>
 <p>Each service asks with an Allow/Deny panel; answering one panel resolves every
-pending panel of the same service. If a decision was already stored in the
-cookie, the panel is skipped entirely. Denied services show a placeholder
+pending panel of the same service. Denied services show a placeholder
 instead of the media, and the map renders without tiles until they are
-allowed. Decisions are stored in a cookie (<code>storymapjs-consent</code>) for 90
-days — clearing cookies asks again.</p>
+allowed.</p>
+<p>Before the story loads, one dialog lists every external service it uses (map
+tiles, media services including slide narration, external fonts) with three
+choices: <strong>Allow all</strong>, <strong>Decline all</strong>, or a decision per service. A story
+with no map (<code>map_type: &quot;none&quot;</code>) has no tile row to answer. The dialog is
+skipped once every service has a stored decision; per-service panels still
+appear for services discovered later (e.g. a preloaded slide).</p>
+<p>Decisions are stored in <code>localStorage</code> under <code>storymapjs-consent</code> and have no
+expiry — clearing site data asks again.</p>
+<p>The consent labels are <strong>not</strong> fully translated. <code>src/language/locale/en.json</code>
+defines every string; 28 bundled locales fall back to English for the keys
+they lack — most are missing one, a handful are missing around ten (the
+per-service consent prompts and the fullscreen button labels). Run
+<code>npm run check:locales</code> to see the current state — it reports the gap per
+locale and is expected to be runnable without failing.</p>
 <h2>Troubleshooting</h2>
 <p>If a storymap fails to render, open the browser console: the viewer logs
 fetch and validation errors (e.g. &quot;could not load storymap data from ...&quot;).

package/dist/embed/index.html

@@ -7,7 +7,7 @@
   <meta name="apple-mobile-web-app-capable" content="yes">
   <meta name="mobile-web-app-capable" content="yes">
   <meta name="apple-touch-fullscreen" content="yes">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <link rel="stylesheet" href="../css/storymap.css">
   <style>
     html, body {
@@ -16,6 +16,64 @@
       padding: 0;
       margin: 0;
     }
+    #storymap-embed {
+      width: 100%;
+      height: 100%;
+    }
+    .storymap-url-prompt {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      width: 100%;
+      height: 100%;
+      padding: 20px;
+      box-sizing: border-box;
+      background-color: #fff;
+      color: #333;
+      font-family: sans-serif;
+    }
+    .storymap-url-card {
+      width: 100%;
+      max-width: 480px;
+      text-align: left;
+    }
+    .storymap-url-card h1 {
+      font-size: 1.25rem;
+      margin: 0 0 8px;
+    }
+    .storymap-url-card p {
+      margin: 0 0 12px;
+    }
+    .storymap-url-card label {
+      display: block;
+      margin-bottom: 6px;
+      font-weight: bold;
+    }
+    .storymap-url-row {
+      display: flex;
+      gap: 8px;
+    }
+    .storymap-url-card input {
+      flex: 1;
+      min-width: 0;
+      padding: 8px 10px;
+      font-size: 1rem;
+      border: 1px solid #999;
+      border-radius: 4px;
+    }
+    .storymap-url-card button {
+      padding: 8px 16px;
+      font-size: 1rem;
+      border: 1px solid #333;
+      border-radius: 4px;
+      background-color: #333;
+      color: #fff;
+      cursor: pointer;
+    }
+    .storymap-url-error {
+      margin-top: 8px;
+      color: #a00;
+    }
   </style>
 </head>
 
@@ -39,6 +97,12 @@
     const getStartSlide = () =>
         urlParams.has("start_at_slide") ? parseInt(urlParams.get("start_at_slide"), 10) : 0;
 
+    // slide duration in milliseconds; missing or invalid values disable autoplay
+    const getAutoplay = () => {
+        const value = parseInt(urlParams.get("autoplay"), 10);
+        return Number.isFinite(value) && value > 0 ? value : 0;
+    };
+
     const onStoryMapTitle = (e) => {
         document.title = "StoryMapJS: " + e.title;
     };
@@ -47,7 +111,7 @@
         if (!data || !data.storymap) {
             return;
         }
-        const options = { start_at_slide: getStartSlide() };
+        const options = { start_at_slide: getStartSlide(), autoplay: getAutoplay() };
         // font theme loading is handled by the library (data.font_css / stock:default)
         storymap = new StoryMap("storymap-embed", data, options, {
             title: onStoryMapTitle,
@@ -71,10 +135,71 @@
         document.getElementById("storymap-embed").append(el);
     };
 
+    const showUrlPrompt = (message) => {
+        const container = document.getElementById("storymap-embed");
+        container.innerHTML = "";
+        const el = document.createElement("div");
+        el.className = "storymap-url-prompt";
+        const card = document.createElement("div");
+        card.className = "storymap-url-card";
+        const heading = document.createElement("h1");
+        heading.textContent = "Open a StoryMap";
+        const hint = document.createElement("p");
+        hint.textContent =
+            message || "Enter the URL of a storymap.json file to view it here.";
+        const form = document.createElement("form");
+        form.id = "storymap-url-form";
+        const label = document.createElement("label");
+        label.setAttribute("for", "storymap-url-input");
+        label.textContent = "Storymap JSON URL";
+        const row = document.createElement("div");
+        row.className = "storymap-url-row";
+        const input = document.createElement("input");
+        input.id = "storymap-url-input";
+        input.name = "url";
+        // type="text" (not "url") so relative storymap paths like
+        // "examples/katrina.json" pass native form validation; validity is
+        // checked via new URL(value, siteRoot) on submit instead.
+        input.type = "text";
+        input.inputMode = "url";
+        input.required = true;
+        input.placeholder = "https://example.com/storymap.json";
+        input.autocomplete = "off";
+        input.spellcheck = false;
+        const button = document.createElement("button");
+        button.type = "submit";
+        button.textContent = "Open storymap";
+        const error = document.createElement("p");
+        error.id = "storymap-url-error";
+        error.className = "storymap-url-error";
+        error.hidden = true;
+        row.append(input, button);
+        form.append(label, row, error);
+        card.append(heading, hint, form);
+        el.append(card);
+        container.append(el);
+        form.addEventListener("submit", (e) => {
+            e.preventDefault();
+            const value = input.value.trim();
+            if (!value) {
+                return;
+            }
+            try {
+                // validate + resolve like the viewer fetch below (supports
+                // relative, root-relative and absolute URLs)
+                new URL(value, siteRoot);
+            } catch {
+                error.textContent = "Please enter a valid URL to a storymap.json file.";
+                error.hidden = false;
+                return;
+            }
+            urlParams.set("url", value);
+            window.location.search = urlParams.toString();
+        });
+    };
+
     if (!urlParam) {
-        showEmbedError(
-            "No storymap url given. Append ?url=<storymap.json> to the embed url.",
-        );
+        showUrlPrompt();
     } else {
         fetch(new URL(urlParam, siteRoot).href)
             .then((response) => {