@projektemacher/storymapjs 0.10.6 → 0.10.8

package/CHANGELOG

@@ -1,10 +1,304 @@
-1.0.0 (unreleased)
+0.10.8 (2026-09-29)
 ------------------------
-Viewer-only restructure of the repository:
+Code audit: one regression, a set of latent bugs, seven stored-XSS sinks, a
+disabled type check that had been hiding them, and a dependency swap.
+
+Added
+-----
+- **`map_type: "none"`: a storymap with no map.** The text and the media are
+  the whole story, which the map's unconditional construction used to make
+  impossible. No `ol/Map` is built, so there is no tile request to consent to
+  and the consent dialog omits its tile row; the overview control is hidden;
+  the slider panel takes the full width, since there is no map to fade over;
+  and `loaded` fires without waiting for a map that will never load. The
+  accessors return their neutral values and the map setters are no-ops.
+  `map_type: ""` and an absent key still mean OpenStreetMap, and `map_type:
+  null` is normalised to that default instead of throwing out of the
+  constructor (the schema already allowed the key to be missing)
+- **`storymapToManifest()` is now a library export**, promoted out of the
+  `convert:iiif` script, so one function both writes and reads the IIIF format
+  and a host can produce a manifest in the browser. The CLI delegates to it
+  (via Node's own type stripping, so no new dependency and no build step), and
+  its output is unchanged byte for byte across all 50 fixtures
+- **Annotation-driven tour stops.** A IIIF manifest whose commenting,
+  tagging, classifying or describing annotations carry a fragment target
+  becomes one slide per annotation, each fitting the region it points at —
+  the Storiiies/Micrio shape. `text/plain` bodies become one paragraph per
+  block (escaped), `text/html` keeps its markup, and a `Sound` body becomes
+  the slide's media. A `PointSelector` becomes a square of 5% of the
+  canvas's smaller side, centred and clamped. New `docs/iiif-authoring.md`
+  (published as `authoring.html`) and a four-stop example,
+  `public/examples-iiif/annotated-image.json`
+- A normalized selector reader: `FragmentSelector`/`ImageApiSelector`
+  (`xywh=`, including `xywh=pixel:`), `PointSelector`, `TextQuoteSelector`,
+  `TimeState` and `SvgSelector` are all read, one level of `refinedBy` is
+  followed, and a string target's `#xywh=` fragment counts. Quote and SVG
+  selectors are preserved but not yet resolved or drawn — the guide says so
+- The painting body's standard fields are the only source for the slide
+  media record: `body.label` (caption), `body.requiredStatement` /
+  `body.provider` (credit), `body.accessibilitySummary` (alt),
+  `body.thumbnail` (thumb), and a `TextualBody` with `format: text/vtt`
+  (subtitles). The `storymap:mediaCaption` / `mediaCredit` / `mediaAlt`
+  extension terms are dropped; a manifest still using them loads, but the
+  strings are no longer read
+  (subtitles)
+- `media.subtitles`: a WebVTT file rendered as a `<track kind="subtitles">`
+  on the audio or video element
+- Per-slide `narration: {url}`, played through one reused audio element
+  rather than the slide's media frame, so switching slides cannot leave a
+  recording playing. Gated by browser autoplay policy (it starts after the
+  first gesture) and by a new `media:narration` consent service, so the GDPR
+  mode has no hole for it
+- `autoplay_media`: with autoplay on, a slide whose media is audio or video
+  advances when it ends instead of on the millisecond timer. The timer stays
+  armed as a fallback, so a media element that never fires `ended` cannot
+  stall the story
+- Per-slide `marker: { icon, iconSize, image, label, popup, audioBadge }`,
+  with `location.*` kept as the legacy spelling and `marker.*` winning. No
+  new `storymap:` term: in a manifest all of it arrives in the `navPlace`
+  Feature `properties` bag, which is a GeoJSON foreign-member bag and needs
+  no vocabulary registration
+- `marker.popup`: the active marker's card toggles on click, with a sanitized
+  headline and excerpt, the media thumb and a real close button. Escape and
+  navigating away both close it, and the marker releases it (and its keydown
+  listener) in `dispose()`. Inactive markers still navigate on click
+- `marker.audioBadge`: a dot on markers whose slide has narration or audio
+  media
+- Browser coverage for the surfaces jsdom cannot reach, and for the changes
+  that came with replacing the map engine: `imageready` against a real
+  asynchronously-attached IIIF source, `dispose()` proving no tile requests
+  happen after teardown, `addTo()`/`removeFrom()` re-measuring a moved map,
+  the `isImageSpace()` contract, runtime option and language changes,
+  per-viewer consent, `tile_source_factory`, and network-level proof that
+  imagery actually reaches the map (the fixture sweep only checked that a
+  container existed, so a grey map used to pass everything)
+- `npm run test:e2e:all` runs the whole suite on Chromium, Firefox and WebKit
+  (`E2E_ALL_BROWSERS=1`). Chromium-only stays the default, so the main CI job is
+  unaffected; a separate, currently non-blocking CI job runs the matrix
+- A typed OpenLayers surface: all OL types (`Map`, `View`, `Layer`,
+  `Source`, ...) plus the StoryMapJS extension types are re-exported, so a
+  consumer can build and type its own layers without depending on `ol`
+  separately. `storymap.map` is the raw `ol/Map` and is now honestly nullable
+  (`OlMap | null`) instead of an `{} as Map` placeholder
+- Accessors for everything the viewer kept private:
+  `getBaseLayer()`, `getOverlayLayers()`/`getOverlayLayer(i)`,
+  `getOverlayCount()`, `setOverlayVisible()`/`setOverlayOpacity()`,
+  `getMinimap()`, `getLine()`/`getLineActive()`, `getMarker(n)`/`getMarkers()`
+  and `setExtraAttributions()`; underscore internals are no longer needed
+- `tile_source_factory` may return a full `ol/layer/Layer`, not only a source,
+  so a custom layer can carry its own opacity, z-index and events. A layer
+  without a source (Allmaps' `WarpedMapLayer`) passes through untouched —
+  the engine fields are `Layer`-typed and source reads go through a
+  capability check instead of assuming a tile source
+- `imageready` event (`{ source, kind, layer }`, now a typed
+  `ImagereadyPayload` export with `kind: "iiif" | "zoomify" | "tiles"`)
+  fired once an image source is actually ready, and re-fired on the
+  storymap: `loaded` can fire before the imagery exists. The zoomify base
+  layer never announced itself — only its minimap did — so a host waiting
+  on the event hung on legacy stories; it fires now
+- `storymap.dispose()` releases timers, the resize observer, window/document
+  listeners, running slide animations, the slider and the OpenLayers map
+- `isImageSpace()` tells an IIIF image presented as a picture of the world
+  (`map_as_image`) from a georeferenced IIIF map; the five places that tested
+  `map_type === "iiif" && map_as_image` inline now share it
+- The no-op `show()`/`hide()` methods (map and marker) are marked deprecated
+  with the reason, and the surviving map/marker methods are documented as
+  aliases over the OpenLayers map
+- `marker.createPopup()` is back as a deprecated no-op, so pre-0.10 code that
+  calls it keeps working. It never did anything upstream either: the base
+  `MapMarker._createPopup` had an empty body and the Leaflet override's body
+  was commented out, so the `map_popup` option that called it never had an
+  effect
+- `map.addTo(container)` / `map.removeFrom(container)` keep their original
+  `DomMixed` behaviour (append/remove the map container, fire
+  `added`/`removed`) and are now OpenLayers-aware: `addTo` re-attaches the map
+  target and calls `updateSize()` after the move, `removeFrom` untargets the
+  map so it does not render into a detached node
+
+Fixed
+-----
+- A IIIF `requiredStatement`'s `label` was discarded, so a manifest that labels
+  its statement — "Credit", "Rights holder", "Photographer" — showed the bare
+  value. The label is now kept ("Attribution: …") where there is one, and an
+  unlabelled statement is still the bare value, unchanged
+- An IIIF `Collection` was accepted as a Manifest and its member Manifests were
+  read as if they were Canvases, producing text-only slides with no media, no
+  locations and no warning. A Collection is now detected and reported by name
+  with its members instead
+- A IIIF manifest's canonical ids were dropped, so a stop could not be
+  addressed by its own id even though the viewer already resolves deep links by
+  `uniqueid`. Canvas `id` (falling back to the Manifest's) now lands on the
+  slide, and an annotation-driven stop gets `<canvasId>#<index>` so it is
+  addressable without colliding with the canvas it annotates
+- A slide with body text and no headline rendered a literal "headline" as an
+  `<h2>`: `Text`'s constructor seeded its data with the placeholder strings
+  "headline"/"text", which `mergeData` only overwrites when the key is
+  present. The empty strings its render guards already expect
+- `e2e/known-issues/issue-288` tested neither half of what it claimed: without
+  `hasTouch` the browser still reports `pointer: fine`, so `Browser.touch` and
+  `Browser.mobile` were false and the desktop branch rendered, and the click
+  landed on `.vco-slidenav-next`, which is `display: none` on mobile. It now
+  enables touch, asserts the mobile branch is the one under test, checks the
+  `touch-action: pan-y` rule the fix is actually about, and drives a real
+  touch drag (via CDP) to show a vertical swipe scrolls the page past the
+  storymap
+- `e2e/known-issues/issue-452` reported a `zoom` declaration that exists in no
+  stylesheet. OpenLayers ships `.ol-viewport canvas { all: unset }`, and Firefox
+  and WebKit enumerate `zoom` as a *declared* property once `all` has reset it
+  while Chromium does not. It now asserts against the stylesheet's source text
+- The touch-scrollbar assertion in `e2e/scroll-hint` compared
+  `getComputedStyle().scrollbarWidth` against `"thin"`/`"auto"`, which is not
+  comparable across engines: Chromium computes `auto`, Firefox computes `none`
+  for the same declaration. The declaration is now checked in the stylesheet
+  source, and the runtime half is skipped where Playwright does not report
+  touch (WebKit)
+- A new georeferenced-IIIF fixture (`issue-iiif-geo`), because the negative
+  `isImageSpace()` case could not be reached from the existing ones: the
+  document sets `map_as_image`, and the document wins over a constructor option
+- The consent registry keyed its stored decisions on a *localized* label, so
+  the same service hashed differently in German than in English and renaming a
+  label orphaned every saved decision. Keys are now stable and namespaced
+  (`map:tiles`, `fonts:web`, `media:<type>`) with the localized name carried
+  alongside, and existing decisions are migrated on read. The per-slide dialog
+  also asked "Load content from youtube?" — it now shows the media's display
+  name, matching the start-of-story dialog
+- 27 of the 29 bundled locales had no `consent_*` strings at all and silently
+  fell back to English, including the whole start-of-story dialog. The 9
+  missing keys are translated in 23 locales; `npm run check:locales` now fails
+  on a new gap (its `--strict` flag was documented but never implemented, and
+  the check was not in CI) instead of only reporting
+- Removing a map marker did not renumber the ones behind it, even though
+  `marker_number` is the index a click hands to `goTo()`: a click on the third
+  pin after removing the second navigated to the wrong slide
+- Every slide got an empty element id. The generated `uniqueid` was only
+  created when the field was the empty string, but it is optional in the
+  schema and absent from 47 of the 48 bundled fixtures
+- `dispose()` released the timers and the OpenLayers map but nothing they
+  owned, so a torn-down storymap left its slider, slides, media players,
+  markers and buttons in the document. Each class now releases what it owns,
+  and three listeners that could not be removed at all (registered as inline
+  arrows or a throwaway `.bind()`) keep a reference
+- A preload was tracked in one `preloadTimer` that held either a
+  `setTimeout` or a `requestIdleCallback` handle. Both are numbers, so
+  cancelling one with the other's API appeared to work while leaking it
+- map_bbox was ignored for every IIIF map: the runtime test was "map_type is
+  iiif", so a *georeferenced* IIIF map was treated as image space and its view
+  was fitted to the image extent instead of the bbox
+- 12 tile/vector source sites declared `attributions: []`, so the OSM, Stadia,
+  Mapbox, Esri, Carto, OpenTopo, Esri Ocean, NASA, overlay and mini-map
+  credits never reached the attribution control. They are now credited from
+  the source; custom `.vco-map-attribution` lines are unchanged
+- Navigating mutated the caller's document: the computed marker zoom was
+  written back onto `slides[i].location.zoom`, and `StoryMap.data` is that very
+  object. The zoom ladder now lives in an internal store; the authored value is
+  left alone and is still used for the min/max bounds
+- `map_options.interactions` was documented as replacing the defaults; it is
+  additive (the viewer's own pan/zoom set is always installed)
+- Image media never called onLoaded(): the call had drifted into a dead
+  position after a `return` in _altText(), so every image slide kept a
+  permanent "Loading Image" overlay painted over it and never rendered its
+  credit or caption
+- Consent-denied media threw a TypeError on desktop: updateMediaDisplay()
+  dereferenced `content_item.style` on the empty placeholder
+- Map.goTo() fired its change event twice for a slide with no location
+- start_at_slide supplied by the storymap *data* was ignored: the field was
+  read before the data merge and the slider's opening goTo() fires before the
+  change listener is attached
+- The menubar collapse toggle was a no-op: the portrait branch it only
+  appears in unconditionally overwrote the map height it asked for
+- map_type "stadia" with no style resolved to a non-Stadia style name, so
+  every tile 404'd; setMapOption("map_bbox") rebuilt the View without the
+  deliberate constraints
+- The start-of-story consent dialog listed services the visitor had already
+  answered, and left answered rows greyed out rather than removing them
+  (two consent e2e tests were failing because of this)
+- The YouTube IFrame API poll retried forever; Vimeo's embed URL used &amp;
+  separators that are not decoded in a URL property; the horizontal swipe
+  constraint clamp was inverted; slide positions were computed from the
+  previous width; goToId() with an unknown id jumped to slide 0
+- 7 of the 18 media types had no icon glyph, so their error boxes were blank
+- he.json carried a UTF-8 BOM that made it unparseable by standard JSON tools
+
+Security
+--------
+- The slide-text sanitizer was a denylist that copied every attribute
+  verbatim. `style` came through untouched, which allowed a pasted
+  full-viewport opaque overlay over the map and controls (chrome spoofing and
+  clickjacking from one attribute). It is now an allowlist; `target` is always
+  forced to `_blank`, `id`/`name` are dropped, `srcset` is validated per
+  candidate, and rebuilt embeds are sandboxed with a no-referrer policy
+- Seven innerHTML sinks that bypassed the sanitizer are routed through it:
+  media credit, media caption, the navigation headline, the call-to-action
+  text, the Juxtapose iframe, and the map attribution line
+- media and image link hrefs are protocol-checked, so a `javascript:` href in
+  the storymap JSON is no longer a click-through XSS
+- a crafted `stock:` font name resolved to an arbitrary same-origin file
+- the schema validator did not implement `anyOf`, so map_bbox,
+  map_overview_center and the zoomify block were accepted completely
+  unvalidated; `format` and `maxLength` are now honoured
+
+Removed
+-------
+- The inert option keys `less_bounce`, `map_subdomains`, `map_popup`,
+  `zoom_distance`, `dragging` and `path_gfx`: documented and accepted, but read
+  by nothing. They are gone from the schema, the types and the defaults, and
+  documents carrying them still validate, because the schema does not close
+  `additionalProperties`
+
+Changed
+-------
+- The map engine is genuinely optional. `StoryMap._map` is `null` rather than a
+  `{}` stub, so the accessors' `this._map ? … : neutral` guards mean what they
+  say instead of passing on a truthy object and then calling a method on it,
+  and the paths that only make sense with a map now throw a named error if they
+  are reached without one
+- `StoryMap._el.map` is `HTMLElement | null` rather than `HTMLElement`
+- A second viewer on a page asking for a different `language` now **throws**
+  instead of silently repainting the first one. The UI strings are a single
+  page-wide binding read while a viewer is constructed, so a conflict was
+  never survivable; the claim is released by `dispose()`. Only an explicit
+  `language` — the constructor option or the document's — counts as a request:
+  a viewer that was not given one adopts the page's current locale, so calling
+  the public `setLanguage()` and then building viewers without a `language`
+  option keeps the locale instead of resetting the page to English. The
+  trade-off is that such a viewer follows a previous viewer's
+  `refreshLanguage()`
+- Several viewers on a page no longer overwrite each other's consent
+  decisions: each manager merges into the shared record and re-reads it on
+  every ask, instead of writing its whole set back
+- With `keyboard: true` on more than one viewer, an arrow keypress goes to the
+  viewer that holds focus, or else the one interacted with most recently
+- External scripts and stylesheets are injected once per URL for the page, so
+  two viewers no longer both load the YouTube/SoundCloud APIs and the font
+  theme
+- `dispose()` empties the host container and turns the public methods and
+  accessors into no-ops; there is no re-init path (build a new StoryMap)
+- strictNullChecks is enabled. The `{} as HTMLElement` placeholders it was
+  masking are now honestly nullable, which is what the consent-denied crash
+  came from
+- morpheus (an inlined UMD build that shipped no types) is replaced by a
+  ~130 line Web Animations API wrapper with the same call signature: one
+  dependency and one hand-maintained .d.ts removed, -5 kB raw and no
+  measurable change over the wire. morpheus gzipped well, so most of the raw
+  saving is offset by the new code; the win here is the dependency and the
+  type stub, not the bytes
+- npm run check:locales reports which locales are missing which strings.
+  28 of 29 are missing 8-10, mostly the per-service consent labels
+- Docs corrected: DEVELOPMENT.md described a CommonJS/UMD build with a
+  KLStoryMap global (it is ESM-only), the CHANGELOG claimed consent labels
+  were fully translated and that zoomify was removed (both false), and
+  README/index.html said slide text is rendered raw (it is sanitized)
+
+0.10.0 - 0.10.7 (2026-09-22 to 2026-09-25)
+------------------------
+Released as eight patches without individual changelog entries; this is the
+consolidated list. Viewer-only restructure of the repository:
 - Removed the editor Flask backend, CDN staging and all legacy build artifacts
 - Replaced webpack with Vite (dev/build/preview), default Vite project layout
 - Converted the source to strict TypeScript (target ES2022, noImplicitAny, no explicit any)
-- Replaced Leaflet with OpenLayers; IIIF Image API replaces Zoomify (breaking: map_type "zoomify" is gone, use "iiif")
+- Replaced Leaflet with OpenLayers. IIIF Image API ("map_type": "iiif") is the
+  recommended image basemap; the legacy Zoomify pyramid ("map_type": "zoomify")
+  is retained as a deprecated basemap and warns when it loads
 - Converted Less to SASS with zero deprecation warnings (@use only, no @import, no vendor prefixes, no postcss-scss)
 - Fonts bundled via @fontsource + @fontsource-utils/scss mixins (woff2, latin subsets); no runtime font CDN requests
 - New exchange format: IIIF Presentation API 3.0 manifests (docs/storymap-as-iiif-manifest.md) with navPlace geo +
@@ -16,6 +310,67 @@ Viewer-only restructure of the repository:
 - Dropped code for pre-2022 browsers: XHR -> fetch, removed vendor detection, engine workarounds, pollers,
   minEmoji sprite polyfill and Knight Lab tracking
 - Bug fixes: null-offset crashes, IIIF source races, unique-id generation, swipe direction check, empty-block cleanup
+- Stacked raster overlays with per-layer presentation (opacity, visibility,
+  attribution, className, blendMode, lon/lat extent), runtime setters and
+  setMapOption rebuild; minimap overview constraint via overview_extent
+- Slide transition events (transitionstart/transitionend), guaranteed goTo
+  change events, opt-in global keyboard navigation
+- Runtime language switching without reload (MenuBar.refreshLabels,
+  StoryMap.refreshLanguage); locale fallback no longer mutates English;
+  German fullscreen labels
+- Attribution refresh on basemap switch (+setExtraAttributions); identical
+  credits collapse to one entry; route lines pinned above rebuilt tile
+  layers; font_css resolves page-relative; slide colors accept any CSS color
+- Consent: decisions persist in localStorage (storymapjs-consent, no expiry)
+  instead of a 90-day cookie; a start-of-story dialog lists the external
+  services the story uses (map tiles, media services, external fonts) and
+  offers allow all, decline all or a decision per service, with per-service
+  panels as the fallback for services discovered later. Only en.json
+  translates every label: the other 28 bundled locales are each missing the
+  per-service consent strings and fall back to English (npm run check:locales)
+- Mobile gestures: iOS swipe navigation fixed — signed gesture deltas (a
+  rightward swipe on the left half no longer counts as "next"), touchcancel
+  handled without leaking touchmove/mouseleave listeners (swipes used to stop
+  working after the first slide), touchend reads changedTouches, and
+  touch-action: pan-y on the slider keeps vertical page scrolling
+- Accessibility: image alt text end-to-end (schema, IIIF storymap:mediaAlt,
+  caption-as-plain-text fallback), aria-live slide announcements, real <button>
+  menubar actions with :focus-visible styling, keyboard-operable slider nav
+  arrows (role/tabindex/Enter/Space), prefers-reduced-motion honored
+  (instant slide changes, no autoplay), embed page allows pinch-zoom
+- Image performance: offscreen slide images are lazy-loaded and
+  async-decoded (upgraded to eager when their slide becomes active), IIIF
+  image URLs request container-matched widths, optional srcset/sizes pass
+  through for plain images
+- Fonts: non-latin subsets (cyrillic, greek, hebrew, vietnamese) shipped
+  from the installed Fontsource packages where a family provides them, plus a
+  new stock:cairo theme with arabic coverage
+- IIIF: per-slide image regions (location.region as IIIF xywh in image
+  pixels) fit the view on navigation for image-map stories, encoded in
+  manifests as storymap:imageRegion
+- Storymap JSON: schema entries for map_area, overlays (with per-layer
+  opacity, visibility, attribution, className, blendMode and lon/lat extent),
+  overview_extent and keyboard — plus the slide fields location.region and
+  media.alt/srcset/sizes, and a fix for overlays and overview_extent being
+  silently dropped when they came from the data file instead of the options
+- IIIF manifests: the same options as storymap:mapArea, storymap:overlays,
+  storymap:overviewExtent and storymap:keyboard terms on the map
+  configuration service, storymap:mediaSrcset / storymap:mediaSizes on the
+  canvas, and the native geospatial vocabulary where IIIF has it — a navPlace
+  Polygon as the story extent (map_bbox), an IIIF Image API Selector as
+  location.region
+- IIIF manifests: storymap:georeferencedLayers places a IIIF image on the
+  geographic map from a Georeference Extension annotation body (affine
+  placement of its ground control points); placements needing a
+  non-affine transform or a rotated sheet are reported and skipped, so
+  warped layers stay a tile_source_factory/Allmaps concern
+- Map providers: tile_source_factory option injects custom OpenLayers tile
+  layers/sources (e.g. WMS) for the base map, overlays and minimap, with
+  recipes in the migration guide
+- Embed: &autoplay=<ms> URL parameter for automatic slide playback
+- Upstream audit: docs/KNOWN_ISSUES.md reconciled with the implementation
+  (60 of 109 triaged issues verified fixed, one-by-one verdicts and
+  regression specs for each)
 
 0.9.5 (2025-11-05)
 * Implement basic Audio and Video media types
@@ -106,16 +461,3 @@ Viewer-only restructure of the repository:
 * PR #302 Media fixes including pause of video types when navigating away from slide
 * PR #303 Adds custom map marker upload in editor
 * PR #312 Adds Greek translation to StoryMap editor
-
-## 1.0.0 (unreleased)
-
-Viewer-only restructure of the repository:
-- Removed the editor Flask backend, staging and legacy build artifacts
-- Replaced webpack with Vite (dev/build/preview), default project layout
-- Converted the source to strict TypeScript (target ES2022)
-- Replaced Leaflet with OpenLayers; IIIF Image API replaces Zoomify (breaking)
-- Converted Less to SASS; fonts bundled from npm (@fontsource) instead of runtime CDN requests
-- Added a JSON Schema for storymap data, runtime validation with console reporting, and a CLI validator
-- Added ESLint + Stylelint and GitHub Actions for linting/tests and release packaging
-- Playwright e2e suite over all examples, Vitest for units
-- Dropped code paths for pre-2022 browsers (legacy vendor prefixes, IE/old-engine fallbacks)

package/README.md

@@ -10,7 +10,9 @@ This fork is a **viewer-only library**: it renders existing StoryMap JSON
 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 `docs/` for the migration notes from the original
-Knight Lab release.
+Knight Lab release. The library also exports `storymapToManifest()`, which
+produces a IIIF manifest from a storymap document (`npm run convert:iiif`
+does the same from the command line; see `docs/storymap-as-iiif-manifest.md`).
 
 ## Development
 
@@ -40,6 +42,14 @@ Points are set to only display on mouseover in image mode, but you can set map_a
 To disable connecting lines on maps set `map_as_image: true` in the storymap
 options (the default `false` renders cartography).
 
+`storymap.map` is the raw OpenLayers map, typed with the re-exported `ol`
+types, and `getBaseLayer()`, `getOverlayLayers()`, `getMinimap()`,
+`getMarkers()` and friends hand out the layers the viewer built. Listen for
+`imageready` to run code against the real imagery, and call
+`storymap.dispose()` when the embedding view goes away — see
+[docs/migration-from-knightlab.md](docs/migration-from-knightlab.md#reaching-the-map-layers-and-markers)
+for the full surface.
+
 The menubar buttons can be disabled individually:
 
     show_overview:       false,   // map overview button
@@ -92,7 +102,8 @@ an opaque slide panel instead of the gradient over the map), set
 
 Any value containing `{z}` renders as a raster XYZ layer; a path without `{z}`
 that looks like a URL/path renders as a vector style layer; anything else falls
-back to classic OSM raster.
+back to classic OSM raster — except `"none"`, which builds no map at all and
+runs the story as text and media only.
 
 ### Switching the basemap at runtime
 
@@ -123,14 +134,22 @@ images, lists, emphasis and spans in your slides, e.g.:
 
 The `vco-note` span renders as a small grey note, like the built-in credits.
 
-**Caution:** the text is rendered raw — it is not sanitized. Only load
-storymaps from sources you trust.
+**Caution:** the text is sanitized, but sanitizing is a mitigation rather
+than a guarantee. Prose and media formatting survive (`class`, `alt`, `width`,
+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 `http(s)`, and `<iframe>` embeds are rebuilt into
+a sandboxed, `no-referrer` element. `style`, `id` and `name` are _not_ allowed,
+and a link's `target` is always forced to `_blank`. The same sanitizer covers
+media credit, media caption, the navigation headline and the map attribution
+line. Still: only load storymaps from sources you trust.
 
 ## GDPR consent for external services
 
 Set the `consent_required` option to `true` 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):
+Twitter or SoundCloud, slide narration audio, map tiles, and external font
+CSS):
 
     {
         "consent_required": true,
@@ -138,11 +157,26 @@ Twitter or SoundCloud, map tiles, and external font CSS):
     }
 
 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 (`storymapjs-consent`) for 90
-days — clearing cookies asks again.
+allowed.
+
+Before the story loads, one dialog lists every external service it uses (map
+tiles, media services including slide narration, external fonts) with three
+choices: **Allow all**, **Decline all**, or a decision per service. A story
+with no map (`map_type: "none"`) 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).
+
+Decisions are stored in `localStorage` under `storymapjs-consent` and have no
+expiry — clearing site data asks again.
+
+The consent labels are **not** fully translated. `src/language/locale/en.json`
+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
+`npm run check:locales` to see the current state — it reports the gap per
+locale and is expected to be runnable without failing.
 
 ## Troubleshooting
 

package/dist/assets/demo-DBpeF31K.js

@@ -0,0 +1 @@
+import"./modulepreload-polyfill-P2Xu9kJm.js";import{t as e}from"./main-DXalctuR.js";function t(e){document.title=`StoryMapJS: `+e.title}window.storymap=new e(`storymap-embed`,`./demo.json`,{},{title:t});

package/dist/assets/harness-Cr0rYpvt.js

@@ -0,0 +1 @@
+import"./modulepreload-polyfill-P2Xu9kJm.js";import{t as e}from"./main-DXalctuR.js";import{n as t,t as n}from"./harness-support-Do7sIp2j.js";window.__smErrors=[],window.__smReady=!1,window.addEventListener(`error`,e=>{window.__smErrors.push(String(e.message||e))});var r=new URLSearchParams(window.location.search),i=r.get(`manifest`),a=r.get(`url`),o=i===null?r.get(`example`):i,s=i===null?`/examples/`:`/examples-iiif/`,c={};if(r.get(`options`))try{c=JSON.parse(r.get(`options`))}catch(e){window.__smErrors.push(`harness: bad options param: `+e)}var l=t(window);l&&(c.tile_source_factory=l);var u=a??s+o+`.json`;fetch(u).then(e=>e.json()).then(t=>{let i=new e(`storymap-embed`,t,c,{});window.__sm=i,n(i,r.get(`record`),window),window.__smReady=!0}).catch(e=>{window.__smErrors.push(`harness: `+(e&&e.message?e.message:String(e))),window.__smReady=!0});

package/dist/assets/harness-multi-CYHgI0a9.js

@@ -0,0 +1 @@
+import"./modulepreload-polyfill-P2Xu9kJm.js";import{t as e}from"./main-DXalctuR.js";import{n as t,t as n}from"./harness-support-Do7sIp2j.js";window.__smErrors=[],window.__smReady=!1,window.addEventListener(`error`,e=>{window.__smErrors.push(String(e.message||e))});var r=new URLSearchParams(window.location.search),i={a:r.get(`a`)??`katrina`,b:r.get(`b`)??`seurat`},a={a:o(r.get(`aopts`)),b:o(r.get(`bopts`))};for(let[e,n]of Object.entries(a)){let r=t(window);r&&(n.tile_source_factory=r),a[e]=n}function o(e){if(!e)return{};try{return JSON.parse(e)}catch(e){return window.__smErrors.push(`harness-multi: bad options: `+e),{}}}async function s(e){let t=await fetch(`/examples/`+i[e]+`.json`);if(!t.ok)throw Error(`no example `+i[e]);return t.json()}var c=r.get(`shared`)===`1`?await s(`a`):null;try{let t=c??await s(`a`);window.__smA=new e(`sm-a`,t,a.a,{}),n(window.__smA,r.get(`record`),window,`A`);let i=c??await s(`b`);window.__smB=new e(`sm-b`,i,a.b,{}),n(window.__smB,r.get(`record`),window,`B`)}catch(e){window.__smErrors.push(`harness-multi: `+(e?.message??e))}window.__smReady=!0;

package/dist/assets/harness-support-Do7sIp2j.js

@@ -0,0 +1 @@
+function e(e,t,r,i=``){let a=(t??``).split(`,`).map(e=>e.trim()).filter(Boolean);if(a.length!==0){r.__events=r.__events??[];for(let t of a)e.on(t,e=>{r.__events.push({type:t,viewer:i,payload:n(e)})})}}function t(e){return typeof e.__tileSourceFactory==`function`?e.__tileSourceFactory:void 0}function n(e){if(typeof e!=`object`||!e)return e;let t={};for(let[a,o]of Object.entries(e))if(typeof o!=`object`||!o)t[a]=typeof o==`function`?`[fn]`:o;else if(a===`source`||a===`layer`)t[a]={type:o.constructor?.name??null,state:typeof o.getState==`function`?o.getState():void 0,url:o.url_??o.href_??r(o,`url`)};else if(a===`target`)t[a]=i(o);else if(Array.isArray(o))t[a]=o.map(e=>n(e));else{let e=Object.getPrototypeOf(o);t[a]=e===Object.prototype||e===null?n(o):{type:o.constructor?.name??null}}return t}function r(e,t){try{return e.get?.(t)}catch{return}}function i(e){let t=a(e)?e:a(e?._map)?e._map:null;if(!t)return{type:e?.constructor?.name??null};let n=t.getView(),r=t.getSize();return{type:e?.constructor?.name??null,size:r?[r[0],r[1]]:null,center:n?.getCenter?.()??null,resolution:n?.getResolution?.()??null,projection:n?.getProjection?.()?.getCode?.()??null}}function a(e){return!!e&&typeof e.getSize==`function`&&typeof e.getView==`function`}export{t as n,e as t};

package/dist/assets/index-wHPqGrBS.js

@@ -0,0 +1 @@
+import"./modulepreload-polyfill-P2Xu9kJm.js";var e=[{id:`katrina`,title:`Hurricane Katrina`,kind:`Map`},{id:`population`,title:`US Population Shifts`,kind:`Map`},{id:`marktwain`,title:`Mark Twain's Travels`,kind:`Map`},{id:`seurat`,title:`A Sunday on La Grande Jatte`,kind:`Large image (legacy)`},{id:`iiif-wellcome`,title:`Wellcome Collection (IIIF)`,kind:`IIIF`},{id:`president`,title:`A Month in the Life of President Obama`,kind:`Map`},{url:`https://s3.amazonaws.com/uploads.knightlab.com/storymapjs/a1a349b51799ee49e96bed10cc235e7f/garden-of-earthly-delights/published.json`,thumb:`bosch-garden`,title:`The Garden of Earthly Delights – Hieronymus Bosch`,kind:`Knight Lab example`},{url:`https://uploads.knightlab.com/storymapjs/3df56e350378e51781746bfb2a2ea428/test/published.json`,thumb:`southern-literary-trail`,title:`Southern Literary Trail`,kind:`Georgia Humanities`}];function t(e){let t=e.url??`examples/`+e.id+`.json`,n=e.thumb??e.id??``,r=document.createElement(`a`);r.className=`card`,r.href=`./embed/index.html?url=${encodeURIComponent(t)}`;let i=document.createElement(`span`);i.className=`header-image`;let a=document.createElement(`span`);a.className=`header-image-background bw`,a.style.backgroundImage=`url('./thumbs/${n}.jpg'), linear-gradient(135deg, #b8b8b8, #646464)`,a.setAttribute(`role`,`img`),a.setAttribute(`aria-label`,e.title),i.append(a);let o=document.createElement(`article`);o.className=`card-content`;let s=document.createElement(`h3`);s.textContent=e.title,o.append(s);let c=document.createElement(`footer`);return c.textContent=e.kind,r.append(i,o,c),r}var n=document.getElementById(`examples-cards`);if(n){n.classList.add(`cards-link`);for(let r of e)n.append(t(r))}var r=document.getElementById(`demo-frame`);if(r){let e=()=>{r.style.height=window.innerHeight-20+`px`};e(),window.addEventListener(`resize`,e)}