@cratis/components 3.6.1 → 4.1.0

package/dist/esm/Canvas/Canvas.js

@@ -1,7 +1,6 @@
 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';
@@ -12,33 +11,17 @@ 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;
+        : 1 - (-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, controlsGlassSurface, controlsLabels, readOnly = false, backgroundDragPans = true, }) {
+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, controlsLabels, controlsGlassSurface, disableControlsGlass = false, captureAttributes, readOnly = false, backgroundDragPans = true, }) {
     const containerRef = useRef(null);
     useDragSelectionGuard(containerRef);
     const appRef = useRef(null);
@@ -49,73 +32,58 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
     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(() => {
+        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);
-    // The read/subscribe side of the registry. The snapshot is a fresh shallow copy taken on every
-    // actual content change (register/unregister guard against no-op writes below), so its identity
-    // is a faithful change signal for useSyncExternalStore consumers — same reference back means
-    // nothing changed. Entry objects are replaced wholesale on update, never mutated, so entries
-    // shared between an old snapshot and a new one are safe to hold onto.
     const registrySnapshotRef = useRef(new Map());
     const registryListenersRef = useRef(new Set());
     const notifyRegistryChanged = useCallback(() => {
         registrySnapshotRef.current = new Map(itemRegistryRef.current);
-        setItemRegistryVersion(version => version + 1);
-        registryListenersRef.current.forEach(listener => listener());
+        setItemRegistryVersion((version) => version + 1);
+        registryListenersRef.current.forEach((listener) => listener());
     }, []);
     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)
+            existing.x === entry.x &&
+            existing.y === entry.y &&
+            existing.width === entry.width &&
+            existing.height === entry.height &&
+            existing.anonymous === entry.anonymous)
             return;
         itemRegistryRef.current.set(id, entry);
         notifyRegistryChanged();
@@ -128,7 +96,9 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
     const getRegistrySnapshot = useCallback(() => registrySnapshotRef.current, []);
     const subscribeToRegistry = useCallback((listener) => {
         registryListenersRef.current.add(listener);
-        return () => { registryListenersRef.current.delete(listener); };
+        return () => {
+            registryListenersRef.current.delete(listener);
+        };
     }, []);
     const registryContextValue = useMemo(() => ({
         register: registerItem,
@@ -138,8 +108,13 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
     }), [registerItem, unregisterItem, getRegistrySnapshot, subscribeToRegistry]);
     const autoMinimapItems = useMemo(() => {
         const result = [];
-        itemRegistryRef.current.forEach(entry => {
-            result.push({ x: entry.x, y: entry.y, width: entry.width, height: entry.height });
+        itemRegistryRef.current.forEach((entry) => {
+            result.push({
+                x: entry.x,
+                y: entry.y,
+                width: entry.width,
+                height: entry.height,
+            });
         });
         return result;
     }, [itemRegistryVersion]);
@@ -156,16 +131,6 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
             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)`;
         }
@@ -173,24 +138,17 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
             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)
@@ -202,8 +160,6 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
             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,
@@ -217,7 +173,6 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
                 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);
@@ -226,18 +181,9 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
             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 });
         })();
@@ -250,8 +196,15 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
             }
             spritesRef.current.clear();
         };
-    }, []); // intentional: PIXI init runs exactly once
-    // Handle container resize
+    }, []);
+    useEffect(() => {
+        const canvas = appRef.current?.canvas;
+        const attribute = captureAttributes?.layer;
+        if (!canvas || !attribute)
+            return;
+        canvas.setAttribute(attribute, 'true');
+        return () => canvas.removeAttribute(attribute);
+    }, [pixiReady, captureAttributes?.layer]);
     useEffect(() => {
         const container = containerRef.current;
         if (!container)
@@ -266,10 +219,6 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
         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;
@@ -281,10 +230,6 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
             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);
@@ -299,30 +244,26 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
         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 };
+        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))
+        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;
@@ -334,7 +275,10 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
             zoomTowards(mouseX, mouseY, Math.exp(-e.deltaY * ZOOM_INTENSITY));
         }
         else {
-            panRef.current = { x: panRef.current.x - e.deltaX, y: panRef.current.y - e.deltaY };
+            panRef.current = {
+                x: panRef.current.x - e.deltaX,
+                y: panRef.current.y - e.deltaY,
+            };
             noteGestureActivity();
             scheduleTransformApply();
         }
@@ -346,15 +290,6 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
         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)
@@ -376,11 +311,12 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
             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('gesturestart', handleGestureStart, {
+            passive: false,
+        });
+        container.addEventListener('gesturechange', handleGestureChange, {
+            passive: false,
+        });
         container.addEventListener('gestureend', handleGestureEnd, { passive: false });
         return () => {
             container.removeEventListener('gesturestart', handleGestureStart);
@@ -388,26 +324,20 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
             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;
+            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 reachesContainerListeners = (event) => event.target instanceof Node &&
+            !!containerRef.current?.contains(event.target);
         const handleWindowWheel = (event) => {
-            if ((event.ctrlKey || event.metaKey) && isWithinCanvas(event.clientX, event.clientY)) {
+            if ((event.ctrlKey || event.metaKey) &&
+                isWithinCanvas(event.clientX, event.clientY)) {
                 event.preventDefault();
             }
         };
@@ -441,11 +371,13 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
             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('gesturestart', handleWindowGestureStart, {
+            passive: false,
+        });
+        window.addEventListener('gesturechange', handleWindowGestureChange, {
+            passive: false,
+        });
         window.addEventListener('gestureend', handleWindowGestureEnd, { passive: false });
         return () => {
             window.removeEventListener('wheel', handleWindowWheel);
@@ -454,9 +386,6 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
             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());
@@ -464,7 +393,6 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
             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);
@@ -472,8 +400,6 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
         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 };
@@ -481,10 +407,6 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
         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)
@@ -516,9 +438,7 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
         };
         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;
@@ -526,8 +446,6 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
         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());
@@ -535,8 +453,6 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
             }
         }
         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)
@@ -545,7 +461,9 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
             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() }];
+                touchPanSamplesRef.current = [
+                    { x: e.clientX, y: e.clientY, time: performance.now() },
+                ];
             }
             e.currentTarget.setPointerCapture(e.pointerId);
         }
@@ -563,29 +481,31 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
         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 };
+        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() }];
+            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() }];
+                touchPanSamplesRef.current = [
+                    { x: remaining.x, y: remaining.y, time: performance.now() },
+                ];
                 return;
             }
         }
@@ -595,13 +515,11 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
         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
+        const incoming = new Map(items.map((item) => [item.id, item]));
         spritesRef.current.forEach((container, id) => {
             if (!incoming.has(id)) {
                 world.removeChild(container);
@@ -609,12 +527,10 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
                 spritesRef.current.delete(id);
             }
         });
-        // Add new items; update positions of existing ones
-        items.forEach(item => {
+        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);
@@ -631,11 +547,8 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
                 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)
@@ -729,7 +642,6 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
         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();
@@ -757,30 +669,45 @@ function Canvas({ children, items = [], renderItem, onItemPointerDown, onReady,
     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
+    const getItemBounds = useCallback(() => Array.from(itemRegistryRef.current.values(), (entry) => ({
+        x: entry.x,
+        y: entry.y,
+        width: entry.width,
+        height: entry.height,
+    })), []);
     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: {
+        onHandleReadyRef.current?.({
+            smoothPanToWorld,
+            smoothPanZoomToWorld,
+            getContainerRect,
+            getItemBounds,
+        });
+    }, [
+        pixiReady,
+        smoothPanToWorld,
+        smoothPanZoomToWorld,
+        getContainerRect,
+        getItemBounds,
+    ]);
+    return (jsxs("div", { ref: containerRef, className: `canvas-surface cratis:relative cratis: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, ...(captureAttributes?.transformHost
+                        ? { [captureAttributes.transformHost]: '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)
+                    }, children: jsx("div", { ref: zoomLayerRef, ...(captureAttributes?.transformHost
+                            ? { [captureAttributes.transformHost]: 'true' }
+                            : {}), 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, glassSurface: controlsGlassSurface, labels: controlsLabels }))] }));
+                            : {
+                                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, labels: controlsLabels, glassSurface: controlsGlassSurface, contentCaptureAttribute: captureAttributes?.content, disableGlass: disableControlsGlass }))] }));
 }
 
 export { Canvas, CanvasItemRegistryContext };