dbf-mirador 4.3.0-testing2 → 4.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dbf-mirador",
-  "version": "4.3.0-testing2",
+  "version": "4.3.1",
   "description": "An open-source, web-based 'multi-up' viewer that supports zoom-pan-rotate functionality, ability to display/compare simple images, and images with annotations.",
   "type": "module",
   "main": "./dist/mirador.min.js",

package/src/components/AnnotationsOverlay.jsx

@@ -2,15 +2,16 @@ import { useRef, useEffect, useCallback, useMemo } from 'react';
 import ReactDOM from 'react-dom';
 import PropTypes from 'prop-types';
 import { useDebouncedCallback } from 'use-debounce';
+import partition from 'lodash/partition';
 import sortBy from 'lodash/sortBy';
 import xor from 'lodash/xor';
 import OpenSeadragonCanvasOverlay from '../lib/OpenSeadragonCanvasOverlay';
 import CanvasWorld from '../lib/CanvasWorld';
-import CanvasAnnotationDisplay from '../lib/CanvasAnnotationDisplay';
+import CanvasAnnotationDisplay, { poiHitTarget } from '../lib/CanvasAnnotationDisplay';
 import { buildPath2D } from '../lib/svgShapesToPath';
 
 /** @private */
-function isAnnotationAtPoint(canvasWorld, osdCanvasOverlay, resource, canvas, point) {
+function isAnnotationAtPoint({ canvasWorld, osdCanvasOverlay, viewer }, resource, canvas, point) {
   const [canvasX, canvasY] = canvasWorld.canvasToWorldCoordinates(canvas.id);
   const relativeX = point.x - canvasX;
   const relativeY = point.y - canvasY;
@@ -21,6 +22,21 @@ function isAnnotationAtPoint(canvasWorld, osdCanvasOverlay, resource, canvas, po
     return [...svgPaths].some((path) => context.isPointInPath(buildPath2D(path), relativeX, relativeY));
   }
 
+  if (resource.pointSelector) {
+    const { x, y } = resource.pointSelector;
+    const osdCanvasIndex = canvasWorld.canvases.findIndex((c) => c.id === canvas.id);
+    const viewportCanvas = viewer.world.getItemAt(osdCanvasIndex);
+    if (!viewportCanvas) return false;
+    // The icon renders at a constant on-screen size regardless of zoom (see
+    // CanvasAnnotationDisplay#pointContext), so its clickable footprint must counter-scale the
+    // same way, or the hit region would shrink/grow with the image instead of the icon.
+    const zoomRatio = viewportCanvas.viewportToImageZoom(viewer.viewport.getZoom(true));
+    const hitTarget = poiHitTarget(x, y, zoomRatio);
+    const dx = relativeX - hitTarget.x;
+    const dy = relativeY - hitTarget.y;
+    return dx * dx + dy * dy <= hitTarget.radius * hitTarget.radius;
+  }
+
   if (resource.fragmentSelector) {
     const [x, y, w, h] = resource.fragmentSelector;
     return x <= relativeX && relativeX <= x + w && y <= relativeY && relativeY <= y + h;
@@ -82,30 +98,36 @@ export function AnnotationsOverlay({
   const annotationsToContext = useCallback(
     (renderedAnnotations, currentPalette) => {
       const context = osdCanvasOverlay.context2d;
-      renderedAnnotations.forEach((annotation) => {
-        annotation.resources.forEach((resource) => {
-          const osdCanvasIndex = canvasWorld.canvases.findIndex((canvas) => canvas.id === resource.targetId);
-          if (osdCanvasIndex === -1) return;
-          const viewportCanvas = viewer.world.getItemAt(osdCanvasIndex);
-          if (!viewportCanvas) return;
-          const offset = canvasWorld.offsetByCanvas(resource.targetId);
-          const zoomRatio = viewportCanvas.viewportToImageZoom(viewer.viewport.getZoom(true));
-          const canvasAnnotationDisplay = new CanvasAnnotationDisplay({
-            hovered: hoveredAnnotationIds.includes(resource.id),
-            offset,
-            palette: {
-              ...currentPalette,
-              default: {
-                ...currentPalette.default,
-                ...(!highlightAllAnnotations && currentPalette.hidden),
-              },
+      const resources = renderedAnnotations.flatMap((annotation) => annotation.resources);
+
+      // POI pins always draw last, on top of every other annotation shape on the same canvas -
+      // notably including a Journey's own annotation target (an svg/fragment selector, not a
+      // pointSelector), which would otherwise draw in plain store order and can end up covering
+      // - and stealing clicks from - a POI pin it happens to overlap on screen.
+      const [otherResources, poiResources] = partition(resources, (resource) => !resource.pointSelector);
+
+      [...otherResources, ...poiResources].forEach((resource) => {
+        const osdCanvasIndex = canvasWorld.canvases.findIndex((canvas) => canvas.id === resource.targetId);
+        if (osdCanvasIndex === -1) return;
+        const viewportCanvas = viewer.world.getItemAt(osdCanvasIndex);
+        if (!viewportCanvas) return;
+        const offset = canvasWorld.offsetByCanvas(resource.targetId);
+        const zoomRatio = viewportCanvas.viewportToImageZoom(viewer.viewport.getZoom(true));
+        const canvasAnnotationDisplay = new CanvasAnnotationDisplay({
+          hovered: hoveredAnnotationIds.includes(resource.id),
+          offset,
+          palette: {
+            ...currentPalette,
+            default: {
+              ...currentPalette.default,
+              ...(!highlightAllAnnotations && currentPalette.hidden),
             },
-            resource,
-            selected: selectedAnnotationId === resource.id,
-            zoomRatio,
-          });
-          canvasAnnotationDisplay.toContext(context);
+          },
+          resource,
+          selected: selectedAnnotationId === resource.id,
+          zoomRatio,
         });
+        canvasAnnotationDisplay.toContext(context);
       });
     },
     [osdCanvasOverlay, viewer, canvasWorld, highlightAllAnnotations, hoveredAnnotationIds, selectedAnnotationId],
@@ -137,12 +159,12 @@ export function AnnotationsOverlay({
         .filter((resource) => {
           if (canvas.id !== resource.targetId) return false;
 
-          return isAnnotationAtPoint(canvasWorld, osdCanvasOverlay, resource, canvas, point);
+          return isAnnotationAtPoint({ canvasWorld, osdCanvasOverlay, viewer }, resource, canvas, point);
         });
 
       return annos;
     },
-    [annotations, canvasWorld, osdCanvasOverlay, searchAnnotations],
+    [annotations, canvasWorld, osdCanvasOverlay, searchAnnotations, viewer],
   );
 
   const onCanvasClick = useCallback(
@@ -188,7 +210,7 @@ export function AnnotationsOverlay({
               const x = Math.cos(degrees * degreesToRadians) * radius + point.x;
               const y = Math.sin(degrees * degreesToRadians) * radius + point.y;
 
-              if (isAnnotationAtPoint(canvasWorld, osdCanvasOverlay, anno, canvas, { x, y })) score += 1;
+              if (isAnnotationAtPoint({ canvasWorld, osdCanvasOverlay, viewer }, anno, canvas, { x, y })) score += 1;
             }
 
             return { anno, score };
@@ -206,7 +228,7 @@ export function AnnotationsOverlay({
         toggleAnnotation(annosWithScore[0].anno.id);
       }
     },
-    [annotationsAtPoint, canvasWorld, osdCanvasOverlay, toggleAnnotation],
+    [annotationsAtPoint, canvasWorld, osdCanvasOverlay, toggleAnnotation, viewer],
   );
 
   const onCanvasMouseMove = useDebouncedCallback(

package/src/lib/AnnotationItem.js

@@ -120,4 +120,22 @@ export default class AnnotationItem {
 
     return match && match[1].split(',').map((str) => parseInt(str, 10));
   }
+
+  /** */
+  get pointSelector() {
+    const { selector } = this;
+    switch (typeof selector) {
+      case 'string':
+        return null;
+      case 'object':
+        return selector.find((s) => s.type && s.type === 'PointSelector');
+      default:
+        return null;
+    }
+  }
+
+  /** the POI's position within its journey (see mirador-annotation-editor's `dbf:journey`), or null when the POI is not part of a journey */
+  get journeyOrder() {
+    return this.resource['dbf:journey']?.order ?? null;
+  }
 }

package/src/lib/AnnotationResource.js

@@ -119,4 +119,18 @@ export default class AnnotationResource {
 
     return match && match[1].split(',').map((str) => parseInt(str, 10));
   }
+
+  /** */
+  get pointSelector() {
+    const { selector } = this;
+    if (selector && typeof selector === 'object' && selector['@type'] === 'oa:PointSelector') {
+      return { x: selector.x, y: selector.y };
+    }
+    return null;
+  }
+
+  /** the POI's position within its journey (see mirador-annotation-editor's `dbf:journey`), or null when the POI is not part of a journey */
+  get journeyOrder() {
+    return this.resource['dbf:journey']?.order ?? null;
+  }
 }

package/src/lib/CanvasAnnotationDisplay.js

@@ -4,6 +4,51 @@
  */
 import { buildPath2D } from '../lib/svgShapesToPath';
 
+/**
+ * The POI marker icon's path data and viewBox, copied from src/assets/icons/poi-marker.svg -
+ * inlined as a Path2D (rather than loaded as an image via drawImage) so it renders as a crisp
+ * vector at any zoom with no async image-load step to coordinate with the render loop. Update
+ * this constant (and the asset file, for reference) together if the icon changes.
+ */
+const POI_ICON_PATH_D =
+  'M50.002 0C30.763 0 15 15.718 15 34.902c0 7.432 2.374 14.34 6.392 20.019L45.73 96.994c3.409 4.453 5.675 3.607 8.51-.235l26.843-45.683c.542-.981.967-2.026 1.338-3.092A34.446 34.446 0 0 0 85 34.902C85 15.718 69.24 0 50.002 0zm0 16.354c10.359 0 18.597 8.218 18.597 18.548c0 10.33-8.238 18.544-18.597 18.544c-10.36 0-18.601-8.215-18.601-18.544c0-10.33 8.241-18.548 18.6-18.548z';
+const POI_ICON_VIEWBOX_SIZE = 100;
+/** The icon's own point (its pin tip), in viewBox units - this is what gets placed exactly on the annotated coordinate, not the icon's bounding-box center. Derived from the path's actual lowest point (~50, 100), not just its nearby `L` command endpoint. */
+const POI_ICON_TIP = { x: 50, y: 100 };
+/** Center/radius of the icon's circular head, in viewBox units - where a journey-order badge is drawn, overlapping the icon like a numbered pin. */
+const POI_ICON_HEAD = { x: 50, y: 34.9, radius: 18.6 };
+/** Font size of the journey-order number, relative to POI_ICON_HEAD.radius, so it's bigger than the badge circle would otherwise imply while the circle itself stays the same size. */
+const POI_ICON_HEAD_FONT_SCALE = 1.6;
+const POI_ICON_DEFAULT_FILL = '#1e88e5';
+/** Constant on-screen height (CSS px) for the POI icon, regardless of zoom - counter-scaled the same way this class already counter-scales stroke width (see `lineWidth /= zoomRatio` in svgContext). */
+export const POI_ICON_HEIGHT_PX = 44;
+/**
+ * On-screen radius (CSS px, before counter-scaling by zoomRatio) of a POI marker's
+ * clickable/tappable hit target - deliberately independent of, and larger than, the icon's
+ * visual size (POI_ICON_HEIGHT_PX). The icon tapers to a fine point at its anchor, which is
+ * hard to hit precisely with a mouse and well under the ~44-48px minimum touch target size
+ * recommended for mobile (Apple HIG / Material Design), so the tappable area is deliberately
+ * generous rather than matching the icon's own footprint.
+ */
+export const POI_ICON_HIT_RADIUS_PX = 32;
+
+/**
+ * The on-screen hit-test circle (already counter-scaled by zoomRatio, in the same coordinate
+ * space as a resource's `pointSelector`) for a POI marker anchored at (x, y). Centered on the
+ * icon's round head rather than its pin tip: the tip is the anchor point used for rendering
+ * (see pointContext/POI_ICON_TIP), but it's the least visually prominent, hardest-to-aim-for
+ * part of the icon, so hit-testing there instead of at the head would make the marker harder,
+ * not easier, to hit.
+ */
+export function poiHitTarget(x, y, zoomRatio) {
+  const iconScale = POI_ICON_HEIGHT_PX / zoomRatio / POI_ICON_VIEWBOX_SIZE;
+  return {
+    radius: POI_ICON_HIT_RADIUS_PX / zoomRatio,
+    x: x + (POI_ICON_HEAD.x - POI_ICON_TIP.x) * iconScale,
+    y: y + (POI_ICON_HEAD.y - POI_ICON_TIP.y) * iconScale,
+  };
+}
+
 export default class CanvasAnnotationDisplay {
   /** */
   constructor({ resource, palette, zoomRatio, offset, selected, hovered }) {
@@ -20,11 +65,70 @@ export default class CanvasAnnotationDisplay {
     this.context = context;
     if (this.resource.svgSelector) {
       this.svgContext();
+    } else if (this.resource.pointSelector) {
+      this.pointContext();
     } else if (this.resource.fragmentSelector) {
       this.fragmentContext();
     }
   }
 
+  /** */
+  currentPalette() {
+    if (this.hovered) return this.palette.hovered;
+    if (this.selected) return this.palette.selected;
+    return this.palette.default;
+  }
+
+  /**
+   * Draws a POI marker (IIIF PointSelector) as the SVG pin icon, at a constant on-screen size,
+   * with the icon's own tip placed exactly on the annotated point. When the annotation carries
+   * journey-order metadata (`dbf:journey.order`), also draws a numbered badge over the icon's
+   * head, so a POI's position within its journey is visible directly on the map.
+   */
+  pointContext() {
+    const { x, y } = this.resource.pointSelector;
+    const currentPalette = this.currentPalette();
+    if (currentPalette.globalAlpha === 0) return;
+
+    const iconHeight = POI_ICON_HEIGHT_PX / this.zoomRatio;
+    const iconScale = iconHeight / POI_ICON_VIEWBOX_SIZE;
+
+    this.context.save();
+    this.context.translate(this.offset.x + x, this.offset.y + y);
+    this.context.scale(iconScale, iconScale);
+    this.context.translate(-POI_ICON_TIP.x, -POI_ICON_TIP.y);
+
+    this.context.globalAlpha = currentPalette.globalAlpha ?? 1;
+    this.context.fillStyle = currentPalette.fillStyle || POI_ICON_DEFAULT_FILL;
+    this.context.fill(new Path2D(POI_ICON_PATH_D));
+
+    const { journeyOrder } = this.resource;
+    if (journeyOrder != null) {
+      this.journeyOrderBadgeContext(journeyOrder);
+    }
+
+    this.context.restore();
+  }
+
+  /**
+   * Draws a small numbered circle over the POI icon's head, in the icon's own (viewBox-unit,
+   * already-scaled/translated) coordinate space - called from within pointContext's transform,
+   * before it restores the context.
+   * @param {number} order
+   */
+  journeyOrderBadgeContext(order) {
+    this.context.beginPath();
+    this.context.arc(POI_ICON_HEAD.x, POI_ICON_HEAD.y, POI_ICON_HEAD.radius, 0, Math.PI * 2);
+    this.context.fillStyle = '#ffffff';
+    this.context.fill();
+
+    this.context.fillStyle = this.currentPalette().fillStyle || POI_ICON_DEFAULT_FILL;
+    this.context.font = `bold ${POI_ICON_HEAD.radius * POI_ICON_HEAD_FONT_SCALE}px sans-serif`;
+    this.context.textAlign = 'center';
+    this.context.textBaseline = 'middle';
+    this.context.fillText(String(order), POI_ICON_HEAD.x, POI_ICON_HEAD.y);
+  }
+
   /** */
   get svgString() {
     return this.resource.svgSelector.value;

package/src/plugins/poiPreviewPlugin.tsx

@@ -0,0 +1,340 @@
+import { useState, type ComponentType } from 'react';
+import {
+  ConnectedCompanionWindow as CompanionWindow,
+  addCompanionWindow,
+  getAnnotations,
+  getCompanionWindow,
+  getCompanionWindows,
+  getVisibleCanvases,
+  updateCompanionWindow,
+} from 'dbf-mirador';
+
+// A "dumb" way to preview a POI/journey (issue #375): a Mirador companion window plugin,
+// registered alongside dbf-mirador-annotation-editor's own (see MiradorMaeViewer.tsx) via
+// Mirador's `companionWindowKey` mechanism - no core patch needed, just adding this plugin
+// to the same `plugins` array. The actual "Preview" button lives per-row in
+// dbf-mirador-annotation-editor's own CanvasListItem.jsx, right next to Edit/Delete
+// (see that package's own PR for issue #375) - it opens this companion window passing the
+// specific row's id as `annotationid`, the same convention MAE's own 'annotationCreation'
+// companion window already uses for its own Edit button.
+//
+// Journeys (issue #378) get a richer path here: instead of the "dumb" dual-locale dump
+// below, a Journey renders its ordered stops as numbered cards with a single active
+// locale (toggle EN/AR), closer to how the public site will eventually present it. Two
+// pieces of the Figma design are intentionally NOT built here, per the issue author's own
+// follow-up comment saying they "wait more precision": numbered pins drawn on the map
+// canvas itself, and an SVG line joining those pins in journey order.
+
+const POI_PREVIEW_CONTENT_ID = 'mapsPoiPreview';
+
+type TextualAnnotationBody = {
+  purpose: 'identifying' | 'describing';
+  type: 'TextualBody';
+  language: string;
+  value: string;
+};
+
+// Mirrors the maps plugin's `Annotation['dbf:mediaEn']`/`Annotation['dbf:mediaAr']`
+// (issue #377) - one media selection per language, unlike the single, language-agnostic
+// `dbf:media` extension issue #391 briefly introduced.
+type DbfMedia = {
+  source: 'upload' | 'iiif-image' | 'media-item';
+  id: string;
+  title: string | null;
+  mediaType?: string | null;
+  thumbnailUrl: string | null;
+};
+
+type RawAnnotation = {
+  id: string;
+  'dbf:kind'?: 'POI' | 'Journey';
+  'dbf:mediaEn'?: DbfMedia | null;
+  'dbf:mediaAr'?: DbfMedia | null;
+  // A POI's membership in a journey and its position within it - a Journey never lists
+  // its own POIs, membership is always POI -> Journey (see mirador-annotation-editor's
+  // annotationListGrouping.js, which this plugin can't import directly since grouping
+  // isn't part of that package's public API - so the same filter+sort is redone below).
+  'dbf:journey'?: { id: string; order: number } | null;
+  body?: TextualAnnotationBody[];
+};
+
+// Both locales, side by side - see the module comment above: the point of a "dumb" preview
+// is to see everything a poi/journey holds, not to render it the way the public site
+// eventually will for one active language.
+const LOCALES = ['en', 'ar'] as const;
+
+const textBody = (
+  annotation: RawAnnotation,
+  language: string,
+  purpose: 'identifying' | 'describing'
+): string =>
+  annotation.body?.find(
+    (item): item is TextualAnnotationBody =>
+      item.type === 'TextualBody' && item.purpose === purpose && item.language === language
+  )?.value ?? '';
+
+const mediaForLocale = (annotation: RawAnnotation, locale: (typeof LOCALES)[number]): DbfMedia | null | undefined =>
+  locale === 'en' ? annotation['dbf:mediaEn'] : annotation['dbf:mediaAr'];
+
+// A journey's ordered stops, derived the same way the rest of the codebase does: every
+// POI whose `dbf:journey.id` points at this journey, sorted by `dbf:journey.order`.
+export const getOrderedJourneyPois = (items: RawAnnotation[], journeyId: string): RawAnnotation[] =>
+  items
+    .filter(
+      (item): item is RawAnnotation & { 'dbf:journey': { id: string; order: number } } =>
+        item['dbf:kind'] === 'POI' && item['dbf:journey']?.id === journeyId
+    )
+    .sort((a, b) => a['dbf:journey'].order - b['dbf:journey'].order);
+
+const JOURNEY_PREVIEW_LOCALES = ['en', 'ar'] as const;
+type JourneyPreviewLocale = (typeof JOURNEY_PREVIEW_LOCALES)[number];
+
+// Arabic is the only RTL locale this project handles today (mirrors the same check in
+// mirador-annotation-editor's POITemplate.jsx/JourneyTemplate.jsx).
+const isRtlLocale = (locale: string) => locale.toLowerCase().startsWith('ar');
+
+interface JourneyPreviewContentProps {
+  id: string;
+  journey: RawAnnotation;
+  pois: RawAnnotation[];
+  windowId: string;
+}
+
+const JourneyPreviewContent = ({ id, journey, pois, windowId }: JourneyPreviewContentProps) => {
+  const [locale, setLocale] = useState<JourneyPreviewLocale>('en');
+  const journeyTitle = textBody(journey, locale, 'identifying');
+
+  return (
+    <CompanionWindow id={id} title={journeyTitle || 'Journey'} windowId={windowId}>
+      <div dir={isRtlLocale(locale) ? 'rtl' : 'ltr'} style={{ padding: 16 }}>
+        <div style={{ display: 'flex', justifyContent: 'flex-end', gap: 4, marginBottom: 16 }}>
+          {JOURNEY_PREVIEW_LOCALES.map((code) => (
+            <button
+              aria-pressed={locale === code}
+              key={code}
+              onClick={() => setLocale(code)}
+              style={{
+                background: locale === code ? '#333' : 'transparent',
+                border: '1px solid #333',
+                borderRadius: 4,
+                color: locale === code ? '#fff' : '#333',
+                cursor: 'pointer',
+                padding: '4px 12px',
+              }}
+              type="button"
+            >
+              {code.toUpperCase()}
+            </button>
+          ))}
+        </div>
+        {pois.length === 0 && <p>This journey has no stops yet.</p>}
+        {pois.map((poi, index) => {
+          const poiTitle = textBody(poi, locale, 'identifying');
+          const description = textBody(poi, locale, 'describing');
+          const media = mediaForLocale(poi, locale);
+          const isLast = index === pois.length - 1;
+          return (
+            <div key={poi.id} style={{ display: 'flex' }}>
+              <div
+                style={{
+                  alignItems: 'center',
+                  display: 'flex',
+                  flexDirection: 'column',
+                  marginInlineEnd: 16,
+                }}
+              >
+                <span
+                  style={{
+                    alignItems: 'center',
+                    background: '#000',
+                    borderRadius: '50%',
+                    color: '#fff',
+                    display: 'flex',
+                    flexShrink: 0,
+                    fontWeight: 'bold',
+                    height: 28,
+                    justifyContent: 'center',
+                    width: 28,
+                  }}
+                >
+                  {index + 1}
+                </span>
+                {/* A plain vertical stepper line standing in for the map's own dashed
+                    connector line, which is out of scope here - see the module comment. */}
+                {!isLast && <div style={{ background: '#ccc', flex: 1, margin: '4px 0', width: 2 }} />}
+              </div>
+              <div style={{ flex: 1, paddingBottom: isLast ? 0 : 24 }}>
+                <h3 style={{ margin: '0 0 8px' }}>{poiTitle || '—'}</h3>
+                {media?.thumbnailUrl && (
+                  <img
+                    alt={media.title ?? ''}
+                    src={media.thumbnailUrl}
+                    style={{ borderRadius: 8, marginBottom: 8, maxWidth: '100%' }}
+                  />
+                )}
+                {description && (
+                  // eslint-disable-next-line react/no-danger -- description is CKEditor HTML, the same content the public site will eventually render
+                  <div dangerouslySetInnerHTML={{ __html: description }} />
+                )}
+              </div>
+            </div>
+          );
+        })}
+      </div>
+    </CompanionWindow>
+  );
+};
+
+interface PoiPreviewContentProps {
+  annotation: RawAnnotation | null;
+  id: string;
+  windowId: string;
+}
+
+const PoiPreviewContent = ({ annotation, id, windowId }: PoiPreviewContentProps) => (
+  <CompanionWindow id={id} title={annotation?.['dbf:kind'] ?? 'Preview'} windowId={windowId}>
+    <div style={{ padding: 16 }}>
+      {!annotation && <p>This annotation could not be found - it may have been deleted.</p>}
+      {annotation &&
+        LOCALES.map((locale) => {
+          const title = textBody(annotation, locale, 'identifying');
+          const description = textBody(annotation, locale, 'describing');
+          const media = mediaForLocale(annotation, locale);
+          return (
+            <section key={locale} style={{ marginBottom: 24 }}>
+              <h3 style={{ textTransform: 'uppercase' }}>{locale}</h3>
+              <p>
+                <strong>{title || '—'}</strong>
+              </p>
+              {description && (
+                // eslint-disable-next-line react/no-danger -- descriptionEn/Ar is CKEditor HTML, the same content the public site will eventually render
+                <div dangerouslySetInnerHTML={{ __html: description }} />
+              )}
+              {media &&
+                (media.thumbnailUrl ? (
+                  <img alt={media.title ?? ''} src={media.thumbnailUrl} style={{ maxWidth: '100%' }} />
+                ) : (
+                  <p>
+                    {media.title}
+                    {media.mediaType ? ` (${media.mediaType})` : ''}
+                  </p>
+                ))}
+            </section>
+          );
+        })}
+    </div>
+  </CompanionWindow>
+);
+
+interface PreviewContentProps {
+  annotation: RawAnnotation | null;
+  id: string;
+  journeyPois: RawAnnotation[];
+  windowId: string;
+}
+
+const PreviewContent = ({ annotation, id, journeyPois, windowId }: PreviewContentProps) => {
+  if (annotation && annotation['dbf:kind'] === 'Journey') {
+    return <JourneyPreviewContent id={id} journey={annotation} pois={journeyPois} windowId={windowId} />;
+  }
+  return <PoiPreviewContent annotation={annotation} id={id} windowId={windowId} />;
+};
+
+const poiPreviewCompanionWindowPlugin = {
+  component: PreviewContent,
+  companionWindowKey: POI_PREVIEW_CONTENT_ID,
+  mapStateToProps: (state: unknown, { id, windowId }: { id: string; windowId: string }) => {
+    const annotationId = getCompanionWindow(state, { companionWindowId: id })?.annotationid as
+      | string
+      | undefined;
+    const canvasId = getVisibleCanvases(state, { windowId })[0]?.id;
+    const pages: Record<string, { json?: { items?: unknown[] } }> | undefined = canvasId
+      ? getAnnotations(state)[canvasId]
+      : undefined;
+    const items = (pages ? Object.values(pages) : []).flatMap(
+      (page) => (page.json?.items ?? []) as RawAnnotation[]
+    );
+    const annotation = items.find((item) => item.id === annotationId) ?? null;
+    return {
+      annotation,
+      journeyPois:
+        annotation && annotation['dbf:kind'] === 'Journey' ? getOrderedJourneyPois(items, annotation.id) : [],
+    };
+  },
+};
+
+// A canvas annotation resource, as AnnotationsOverlay's own `annotations`/`searchAnnotations`
+// props carry it (see AnnotationItem#pointSelector) - a POI marker is any resource with a
+// pointSelector, exactly the condition CanvasAnnotationDisplay#pointContext draws on.
+type AnnotationResourceLike = { id: string; pointSelector?: unknown };
+type AnnotationListItem = { resources?: AnnotationResourceLike[] };
+
+interface AnnotationsOverlayTargetProps {
+  annotations?: AnnotationListItem[];
+  searchAnnotations?: AnnotationListItem[];
+  selectAnnotation?: (windowId: string, annotationId: string) => void;
+  windowId: string;
+  [key: string]: unknown;
+}
+
+interface AnnotationsOverlayPoiClickWrapperProps {
+  TargetComponent: ComponentType<Record<string, unknown>>;
+  targetProps: AnnotationsOverlayTargetProps;
+  addCompanionWindow: typeof addCompanionWindow;
+  updateCompanionWindow: typeof updateCompanionWindow;
+  existingPreviewCompanionWindowId?: string;
+}
+
+// Wraps AnnotationsOverlay (the component that owns the OSD canvas-click handler and the
+// select/deselect-annotation dispatch, see AnnotationsOverlay#toggleAnnotation) so that
+// clicking a POI marker on the canvas - not just a row in a list somewhere - opens this same
+// preview companion window a "Preview" button would (issue #375's own follow-up: pins on the
+// map itself). Re-uses an already-open preview window instead of stacking a new one per click.
+const AnnotationsOverlayPoiClickWrapper = ({
+  TargetComponent,
+  targetProps,
+  addCompanionWindow: dispatchAddCompanionWindow,
+  updateCompanionWindow: dispatchUpdateCompanionWindow,
+  existingPreviewCompanionWindowId,
+}: AnnotationsOverlayPoiClickWrapperProps) => {
+  const { annotations = [], searchAnnotations = [], selectAnnotation } = targetProps;
+
+  const selectAnnotationAndMaybePreview = (clickedWindowId: string, annotationId: string) => {
+    selectAnnotation?.(clickedWindowId, annotationId);
+
+    const resource = [...annotations, ...searchAnnotations]
+      .flatMap((item) => item.resources ?? [])
+      .find((item) => item.id === annotationId);
+
+    if (!resource?.pointSelector) return;
+
+    if (existingPreviewCompanionWindowId) {
+      dispatchUpdateCompanionWindow(clickedWindowId, existingPreviewCompanionWindowId, {
+        annotationid: annotationId,
+      });
+    } else {
+      dispatchAddCompanionWindow(clickedWindowId, {
+        annotationid: annotationId,
+        content: POI_PREVIEW_CONTENT_ID,
+        position: 'right',
+      });
+    }
+  };
+
+  return <TargetComponent {...targetProps} selectAnnotation={selectAnnotationAndMaybePreview} />;
+};
+
+const poiPreviewClickPlugin = {
+  target: 'AnnotationsOverlay',
+  mode: 'wrap',
+  component: AnnotationsOverlayPoiClickWrapper,
+  mapStateToProps: (state: unknown, { windowId }: { windowId: string }) => {
+    const existing = Object.values(getCompanionWindows(state) as Record<string, { id: string; windowId: string; content: string | null }>).find(
+      (cw) => cw.windowId === windowId && cw.content === POI_PREVIEW_CONTENT_ID,
+    );
+    return { existingPreviewCompanionWindowId: existing?.id };
+  },
+  mapDispatchToProps: { addCompanionWindow, updateCompanionWindow },
+};
+
+export const poiPreviewPlugins = [poiPreviewCompanionWindowPlugin, poiPreviewClickPlugin];