@projektemacher/storymapjs 0.10.7 → 0.10.8

package/dist/docs/iiif.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,15 +55,50 @@ the fixtures in <a href="../examples/"><code>public/examples/</code></a> are rea
 <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>
 <h2>Contexts</h2>
-<p>A manifest carries three context URLs: the Presentation 3.0 context, the
-official <a href="https://iiif.io/api/extension/navplace/">navPlace extension</a> context,
-and the StoryMap extension context:</p>
+<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
+§3.1 of the extension requires before Presentation 3), the Presentation 3.0
+context, the navPlace properties context, and the StoryMap extension context.
+The last of the four resolves to the document below — shown inline here for
+reference; a manifest must reference it by URL, not paste it in (see the
+<code>@context</code> rule under &quot;Validator interop&quot;):</p>
 <pre><code class="language-json">{
-    &quot;@context&quot;: [
-        &quot;http://iiif.io/api/presentation/3/context.json&quot;,
-        &quot;http://iiif.io/api/extension/navplace/context.json&quot;,
-        &quot;https://cmahnke.github.io/StoryMapJS/context.json&quot;
-    ]
+    &quot;@context&quot;: {
+        &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;,
+        &quot;mapCenterOffset&quot;: &quot;storymap:mapCenterOffset&quot;,
+        &quot;fontCss&quot;: &quot;storymap:fontCss&quot;,
+        &quot;callToAction&quot;: &quot;storymap:callToAction&quot;,
+        &quot;callToActionText&quot;: &quot;storymap:callToActionText&quot;,
+        &quot;startAtSlide&quot;: &quot;storymap:startAtSlide&quot;,
+        &quot;language&quot;: &quot;storymap:language&quot;,
+        &quot;calculateZoom&quot;: &quot;storymap:calculateZoom&quot;,
+        &quot;lineFollowsPath&quot;: &quot;storymap:lineFollowsPath&quot;,
+        &quot;showLines&quot;: &quot;storymap:showLines&quot;,
+        &quot;showHistoryLine&quot;: &quot;storymap:showHistoryLine&quot;,
+        &quot;lineColor&quot;: &quot;storymap:lineColor&quot;,
+        &quot;lineColorInactive&quot;: &quot;storymap:lineColorInactive&quot;,
+        &quot;lineWeight&quot;: &quot;storymap:lineWeight&quot;,
+        &quot;lineOpacity&quot;: &quot;storymap:lineOpacity&quot;,
+        &quot;lineDash&quot;: &quot;storymap:lineDash&quot;,
+        &quot;lineJoin&quot;: &quot;storymap:lineJoin&quot;,
+        &quot;useCustomMarkers&quot;: &quot;storymap:useCustomMarkers&quot;,
+        &quot;mapArea&quot;: &quot;storymap:mapArea&quot;,
+        &quot;overviewExtent&quot;: &quot;storymap:overviewExtent&quot;,
+        &quot;keyboard&quot;: &quot;storymap:keyboard&quot;,
+        &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;
+    }
 }
 </code></pre>
 <h3>navPlace context (official)</h3>
@@ -89,20 +125,18 @@ 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;mapType&quot;: &quot;storymap:mapType&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;,
         &quot;mapBackgroundColor&quot;: &quot;storymap:mapBackgroundColor&quot;,
         &quot;mapCenterOffset&quot;: &quot;storymap:mapCenterOffset&quot;,
-        &quot;mapSubdomains&quot;: &quot;storymap:mapSubdomains&quot;,
-        &quot;iiifUrl&quot;: { &quot;@id&quot;: &quot;storymap:iiifUrl&quot;, &quot;@type&quot;: &quot;@id&quot; },
         &quot;fontCss&quot;: &quot;storymap:fontCss&quot;,
         &quot;callToAction&quot;: &quot;storymap:callToAction&quot;,
         &quot;callToActionText&quot;: &quot;storymap:callToActionText&quot;,
         &quot;startAtSlide&quot;: &quot;storymap:startAtSlide&quot;,
         &quot;language&quot;: &quot;storymap:language&quot;,
         &quot;calculateZoom&quot;: &quot;storymap:calculateZoom&quot;,
-        &quot;lessBounce&quot;: &quot;storymap:lessBounce&quot;,
         &quot;lineFollowsPath&quot;: &quot;storymap:lineFollowsPath&quot;,
         &quot;showLines&quot;: &quot;storymap:showLines&quot;,
         &quot;showHistoryLine&quot;: &quot;storymap:showHistoryLine&quot;,
@@ -113,11 +147,13 @@ what the fixtures reference. Content:</p>
         &quot;lineDash&quot;: &quot;storymap:lineDash&quot;,
         &quot;lineJoin&quot;: &quot;storymap:lineJoin&quot;,
         &quot;useCustomMarkers&quot;: &quot;storymap:useCustomMarkers&quot;,
+        &quot;mapArea&quot;: &quot;storymap:mapArea&quot;,
+        &quot;overviewExtent&quot;: &quot;storymap:overviewExtent&quot;,
+        &quot;keyboard&quot;: &quot;storymap:keyboard&quot;,
+        &quot;overlays&quot;: &quot;storymap:overlays&quot;,
         &quot;type&quot;: { &quot;@id&quot;: &quot;storymap:type&quot;, &quot;@type&quot;: &quot;@id&quot; },
-        &quot;background&quot;: &quot;storymap:background&quot;,
-        &quot;mediaCaption&quot;: &quot;storymap:mediaCaption&quot;,
-        &quot;mediaCredit&quot;: &quot;storymap:mediaCredit&quot;,
-        &quot;date&quot;: &quot;storymap:date&quot;
+        &quot;mediaSrcset&quot;: &quot;storymap:mediaSrcset&quot;,
+        &quot;mediaSizes&quot;: &quot;storymap:mediaSizes&quot;
     }
 }
 </code></pre>
@@ -217,7 +253,7 @@ what the fixtures reference. Content:</p>
 <tr>
 <td><code>items</code></td>
 <td><code>slide.media</code></td>
-<td>AnnotationPage with the painting annotation, see below</td>
+<td>AnnotationPage with the painting annotation, see below — which also carries the caption, credit and alt text</td>
 </tr>
 <tr>
 <td><code>storymap:type</code></td>
@@ -225,24 +261,29 @@ what the fixtures reference. Content:</p>
 <td><code>&quot;overview&quot;</code> marks the map overview slide</td>
 </tr>
 <tr>
-<td><code>storymap:background</code></td>
+<td><code>background</code></td>
 <td><code>slide.background</code></td>
-<td><code>{url, color}</code> — only present keys</td>
+<td>A painting annotation whose body is an <code>Image</code> (the url) and/or a <code>Color</code> (the colour)</td>
 </tr>
 <tr>
-<td><code>storymap:mediaCaption</code></td>
-<td><code>slide.media.caption</code></td>
-<td></td>
+<td><code>storymap:mediaSrcset</code></td>
+<td><code>slide.media.srcset</code></td>
+<td>Responsive image candidates, passed through to the <code>img</code> element</td>
 </tr>
 <tr>
-<td><code>storymap:mediaCredit</code></td>
-<td><code>slide.media.credit</code></td>
-<td></td>
+<td><code>storymap:mediaSizes</code></td>
+<td><code>slide.media.sizes</code></td>
+<td>The <code>sizes</code> companion of <code>mediaSrcset</code></td>
 </tr>
 <tr>
-<td><code>storymap:date</code></td>
+<td><em>(target selector)</em></td>
+<td><code>slide.location.region</code></td>
+<td><code>ImageApiSelector</code> <code>xywh=pixel:x,y,w,h</code>; image stops on image-map slides</td>
+</tr>
+<tr>
+<td><code>navDate</code></td>
 <td><code>slide.date</code></td>
-<td>String or object, verbatim</td>
+<td>Plain string, verbatim; the official validator applies no format rule at all, so a human date is fine</td>
 </tr>
 <tr>
 <td><code>navPlace</code></td>
@@ -260,11 +301,42 @@ 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>zoom</code>, <code>line</code>, <code>icon</code>, <code>iconSize</code>, <code>image</code>,
-<code>use_custom_marker</code>, <code>name</code> (only present keys).</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>location.use_custom_marker</code> / <code>use_custom_markers</code> (manifest) opt into
 custom marker rendering; see the storymap terms below.</li>
 </ul>
+<p>Those properties are described by <strong><code>https://cmahnke.github.io/StoryMapJS/navplace-properties.json</code></strong>,
+which a manifest using a <code>properties</code> bag should name in its <code>@context</code>. The
+extension requires it (§3.2): terms in a GeoJSON Feature&#39;s <code>properties</code> must be
+described either by a registered IIIF extension or by a local linked-data
+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
+(<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
+context — §3.1 of the extension:</p>
+<blockquote>
+<p>The navPlace extension linked data context must be included before the IIIF
+Presentation API 3 linked data context on the top-level object.</p>
+</blockquote>
+<p>So a manifest that uses <code>navPlace</code> declares:</p>
+<pre><code class="language-json">&quot;@context&quot;: [
+    &quot;http://iiif.io/api/extension/navplace/context.json&quot;,
+    &quot;http://iiif.io/api/presentation/3/context.json&quot;,
+    &quot;https://cmahnke.github.io/StoryMapJS/navplace-properties.json&quot;,
+    &quot;https://cmahnke.github.io/StoryMapJS/context.json&quot;
+]
+</code></pre>
+<p>Getting this backwards does not break a viewer — the reader does not consult
+either context — but it does make the document wrong as linked data, which is
+the point of shipping a context at all. Every fixture in this repository had it
+backwards.</p>
 <p>Alternatively a manifest MAY aggregate all slide locations in a single
 manifest-level <code>navPlace</code> with one Feature per Canvas in <code>items</code> order.</p>
 <h2>Slide media</h2>
@@ -310,7 +382,7 @@ actual image dimensions. Two body variants are valid:</p>
 }
 </code></pre>
 <p>The converter emits variant (b). Legacy <code>zoomify</code> storymaps are converted to
-<code>storymap:mapType: &quot;iiif&quot;</code>; since the original zoomify tile paths are dead, the
+<code>storymap:basemap: &quot;iiif&quot;</code>; since the original zoomify tile paths are dead, the
 converter substitutes the IIIF reference image above (the legacy pyramid
 definition is not carried — nothing reads it).</p>
 <h2>StoryMap-specific terms</h2>
@@ -326,12 +398,76 @@ properties):</p>
         {
             &quot;id&quot;: &quot;https://example.org/storymap/&lt;name&gt;/map-config&quot;,
             &quot;type&quot;: &quot;Service&quot;,
-            &quot;profile&quot;: &quot;https://christianmahnke.de/iiif/storymap/mapconfig&quot;,
-            &quot;storymap:mapType&quot;: &quot;osm:standard&quot;
+            &quot;profile&quot;: &quot;https://cmahnke.github.io/StoryMapJS/context.json/mapconfig&quot;,
+            &quot;storymap:basemap&quot;: &quot;osm:standard&quot;
+        }
+    ]
+}
+</code></pre>
+<h3>TileJSON for a tile service</h3>
+<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
+<code>tiles</code> is required:</p>
+<pre><code class="language-json">{
+    &quot;service&quot;: [
+        {
+            &quot;id&quot;: &quot;https://example.org/storymap/&lt;name&gt;/map-config&quot;,
+            &quot;type&quot;: &quot;Service&quot;,
+            &quot;profile&quot;: &quot;https://cmahnke.github.io/StoryMapJS/context.json/mapconfig&quot;,
+            &quot;tilejson&quot;: {
+                &quot;tiles&quot;: [&quot;https://tiles.example.org/{z}/{x}/{y}.png&quot;],
+                &quot;minzoom&quot;: 4,
+                &quot;maxzoom&quot;: 17,
+                &quot;bounds&quot;: [-122.7, 37.1, -121.1, 38.1],
+                &quot;scheme&quot;: &quot;tms&quot;,
+                &quot;center&quot;: [4.4777, 51.9244, 12]
+            }
+            // `tiles` may also be a single template string — that is what the
+            // converter writes. The reader accepts both forms.
         }
     ]
 }
 </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>
+<table>
+<thead>
+<tr>
+<th>Member</th>
+<th>Effect</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>tiles</code></td>
+<td>the tile URL template, as <code>map_type</code></td>
+</tr>
+<tr>
+<td><code>minzoom</code></td>
+<td>the view&#39;s minimum zoom, and the tile grid&#39;s range</td>
+</tr>
+<tr>
+<td><code>maxzoom</code></td>
+<td>the view&#39;s maximum zoom, and the tile grid&#39;s range</td>
+</tr>
+<tr>
+<td><code>bounds</code></td>
+<td>a <code>[west, south, east, north]</code> lon/lat box the view center is kept inside</td>
+</tr>
+<tr>
+<td><code>scheme</code></td>
+<td><code>tms</code> flips the tile row, which is counted from the bottom in TMS</td>
+</tr>
+<tr>
+<td><code>center</code></td>
+<td><code>[lon, lat, zoom]</code>, the initial view</td>
+</tr>
+</tbody></table>
+<p>The <code>center</code> is the initial view only, and <code>bounds</code> constrains the center
+without pinning the resolution — a hard extent constraint would fight the panel
+offset, the same reason <code>map_bbox</code> works the way it does.</p>
 <table>
 <thead>
 <tr>
@@ -341,9 +477,14 @@ properties):</p>
 </tr>
 </thead>
 <tbody><tr>
-<td><code>mapType</code></td>
+<td><code>basemap</code></td>
 <td><code>map_type</code></td>
-<td><code>osm:standard</code>, <code>mapbox:...</code>, <code>stadia:...</code>, <code>iiif</code>, or an <code>https://...</code> tile URL; <code>zoomify</code> is replaced by <code>iiif</code></td>
+<td>A keyword the viewer configures itself: <code>osm:standard</code>, <code>mapbox://styles/...</code>, <code>stadia:...</code>, <code>iiif</code>. <code>zoomify</code> is replaced by <code>iiif</code></td>
+</tr>
+<tr>
+<td><em>(unprefixed)</em> <code>tilejson</code></td>
+<td><code>map_type</code> + <code>tilejson</code></td>
+<td>TileJSON 2.1 for an arbitrary tile service — see below</td>
 </tr>
 <tr>
 <td><code>mapAsImage</code></td>
@@ -371,9 +512,9 @@ properties):</p>
 <td>Tile URL subdomains</td>
 </tr>
 <tr>
-<td><code>iiifUrl</code></td>
+<td><em>(none)</em></td>
 <td><code>iiif.url</code></td>
-<td>IIIF Image API <code>info.json</code> URL for image-map storymaps</td>
+<td>From the Image API <code>service[]</code> a painting body carries, plus <code>/info.json</code>; see below</td>
 </tr>
 <tr>
 <td><code>fontCss</code></td>
@@ -460,15 +601,362 @@ properties):</p>
 <td><code>use_custom_markers</code></td>
 <td>boolean</td>
 </tr>
+<tr>
+<td><code>mapArea</code></td>
+<td><code>map_area</code></td>
+<td><code>&quot;full&quot;</code> (default) or <code>&quot;left&quot;</code></td>
+</tr>
+<tr>
+<td><code>overviewExtent</code></td>
+<td><code>overview_extent</code></td>
+<td><code>[west, south, east, north]</code> lon/lat box for the minimap overview</td>
+</tr>
+<tr>
+<td><code>keyboard</code></td>
+<td><code>keyboard</code></td>
+<td>boolean: arrow keys navigate the story from anywhere</td>
+</tr>
+<tr>
+<td><code>overlays</code></td>
+<td><code>overlays</code></td>
+<td>array of stacked layers (see below)</td>
+</tr>
+<tr>
+<td><em>(georeferencing annotation)</em></td>
+<td><code>overlays[]</code> (georeference entries)</td>
+<td>IIIF images placed from ground control points — see &quot;Geo-referenced layers&quot;</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>, <code>storymap:background</code>,
-<code>storymap:mediaCaption</code>, <code>storymap:mediaCredit</code>, <code>storymap:date</code> (see the
-Canvas table above).</p>
+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
+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
+defines them. A manifest written against the old terms still loads — the strings
+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>
+<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
+one slide, appended after that Canvas&#39;s own slide. This is the shape Storiiies
+and Micrio use for a guided tour of one image, and it is the subject of
+<a href="./authoring.html"">docs/iiif-authoring.md</a>.</p>
+<ul>
+<li><strong>Target</strong> — <code>xywh=</code> fragment / Image API Selector, or a <code>PointSelector</code>
+(synthesized into a square of 5% of the Canvas&#39;s smaller side, centred and
+clamped). A <code>TextQuoteSelector</code>, <code>TimeState</code> or <code>SvgSelector</code> is preserved
+but not resolved or drawn. A bare string target&#39;s <code>#xywh=</code> counts. An
+annotation aimed at the whole Canvas is <strong>not</strong> a stop.</li>
+<li><strong>Body</strong> — a <code>TextualBody</code> supplies the slide text (<code>text/plain</code> escaped and
+split per blank-line block, <code>text/html</code> kept as markup); a body with an
+<code>id</code> (e.g. <code>type: &quot;Sound&quot;</code>) supplies <code>media.url</code>, whose extension picks the
+player. An annotation with a region but no body is not a stop.</li>
+<li><strong>Region stops are honoured in image mode</strong> only — the same rule as a
+<code>xywh=pixel:</code> region. A geographic map ignores them.</li>
+<li><code>navPlace</code> may not appear on an Annotation (the extension forbids it), so
+all stops on a Canvas share that Canvas&#39;s location and marker presentation.</li>
+</ul>
+<h2>What the body record carries</h2>
+<p>The painting annotation&#39;s body is read into one shared record. The
+<code>storymap:mediaCaption</code> / <code>mediaCredit</code> / <code>mediaAlt</code> extension terms are
+dropped — a manifest still using them loads, but the strings are not read —
+and the standard properties are the only source:</p>
+<table>
+<thead>
+<tr>
+<th>Body property</th>
+<th>Slide media field</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>label</code></td>
+<td><code>caption</code></td>
+</tr>
+<tr>
+<td><code>requiredStatement</code> (one <code>{label, value}</code> object) or <code>provider</code></td>
+<td><code>credit</code></td>
+</tr>
+<tr>
+<td><code>accessibilitySummary</code></td>
+<td><code>alt</code></td>
+</tr>
+<tr>
+<td><code>thumbnail</code></td>
+<td><code>thumb</code></td>
+</tr>
+<tr>
+<td><code>type</code>, <code>format</code></td>
+<td>player selection (<code>MediaType()</code>)</td>
+</tr>
+<tr>
+<td><code>duration</code>, <code>start</code>, <code>end</code></td>
+<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>
+</tr>
+</tbody></table>
+<h2>Native IIIF vs. the StoryMap extension</h2>
+<p>IIIF defines three approved Presentation API extensions — navPlace, Text
+Granularity and Georeference — and <strong>no vocabulary for a basemap or a tile
+layer stack</strong>. Everything the viewer draws under and over the story (basemap
+type, layout, minimap bounds, stacked layers, keyboard navigation) therefore
+stays in the <code>storymap:</code> terms of the map configuration service, which is the
+JSON-LD-idiomatic place for extended configuration. What IIIF <em>does</em> model
+natively is used wherever it exists:</p>
+<table>
+<thead>
+<tr>
+<th>Story</th>
+<th>Native IIIF</th>
+<th>Used here</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>Slide location</td>
+<td><code>navPlace</code> Point</td>
+<td>yes</td>
+</tr>
+<tr>
+<td>Story extent</td>
+<td><code>navPlace</code> Polygon (an explicit navPlace use case)</td>
+<td>yes — a canvas polygon becomes <code>map_bbox</code></td>
+</tr>
+<tr>
+<td>Image region stops</td>
+<td><code>ImageApiSelector</code> <code>xywh=pixel:</code> on the painting annotation target</td>
+<td>yes — the selector is the only source (§2.8)</td>
+</tr>
+<tr>
+<td>Raster layer placed on a map</td>
+<td><a href="https://iiif.io/api/extension/georef">Georeference Extension</a> (GCPs, <code>motivation: &quot;georeferencing&quot;</code>)</td>
+<td>yes — see below</td>
+</tr>
+<tr>
+<td>Basemap, layer stack, layout, keyboard</td>
+<td>—</td>
+<td>no; <code>storymap:</code> terms</td>
+</tr>
+</tbody></table>
+<h3>Groups and the slide order</h3>
+<p><code>structures</code> does two jobs. A Range with a <code>label</code> and no <code>start</code> is a <strong>group</strong>,
+and every canvas it contains gets that value as <code>slide.group</code>; nested Ranges are
+chapters inside it, and the outermost labelled Range is the group. And the order
+canvases appear in is the <strong>slide order</strong> — a Range is allowed to run them in a
+order the document does not, which is what a storyboard is for:</p>
+<pre><code class="language-json">{
+    &quot;structures&quot;: [
+        {
+            &quot;id&quot;: &quot;https://example.org/storymap/&lt;name&gt;/range/1&quot;,
+            &quot;type&quot;: &quot;Range&quot;,
+            &quot;label&quot;: { &quot;none&quot;: [&quot;Act I&quot;] },
+            &quot;items&quot;: [
+                &quot;https://example.org/storymap/&lt;name&gt;/canvas/1&quot;,
+                &quot;https://example.org/storymap/&lt;name&gt;/canvas/3&quot;
+            ]
+        }
+    ]
+}
+</code></pre>
+<p>A canvas in no Range keeps its document position, after the ones a Range does
+mention. A Range with a <code>start</code> is a time segment of a canvas, not a group: it
+contributes order and nothing else.</p>
+<h3>Deep links and external annotations</h3>
+<p>Two things a manifest can offer that a viewer used to ignore.</p>
+<p><strong>A stop can be linked by its identity.</strong> Every canvas id is a <code>uniqueid</code>
+(§2.3), so a stop is addressable by something that survives a slide being
+inserted above it. The viewer writes both forms:</p>
+<table>
+<thead>
+<tr>
+<th>Where</th>
+<th>Form</th>
+<th>Example</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>change</code> payload</td>
+<td><code>current_id</code>, next to <code>current_slide</code></td>
+<td>—</td>
+</tr>
+<tr>
+<td>URL hash</td>
+<td><code>#slide-&lt;uniqueid&gt;</code>, or <code>#slide-3</code> for a storymap-JSON slide</td>
+<td><code>#slide-https%3A%2F%2F…%2Fcanvas%2F3</code></td>
+</tr>
+<tr>
+<td>Query parameter</td>
+<td><code>iiif-content</code>, IIIF Content State 1.0</td>
+<td><code>?iiif-content=https://…/canvas/3</code></td>
+</tr>
+</tbody></table>
+<p>Both are read on load, and the hash again on every <code>hashchange</code>, so browser
+back/forward keeps working. The index form is still accepted, so links shared
+before ids were emitted keep resolving.</p>
+<p>The <code>iiif-content</code> parameter is the standard&#39;s own format and follows its
+encoding rule, which is deliberately asymmetric: a <strong>plain URI is written
+unencoded</strong>, a <strong>JSON-LD form is content-state-encoded</strong> (base64url, no
+padding). A whole canvas is therefore a bare target URI, while a region — which
+the spec says a bare URI cannot express — is the encoded Target Body:</p>
+<pre><code class="language-json">{
+    &quot;target&quot;: {
+        &quot;type&quot;: &quot;SpecificResource&quot;,
+        &quot;source&quot;: { &quot;id&quot;: &quot;https://example.org/canvas/7&quot;, &quot;type&quot;: &quot;Canvas&quot; },
+        &quot;selector&quot;: { &quot;type&quot;: &quot;ImageApiSelector&quot;, &quot;value&quot;: &quot;xywh=pixel:10,20,30,40&quot; }
+    }
+}
+</code></pre>
+<p><strong>External annotations.</strong> A manifest&#39;s <code>seeAlso</code> points at annotation
+collections or pages that live on an annotation server. They are recorded on the
+data as <code>see_also</code> but <strong>not fetched</strong> — reading them is a network round trip
+per document, and a viewer should not block its first paint on a third party. A
+host opts in:</p>
+<pre><code class="language-js">const { stops, searchService, failed } = await storymap.loadAnnotations();
+</code></pre>
+<p>which fetches, merges the annotations for the canvases being rendered into tour
+stops, and fires <code>annotationsloaded</code> with the same value. A <code>SearchService1</code> in
+<code>seeAlso</code> is reported as <code>searchService</code> rather than followed. One level of
+indirection is followed, so a collection may reference its pages, but a cycle
+cannot become an infinite walk. Fetching is cached per document, so two calls
+share one request.</p>
+<h3>Institutional credit</h3>
+<p>A manifest says who published it and under what licence, and all of it ends up
+on the one credit line the viewer renders — the map attribution the host can
+also feed with <code>setExtraAttributions()</code>:</p>
+<table>
+<thead>
+<tr>
+<th>Manifest property</th>
+<th>Becomes</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>requiredStatement</code></td>
+<td><code>Attribution: &lt;value&gt;</code></td>
+</tr>
+<tr>
+<td><code>provider</code> (Agent)</td>
+<td><code>Provider: &lt;label, or the id&gt;</code></td>
+</tr>
+<tr>
+<td><code>rights</code></td>
+<td><code>Licence: &lt;uri&gt;</code></td>
+</tr>
+<tr>
+<td><code>homepage</code> (Agent)</td>
+<td>the Agent&#39;s label or id, unlabelled</td>
+</tr>
+</tbody></table>
+<p>They are joined with <code>·</code> in that order. <code>logo</code> is an image rather than a
+credit line, so it is offered as <code>data.logo</code>, and <code>metadata</code>&#39;s label/value
+pairs are handed on as <code>data.metadata[]</code> — arbitrary pairs cannot be rendered
+generically, and dropping them loses provenance.</p>
+<p>The converter writes a <code>metadata</code> pair reading &quot;Generated by: StoryMapJS&quot;
+rather than claiming to be the manifest&#39;s <code>provider</code>. P3&#39;s <code>provider</code> is
+whoever published the content, and the converter does not know that; writing
+itself there would put &quot;Provider: StoryMapJS&quot; on the credit line of every
+converted storymap.</p>
+<h3>Geo-referenced layers</h3>
+<p>A <code>motivation: &quot;georeferencing&quot;</code> annotation carries the Georeference Extension
+payload: the IIIF Image API service to place in its <code>target</code>, and its ground
+control points (<code>properties.resourceCoords</code> ↔ <code>geometry.coordinates</code>, WGS84) in
+its <code>body</code>. Per the extension, a layer that is not part of the canvas it ships
+in — which is every map layer — embeds the image it places in <code>target</code> rather
+than referencing it. The viewer fits the points affinely and places the image,
+which OpenLayers reprojects onto the view exactly like the IIIF basemap:</p>
+<pre><code class="language-json">{
+    &quot;items&quot;: [
+        {
+            &quot;id&quot;: &quot;https://example.org/storymap/&lt;name&gt;/canvas/1&quot;,
+            &quot;type&quot;: &quot;Canvas&quot;,
+            &quot;items&quot;: [
+                {
+                    &quot;id&quot;: &quot;https://example.org/storymap/&lt;name&gt;/canvas/1/georeferencing/1&quot;,
+                    &quot;type&quot;: &quot;Annotation&quot;,
+                    &quot;motivation&quot;: &quot;georeferencing&quot;,
+                    &quot;target&quot;: {
+                        &quot;id&quot;: &quot;https://iiif.example.org/image1&quot;,
+                        &quot;type&quot;: &quot;Image&quot;,
+                        &quot;width&quot;: 5965,
+                        &quot;height&quot;: 2514,
+                        &quot;service&quot;: [
+                            {
+                                &quot;id&quot;: &quot;https://iiif.example.org/image1&quot;,
+                                &quot;type&quot;: &quot;ImageService3&quot;,
+                                &quot;profile&quot;: &quot;level2&quot;
+                            }
+                        ]
+                    },
+                    &quot;requiredStatement&quot;: {
+                        &quot;label&quot;: { &quot;none&quot;: [&quot;Attribution&quot;] },
+                        &quot;value&quot;: { &quot;none&quot;: [&quot;Sheet 12, 1789&quot;] }
+                    },
+                    &quot;body&quot;: {
+                        &quot;type&quot;: &quot;FeatureCollection&quot;,
+                        &quot;transformation&quot;: { &quot;type&quot;: &quot;polynomial&quot;, &quot;options&quot;: { &quot;order&quot;: 1 } },
+                        &quot;features&quot;: [
+                            {
+                                &quot;type&quot;: &quot;Feature&quot;,
+                                &quot;properties&quot;: { &quot;resourceCoords&quot;: [5085, 782] },
+                                &quot;geometry&quot;: {
+                                    &quot;type&quot;: &quot;Point&quot;,
+                                    &quot;coordinates&quot;: [4.4885839, 51.9101828]
+                                }
+                            }
+                        ]
+                    }
+                }
+            ]
+        }
+    ]
+}
+</code></pre>
+<p>An annotation is canvas-scoped but the layer it describes is map-wide, so the
+annotations are collected from <strong>every</strong> canvas: a layer annotated on the first
+canvas still applies to the whole story. <code>requiredStatement</code> is read as the
+layer&#39;s attribution. The other presentation keys the term could carry —
+<code>opacity</code>, <code>visible</code>, <code>className</code>, <code>blendMode</code> — have no IIIF vocabulary for a
+georeferencing annotation and are not read; the extent is not lost in substance,
+because the control points describe it. Entries with fewer than three usable
+points are dropped while reading.</p>
+<p><strong>A caveat about the official validator.</strong> The Presentation 3.0 validator checks
+against the base JSON Schema, which predates the Georeference Extension, so it
+rejects a <code>FeatureCollection</code> body and an embedded <code>Image</code> target with <em>&quot;is not
+valid under any of the given schemas&quot;</em> — even with the extension&#39;s own context
+declared, which does resolve at
+<code>http://iiif.io/api/extension/georef/1/context.json</code>. We keep the extension&#39;s
+spelling anyway: a georeferenced manifest that other IIIF tools can read is
+worth more than one this particular validator accepts. <code>npm run validate:iiif</code>
+reports the two georeferenced fixtures as <em>not covered</em> rather than as failures,
+with that reason.</p>
+<p>The result is an <code>overlays[]</code> entry, so <code>setOverlayVisible()</code> /
+<code>setOverlayOpacity()</code> and the rest of the layer API work on it as for any other
+layer. A storymap-JSON <code>overlays[]</code> entry may carry a <code>georeference</code> in place
+of a <code>map_type</code>, which is the shape the converter writes these annotations
+from.</p>
+<p><strong>Limits.</strong> The extension also allows second/third-order polynomials, thin
+plate splines and rotated or skewed sheets. OpenLayers places an image as an
+axis-aligned extent, so the viewer fits the affine (first-order) case only:
+anything else is reported in the console and skipped rather than drawn in the
+wrong place. For true warping, plug
+<a href="https://www.npmjs.com/package/@allmaps/openlayers">Allmaps&#39; <code>WarpedMapLayer</code></a>
+(or any OpenLayers layer) into the <code>tile_source_factory</code> option and keep the
+georeference data on your side — see the &quot;IIIF extensions&quot; recipe in
+<a href="./migration.html">docs/migration-from-knightlab.md</a>. Image-space
+maps (<code>map_as_image</code>, zoomify) have no geographic view, so a placed sheet is
+skipped there as well.</p>
+<p>A storymap-JSON <code>overlays[]</code> entry can carry a <code>georeference</code> — url, width,
+height and the FeatureCollection body — instead of a <code>map_type</code>, and the
+converter writes it as the annotation above, on the first canvas. The two
+georeferenced fixtures are still hand-authored: they are the only manifests in
+the set with no storymap-JSON source. <code>georeferenced-layer.json</code> places its
+sheet; <code>georeferenced-layer-unsupported.json</code> shows the skip path.</p>
 <h2>Validator interop</h2>
 <p>The official IIIF presentation validator
 (<code>https://presentation-validator.iiif.io/validate?version=3.0&amp;format=json</code>)
@@ -489,8 +977,9 @@ official validator and fails CI when any of them is rejected.</p>
 photo, and a slide with a YouTube video — full manifest:</p>
 <pre><code class="language-json">{
     &quot;@context&quot;: [
-        &quot;http://iiif.io/api/presentation/3/context.json&quot;,
         &quot;http://iiif.io/api/extension/navplace/context.json&quot;,
+        &quot;http://iiif.io/api/presentation/3/context.json&quot;,
+        &quot;https://cmahnke.github.io/StoryMapJS/navplace-properties.json&quot;,
         &quot;https://cmahnke.github.io/StoryMapJS/context.json&quot;
     ],
     &quot;id&quot;: &quot;https://example.org/storymap/storm&quot;,
@@ -508,8 +997,8 @@ photo, and a slide with a YouTube video — full manifest:</p>
         {
             &quot;id&quot;: &quot;https://example.org/storymap/storm/map-config&quot;,
             &quot;type&quot;: &quot;Service&quot;,
-            &quot;profile&quot;: &quot;https://christianmahnke.de/iiif/storymap/mapconfig&quot;,
-            &quot;storymap:mapType&quot;: &quot;osm:standard&quot;,
+            &quot;profile&quot;: &quot;https://cmahnke.github.io/StoryMapJS/context.json/mapconfig&quot;,
+            &quot;storymap:basemap&quot;: &quot;osm:standard&quot;,
             &quot;storymap:language&quot;: &quot;en&quot;,
             &quot;storymap:showLines&quot;: true,
             &quot;storymap:showHistoryLine&quot;: true,
@@ -546,7 +1035,7 @@ photo, and a slide with a YouTube video — full manifest:</p>
                 }
             ],
             &quot;storymap:type&quot;: &quot;overview&quot;,
-            &quot;storymap:date&quot;: &quot;Sep 1&quot;
+            &quot;navDate&quot;: &quot;Sep 1&quot;
         },
         {
             &quot;id&quot;: &quot;https://example.org/storymap/storm/canvas/2&quot;,
@@ -569,14 +1058,17 @@ photo, and a slide with a YouTube video — full manifest:</p>
                                 &quot;type&quot;: &quot;Image&quot;,
                                 &quot;format&quot;: &quot;image/jpeg&quot;
                             },
-                            &quot;target&quot;: &quot;https://example.org/storymap/storm/canvas/2&quot;
+                            &quot;target&quot;: &quot;https://example.org/storymap/storm/canvas/2&quot;,
+                            &quot;label&quot;: &quot;Landfall&quot;,
+                            &quot;requiredStatement&quot;: {
+                                &quot;label&quot;: { &quot;none&quot;: [&quot;Credit&quot;] },
+                                &quot;value&quot;: { &quot;none&quot;: [&quot;Weather Service&quot;] }
+                            }
                         }
                     ]
                 }
             ],
-            &quot;storymap:mediaCaption&quot;: &quot;Landfall&quot;,
-            &quot;storymap:mediaCredit&quot;: &quot;Weather Service&quot;,
-            &quot;storymap:date&quot;: &quot;Sep 2&quot;,
+            &quot;navDate&quot;: &quot;Sep 2&quot;,
             &quot;navPlace&quot;: {
                 &quot;id&quot;: &quot;https://example.org/storymap/storm/canvas/2/navplace&quot;,
                 &quot;type&quot;: &quot;FeatureCollection&quot;,
@@ -609,13 +1101,16 @@ photo, and a slide with a YouTube video — full manifest:</p>
                                 &quot;id&quot;: &quot;https://www.youtube.com/watch?v=example&quot;,
                                 &quot;type&quot;: &quot;Video&quot;
                             },
-                            &quot;target&quot;: &quot;https://example.org/storymap/storm/canvas/3&quot;
+                            &quot;target&quot;: &quot;https://example.org/storymap/storm/canvas/3&quot;,
+                            &quot;requiredStatement&quot;: {
+                                &quot;label&quot;: { &quot;none&quot;: [&quot;Credit&quot;] },
+                                &quot;value&quot;: { &quot;none&quot;: [&quot;News&quot;] }
+                            }
                         }
                     ]
                 }
             ],
-            &quot;storymap:mediaCredit&quot;: &quot;News&quot;,
-            &quot;storymap:date&quot;: &quot;Sep 3&quot;,
+            &quot;navDate&quot;: &quot;Sep 3&quot;,
             &quot;navPlace&quot;: {
                 &quot;id&quot;: &quot;https://example.org/storymap/storm/canvas/3/navplace&quot;,
                 &quot;type&quot;: &quot;FeatureCollection&quot;,
@@ -650,7 +1145,7 @@ photo, and a slide with a YouTube video — full manifest:</p>
 </tr>
 <tr>
 <td><code>map_type</code></td>
-<td><code>service[0].storymap:mapType</code> (<code>zoomify</code> → <code>iiif</code>)</td>
+<td><code>service[0].storymap:basemap</code> (<code>zoomify</code> → <code>iiif</code>), or <code>tilejson.tiles</code></td>
 </tr>
 <tr>
 <td><code>map_as_image</code></td>
@@ -662,7 +1157,7 @@ photo, and a slide with a YouTube video — full manifest:</p>
 </tr>
 <tr>
 <td><code>map_subdomains</code></td>
-<td><code>service[0].storymap:mapSubdomains</code></td>
+<td><em>dropped</em> (inert, no reader)</td>
 </tr>
 <tr>
 <td><code>map_access_token</code></td>
@@ -685,6 +1180,22 @@ photo, and a slide with a YouTube video — full manifest:</p>
 <td><code>service[0].storymap:useCustomMarkers</code></td>
 </tr>
 <tr>
+<td><code>map_area</code></td>
+<td><code>service[0].storymap:mapArea</code></td>
+</tr>
+<tr>
+<td><code>overview_extent</code></td>
+<td><code>service[0].storymap:overviewExtent</code></td>
+</tr>
+<tr>
+<td><code>keyboard</code></td>
+<td><code>service[0].storymap:keyboard</code></td>
+</tr>
+<tr>
+<td><code>overlays</code> (georeference)</td>
+<td>Georeferencing annotation <code>target</code> + <code>body</code></td>
+</tr>
+<tr>
 <td><code>zoom_distance</code></td>
 <td><em>dropped</em> (viewer setting)</td>
 </tr>
@@ -694,7 +1205,7 @@ photo, and a slide with a YouTube video — full manifest:</p>
 </tr>
 <tr>
 <td><code>less_bounce</code></td>
-<td><code>service[0].storymap:lessBounce</code></td>
+<td><em>dropped</em> (inert, no reader)</td>
 </tr>
 <tr>
 <td><code>line_follows_path</code></td>
@@ -734,7 +1245,7 @@ photo, and a slide with a YouTube video — full manifest:</p>
 </tr>
 <tr>
 <td><code>iiif.url</code></td>
-<td><code>service[0].storymap:iiifUrl</code> + canvas Image annotation <code>service[]</code></td>
+<td>Canvas Image annotation <code>service[0].id</code> + <code>/info.json</code></td>
 </tr>
 <tr>
 <td><code>iiif.attribution</code></td>
@@ -782,7 +1293,7 @@ photo, and a slide with a YouTube video — full manifest:</p>
 </tr>
 <tr>
 <td><code>date</code></td>
-<td>Canvas <code>storymap:date</code></td>
+<td>Canvas <code>navDate</code></td>
 </tr>
 <tr>
 <td><code>text.headline</code></td>
@@ -846,28 +1357,65 @@ photo, and a slide with a YouTube video — full manifest:</p>
 </tr>
 <tr>
 <td><code>media.caption</code></td>
-<td>Canvas <code>storymap:mediaCaption</code></td>
+<td>Painting annotation <code>label</code></td>
 </tr>
 <tr>
 <td><code>media.credit</code></td>
-<td>Canvas <code>storymap:mediaCredit</code></td>
+<td>Painting annotation <code>requiredStatement</code> (<code>{label, value}</code>)</td>
+</tr>
+<tr>
+<td><code>media.alt</code></td>
+<td>Painting annotation <code>accessibilitySummary</code></td>
+</tr>
+<tr>
+<td><code>media.srcset</code></td>
+<td>Canvas <code>storymap:mediaSrcset</code></td>
+</tr>
+<tr>
+<td><code>media.sizes</code></td>
+<td>Canvas <code>storymap:mediaSizes</code></td>
+</tr>
+<tr>
+<td><code>location.region</code></td>
+<td>Painting annotation target <code>ImageApiSelector</code> <code>xywh=pixel:</code></td>
 </tr>
 <tr>
 <td><code>media.thumb</code></td>
-<td><em>dropped</em> (thumbnails may be added via Canvas <code>thumbnail</code>)</td>
+<td>Canvas <code>thumbnail[]</code> or the body <code>thumbnail[]</code></td>
 </tr>
 <tr>
 <td><code>background</code></td>
-<td>Canvas <code>storymap:background</code> <code>{url, color}</code></td>
+<td>Canvas <code>background</code> painting annotation (Image + Color body)</td>
 </tr>
 <tr>
 <td><code>uniqueid</code></td>
-<td><em>dropped</em> (canvas <code>id</code>s are the canonical identifiers)</td>
+<td>Canvas <code>id</code></td>
+</tr>
+<tr>
+<td><code>group</code></td>
+<td>A <code>structures</code> Range label; the Range order is the slide order</td>
+</tr>
+<tr>
+<td><code>language</code> (per slide)</td>
+<td>The language tag the slide&#39;s text was read in (§3.4)</td>
+</tr>
+<tr>
+<td><code>logo</code>, <code>metadata</code></td>
+<td>Read into <code>data.logo</code> / <code>data.metadata[]</code></td>
+</tr>
+<tr>
+<td><code>tilejson</code></td>
+<td><code>service[0].tilejson</code></td>
+</tr>
+<tr>
+<td><code>title</code></td>
+<td>Manifest <code>label</code> (a label is required, so the converter uses the file name)</td>
 </tr>
 </tbody></table>
 <h2>Conversion</h2>
-<p><code>node scripts/convert-to-iiif.mjs</code> regenerates <code>public/examples-iiif/</code> from
-<code>public/examples/</code>. Ids are deterministic:</p>
+<p><code>npm run convert:iiif</code> regenerates <code>public/examples-iiif/</code> from
+<code>public/examples/</code> (it needs Node 22.6+, since the script imports the
+TypeScript library source via type stripping). Ids are deterministic:</p>
 <ul>
 <li>Manifest: <code>https://example.org/storymap/&lt;name&gt;</code></li>
 <li>Canvas: <code>&lt;manifest-id&gt;/canvas/&lt;n&gt;</code> (1-based, slide order)</li>
@@ -875,6 +1423,13 @@ photo, and a slide with a YouTube video — full manifest:</p>
 <li>Annotation: <code>&lt;canvas-id&gt;/annotation/1</code></li>
 <li>FeatureCollection / Feature: <code>&lt;canvas-id&gt;/navplace[.../feature/1]</code></li>
 </ul>
+<p>Three fixtures in <code>public/examples-iiif/</code> are hand-authored and not
+overwritten by a full run: <code>georeferenced-layer.json</code> and
+<code>georeferenced-layer-unsupported.json</code>, which exercise the Georeference
+Extension payloads (the legacy format cannot express ground control points,
+so there is nothing to convert from), and <code>annotated-image.json</code>, the
+annotation-driven tour (there is no storymap document to convert from —
+annotation stops only exist on the manifest side).</p>
 
         </main>