@inkra/react 0.12.0 → 0.13.0

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

@@ -1,5 +1,7 @@
 import { type HTMLAttributes } from 'react';
 import type { GeoJsonObject } from 'geojson';
+import { type JourneyMapRendering } from './rendering.js';
+export type { JourneyMapRendering, JourneyMapRenderingOptions } from './rendering.js';
 export interface JourneyPlace {
     id: string;
     label: string;
@@ -22,12 +24,25 @@ export interface JourneyMapProps extends HTMLAttributes<HTMLDivElement> {
     attribution: string;
     attributionDisplay?: 'inline' | 'popover';
     height?: number;
+    /** Maximum zoom used by fit/reset; 0..20, default 12. Use 18 for street-scale data. */
+    maxFitZoom?: number;
+    /** Paper suits street diagrams without an ocean layer; default sea. */
+    background?: 'sea' | 'paper';
     /** Controls viewport gestures, not place selection or explicit zoom buttons. */
     interactive?: boolean;
     scrollWheelZoom?: boolean;
     showControls?: boolean;
     showPlaceList?: boolean;
+    /** Focus pin/list clicks and later selectedPlace changes; initial view stays fitted. */
     focusSelectedPlace?: boolean;
+    /** Magnification relative to the initial overview, 1..64; default 2. */
+    focusZoomScale?: number;
+    /** Animate programmatic view changes; reduced-motion preference always wins. */
+    animate?: boolean;
+    /** View transition duration in milliseconds, 0..5000; default 420. */
+    animationDuration?: number;
+    /** Auto uses bounded base caching, backing-store reuse and offscreen stroke rejection. */
+    rendering?: JourneyMapRendering;
     labels?: {
         zoomIn: string;
         zoomOut: string;
@@ -36,4 +51,4 @@ export interface JourneyMapProps extends HTMLAttributes<HTMLDivElement> {
         attribution?: string;
     };
 }
-export declare function JourneyMap({ places, routes, geography, landCover, water, selectedPlace, onPlaceSelect, attribution, attributionDisplay, height, interactive, scrollWheelZoom, showControls, showPlaceList, focusSelectedPlace, labels: labelOverrides, className, ...props }: JourneyMapProps): import("react").JSX.Element;
+export declare function JourneyMap({ places, routes, geography, landCover, water, selectedPlace, onPlaceSelect, attribution, attributionDisplay, height, maxFitZoom, background, interactive, scrollWheelZoom, showControls, showPlaceList, focusSelectedPlace, focusZoomScale, animate, animationDuration, rendering, labels: labelOverrides, className, ...props }: JourneyMapProps): import("react").JSX.Element;

package/dist/journey-map/index.js

@@ -10,10 +10,12 @@ import { TravelIcon } from '../internal/travelIcons.js';
 import { paintTerrain, paintStop, paintSea } from './terrain.js';
 import { MapScale } from './MapScale.js';
 import { seedToNumber } from '../internal/random.js';
+import { PENCIL_RENDERER_VERSION } from '../internal/cache.js';
+import { JourneyBaseBitmap, journeyAnimationMs, journeyCanvasSize, journeyFocusZoom, journeyPanRegions, prepareJourneyCanvas, resolveJourneyMapRendering } from './rendering.js';
 const defaults = (t) => ({ zoomIn: t('common.zoomIn'), zoomOut: t('common.zoomOut'), reset: t('common.resetView'), unavailable: t('map.unavailable') });
 const noRoutes = [];
 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, 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 root = useRef(null);
@@ -21,6 +23,9 @@ export function JourneyMap({ places, routes = noRoutes, geography, landCover, wa
     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,7 +34,20 @@ 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;
@@ -67,82 +85,217 @@ export function JourneyMap({ places, routes = noRoutes, geography, landCover, wa
             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()];
             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 ink = 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) {
+                    const selected = selectedRef.current === pin.place.id;
+                    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;
+                // 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 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');
+                }
+                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 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, 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 } : {}) });
                 };
-                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);
-                });
+                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));
+                        routePoints.forEach((line, i) => draw(line, accent, i + 717, 2, 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';
+                symbol.append(ink, node);
+                const pin = { place, canvas: ink, key: '', restore: () => { pin.key = ''; paintPins(); } };
+                ink.addEventListener('contextrestored', pin.restore);
+                pinSurfaces.push(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 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 +309,35 @@ 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 = []; 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, 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 });
-            else
-                map?.flyTo([place.latitude, place.longitude], targetZoom, { duration: .85 });
-        }
-    }, [selectedPlace, focusSelectedPlace, ready]);
+        if (focusSelectedPlace && changed && place)
+            focusRef.current(place);
+    }, [selectedPlace, focusSelectedPlace, focusZoomScale, ready]);
+    useEffect(() => { paintRef.current(); }, [renderingOptions.boundaryViewport, renderingOptions.terrainViewport, renderingOptions.reuseCanvas, renderingOptions.cacheBase]);
     useEffect(() => {
         const map = mapRef.current;
         if (!map || !ready)
@@ -196,5 +353,5 @@ export function JourneyMap({ places, routes = noRoutes, geography, landCover, wa
         else
             map.scrollWheelZoom.disable();
     }, [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 }) => 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: () => 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)) })] });
 }

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;
+}

package/dist/journey-map/rendering.js

@@ -0,0 +1,144 @@
+export function journeyAnimationMs(animate, duration, reducedMotion) {
+    if (!animate || reducedMotion)
+        return 0;
+    return Number.isFinite(duration) ? Math.max(0, Math.min(duration, 5000)) : 420;
+}
+export function journeyFocusZoom(overviewZoom, scale) {
+    const ratio = Number.isFinite(scale) && scale >= 1 ? Math.min(scale, 64) : 2;
+    return overviewZoom + Math.log2(ratio);
+}
+export function resolveJourneyMapRendering(rendering = 'auto') {
+    if (rendering === 'legacy')
+        return { boundaryViewport: false, terrainViewport: false, reuseCanvas: false, cacheBase: false };
+    const options = typeof rendering === 'object' ? rendering : {};
+    return {
+        boundaryViewport: options.boundaryViewport ?? true,
+        terrainViewport: options.terrainViewport ?? true,
+        reuseCanvas: options.reuseCanvas ?? true,
+        cacheBase: options.cacheBase ?? true,
+    };
+}
+const MAX_SIDE = 8192;
+const MAX_LAYER_PIXELS = 4 * 1024 * 1024;
+// One base bitmap per map; together with the visible bitmap, at most 6 Mi pixels.
+const MAX_BASE_PIXELS = 3 * 1024 * 1024;
+/** Non-overlapping newly exposed strips after moving an existing base bitmap. */
+export function journeyPanRegions(width, height, dx, dy) {
+    if (Math.abs(dx) >= width || Math.abs(dy) >= height)
+        return [[0, 0, width, height]];
+    const regions = [];
+    if (dx)
+        regions.push([dx > 0 ? 0 : width + dx, 0, Math.abs(dx), height]);
+    if (dy)
+        regions.push([Math.max(0, dx), dy > 0 ? 0 : height + dy, width - Math.abs(dx), Math.abs(dy)]);
+    return regions;
+}
+/** Pure and SSR safe: browser DPR is supplied by the caller. */
+export function journeyCanvasSize(width, height, requestedDpr) {
+    if (![width, height].every(value => Number.isFinite(value) && value > 0))
+        return;
+    const requested = Number.isFinite(requestedDpr) ? Math.max(1, Math.min(requestedDpr, 2)) : 1;
+    const dpr = Math.min(requested, MAX_SIDE / width, MAX_SIDE / height, Math.sqrt(MAX_LAYER_PIXELS / (width * height)));
+    if (dpr < 1)
+        return;
+    const pixelWidth = Math.round(width * dpr), pixelHeight = Math.round(height * dpr);
+    // Round-down adjustment prevents rounding the two sides over the pixel budget.
+    const boundedDpr = pixelWidth * pixelHeight > MAX_LAYER_PIXELS
+        ? Math.min(dpr, Math.floor(width * dpr) / width, Math.floor(height * dpr) / height) : dpr;
+    return { width, height, pixelWidth: Math.round(width * boundedDpr), pixelHeight: Math.round(height * boundedDpr), dpr: boundedDpr };
+}
+function releaseCanvas(canvas) {
+    canvas.width = 0;
+    canvas.height = 0;
+}
+export function prepareJourneyCanvas(canvas, size, reuse) {
+    const changed = canvas.width !== size.pixelWidth || canvas.height !== size.pixelHeight;
+    if (changed)
+        releaseCanvas(canvas); // Avoid an oversized intermediate width/height swap.
+    if (changed || !reuse) {
+        canvas.width = size.pixelWidth;
+        canvas.height = size.pixelHeight;
+    }
+    canvas.style.width = `${size.width}px`;
+    canvas.style.height = `${size.height}px`;
+    const context = canvas.getContext('2d');
+    if (!context || context.isContextLost?.())
+        return null;
+    // Never accumulate DPR transforms when the backing store is reused.
+    context.setTransform(1, 0, 0, 1, 0, 0);
+    context.globalAlpha = 1;
+    context.globalCompositeOperation = 'source-over';
+    context.clearRect(0, 0, size.pixelWidth, size.pixelHeight);
+    context.setTransform(size.dpr, 0, 0, size.dpr, 0, 0);
+    return context;
+}
+/** Per-map, memory-only, single-entry cache. No DOM or allocation until capture. */
+export class JourneyBaseBitmap {
+    constructor() {
+        this.invalidate = () => { this.key = undefined; };
+    }
+    restore(context, key, offset = [0, 0]) {
+        if (key !== this.key || !this.canvas)
+            return false;
+        const cachedContext = this.canvas.getContext('2d');
+        if (!cachedContext || cachedContext.isContextLost?.()) {
+            this.clear();
+            return false;
+        }
+        try {
+            context.save();
+            context.setTransform(1, 0, 0, 1, 0, 0);
+            context.drawImage(this.canvas, offset[0], offset[1]);
+            return true;
+        }
+        catch {
+            this.clear();
+            return false;
+        }
+        finally {
+            context.restore();
+        }
+    }
+    capture(source, size, key) {
+        if (size.pixelWidth * size.pixelHeight > MAX_BASE_PIXELS) {
+            this.clear();
+            return;
+        }
+        try {
+            const canvas = this.canvas ?? document.createElement('canvas');
+            if (!this.canvas) {
+                canvas.addEventListener('contextlost', this.invalidate);
+                canvas.addEventListener('contextrestored', this.invalidate);
+                this.canvas = canvas;
+            }
+            this.key = undefined;
+            if (canvas.width !== size.pixelWidth || canvas.height !== size.pixelHeight) {
+                releaseCanvas(canvas);
+                canvas.width = size.pixelWidth;
+                canvas.height = size.pixelHeight;
+            }
+            const context = canvas.getContext('2d');
+            if (!context || context.isContextLost?.()) {
+                this.clear();
+                return;
+            }
+            context.setTransform(1, 0, 0, 1, 0, 0);
+            context.clearRect(0, 0, size.pixelWidth, size.pixelHeight);
+            context.drawImage(source, 0, 0);
+            this.key = key;
+        }
+        catch {
+            // Allocation/copy failures affect optimization, never the already drawn map.
+            this.clear();
+        }
+    }
+    clear() {
+        this.key = undefined;
+        if (!this.canvas)
+            return;
+        this.canvas.removeEventListener('contextlost', this.invalidate);
+        this.canvas.removeEventListener('contextrestored', this.invalidate);
+        releaseCanvas(this.canvas);
+        this.canvas = undefined;
+    }
+}

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

@@ -3,6 +3,9 @@ import { type PencilPoint } from '../internal/stroke.js';
 type Project = (position: Position) => PencilPoint;
 export declare function paintSea(ctx: CanvasRenderingContext2D, width: number, height: number, anchor: PencilPoint): void;
 export declare function mapFeatures(data: GeoJsonObject): Feature[];
-export declare function paintTerrain(ctx: CanvasRenderingContext2D, data: GeoJsonObject, project: Project, width: number, height: number, dark: boolean, defaultKind?: string): void;
+/** Conservative x bounds of polygon edges inside a horizontal strip.
+ * Hole rings may widen the bounds, but never remove visible fill. */
+export declare function terrainRowBounds(rings: readonly (readonly PencilPoint[])[], top: number, bottom: number): readonly [number, number] | undefined;
+export declare function paintTerrain(ctx: CanvasRenderingContext2D, data: GeoJsonObject, project: Project, width: number, height: number, dark: boolean, defaultKind?: string, terrainViewport?: boolean): void;
 export declare function paintStop(ctx: CanvasRenderingContext2D, x: number, y: number, seed: number, color: string, paper: string, selected: boolean): void;
 export {};

package/dist/journey-map/terrain.js

@@ -45,7 +45,31 @@ export function mapFeatures(data) {
         return [data];
     return [{ type: 'Feature', properties: {}, geometry: data }];
 }
-export function paintTerrain(ctx, data, project, width, height, dark, defaultKind = 'land') {
+/** Conservative x bounds of polygon edges inside a horizontal strip.
+ * Hole rings may widen the bounds, but never remove visible fill. */
+export function terrainRowBounds(rings, top, bottom) {
+    let left = Infinity, right = -Infinity;
+    for (const ring of rings)
+        for (let i = 0; i < ring.length; i++) {
+            const [ax, ay] = ring[i], [bx, by] = ring[(i + 1) % ring.length];
+            if ((ay < top && by < top) || (ay > bottom && by > bottom))
+                continue;
+            if (!Number.isFinite(ax) || !Number.isFinite(ay) || !Number.isFinite(bx) || !Number.isFinite(by))
+                return [-Infinity, Infinity];
+            if (ay === by) {
+                left = Math.min(left, ax, bx);
+                right = Math.max(right, ax, bx);
+                continue;
+            }
+            const low = Math.max(0, Math.min(1, (top - ay) / (by - ay)));
+            const high = Math.max(0, Math.min(1, (bottom - ay) / (by - ay)));
+            const x1 = ax + (bx - ax) * low, x2 = ax + (bx - ax) * high;
+            left = Math.min(left, x1, x2);
+            right = Math.max(right, x1, x2);
+        }
+    return left <= right ? [left, right] : undefined;
+}
+export function paintTerrain(ctx, data, project, width, height, dark, defaultKind = 'land', terrainViewport = false) {
     for (const [featureIndex, feature] of mapFeatures(data).entries()) {
         const geometry = feature.geometry;
         if (!geometry)
@@ -87,7 +111,15 @@ export function paintTerrain(ctx, data, project, width, height, dark, defaultKin
             const spacing = kind === 'forest' ? 9 : 13;
             const seed = 21000 + featureIndex * 43 + polygonIndex;
             for (let row = Math.floor((top - origin[1]) / spacing); row <= Math.ceil((bottom - origin[1]) / spacing); row++) {
-                for (let col = Math.floor((left - origin[0]) / 36); col <= Math.ceil((right - origin[0]) / 36); col++) {
+                // Jitter, the 44px hatch, category glyphs and pencil bleed all fit this
+                // envelope. Keep the original world-grid indices and per-cell seeds.
+                const rowY = origin[1] + row * spacing;
+                const band = terrainViewport ? terrainRowBounds(rings, rowY - 25, rowY + 20) : [left, right];
+                if (!band)
+                    continue;
+                const first = Math.max(Math.floor((left - origin[0]) / 36), terrainViewport ? Math.ceil((band[0] - origin[0] - 68) / 36) : -Infinity);
+                const last = Math.min(Math.ceil((right - origin[0]) / 36), terrainViewport ? Math.floor((band[1] - origin[0] + 17) / 36) : Infinity);
+                for (let col = first; col <= last; col++) {
                     const cell = (seed ^ Math.imul(col, 73856093) ^ Math.imul(row, 19349663)) >>> 0;
                     const rng = seededRandom(cell);
                     if (rng() < .2)

package/dist/styles/journey-map.css

@@ -1,9 +1,11 @@
 .inkra-journey-map { min-width: 0; width: 100%; color: var(--inkra-ink); }
 .inkra-journey-map__viewport { position: relative; overflow: hidden; isolation: isolate; background: var(--inkra-paper); }
 .inkra-journey-map__host { position: absolute; inset: 0; background: transparent; font: inherit; }
-.inkra-journey-map__ink { position: absolute; inset: 0; pointer-events: none; z-index: 350; }
+.inkra-journey-map__ink { position: absolute; top: 0; left: 0; pointer-events: none; z-index: 350; }
 .inkra-journey-map__tools { position: absolute; z-index: 600; inset-block-end: 9px; inset-inline-start: 9px; display: grid; gap: 4px; }
 .inkra-journey-map__marker { display: grid; place-items: center; }
+.inkra-journey-map__symbol, .inkra-journey-map__stop { display: block; width: 44px; height: 44px; }
+.inkra-journey-map__stop { pointer-events: none; }
 .inkra-journey-map__pin { position: absolute; top: 37px; left: 50%; transform: translateX(-50%); width: max-content; max-width: 140px; text-align: center; color: var(--inkra-ink); font: 14px/1.4 var(--inkra-font-hand); }
 .inkra-journey-map__marker[aria-pressed="true"] .inkra-journey-map__pin { color: var(--inkra-accent-strong); }
 .inkra-journey-map__orientation { position: absolute; bottom: 18px; right: 18px; z-index: 600; display: flex; align-items: end; gap: 12px; pointer-events: none; }

package/dist/styles/markdown.css

@@ -1,4 +1,5 @@
 .inkra-markdown {
+  inline-size: 100%;
   color: var(--inkra-ink);
   font-family: var(--inkra-font-body);
   font-size: var(--inkra-text-md);
@@ -203,6 +204,7 @@
 .inkra-markdown__code-text > .inkra-pencil-text__source { font-family: inherit; }
 
 .inkra-markdown__code-frame {
+  inline-size: 100%;
   margin-block: 0 var(--inkra-space-4);
   max-width: 100%;
   min-width: 0;

package/dist/styles.css

@@ -8781,6 +8781,7 @@ div.inkra-choice-grid > .inkra-radio-group {
 }
 
 .inkra-markdown {
+  inline-size: 100%;
   color: var(--inkra-ink);
   font-family: var(--inkra-font-body);
   font-size: var(--inkra-text-md);
@@ -8985,6 +8986,7 @@ div.inkra-choice-grid > .inkra-radio-group {
 .inkra-markdown__code-text > .inkra-pencil-text__source { font-family: inherit; }
 
 .inkra-markdown__code-frame {
+  inline-size: 100%;
   margin-block: 0 var(--inkra-space-4);
   max-width: 100%;
   min-width: 0;
@@ -10018,9 +10020,11 @@ svg.leaflet-image-layer.leaflet-interactive path {
 .inkra-journey-map { min-width: 0; width: 100%; color: var(--inkra-ink); }
 .inkra-journey-map__viewport { position: relative; overflow: hidden; isolation: isolate; background: var(--inkra-paper); }
 .inkra-journey-map__host { position: absolute; inset: 0; background: transparent; font: inherit; }
-.inkra-journey-map__ink { position: absolute; inset: 0; pointer-events: none; z-index: 350; }
+.inkra-journey-map__ink { position: absolute; top: 0; left: 0; pointer-events: none; z-index: 350; }
 .inkra-journey-map__tools { position: absolute; z-index: 600; inset-block-end: 9px; inset-inline-start: 9px; display: grid; gap: 4px; }
 .inkra-journey-map__marker { display: grid; place-items: center; }
+.inkra-journey-map__symbol, .inkra-journey-map__stop { display: block; width: 44px; height: 44px; }
+.inkra-journey-map__stop { pointer-events: none; }
 .inkra-journey-map__pin { position: absolute; top: 37px; left: 50%; transform: translateX(-50%); width: max-content; max-width: 140px; text-align: center; color: var(--inkra-ink); font: 14px/1.4 var(--inkra-font-hand); }
 .inkra-journey-map__marker[aria-pressed="true"] .inkra-journey-map__pin { color: var(--inkra-accent-strong); }
 .inkra-journey-map__orientation { position: absolute; bottom: 18px; right: 18px; z-index: 600; display: flex; align-items: end; gap: 12px; pointer-events: none; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inkra/react",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Hand-drawn React controls with native semantics and deterministic decoration.",
   "type": "module",
   "license": "MIT",