@cratis/components 3.4.0 → 3.5.0

package/dist/esm/Canvas/Canvas.js

@@ -0,0 +1,767 @@
+import { jsxs, jsx } from 'react/jsx-runtime';
+import React, { useRef, useState, useCallback, useEffect, useMemo } from 'react';
+import * as PIXI from 'pixi.js';
+import { LAYER_ATTR, TRANSFORM_HOST_ATTR } from './glassAttributes.js';
+import { CanvasControls } from './CanvasControls.js';
+import { canvasGesture } from './canvasGesture.js';
+import { canvasTransformActivity } from './canvasTransformActivity.js';
+import { isBackgroundPointerTarget } from './isBackgroundPointerTarget.js';
+import { isWithinScrollableContent } from './isWithinScrollableContent.js';
+import { velocityFromSamples, trimSamples, decayVelocity } from './panMomentum.js';
+import { pinchSnapshotOf, pinchChangeBetween } from './pinchGesture.js';
+import { useDragSelectionGuard } from './useDragSelectionGuard.js';
+import { applyZoomLayer, shouldUseCssZoom, isMultiTouchCapableDevice } from './zoomMechanism.js';
+
+/**
+ * The easing curve for programmatic camera moves: a cubic ease-in-out, so the camera picks up speed gently
+ * and settles gently instead of starting at full tilt — the difference between a camera move and a yank.
+ * @param progress Linear progress through the animation, 0 to 1.
+ * @returns The eased progress.
+ */
+function easeInOutCubic(progress) {
+    return progress < 0.5
+        ? 4 * progress * progress * progress
+        : 1 - Math.pow(-2 * progress + 2, 3) / 2;
+}
+const CanvasItemRegistryContext = React.createContext(null);
+const ZOOM_INTENSITY = 0.008;
+// How long after the last wheel event a gesture counts as settled - the moment the crisp resting zoom is
+// re-applied and the held-back virtualization updates flush.
+const GESTURE_SETTLE_MS = 150;
+// A trackpad's momentum comes for free — the OS keeps delivering decaying wheel events after the
+// fingers lift. A touch drag has no such thing: `touch-action: none` hands the whole gesture to us,
+// so lifting a finger stops the pan dead unless we fake the same decay ourselves. These tune that feel.
+// Only samples within this trailing window (from the drag's last moment, not its whole history)
+// contribute to the release velocity, so a drag that was moving fast but came to rest before the
+// finger actually lifted correctly produces no momentum.
+const MOMENTUM_SAMPLE_WINDOW_MS = 100;
+// Below this speed (px/ms) momentum is imperceptible — used both to skip starting it on a slow
+// release and to end the decay loop once it coasts down to a stop.
+const MOMENTUM_MIN_VELOCITY = 0.02;
+function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady, onTransformChange, onHandleReady, initialZoom = 1, initialPan = { x: 0, y: 0 }, minZoom = 0.1, maxZoom = 5, showControls = true, showMinimap = false, minimapWorldWidth, minimapWorldHeight, minimapItems, controlsPlacement = 'bottom-left', className, style, onHelp, helpTitle, disableControlsGlass = false, readOnly = false, backgroundDragPans = true, }) {
+    const containerRef = useRef(null);
+    useDragSelectionGuard(containerRef);
+    const appRef = useRef(null);
+    const worldRef = useRef(null);
+    const minimapRef = useRef(null);
+    const overlayRef = useRef(null);
+    const zoomLayerRef = useRef(null);
+    const spritesRef = useRef(new Map());
+    const animationFrameRef = useRef(null);
+    const [pixiReady, setPixiReady] = useState(false);
+    // Mutable refs so event callbacks always read current values without re-binding
+    const panRef = useRef({ x: initialPan.x, y: initialPan.y });
+    const zoomRef = useRef(initialZoom);
+    // The transform styles rendered by JSX are frozen at their first-mount values: after mount the
+    // overlay/zoom-layer styles are owned exclusively by the imperative per-frame writes. If the JSX
+    // re-rendered them from live props (a parent may persist and echo the transform back through
+    // `initialPan`/`initialZoom`), a React commit racing a gesture would rewrite the styles with
+    // stale values — visible as the viewport flicking to an old position and back.
+    const initialTransformRef = useRef({ pan: initialPan, zoom: initialZoom });
+    // Wheel gestures coalesce onto animation frames (trackpads deliver several events per frame, and each
+    // direct style write would reflow), and while a gesture is in motion the zoom layer stays on the
+    // composited transform path with virtualization told to hold still. The settle timer restores the crisp
+    // resting state shortly after the last wheel event.
+    const gestureActiveRef = useRef(false);
+    const gestureSettleTimerRef = useRef(undefined);
+    const transformFramePendingRef = useRef(false);
+    const isPanningRef = useRef(false);
+    const lastPointerRef = useRef({ x: 0, y: 0 });
+    // Direct DOM write, not React state — the container's base cursor is 'default' (StudioIssues#222:
+    // an idle background shouldn't look grabbable until you actually start dragging it), and swapping
+    // to 'grabbing' for the life of a drag-pan is exactly the kind of per-gesture churn this file
+    // already avoids re-rendering for elsewhere (see the transform writes below).
+    const setPanCursor = useCallback((panning) => {
+        if (containerRef.current)
+            containerRef.current.style.cursor = panning ? 'grabbing' : 'default';
+    }, []);
+    // Touch pointers currently down on the canvas, in the order they landed, plus the pinch geometry
+    // they had on the previous move. Touch is the only input that can deliver several simultaneous
+    // pointers, so mouse/pen never enter this map and keep the single-pointer drag path below.
+    const touchPointersRef = useRef(new Map());
+    const pinchRef = useRef(null);
+    // Recent positions of the single finger currently panning, newest last, trimmed to
+    // MOMENTUM_SAMPLE_WINDOW_MS — the trailing window startTouchMomentum reads the release velocity from.
+    const touchPanSamplesRef = useRef([]);
+    // Keep callback refs current to avoid stale closures in PIXI event handlers
+    const onReadyRef = useRef(onReady);
+    const onItemPointerDownRef = useRef(onItemPointerDown);
+    const onTransformChangeRef = useRef(onTransformChange);
+    const onHandleReadyRef = useRef(onHandleReady);
+    const itemsRef = useRef(items);
+    useEffect(() => { onReadyRef.current = onReady; }, [onReady]);
+    useEffect(() => { onItemPointerDownRef.current = onItemPointerDown; }, [onItemPointerDown]);
+    useEffect(() => { onTransformChangeRef.current = onTransformChange; }, [onTransformChange]);
+    useEffect(() => { onHandleReadyRef.current = onHandleReady; }, [onHandleReady]);
+    useEffect(() => {
+        itemsRef.current = items;
+    }, [items]);
+    // ── Item registry — auto-builds minimap items from CanvasItem children ──
+    const itemRegistryRef = useRef(new Map());
+    const [itemRegistryVersion, setItemRegistryVersion] = useState(0);
+    const registerItem = useCallback((id, entry) => {
+        const existing = itemRegistryRef.current.get(id);
+        if (existing &&
+            existing.x === entry.x && existing.y === entry.y &&
+            existing.width === entry.width && existing.height === entry.height)
+            return;
+        itemRegistryRef.current.set(id, entry);
+        setItemRegistryVersion(version => version + 1);
+    }, []);
+    const unregisterItem = useCallback((id) => {
+        itemRegistryRef.current.delete(id);
+        setItemRegistryVersion(version => version + 1);
+    }, []);
+    const registryContextValue = useMemo(() => ({
+        register: registerItem,
+        unregister: unregisterItem,
+    }), [registerItem, unregisterItem]);
+    const autoMinimapItems = useMemo(() => {
+        const result = [];
+        itemRegistryRef.current.forEach(entry => {
+            result.push({ x: entry.x, y: entry.y, width: entry.width, height: entry.height });
+        });
+        return result;
+    }, [itemRegistryVersion]);
+    const effectiveMinimapItems = minimapItems ?? autoMinimapItems;
+    const refreshMinimap = useCallback(() => {
+        const app = appRef.current;
+        if (!app || !minimapRef.current)
+            return;
+        minimapRef.current.update(panRef.current, zoomRef.current, app.renderer.width, app.renderer.height);
+    }, []);
+    const applyWorldTransform = useCallback(() => {
+        const world = worldRef.current;
+        if (!world)
+            return;
+        world.position.set(panRef.current.x, panRef.current.y);
+        world.scale.set(zoomRef.current);
+        // Pan is a CSS transform on the outer overlay; zoom is applied to an inner layer. The zoom
+        // mechanism is hybrid, split at 100% (the two are identical there, so the switch is seamless):
+        //  - Above 100% we use CSS `zoom`, which re-lays-out and re-rasterizes at the effective
+        //    resolution — `transform: scale()` would rasterize once at 1x and stretch, blurring text
+        //    when UPSCALING in Safari. EXCEPT on multi-touch-capable devices (iPad and friends), which
+        //    always use `transform: scale()` even above 100% — see zoomMechanism.ts for why.
+        //  - At or below 100% we use `transform: scale()`, which is GPU-composited: zooming out stays
+        //    smooth (no per-frame full-board reflow) and text scales down properly. CSS `zoom` instead
+        //    reflows every step (jerky) and clamps font-size to a floor when zoomed out, so labels stop
+        //    shrinking and word-wrap. Downscaling never blurs, so the crispness reason does not apply here.
+        if (overlayRef.current) {
+            overlayRef.current.style.transform = `translate(${panRef.current.x}px, ${panRef.current.y}px)`;
+        }
+        if (zoomLayerRef.current) {
+            applyZoomLayer(zoomLayerRef.current, zoomRef.current, gestureActiveRef.current);
+        }
+        onTransformChangeRef.current?.(zoomRef.current, panRef.current);
+        // Every applied transform frame is announced so followers (cursors, selection toolbar, tour
+        // anchors) can ride the transform instead of polling it on their own animation-frame loops.
+        canvasTransformActivity.notify();
+    }, []);
+    const render = useCallback(() => {
+        const app = appRef.current;
+        if (!app)
+            return;
+        // Boards that only use the HTML overlay leave the PIXI world empty — skip the per-frame
+        // GPU pass entirely rather than clearing and presenting an empty stage on every gesture frame.
+        if ((worldRef.current?.children.length ?? 0) === 0)
+            return;
+        // The system ticker is stopped (see the init effect below) — drive pixi's scheduled
+        // housekeeping (texture GC and friends) from the frames that actually render instead.
+        PIXI.Ticker.system.update();
+        app.renderer.render(app.stage);
+    }, []);
+    // Initialize PIXI once
+    useEffect(() => {
+        const container = containerRef.current;
+        if (!container || appRef.current)
+            return;
+        let mounted = true;
+        (async () => {
+            const rect = container.getBoundingClientRect();
+            const width = rect.width > 0 ? rect.width : container.clientWidth || 800;
+            const height = rect.height > 0 ? rect.height : container.clientHeight || 600;
+            const app = new PIXI.Application();
+            await app.init({
+                // Transparent clear: the body carries the surface color and the user-selected
+                // appearance background, which must show through the canvas like everywhere else.
+                backgroundAlpha: 0,
+                antialias: true,
+                autoDensity: true,
+                resolution: window.devicePixelRatio || 1,
+                width,
+                height,
+                autoStart: false,
+            });
+            if (!mounted || !containerRef.current) {
+                app.destroy(true, { children: true });
+                return;
+            }
+            appRef.current = app;
+            // World container - all items live here; zoom/pan applied via transform
+            const world = new PIXI.Container();
+            world.position.set(panRef.current.x, panRef.current.y);
+            world.scale.set(zoomRef.current);
+            app.stage.addChild(world);
+            worldRef.current = world;
+            const canvas = app.canvas;
+            canvas.style.display = 'block';
+            canvas.style.touchAction = 'none';
+            // WebGL canvases rasterize as opaque black in the glass capture pipeline - exclude
+            // this one from every captured scene so glass never refracts a black rectangle.
+            canvas.setAttribute(LAYER_ATTR, 'true');
+            containerRef.current.appendChild(canvas);
+            setPixiReady(true);
+            app.renderer.render(app.stage);
+            // Initializing a renderer hooks pixi's SchedulerSystem onto the auto-starting system
+            // ticker, which then runs a requestAnimationFrame loop forever even though nothing here
+            // renders from a ticker (autoStart is false and every render is explicit) — one of the
+            // permanent loops that kept an idle board page busy (StudioIssues#200). Stop it after
+            // every init, because each new renderer restarts it; render() drives the scheduled
+            // housekeeping instead.
+            PIXI.Ticker.system.stop();
+            onReadyRef.current?.({ app, world });
+        })();
+        return () => {
+            mounted = false;
+            if (appRef.current) {
+                appRef.current.destroy(true, { children: true });
+                appRef.current = null;
+                worldRef.current = null;
+            }
+            spritesRef.current.clear();
+        };
+    }, []); // intentional: PIXI init runs exactly once
+    // Handle container resize
+    useEffect(() => {
+        const container = containerRef.current;
+        if (!container)
+            return;
+        const observer = new ResizeObserver(() => {
+            const app = appRef.current;
+            if (!app)
+                return;
+            app.renderer.resize(container.clientWidth, container.clientHeight);
+            render();
+        });
+        observer.observe(container);
+        return () => observer.disconnect();
+    }, [render]);
+    // One transform apply per animation frame, no matter how many wheel events arrived - the refs already
+    // hold the latest pan/zoom, so coalescing loses nothing and avoids multiple reflows per frame.
+    // No React state is touched here: a gesture must cause zero Canvas re-renders (the controls'
+    // zoom readout polls the ref on its own slow interval instead).
+    const scheduleTransformApply = useCallback(() => {
+        if (transformFramePendingRef.current)
+            return;
+        transformFramePendingRef.current = true;
+        requestAnimationFrame(() => {
+            transformFramePendingRef.current = false;
+            applyWorldTransform();
+            refreshMinimap();
+            render();
+        });
+    }, [applyWorldTransform, refreshMinimap, render]);
+    // Marks the gesture active (composited zoom path, virtualization held still) and re-arms the settle
+    // timer. On settle the crisp resting hybrid is re-applied through the same applyWorldTransform as
+    // every gesture frame — one writer, one atomic style pass — and a new gesture cancels the timer,
+    // so a settle can never land in the middle of the next gesture.
+    const noteGestureActivity = useCallback(() => {
+        gestureActiveRef.current = true;
+        canvasGesture.set(true);
+        clearTimeout(gestureSettleTimerRef.current);
+        gestureSettleTimerRef.current = setTimeout(() => {
+            gestureActiveRef.current = false;
+            applyWorldTransform();
+            canvasGesture.set(false);
+        }, GESTURE_SETTLE_MS);
+    }, [applyWorldTransform]);
+    useEffect(() => () => {
+        clearTimeout(gestureSettleTimerRef.current);
+        canvasGesture.set(false);
+    }, []);
+    // Zooms toward a fixed focus point on the container, holding the world point under it still —
+    // the one zoom every input path shares, whether the factor came from a wheel delta or a pinch.
+    const zoomTowards = useCallback((focusX, focusY, factor) => {
+        const newZoom = Math.max(minZoom, Math.min(maxZoom, zoomRef.current * factor));
+        const worldX = (focusX - panRef.current.x) / zoomRef.current;
+        const worldY = (focusY - panRef.current.y) / zoomRef.current;
+        panRef.current = { x: focusX - worldX * newZoom, y: focusY - worldY * newZoom };
+        zoomRef.current = newZoom;
+        noteGestureActivity();
+        scheduleTransformApply();
+    }, [minZoom, maxZoom, noteGestureActivity, scheduleTransformApply]);
+    // Wheel: pan (scroll) or zoom (Ctrl+scroll / pinch)
+    const handleWheel = useCallback((e) => {
+        const container = containerRef.current;
+        if (!container)
+            return;
+        // A plain scroll/trackpad gesture landing over a scrollable overlay (a chat's message list
+        // and similar) scrolls that content instead of panning the board underneath it
+        // (StudioIssues#229). A zoom gesture (ctrl/cmd) always wins — pinch-to-zoom over a chat
+        // panel is still a zoom, not a captured scroll.
+        if (!(e.ctrlKey || e.metaKey) && isWithinScrollableContent(e.target, container))
+            return;
+        e.preventDefault();
+        // A fresh gesture always wins over a still-coasting one from the last touch pan.
+        if (animationFrameRef.current !== null) {
+            cancelAnimationFrame(animationFrameRef.current);
+            animationFrameRef.current = null;
+        }
+        const rect = container.getBoundingClientRect();
+        const mouseX = e.clientX - rect.left;
+        const mouseY = e.clientY - rect.top;
+        if (e.ctrlKey || e.metaKey) {
+            zoomTowards(mouseX, mouseY, Math.exp(-e.deltaY * ZOOM_INTENSITY));
+        }
+        else {
+            panRef.current = { x: panRef.current.x - e.deltaX, y: panRef.current.y - e.deltaY };
+            noteGestureActivity();
+            scheduleTransformApply();
+        }
+    }, [zoomTowards, noteGestureActivity, scheduleTransformApply]);
+    useEffect(() => {
+        const container = containerRef.current;
+        if (!container)
+            return;
+        container.addEventListener('wheel', handleWheel, { passive: false });
+        return () => container.removeEventListener('wheel', handleWheel);
+    }, [handleWheel]);
+    // Safari/WebKit reports a trackpad pinch through its own non-standard gesture events —
+    // including on iPadOS with a Magic Keyboard trackpad — separately from the wheel+ctrlKey path
+    // above, which Safari never fires for a trackpad pinch. Left unhandled, Safari's default action
+    // is to zoom the whole page instead of the canvas — but canceling that alone would swallow the
+    // pinch entirely, so gesturechange also drives the same zoom-towards-focus the ctrl+wheel path
+    // applies. A touchscreen pinch fires these gesture events too, alongside the pointer events the
+    // touch path already zooms from — with touch pointers down, this handler only cancels the page
+    // zoom and leaves the zooming to the touch path. The events don't exist outside WebKit, so all
+    // of this is a no-op everywhere else.
+    useEffect(() => {
+        const container = containerRef.current;
+        if (!container)
+            return;
+        let lastScale = 1;
+        const handleGestureStart = (event) => {
+            event.preventDefault();
+            lastScale = event.scale || 1;
+        };
+        const handleGestureChange = (event) => {
+            event.preventDefault();
+            if (touchPointersRef.current.size > 0)
+                return;
+            const gesture = event;
+            if (!gesture.scale || !lastScale)
+                return;
+            const rect = container.getBoundingClientRect();
+            zoomTowards(gesture.clientX - rect.left, gesture.clientY - rect.top, gesture.scale / lastScale);
+            lastScale = gesture.scale;
+        };
+        const handleGestureEnd = (event) => event.preventDefault();
+        // Explicitly non-passive: WebKit is free to treat an options-less gesture listener as
+        // passive, silently ignoring preventDefault() — which reads as "pinch zooms the browser
+        // page" on an iPad Magic Keyboard trackpad (StudioIssues#241, previously #73).
+        container.addEventListener('gesturestart', handleGestureStart, { passive: false });
+        container.addEventListener('gesturechange', handleGestureChange, { passive: false });
+        container.addEventListener('gestureend', handleGestureEnd, { passive: false });
+        return () => {
+            container.removeEventListener('gesturestart', handleGestureStart);
+            container.removeEventListener('gesturechange', handleGestureChange);
+            container.removeEventListener('gestureend', handleGestureEnd);
+        };
+    }, [zoomTowards]);
+    // The two handlers above only ever see events that bubble through the canvas surface's own DOM
+    // subtree — but a toolbar, panel, or minimap floating over the canvas is frequently portalled to
+    // document.body (or otherwise rendered as a sibling, not a descendant), so a pinch or Ctrl/Cmd+
+    // wheel with the cursor sitting over one of those never reaches the listeners above at all, and
+    // the browser is free to zoom the whole page instead (StudioIssues#228). Listen at the window
+    // level too, and go purely by screen position — no matter what element actually receives the
+    // event, if it lands within the canvas's own rectangle the browser's native zoom is cancelled.
+    // For events whose target sits inside the canvas subtree this only cancels the browser zoom —
+    // the container's own listeners drive the canvas zoom, so applying it here too would double up.
+    // For a pinch whose target is a portalled sibling (never reaching the container listeners), it
+    // also drives the same zoom-towards-focus, so a pinch over a floating panel zooms the board
+    // instead of dying with the browser zoom cancelled (StudioIssues#241).
+    useEffect(() => {
+        const isWithinCanvas = (x, y) => {
+            const rect = containerRef.current?.getBoundingClientRect();
+            return !!rect && x >= rect.left && x <= rect.right && y >= rect.top && y <= rect.bottom;
+        };
+        const reachesContainerListeners = (event) => event.target instanceof Node && !!containerRef.current?.contains(event.target);
+        const handleWindowWheel = (event) => {
+            if ((event.ctrlKey || event.metaKey) && isWithinCanvas(event.clientX, event.clientY)) {
+                event.preventDefault();
+            }
+        };
+        let lastScale = 1;
+        const handleWindowGestureStart = (event) => {
+            const gesture = event;
+            if (!isWithinCanvas(gesture.clientX, gesture.clientY))
+                return;
+            event.preventDefault();
+            lastScale = gesture.scale || 1;
+        };
+        const handleWindowGestureChange = (event) => {
+            const gesture = event;
+            if (!isWithinCanvas(gesture.clientX, gesture.clientY))
+                return;
+            event.preventDefault();
+            if (reachesContainerListeners(event))
+                return;
+            if (touchPointersRef.current.size > 0)
+                return;
+            if (!gesture.scale || !lastScale)
+                return;
+            const rect = containerRef.current?.getBoundingClientRect();
+            if (!rect)
+                return;
+            zoomTowards(gesture.clientX - rect.left, gesture.clientY - rect.top, gesture.scale / lastScale);
+            lastScale = gesture.scale;
+        };
+        const handleWindowGestureEnd = (event) => {
+            const gesture = event;
+            if (isWithinCanvas(gesture.clientX, gesture.clientY))
+                event.preventDefault();
+        };
+        // Non-passive everywhere: WebKit treating any of these as passive is what lets the page
+        // zoom through, and window-level listeners are exactly where it is most inclined to.
+        window.addEventListener('wheel', handleWindowWheel, { passive: false });
+        window.addEventListener('gesturestart', handleWindowGestureStart, { passive: false });
+        window.addEventListener('gesturechange', handleWindowGestureChange, { passive: false });
+        window.addEventListener('gestureend', handleWindowGestureEnd, { passive: false });
+        return () => {
+            window.removeEventListener('wheel', handleWindowWheel);
+            window.removeEventListener('gesturestart', handleWindowGestureStart);
+            window.removeEventListener('gesturechange', handleWindowGestureChange);
+            window.removeEventListener('gestureend', handleWindowGestureEnd);
+        };
+    }, [zoomTowards]);
+    // Touch: two fingers pan and zoom together, anywhere on the surface — the trackpad's
+    // wheel/ctrl+wheel equivalent for a tablet. The world point under the pinch midpoint stays put
+    // while the midpoint itself drags the board, so zooming and panning feel like one gesture.
+    const applyPinch = useCallback(() => {
+        const container = containerRef.current;
+        const snapshot = pinchSnapshotOf(touchPointersRef.current.values());
+        if (!container || !snapshot)
+            return;
+        const previous = pinchRef.current;
+        pinchRef.current = snapshot;
+        // The first move of a gesture only establishes the baseline — there is nothing to move yet.
+        if (!previous)
+            return;
+        const change = pinchChangeBetween(previous, snapshot);
+        const rect = container.getBoundingClientRect();
+        const focusX = snapshot.center.x - rect.left;
+        const focusY = snapshot.center.y - rect.top;
+        const newZoom = Math.max(minZoom, Math.min(maxZoom, zoomRef.current * change.scale));
+        // The world point that was under the midpoint BEFORE this step is the one being held, so the
+        // midpoint's own movement is what pans — exactly as zoom-towards-cursor does for the wheel.
+        const worldX = (focusX - change.panX - panRef.current.x) / zoomRef.current;
+        const worldY = (focusY - change.panY - panRef.current.y) / zoomRef.current;
+        panRef.current = { x: focusX - worldX * newZoom, y: focusY - worldY * newZoom };
+        zoomRef.current = newZoom;
+        noteGestureActivity();
+        scheduleTransformApply();
+    }, [minZoom, maxZoom, noteGestureActivity, scheduleTransformApply]);
+    // Coasts the board after a touch pan release, decaying the release velocity to a stop — the
+    // manual equivalent of the momentum a trackpad's own wheel-event stream gives panning for free.
+    // Shares animationFrameRef with smoothPanToWorld/smoothPanZoomToWorld so only one of the three
+    // ever drives the transform at once; each cancels whichever of the others was still running.
+    const startTouchMomentum = useCallback(() => {
+        const initialVelocity = velocityFromSamples(touchPanSamplesRef.current, MOMENTUM_MIN_VELOCITY);
+        if (!initialVelocity)
+            return;
+        if (animationFrameRef.current !== null) {
+            cancelAnimationFrame(animationFrameRef.current);
+            animationFrameRef.current = null;
+        }
+        let velocity = initialVelocity;
+        let lastFrameTime = performance.now();
+        const animate = (currentTime) => {
+            const frameElapsedMs = currentTime - lastFrameTime;
+            lastFrameTime = currentTime;
+            panRef.current = {
+                x: panRef.current.x + velocity.x * frameElapsedMs,
+                y: panRef.current.y + velocity.y * frameElapsedMs,
+            };
+            velocity = decayVelocity(velocity, frameElapsedMs);
+            applyWorldTransform();
+            refreshMinimap();
+            render();
+            noteGestureActivity();
+            if (Math.hypot(velocity.x, velocity.y) > MOMENTUM_MIN_VELOCITY) {
+                animationFrameRef.current = requestAnimationFrame(animate);
+            }
+            else {
+                animationFrameRef.current = null;
+            }
+        };
+        animationFrameRef.current = requestAnimationFrame(animate);
+    }, [applyWorldTransform, refreshMinimap, render, noteGestureActivity]);
+    // Pointer: pan via middle mouse, left-click on empty background, or a single finger on it
+    const handlePointerDown = useCallback((e) => {
+        // A fresh gesture always wins over a still-coasting one from the last touch pan.
+        if (animationFrameRef.current !== null) {
+            cancelAnimationFrame(animationFrameRef.current);
+            animationFrameRef.current = null;
+        }
+        if (e.pointerType === 'touch') {
+            touchPointersRef.current.set(e.pointerId, { x: e.clientX, y: e.clientY });
+            if (touchPointersRef.current.size > 1) {
+                // A second finger turns whatever was happening into a pinch: end the one-finger drag
+                // so the two paths never both move the board in the same frame.
+                isPanningRef.current = false;
+                setPanCursor(false);
+                pinchRef.current = pinchSnapshotOf(touchPointersRef.current.values());
+                return;
+            }
+        }
+        const isBackground = isBackgroundPointerTarget(e.pointerType, readOnly, e.target, containerRef.current);
+        // A host that claims the background drag for itself only gives up the mouse/pen gesture: touch
+        // has no middle button and no wheel, so one finger must keep panning or the board is stuck.
+        const mayDragPan = backgroundDragPans || e.pointerType === 'touch';
+        if (e.button === 1 || (e.button === 0 && isBackground && mayDragPan)) {
+            if (e.button === 1)
+                e.preventDefault();
+            isPanningRef.current = true;
+            setPanCursor(true);
+            lastPointerRef.current = { x: e.clientX, y: e.clientY };
+            if (e.pointerType === 'touch') {
+                touchPanSamplesRef.current = [{ x: e.clientX, y: e.clientY, time: performance.now() }];
+            }
+            e.currentTarget.setPointerCapture(e.pointerId);
+        }
+    }, [readOnly, backgroundDragPans, setPanCursor]);
+    const handlePointerMove = useCallback((e) => {
+        if (e.pointerType === 'touch' && touchPointersRef.current.has(e.pointerId)) {
+            touchPointersRef.current.set(e.pointerId, { x: e.clientX, y: e.clientY });
+            if (touchPointersRef.current.size > 1) {
+                applyPinch();
+                return;
+            }
+        }
+        if (!isPanningRef.current)
+            return;
+        const deltaX = e.clientX - lastPointerRef.current.x;
+        const deltaY = e.clientY - lastPointerRef.current.y;
+        lastPointerRef.current = { x: e.clientX, y: e.clientY };
+        panRef.current = { x: panRef.current.x + deltaX, y: panRef.current.y + deltaY };
+        if (e.pointerType === 'touch') {
+            const samples = [...touchPanSamplesRef.current, { x: e.clientX, y: e.clientY, time: performance.now() }];
+            touchPanSamplesRef.current = trimSamples(samples, MOMENTUM_SAMPLE_WINDOW_MS);
+        }
+        // Same gesture path as wheel pan: coalesce onto one rAF and signal the gesture so
+        // virtualization holds still during a drag-pan too.
+        noteGestureActivity();
+        scheduleTransformApply();
+    }, [applyPinch, noteGestureActivity, scheduleTransformApply]);
+    const handlePointerUp = useCallback((e) => {
+        if (touchPointersRef.current.delete(e.pointerId)) {
+            // Re-baseline on the fingers that are left: keeping the old geometry would register the
+            // lifted finger's absence as a huge pinch/pan step on the next move.
+            pinchRef.current = pinchSnapshotOf(touchPointersRef.current.values());
+            const [remaining] = [...touchPointersRef.current.values()];
+            if (remaining) {
+                // Lifting back down to one finger continues the same gesture as a plain drag-pan
+                // rather than stopping dead until the user lifts and starts over.
+                isPanningRef.current = true;
+                setPanCursor(true);
+                lastPointerRef.current = { x: remaining.x, y: remaining.y };
+                touchPanSamplesRef.current = [{ x: remaining.x, y: remaining.y, time: performance.now() }];
+                return;
+            }
+        }
+        const wasPanningTouch = e.pointerType === 'touch' && isPanningRef.current;
+        isPanningRef.current = false;
+        setPanCursor(false);
+        if (wasPanningTouch)
+            startTouchMomentum();
+    }, [startTouchMomentum, setPanCursor]);
+    // Sync items → PIXI containers
+    useEffect(() => {
+        const world = worldRef.current;
+        if (!pixiReady || !world || !renderItem)
+            return;
+        const incoming = new Map(items.map(item => [item.id, item]));
+        // Remove deleted items
+        spritesRef.current.forEach((container, id) => {
+            if (!incoming.has(id)) {
+                world.removeChild(container);
+                container.destroy({ children: true });
+                spritesRef.current.delete(id);
+            }
+        });
+        // Add new items; update positions of existing ones
+        items.forEach(item => {
+            const existing = spritesRef.current.get(item.id);
+            if (existing) {
+                existing.position.set(item.x, item.y);
+                // Refresh handler so it always references the latest item object
+                existing.removeAllListeners('pointerdown');
+                existing.on('pointerdown', (event) => {
+                    onItemPointerDownRef.current?.(item, event);
+                });
+            }
+            else {
+                const container = renderItem(item);
+                container.position.set(item.x, item.y);
+                container.eventMode = 'static';
+                container.on('pointerdown', (event) => {
+                    onItemPointerDownRef.current?.(item, event);
+                });
+                world.addChild(container);
+                spritesRef.current.set(item.id, container);
+            }
+        });
+        // Render directly (not via the empty-world-skipping render()) so removing the last item
+        // still clears its pixels from the canvas.
+        appRef.current?.renderer.render(appRef.current.stage);
+    }, [pixiReady, items, renderItem]);
+    // Controls handlers
+    const handleZoomIn = useCallback(() => {
+        const container = containerRef.current;
+        if (!container)
+            return;
+        const cx = container.clientWidth / 2;
+        const cy = container.clientHeight / 2;
+        const factor = 1.2;
+        const newZoom = Math.min(maxZoom, zoomRef.current * factor);
+        const worldX = (cx - panRef.current.x) / zoomRef.current;
+        const worldY = (cy - panRef.current.y) / zoomRef.current;
+        panRef.current = { x: cx - worldX * newZoom, y: cy - worldY * newZoom };
+        zoomRef.current = newZoom;
+        applyWorldTransform();
+        refreshMinimap();
+        render();
+    }, [maxZoom, applyWorldTransform, refreshMinimap, render]);
+    const handleZoomOut = useCallback(() => {
+        const container = containerRef.current;
+        if (!container)
+            return;
+        const cx = container.clientWidth / 2;
+        const cy = container.clientHeight / 2;
+        const factor = 1.2;
+        const newZoom = Math.max(minZoom, zoomRef.current / factor);
+        const worldX = (cx - panRef.current.x) / zoomRef.current;
+        const worldY = (cy - panRef.current.y) / zoomRef.current;
+        panRef.current = { x: cx - worldX * newZoom, y: cy - worldY * newZoom };
+        zoomRef.current = newZoom;
+        applyWorldTransform();
+        refreshMinimap();
+        render();
+    }, [minZoom, applyWorldTransform, refreshMinimap, render]);
+    const handleZoomReset = useCallback(() => {
+        zoomRef.current = 1;
+        applyWorldTransform();
+        refreshMinimap();
+        render();
+    }, [applyWorldTransform, refreshMinimap, render]);
+    const handleMinimapPan = useCallback((pan) => {
+        panRef.current = pan;
+        applyWorldTransform();
+        refreshMinimap();
+        render();
+    }, [applyWorldTransform, refreshMinimap, render]);
+    const smoothPanToWorld = useCallback((worldX, worldY, durationMs = 600) => {
+        const container = containerRef.current;
+        if (!container)
+            return;
+        if (animationFrameRef.current !== null) {
+            cancelAnimationFrame(animationFrameRef.current);
+            animationFrameRef.current = null;
+        }
+        const viewportWidth = container.clientWidth;
+        const viewportHeight = container.clientHeight;
+        const targetPanX = viewportWidth / 2 - worldX * zoomRef.current;
+        const targetPanY = viewportHeight / 2 - worldY * zoomRef.current;
+        const startPanX = panRef.current.x;
+        const startPanY = panRef.current.y;
+        const startTime = performance.now();
+        const animate = (currentTime) => {
+            const elapsed = currentTime - startTime;
+            const progress = Math.min(elapsed / durationMs, 1);
+            const eased = easeInOutCubic(progress);
+            panRef.current = {
+                x: startPanX + (targetPanX - startPanX) * eased,
+                y: startPanY + (targetPanY - startPanY) * eased,
+            };
+            applyWorldTransform();
+            refreshMinimap();
+            render();
+            if (progress < 1) {
+                animationFrameRef.current = requestAnimationFrame(animate);
+            }
+            else {
+                animationFrameRef.current = null;
+            }
+        };
+        animationFrameRef.current = requestAnimationFrame(animate);
+    }, [applyWorldTransform, refreshMinimap, render]);
+    const smoothPanZoomToWorld = useCallback((worldX, worldY, targetZoom = 1, durationMs = 600) => {
+        const container = containerRef.current;
+        if (!container)
+            return;
+        if (animationFrameRef.current !== null) {
+            cancelAnimationFrame(animationFrameRef.current);
+            animationFrameRef.current = null;
+        }
+        const viewportWidth = container.clientWidth;
+        const viewportHeight = container.clientHeight;
+        const startZoom = zoomRef.current;
+        const endZoom = Math.min(maxZoom, Math.max(minZoom, targetZoom));
+        const startPanX = panRef.current.x;
+        const startPanY = panRef.current.y;
+        // Final pan that centers the world point at the target zoom.
+        const endPanX = viewportWidth / 2 - worldX * endZoom;
+        const endPanY = viewportHeight / 2 - worldY * endZoom;
+        const startTime = performance.now();
+        const animate = (currentTime) => {
+            const elapsed = currentTime - startTime;
+            const progress = Math.min(elapsed / durationMs, 1);
+            const eased = easeInOutCubic(progress);
+            zoomRef.current = startZoom + (endZoom - startZoom) * eased;
+            panRef.current = {
+                x: startPanX + (endPanX - startPanX) * eased,
+                y: startPanY + (endPanY - startPanY) * eased,
+            };
+            applyWorldTransform();
+            refreshMinimap();
+            render();
+            if (progress < 1) {
+                animationFrameRef.current = requestAnimationFrame(animate);
+            }
+            else {
+                animationFrameRef.current = null;
+            }
+        };
+        animationFrameRef.current = requestAnimationFrame(animate);
+    }, [maxZoom, minZoom, applyWorldTransform, refreshMinimap, render]);
+    const getContainerRect = useCallback(() => {
+        return containerRef.current?.getBoundingClientRect() ?? null;
+    }, []);
+    // Measured, not estimated: the registry holds what each CanvasItem's ResizeObserver last reported, so a
+    // fit-to-content computed from it includes everything an item really renders (specifications under the
+    // rows included), unlike the size estimates the minimap falls back to before anything has mounted.
+    const getItemBounds = useCallback(() => Array.from(itemRegistryRef.current.values(), entry => ({ x: entry.x, y: entry.y, width: entry.width, height: entry.height })), []);
+    // Expose imperative handle once the canvas is set up
+    useEffect(() => {
+        if (!pixiReady)
+            return;
+        onHandleReadyRef.current?.({ smoothPanToWorld, smoothPanZoomToWorld, getContainerRect, getItemBounds });
+    }, [pixiReady, smoothPanToWorld, smoothPanZoomToWorld, getContainerRect, getItemBounds]);
+    return (jsxs("div", { ref: containerRef, className: `canvas-surface relative overflow-hidden${className ? ` ${className}` : ''}`, style: { cursor: 'default', ...style }, onPointerDown: handlePointerDown, onPointerMove: handlePointerMove, onPointerUp: handlePointerUp, onPointerCancel: handlePointerUp, children: [jsx(CanvasItemRegistryContext.Provider, { value: registryContextValue, children: jsx("div", { ref: overlayRef, [TRANSFORM_HOST_ATTR]: 'true', style: {
+                        position: 'absolute',
+                        top: 0,
+                        left: 0,
+                        transformOrigin: '0 0',
+                        transform: `translate(${initialTransformRef.current.pan.x}px, ${initialTransformRef.current.pan.y}px)`,
+                        pointerEvents: 'none',
+                    }, children: jsx("div", { ref: zoomLayerRef, [TRANSFORM_HOST_ATTR]: 'true', 
+                        // The read-only overlay below keeps pointers off the board; `inert` keeps the keyboard
+                        // and assistive tech off it too, so nothing on a read-only board can be tabbed to and
+                        // activated (a public viewer must never be able to fire a command).
+                        inert: readOnly, style: shouldUseCssZoom(initialTransformRef.current.zoom, false, isMultiTouchCapableDevice)
+                            ? { zoom: initialTransformRef.current.zoom }
+                            : { transform: `scale(${initialTransformRef.current.zoom})`, transformOrigin: '0 0' }, children: children }) }) }), readOnly && (jsx("div", { style: { position: 'absolute', inset: 0, zIndex: 2, cursor: 'grab' } })), showControls && (jsx(CanvasControls, { getZoom: () => zoomRef.current, onZoomIn: handleZoomIn, onZoomOut: handleZoomOut, onZoomReset: handleZoomReset, showMinimapToggle: showMinimap, minimapRef: minimapRef, minimapWorldWidth: minimapWorldWidth, minimapWorldHeight: minimapWorldHeight, minimapItems: effectiveMinimapItems, onMinimapPan: handleMinimapPan, placement: controlsPlacement, onHelp: onHelp, helpTitle: helpTitle, disableGlass: disableControlsGlass }))] }));
+}
+
+export { Canvas, CanvasItemRegistryContext };
+//# sourceMappingURL=Canvas.js.map