@inkra/react 0.12.0 → 0.14.0

package/dist/journey-map/index.js

@@ -1,26 +1,40 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useInkraLocale } from '../i18n/index.js';
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useMemo, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 import { Button } from '../Button.js';
 import { Popover } from '../overlay/index.js';
+import { PencilSurface } from '../PencilSurface.js';
 import { PencilText } from '../PencilText.js';
 import { pencilStroke } from '../internal/stroke.js';
 import { TravelIcon } from '../internal/travelIcons.js';
 import { paintTerrain, paintStop, paintSea } from './terrain.js';
 import { MapScale } from './MapScale.js';
 import { seedToNumber } from '../internal/random.js';
-const defaults = (t) => ({ zoomIn: t('common.zoomIn'), zoomOut: t('common.zoomOut'), reset: t('common.resetView'), unavailable: t('map.unavailable') });
+import { PENCIL_RENDERER_VERSION } from '../internal/cache.js';
+import { JourneyBaseBitmap, journeyAnimationMs, journeyCanvasSize, journeyFocusZoom, journeyPanRegions, prepareJourneyCanvas, resolveJourneyMapRendering } from './rendering.js';
+import { attachJourneyTrackpad } from './trackpad.js';
+import { areaPolygons, journeyAreaLabel, paintJourneyArea, validJourneyArea } from './annotations.js';
+const defaults = (t) => ({ zoomIn: t('common.zoomIn'), zoomOut: t('common.zoomOut'), reset: t('common.resetView'), unavailable: t('map.unavailable'), features: t('map.features') });
 const noRoutes = [];
+const noAreas = [];
 const valid = (place) => Number.isFinite(place.latitude) && Number.isFinite(place.longitude) && Math.abs(place.latitude) <= 85 && Math.abs(place.longitude) <= 180;
-export function JourneyMap({ places, routes = noRoutes, geography, landCover, water, selectedPlace, onPlaceSelect, attribution, attributionDisplay = 'inline', height = 480, interactive = true, scrollWheelZoom = false, showControls = true, showPlaceList = false, focusSelectedPlace = false, labels: labelOverrides, className, ...props }) {
+export function JourneyMap({ places, routes = noRoutes, areas = noAreas, selectedRoute, onRouteSelect, selectedArea, onAreaSelect, showFeatureList = false, geography, landCover, water, selectedPlace, onPlaceSelect, attribution, attributionDisplay = 'inline', height = 480, maxFitZoom = 12, background = 'sea', interactive = true, scrollWheelZoom = false, showControls = true, showPlaceList = false, focusSelectedPlace = true, focusZoomScale = 2, animate = true, animationDuration = 420, rendering = 'auto', labels: labelOverrides, className, ...props }) {
     const { t } = useInkraLocale();
     const labels = { ...defaults(t), ...labelOverrides };
+    const usableAreas = useMemo(() => areas.filter(validJourneyArea), [areas]);
+    const annotationSelection = useRef({ selectedRoute, onRouteSelect, selectedArea, onAreaSelect });
+    annotationSelection.current = { selectedRoute, onRouteSelect, selectedArea, onAreaSelect };
+    const featureHits = useRef([]);
+    const [featureLabels, setFeatureLabels] = useState([]);
     const root = useRef(null);
     const host = useRef(null);
     const mapRef = useRef(null);
     const fitRef = useRef(() => { });
     const paintRef = useRef(() => { });
+    const viewRef = useRef(() => { });
+    const zoomRef = useRef(() => { });
+    const focusRef = useRef(() => { });
     const fitZoomRef = useRef(2);
     const selectionRef = useRef(onPlaceSelect);
     selectionRef.current = onPlaceSelect;
@@ -29,13 +43,28 @@ export function JourneyMap({ places, routes = noRoutes, geography, landCover, wa
     const [placeLabels, setPlaceLabels] = useState([]);
     const selectedRef = useRef(selectedPlace);
     selectedRef.current = selectedPlace;
+    const previousSelection = useRef({ place: selectedPlace, scale: focusZoomScale });
+    const viewOptions = useRef({ animate, animationDuration, focusSelectedPlace, focusZoomScale });
+    viewOptions.current = { animate, animationDuration, focusSelectedPlace, focusZoomScale };
+    const selectPlace = (place, fromList = false) => {
+        if (viewOptions.current.focusSelectedPlace)
+            focusRef.current(place);
+        else if (fromList && mapRef.current)
+            viewRef.current([place.latitude, place.longitude], mapRef.current.getZoom());
+        selectionRef.current?.(place);
+    };
     const markersRef = useRef([]);
+    const renderingOptions = resolveJourneyMapRendering(rendering);
+    const renderingRef = useRef(renderingOptions);
+    renderingRef.current = renderingOptions;
     useEffect(() => {
         let cancelled = false;
         let cleanup;
         setReady(false);
         setFailed(false);
         setPlaceLabels([]);
+        setFeatureLabels([]);
+        featureHits.current = [];
         void import('leaflet').then(L => {
             if (cancelled || !host.current)
                 return;
@@ -65,84 +94,287 @@ export function JourneyMap({ places, routes = noRoutes, geography, landCover, wa
                 layer.eachLayer(collect);
             }
             const routePoints = routes.map(route => route.coordinates.filter(([lat, lng]) => Number.isFinite(lat) && Number.isFinite(lng) && Math.abs(lat) <= 85 && Math.abs(lng) <= 180).map(([lat, lng]) => L.latLng(lat, lng)));
-            const all = [...points.map(place => L.latLng(place.latitude, place.longitude)), ...boundaries.flat(), ...routePoints.flat()];
+            const all = [...points.map(place => L.latLng(place.latitude, place.longitude)), ...boundaries.flat(), ...routePoints.flat(), ...usableAreas.flatMap(area => areaPolygons(area.geometry).flat(2).map(([lng, lat]) => L.latLng(lat, lng)))];
+            const areaLayers = usableAreas.map(area => L.geoJSON(area.geometry, { style: { color: area.color || 'var(--inkra-accent)', weight: 1, opacity: 0, fillOpacity: 0 }, bubblingMouseEvents: false }));
+            const routeLayers = routePoints.map((line, i) => L.polyline(line, { color: routes[i].color || 'var(--inkra-accent)', weight: 18, opacity: 0, bubblingMouseEvents: false }));
+            const captions = [];
+            const caption = (kind, id, label, position) => {
+                const node = document.createElement('span');
+                node.className = 'inkra-journey-map__caption';
+                const marker = L.marker(position, { interactive: false, keyboard: false, icon: L.divIcon({ html: node, className: 'inkra-journey-map__caption-marker', iconSize: [0, 0] }) }).addTo(map);
+                marker.getElement()?.setAttribute('aria-hidden', 'true');
+                captions.push({ kind, id, label, node });
+            };
+            const hit = (layer, kind, id, label, select) => {
+                const path = layer.getElement();
+                if (!path)
+                    return;
+                path.classList.add('inkra-journey-map__feature-hit');
+                featureHits.current.push({ kind, id, label, path });
+                layer.on('click', select);
+                path.addEventListener('keydown', event => {
+                    const key = event.key;
+                    if (key === 'Enter' || key === ' ') {
+                        event.preventDefault();
+                        event.stopPropagation();
+                        select();
+                    }
+                });
+            };
+            areaLayers.forEach((group, i) => {
+                const area = usableAreas[i];
+                group.addTo(map);
+                group.eachLayer(layer => { if (layer instanceof L.Path)
+                    hit(layer, 'area', area.id, area.label, () => annotationSelection.current.onAreaSelect?.(area)); });
+                const [lng, lat] = journeyAreaLabel(area);
+                caption('area', area.id, area.label, [lat, lng]);
+            });
+            routeLayers.forEach((layer, i) => {
+                const route = routes[i];
+                layer.addTo(map);
+                if (routePoints[i].length < 2)
+                    return;
+                hit(layer, 'route', route.id, route.label || route.id, () => annotationSelection.current.onRouteSelect?.(route));
+                if (route.label)
+                    caption('route', route.id, route.label, routePoints[i][Math.floor((routePoints[i].length - 1) / 2)]);
+            });
+            setFeatureLabels(captions);
             let fitted = false;
-            const fit = () => {
+            const fit = (animated = false) => {
                 map.invalidateSize();
                 const size = map.getSize();
                 if (size.x <= 0 || size.y <= 0)
                     return;
-                if (all.length)
-                    map.fitBounds(L.latLngBounds(all), { padding: [44, 44], maxZoom: 12, animate: false });
-                fitZoomRef.current = map.getZoom();
+                if (all.length) {
+                    const bounds = L.latLngBounds(all);
+                    const zoom = Math.min(map.getBoundsZoom(bounds, false, L.point(88, 88)), Number.isFinite(maxFitZoom) ? Math.max(0, Math.min(20, maxFitZoom)) : 12);
+                    const center = map.unproject(map.project(bounds.getSouthWest(), zoom).add(map.project(bounds.getNorthEast(), zoom)).divideBy(2), zoom);
+                    fitZoomRef.current = zoom;
+                    if (animated)
+                        viewRef.current(center, zoom);
+                    else
+                        map.setView(center, zoom, { animate: false });
+                }
+                else
+                    fitZoomRef.current = map.getZoom();
                 fitted = true;
             };
-            fitRef.current = fit;
+            fitRef.current = () => fit(true);
             const canvas = document.createElement('canvas');
             canvas.className = 'inkra-journey-map__ink';
             canvas.setAttribute('aria-hidden', 'true');
             host.current.append(canvas);
+            const base = new JourneyBaseBitmap();
+            const pinSurfaces = [];
+            const paintPins = () => {
+                const style = getComputedStyle(host.current);
+                const defaultInk = style.getPropertyValue('--inkra-accent-strong').trim();
+                const paper = style.getPropertyValue('--inkra-paper').trim();
+                const size = journeyCanvasSize(44, 44, window.devicePixelRatio || 1);
+                for (const pin of pinSurfaces) {
+                    if (pin.place.icon !== undefined && pin.place.icon !== null && pin.place.icon !== false)
+                        continue;
+                    const selected = selectedRef.current === pin.place.id;
+                    pin.canvas.style.color = defaultInk;
+                    if (pin.place.color)
+                        pin.canvas.style.color = pin.place.color;
+                    const ink = getComputedStyle(pin.canvas).color;
+                    const key = JSON.stringify([PENCIL_RENDERER_VERSION, ink, paper, size.dpr, selected]);
+                    if (pin.key === key)
+                        continue;
+                    const context = prepareJourneyCanvas(pin.canvas, size, true);
+                    if (!context)
+                        continue;
+                    paintStop(context, 22, 22, seedToNumber(pin.place.id), ink, paper, selected);
+                    pin.key = key;
+                }
+            };
             let frame = 0;
+            let animating = false, preparingView = false;
+            let activeView;
             let paintOrigin = map.containerPointToLatLng([0, 0]), paintZoom = map.getZoom();
+            let paintWidth = 0, paintHeight = 0, previousSignature = '', previousKey = '';
             const paint = () => {
                 frame = 0;
-                const { x: width, y: height } = map.getSize();
-                if (!width || !height)
+                const viewport = map.getSize();
+                if (!viewport.x || !viewport.y)
                     return;
-                const dpr = Math.min(window.devicePixelRatio || 1, 2);
-                canvas.width = Math.round(width * dpr);
-                canvas.height = Math.round(height * dpr);
-                canvas.style.width = `${width}px`;
-                canvas.style.height = `${height}px`;
-                const context = canvas.getContext('2d');
+                // A small reserve keeps ordinary pans on the compositor. Larger pans
+                // replenish only exposed strips, within the same backing-store budgets.
+                let padding = 64;
+                let size = journeyCanvasSize(viewport.x + padding * 2, viewport.y + padding * 2, window.devicePixelRatio || 1);
+                if (!size) {
+                    padding = 0;
+                    size = journeyCanvasSize(viewport.x, viewport.y, window.devicePixelRatio || 1);
+                }
+                if (!size) {
+                    base.clear();
+                    canvas.width = canvas.height = 0;
+                    return;
+                }
+                const { width, height } = size;
+                const options = renderingRef.current;
+                // Release the old snapshot before resizing the main canvas so the two
+                // live backing stores stay within the combined six-Mi-pixel budget.
+                if (!options.cacheBase || canvas.width !== size.pixelWidth || canvas.height !== size.pixelHeight)
+                    base.clear();
+                const context = prepareJourneyCanvas(canvas, size, options.reuseCanvas);
                 if (!context)
                     return;
-                canvas.style.transform = '';
-                paintOrigin = map.containerPointToLatLng([0, 0]);
-                paintZoom = map.getZoom();
-                context.scale(dpr, dpr);
+                const zoom = map.getZoom();
                 const style = getComputedStyle(host.current);
                 const paper = style.getPropertyValue('--inkra-paper').trim();
                 const dark = Number.parseInt(paper.replace('#', '').slice(0, 2), 16) < 100;
-                const project = (position) => { const point = map.latLngToContainerPoint([position[1], position[0]]); return [point.x, point.y]; };
-                paintSea(context, width, height, project([0, 0]));
-                if (geography)
-                    paintTerrain(context, geography, project, width, height, dark);
-                if (landCover)
-                    paintTerrain(context, landCover, project, width, height, dark);
-                if (water)
-                    paintTerrain(context, water, project, width, height, dark, 'water');
-                const draw = (line, color, seed, weight) => {
-                    const projected = line.map(point => { const p = map.latLngToContainerPoint(point); return [p.x, p.y]; });
-                    pencilStroke(context, projected, color, weight, seed, .3, 3, false, { grain: .7, breaks: .15, variation: .8, gain: 2.5, step: .8 });
+                const border = style.getPropertyValue('--inkra-border-strong').trim();
+                const accent = style.getPropertyValue('--inkra-accent').trim();
+                const colors = featureHits.current.map(item => getComputedStyle(item.path).stroke || accent);
+                const colorLookup = new Map(featureHits.current.map((item, i) => [`${item.kind}:${item.id}`, colors[i]]));
+                const featureColor = (kind, id) => {
+                    const color = colorLookup.get(`${kind}:${id}`);
+                    return color && color !== 'none' ? color : accent;
                 };
-                boundaries.forEach((line, i) => draw(line, style.getPropertyValue('--inkra-border-strong').trim(), i + 137, 1.2));
-                routePoints.forEach((line, i) => draw(line, style.getPropertyValue('--inkra-accent').trim(), i + 717, 2));
-                points.forEach(place => {
-                    const p = map.latLngToContainerPoint([place.latitude, place.longitude]);
-                    paintStop(context, p.x, p.y, seedToNumber(place.id), style.getPropertyValue('--inkra-accent-strong').trim(), paper, selectedRef.current === place.id);
-                });
+                const selection = annotationSelection.current;
+                const project = (position) => { const point = map.latLngToContainerPoint([position[1], position[0]]); return [point.x + padding, point.y + padding]; };
+                const origin = project([0, 0]);
+                // Data belongs to this effect instance. Its cleanup releases the bitmap;
+                // the remaining key covers every base-pixel input that can change in it.
+                const signature = JSON.stringify([PENCIL_RENDERER_VERSION, 'journey-base-v2', background, width, height, size.pixelWidth, size.pixelHeight, size.dpr,
+                    zoom, paper, dark, border, accent, colors, selection.selectedRoute, selection.selectedArea, options.boundaryViewport, options.terrainViewport]);
+                const baseKey = signature + JSON.stringify(origin);
+                const draw = (line, color, seed, weight, x, y, w, h) => {
+                    const projected = line.map(point => { const p = map.latLngToContainerPoint(point); return [p.x + padding - x, p.y + padding - y]; });
+                    pencilStroke(context, projected, color, weight, seed, .3, 3, false, { grain: .7, breaks: .15, variation: .8, gain: 2.5, step: .8,
+                        ...(options.boundaryViewport ? { viewport: [w, h], viewportTop: -8 } : {}) });
+                };
+                if (!options.cacheBase || !base.restore(context, baseKey)) {
+                    const oldOrigin = map.latLngToContainerPoint(paintOrigin);
+                    const offsetX = (oldOrigin.x + padding) * size.dpr, offsetY = (oldOrigin.y + padding) * size.dpr;
+                    const pixelX = Math.round(offsetX), pixelY = Math.round(offsetY);
+                    const dx = pixelX / size.dpr, dy = pixelY / size.dpr;
+                    // Fractional backing-pixel copies would repeatedly blur pencil ink.
+                    // Geographic round trips can add tiny floating-point residue.
+                    const aligned = Math.abs(offsetX - pixelX) < 1e-6 && Math.abs(offsetY - pixelY) < 1e-6;
+                    const shifted = options.cacheBase && previousSignature === signature && aligned
+                        && Math.abs(dx) < width && Math.abs(dy) < height
+                        && base.restore(context, previousKey, [pixelX, pixelY]);
+                    const regions = shifted ? journeyPanRegions(width, height, dx, dy) : [[0, 0, width, height]];
+                    for (const [x, y, w, h] of regions) {
+                        context.save();
+                        context.translate(x, y);
+                        context.beginPath();
+                        context.rect(0, 0, w, h);
+                        context.clip();
+                        const localProject = (position) => { const p = project(position); return [p[0] - x, p[1] - y]; };
+                        if (background === 'sea')
+                            paintSea(context, w, h, localProject([0, 0]));
+                        if (geography)
+                            paintTerrain(context, geography, localProject, w, h, dark, 'land', options.terrainViewport);
+                        if (landCover)
+                            paintTerrain(context, landCover, localProject, w, h, dark, 'land', options.terrainViewport);
+                        if (water)
+                            paintTerrain(context, water, localProject, w, h, dark, 'water', options.terrainViewport);
+                        boundaries.forEach((line, i) => draw(line, border, i + 137, 1.2, x, y, w, h));
+                        [...usableAreas].sort((a, b) => Number(a.id === selection.selectedArea) - Number(b.id === selection.selectedArea)).forEach(area => paintJourneyArea(context, area, localProject, w, h, featureColor('area', area.id), selection.selectedArea === area.id));
+                        routePoints.map((line, i) => ({ line, route: routes[i] })).sort((a, b) => Number(a.route.id === selection.selectedRoute) - Number(b.route.id === selection.selectedRoute)).forEach(({ line, route }) => {
+                            const width = Number.isFinite(route.width) ? Math.max(.5, Math.min(8, route.width)) : 2;
+                            draw(line, featureColor('route', route.id), seedToNumber(route.id), width + (route.id === selection.selectedRoute ? 1 : 0), x, y, w, h);
+                        });
+                        context.restore();
+                    }
+                    if (options.cacheBase)
+                        base.capture(canvas, size, baseKey);
+                }
+                previousSignature = signature;
+                previousKey = baseKey;
+                paintOrigin = map.containerPointToLatLng([-padding, -padding]);
+                paintZoom = zoom;
+                paintWidth = width;
+                paintHeight = height;
+                canvas.style.transformOrigin = '0 0';
+                canvas.style.transform = `translate(${-padding}px, ${-padding}px)`;
             };
-            const schedule = () => { if (!frame)
+            const schedule = () => { paintPins(); if (!animating && !frame)
                 frame = requestAnimationFrame(paint); };
             paintRef.current = schedule;
+            viewRef.current = (center, targetZoom) => {
+                const target = L.latLng(center);
+                const zoom = Math.max(map.getMinZoom(), Math.min(map.getMaxZoom(), targetZoom));
+                if (activeView?.center.equals(target) && activeView.zoom === zoom)
+                    return;
+                map.stop();
+                animating = false;
+                activeView = undefined;
+                const settings = viewOptions.current;
+                const duration = journeyAnimationMs(settings.animate, settings.animationDuration, matchMedia('(prefers-reduced-motion: reduce)').matches);
+                if (!duration || (map.getCenter().equals(target) && map.getZoom() === zoom)) {
+                    map.setView(target, zoom, { animate: false });
+                    if (frame)
+                        cancelAnimationFrame(frame);
+                    paint();
+                    return;
+                }
+                const start = map.getCenter(), startZoom = map.getZoom(), viewport = map.getSize();
+                const from = map.project(start, startZoom), to = map.project(target, startZoom);
+                const extent = Math.max(viewport.x, viewport.y);
+                // Bound Leaflet's flyTo camera envelope (rho² < 2.1), including its
+                // temporary zoom-out. Rasterize it once, then transform that bitmap.
+                const span = extent * (1 + map.getZoomScale(startZoom, zoom)) + 2.1 * from.distanceTo(to);
+                const scale = Math.max((Math.abs(to.x - from.x) + viewport.x * span / extent) / viewport.x, (Math.abs(to.y - from.y) + viewport.y * span / extent) / viewport.y);
+                const overview = map.unproject(from.add(to).divideBy(2), startZoom);
+                animating = true;
+                preparingView = true;
+                if (frame)
+                    cancelAnimationFrame(frame);
+                frame = 0;
+                map.setView(overview, startZoom - Math.log2(scale), { animate: false });
+                paint();
+                map.setView(start, startZoom, { animate: false });
+                preparingView = false;
+                activeView = { center: target, zoom };
+                map.flyTo(target, zoom, { animate: true, duration: duration / 1000 });
+            };
+            zoomRef.current = delta => viewRef.current(activeView?.center ?? map.getCenter(), (activeView?.zoom ?? map.getZoom()) + delta);
+            focusRef.current = place => viewRef.current([place.latitude, place.longitude], journeyFocusZoom(fitZoomRef.current, viewOptions.current.focusZoomScale));
+            const restore = () => { base.clear(); schedule(); };
+            canvas.addEventListener('contextrestored', restore);
             // Reuse the existing raster during a pan; repaint geographical detail on rest.
             const translate = () => {
                 const point = map.latLngToContainerPoint(paintOrigin);
+                const scale = map.getZoomScale(map.getZoom(), paintZoom);
                 canvas.style.transformOrigin = '0 0';
-                canvas.style.transform = `translate(${point.x}px, ${point.y}px) scale(${map.getZoomScale(map.getZoom(), paintZoom)})`;
+                canvas.style.transform = `translate(${point.x}px, ${point.y}px) scale(${scale})`;
+                const viewport = map.getSize();
+                if (!animating && (point.x > 0 || point.y > 0 || point.x + paintWidth * scale < viewport.x || point.y + paintHeight * scale < viewport.y))
+                    schedule();
             };
-            const settle = () => { canvas.style.transform = ''; paintOrigin = map.containerPointToLatLng([0, 0]); paintZoom = map.getZoom(); schedule(); };
+            const settle = () => { if (preparingView)
+                return; animating = false; activeView = undefined; schedule(); };
             map.on('move', translate);
             map.on('moveend zoomend resize', settle);
-            map.on('dragstart', () => map.stop());
+            map.on('dragstart', () => { map.stop(); animating = false; activeView = undefined; });
             const labelNodes = [];
             markersRef.current = points.map(place => {
+                const symbol = document.createElement('span');
+                symbol.className = 'inkra-journey-map__symbol';
+                const ink = document.createElement('canvas');
+                ink.className = 'inkra-journey-map__stop';
+                ink.setAttribute('aria-hidden', 'true');
                 const node = document.createElement('span');
                 node.className = 'inkra-journey-map__pin';
-                labelNodes.push({ place, node });
-                const marker = L.marker([place.latitude, place.longitude], { icon: L.divIcon({ html: node, className: 'inkra-journey-map__marker', iconSize: [44, 44], iconAnchor: [22, 22] }), keyboard: true, title: place.label, alt: place.label }).addTo(map);
-                marker.on('click', () => selectionRef.current?.(place));
+                const icon = document.createElement('span');
+                icon.className = 'inkra-journey-map__custom-icon';
+                if (place.color)
+                    icon.style.color = place.color;
+                const custom = place.icon !== undefined && place.icon !== null && place.icon !== false;
+                ink.hidden = custom;
+                icon.hidden = !custom;
+                symbol.append(ink, icon, node);
+                const pin = { place, canvas: ink, key: '', restore: () => { pin.key = ''; paintPins(); } };
+                ink.addEventListener('contextrestored', pin.restore);
+                pinSurfaces.push(pin);
+                labelNodes.push({ place, node, icon });
+                const marker = L.marker([place.latitude, place.longitude], { icon: L.divIcon({ html: symbol, className: 'inkra-journey-map__marker', iconSize: [44, 44], iconAnchor: [22, 22] }), keyboard: true, title: place.label, alt: place.label }).addTo(map);
+                marker.on('click', () => selectPlace(place));
                 marker.getElement()?.setAttribute('aria-pressed', String(selectedRef.current === place.id));
                 return { place, marker };
             });
@@ -156,31 +388,59 @@ export function JourneyMap({ places, routes = noRoutes, geography, landCover, wa
             }
             const scheme = matchMedia('(prefers-color-scheme: dark)');
             scheme.addEventListener('change', schedule);
+            let resolution;
+            const watchResolution = () => {
+                resolution?.removeEventListener('change', resolutionChanged);
+                resolution = matchMedia(`(resolution: ${window.devicePixelRatio || 1}dppx)`);
+                resolution.addEventListener('change', resolutionChanged);
+            };
+            const resolutionChanged = () => { watchResolution(); schedule(); };
+            watchResolution();
             fit();
             schedule();
             setReady(true);
-            cleanup = () => { cancelAnimationFrame(frame); observer.disconnect(); appearance.disconnect(); scheme.removeEventListener('change', schedule); map.remove(); canvas.remove(); mapRef.current = null; markersRef.current = []; paintRef.current = () => { }; };
+            cleanup = () => { cancelAnimationFrame(frame); observer.disconnect(); appearance.disconnect(); scheme.removeEventListener('change', schedule); resolution.removeEventListener('change', resolutionChanged); canvas.removeEventListener('contextrestored', restore); base.clear(); pinSurfaces.forEach(pin => { pin.canvas.removeEventListener('contextrestored', pin.restore); pin.canvas.width = pin.canvas.height = 0; }); map.remove(); canvas.width = canvas.height = 0; canvas.remove(); mapRef.current = null; markersRef.current = []; featureHits.current = []; paintRef.current = () => { }; viewRef.current = () => { }; zoomRef.current = () => { }; focusRef.current = () => { }; };
         }).catch(() => { if (!cancelled) {
             setFailed(true);
             cleanup?.();
             cleanup = undefined;
         } });
         return () => { cancelled = true; cleanup?.(); };
-    }, [places, routes, geography, landCover, water]);
+    }, [places, routes, areas, geography, landCover, water, maxFitZoom, background]);
     useEffect(() => {
         markersRef.current.forEach(({ place, marker }) => marker.getElement()?.setAttribute('aria-pressed', String(selectedPlace === place.id)));
         paintRef.current();
+        const changed = previousSelection.current.place !== selectedPlace || previousSelection.current.scale !== focusZoomScale;
+        previousSelection.current = { place: selectedPlace, scale: focusZoomScale };
         const place = markersRef.current.find(item => item.place.id === selectedPlace)?.place;
-        if (focusSelectedPlace && place) {
-            const map = mapRef.current;
-            map?.stop();
-            const targetZoom = fitZoomRef.current + Math.log2(10);
-            if (matchMedia('(prefers-reduced-motion: reduce)').matches)
-                map?.setView([place.latitude, place.longitude], targetZoom, { animate: false });
+        if (focusSelectedPlace && changed && place)
+            focusRef.current(place);
+    }, [selectedPlace, focusSelectedPlace, focusZoomScale, ready]);
+    useEffect(() => {
+        for (const item of featureHits.current) {
+            const enabled = item.kind === 'route' ? Boolean(onRouteSelect) : Boolean(onAreaSelect);
+            const selected = item.id === (item.kind === 'route' ? selectedRoute : selectedArea);
+            item.path.style.pointerEvents = enabled ? 'auto' : 'none';
+            item.path.setAttribute('role', enabled ? 'button' : 'img');
+            item.path.setAttribute('tabindex', enabled ? '0' : '-1');
+            item.path.setAttribute('aria-label', item.label);
+            if (enabled)
+                item.path.setAttribute('aria-pressed', String(selected));
             else
-                map?.flyTo([place.latitude, place.longitude], targetZoom, { duration: .85 });
+                item.path.removeAttribute('aria-pressed');
         }
-    }, [selectedPlace, focusSelectedPlace, ready]);
+        // Keep native hit order consistent with the painted selected-on-top order.
+        const order = [...featureHits.current].sort((a, b) => {
+            if (a.kind !== b.kind)
+                return a.kind === 'area' ? -1 : 1;
+            const selected = a.kind === 'area' ? selectedArea : selectedRoute;
+            return Number(a.id === selected) - Number(b.id === selected);
+        });
+        for (const item of order)
+            item.path.parentNode?.appendChild(item.path);
+        paintRef.current();
+    }, [selectedRoute, selectedArea, Boolean(onRouteSelect), Boolean(onAreaSelect), ready]);
+    useEffect(() => { paintRef.current(); }, [renderingOptions.boundaryViewport, renderingOptions.terrainViewport, renderingOptions.reuseCanvas, renderingOptions.cacheBase]);
     useEffect(() => {
         const map = mapRef.current;
         if (!map || !ready)
@@ -195,6 +455,8 @@ export function JourneyMap({ places, routes = noRoutes, geography, landCover, wa
             map.scrollWheelZoom.enable();
         else
             map.scrollWheelZoom.disable();
+        if (interactive && host.current)
+            return attachJourneyTrackpad(host.current, map);
     }, [interactive, scrollWheelZoom, ready]);
-    return _jsxs("div", { ...props, ref: root, className: ['inkra-journey-map', className].filter(Boolean).join(' '), children: [placeLabels.map(({ place, node }) => createPortal(_jsx(PencilText, { children: place.label }), node, place.id)), _jsxs("div", { className: "inkra-journey-map__viewport", style: { height: Math.max(240, Math.min(800, height)) }, children: [attributionDisplay === 'popover' && _jsx("div", { className: "inkra-journey-map__credits", children: _jsxs(Popover.Root, { children: [_jsx(Popover.Trigger, { asChild: true, children: _jsx(Button, { size: "icon", variant: "ghost", "aria-label": labels.attribution ?? t('map.credits'), title: labels.attribution ?? t('map.credits'), children: _jsx(TravelIcon, { name: "info" }) }) }), _jsx(Popover.Portal, { children: _jsxs(Popover.Content, { align: "end", sideOffset: 8, collisionPadding: 20, className: "inkra-journey-map__credits-content", children: [_jsx(Popover.Title, { children: labels.attribution ?? t('map.credits') }), _jsx(Popover.Description, { children: attribution })] }) })] }) }), _jsx("div", { ref: host, className: "inkra-journey-map__host", "aria-label": props['aria-label'] ?? t('map.label') }), showControls && _jsxs("div", { className: "inkra-journey-map__tools", children: [_jsx(Button, { size: "icon", variant: "ghost", disabled: !ready, "aria-label": labels.zoomIn, title: labels.zoomIn, onClick: () => { mapRef.current?.stop(); mapRef.current?.zoomIn(); }, children: _jsx(TravelIcon, { name: "plus" }) }), _jsx(Button, { size: "icon", variant: "ghost", disabled: !ready, "aria-label": labels.zoomOut, title: labels.zoomOut, onClick: () => { mapRef.current?.stop(); mapRef.current?.zoomOut(); }, children: _jsx(TravelIcon, { name: "minus" }) }), _jsx(Button, { size: "icon", variant: "ghost", disabled: !ready, "aria-label": labels.reset, title: labels.reset, onClick: () => { mapRef.current?.stop(); fitRef.current(); }, children: _jsx(TravelIcon, { name: "reset" }) })] }), ready && _jsx(MapScale, { map: mapRef.current }), failed && _jsx("p", { role: "status", children: labels.unavailable })] }), attributionDisplay === 'inline' && _jsx("p", { className: "inkra-journey-map__attribution", children: attribution }), (showPlaceList || !ready || failed) && _jsx("ol", { className: "inkra-journey-map__places", children: places.filter(valid).map((place, index) => _jsx("li", { children: _jsxs("button", { type: "button", "aria-pressed": selectedPlace === place.id, onClick: () => { mapRef.current?.panTo([place.latitude, place.longitude], { animate: false }); onPlaceSelect?.(place); }, children: [_jsx("span", { "aria-hidden": "true", children: index + 1 }), _jsx(PencilText, { children: place.label })] }) }, place.id)) })] });
+    return _jsxs("div", { ...props, ref: root, className: ['inkra-journey-map', className].filter(Boolean).join(' '), children: [placeLabels.map(({ place, node, icon }) => _jsxs("span", { className: "inkra-journey-map__portal-owner", children: [createPortal(_jsx(PencilText, { children: place.label }), node), createPortal(place.icon, icon)] }, place.id)), featureLabels.map(({ kind, id, label, node }) => createPortal(_jsx(PencilSurface, { variant: "paper", radius: 4, className: "inkra-journey-map__feature-label", "data-selected": id === (kind === 'area' ? selectedArea : selectedRoute), children: _jsx(PencilText, { children: label }) }), node, `${kind}:${id}`)), _jsxs("div", { className: "inkra-journey-map__viewport", style: { height: Math.max(240, Math.min(800, height)) }, children: [attributionDisplay === 'popover' && _jsx("div", { className: "inkra-journey-map__credits", children: _jsxs(Popover.Root, { children: [_jsx(Popover.Trigger, { asChild: true, children: _jsx(Button, { size: "icon", variant: "ghost", "aria-label": labels.attribution ?? t('map.credits'), title: labels.attribution ?? t('map.credits'), children: _jsx(TravelIcon, { name: "info" }) }) }), _jsx(Popover.Portal, { children: _jsxs(Popover.Content, { align: "end", sideOffset: 8, collisionPadding: 20, className: "inkra-journey-map__credits-content", children: [_jsx(Popover.Title, { children: labels.attribution ?? t('map.credits') }), _jsx(Popover.Description, { children: attribution })] }) })] }) }), _jsx("div", { ref: host, className: "inkra-journey-map__host", "aria-label": props['aria-label'] ?? t('map.label') }), showControls && _jsxs("div", { className: "inkra-journey-map__tools", children: [_jsx(Button, { size: "icon", variant: "ghost", disabled: !ready, "aria-label": labels.zoomIn, title: labels.zoomIn, onClick: () => zoomRef.current(1), children: _jsx(TravelIcon, { name: "plus" }) }), _jsx(Button, { size: "icon", variant: "ghost", disabled: !ready, "aria-label": labels.zoomOut, title: labels.zoomOut, onClick: () => zoomRef.current(-1), children: _jsx(TravelIcon, { name: "minus" }) }), _jsx(Button, { size: "icon", variant: "ghost", disabled: !ready, "aria-label": labels.reset, title: labels.reset, onClick: () => { mapRef.current?.stop(); fitRef.current(); }, children: _jsx(TravelIcon, { name: "reset" }) })] }), ready && _jsx(MapScale, { map: mapRef.current }), failed && _jsx("p", { role: "status", children: labels.unavailable })] }), attributionDisplay === 'inline' && _jsx("p", { className: "inkra-journey-map__attribution", children: attribution }), (showPlaceList || !ready || failed) && _jsx("ol", { className: "inkra-journey-map__places", children: places.filter(valid).map((place, index) => _jsx("li", { children: _jsxs("button", { type: "button", "aria-pressed": selectedPlace === place.id, onClick: () => selectPlace(place, true), children: [_jsx("span", { "aria-hidden": "true", children: index + 1 }), _jsx(PencilText, { children: place.label })] }) }, place.id)) }), (showFeatureList || !ready || failed) && (routes.length > 0 || usableAreas.length > 0) && _jsxs("ol", { className: "inkra-journey-map__features", "aria-label": labels.features, children: [routes.map(route => _jsx("li", { children: onRouteSelect ? _jsx("button", { type: "button", "aria-pressed": selectedRoute === route.id, onClick: () => onRouteSelect(route), children: _jsx(PencilText, { children: route.label || route.id }) }) : _jsx(PencilText, { children: route.label || route.id }) }, `route:${route.id}`)), usableAreas.map(area => _jsx("li", { children: onAreaSelect ? _jsx("button", { type: "button", "aria-pressed": selectedArea === area.id, onClick: () => onAreaSelect(area), children: _jsx(PencilText, { children: area.label }) }) : _jsx(PencilText, { children: area.label }) }, `area:${area.id}`))] })] });
 }

package/dist/journey-map/rendering.d.ts

@@ -0,0 +1,36 @@
+/** Independent rendering strategies; omitted options inherit the auto defaults. */
+export interface JourneyMapRenderingOptions {
+    /** Reject offscreen boundary/route stroke segments without changing their samples. */
+    boundaryViewport?: boolean;
+    /** Skip terrain cells whose entire ink envelope misses the polygon row band. */
+    terrainViewport?: boolean;
+    /** Keep an unchanged backing size and explicitly clear/reset the drawing transform. */
+    reuseCanvas?: boolean;
+    /** Reuse one bounded base bitmap when only place selection changes. */
+    cacheBase?: boolean;
+}
+export type JourneyMapRendering = 'auto' | 'legacy' | JourneyMapRenderingOptions;
+export declare function journeyAnimationMs(animate: boolean, duration: number, reducedMotion: boolean): number;
+export declare function journeyFocusZoom(overviewZoom: number, scale: number): number;
+export declare function resolveJourneyMapRendering(rendering?: JourneyMapRendering): Required<JourneyMapRenderingOptions>;
+export interface JourneyCanvasSize {
+    width: number;
+    height: number;
+    pixelWidth: number;
+    pixelHeight: number;
+    dpr: number;
+}
+/** Non-overlapping newly exposed strips after moving an existing base bitmap. */
+export declare function journeyPanRegions(width: number, height: number, dx: number, dy: number): readonly (readonly [number, number, number, number])[];
+/** Pure and SSR safe: browser DPR is supplied by the caller. */
+export declare function journeyCanvasSize(width: number, height: number, requestedDpr: number): JourneyCanvasSize | undefined;
+export declare function prepareJourneyCanvas(canvas: HTMLCanvasElement, size: JourneyCanvasSize, reuse: boolean): CanvasRenderingContext2D | null;
+/** Per-map, memory-only, single-entry cache. No DOM or allocation until capture. */
+export declare class JourneyBaseBitmap {
+    private canvas;
+    private key;
+    private readonly invalidate;
+    restore(context: CanvasRenderingContext2D, key: string, offset?: readonly [number, number]): boolean;
+    capture(source: HTMLCanvasElement, size: JourneyCanvasSize, key: string): void;
+    clear(): void;
+}