feat: add zero-config pointer/raycaster system and pinch-to-zoom gestures

- Implemented complete pointer interaction system (hover, click, multitouch)
- Added pinch-to-zoom and two-finger pan gesture controls
- Removed manual raycasting boilerplate from all examples
- Fixed multi-selection to support contiguous range with Shift+Click
- Added Vite plugin for automatic playground rebuild on snippet changes

Pointer System:
- PointerController: Event-driven raycasting (no per-frame overhead)
- DOMPointerAdapter: DOM event → abstract pointer state
- Auto-highlight on hover, auto-select on click (configurable)
- Multi-pointer support with per-pointer highlight tracking
- Transport-agnostic (works with local and remote pointers)
- 13 tests passing

Gesture System:
- GestureController: Pinch-to-zoom and two-finger pan
- Touch point tracking with distance calculation
- Configurable zoom/pan speeds, auto-clamped zoom (0.1x-10x)
- Passive:false event listeners for preventDefault support
- 8 tests passing

New Examples:
- 18-custom-click-handling.md: preventDefault pattern, modifier keys
- 19-multitouch.md: Multi-pointer interaction, pressure sensitivity
- 20-remote-pointer.md: Transport-based pointer sync architecture
- 21-pinch-to-zoom.md: Touch gesture controls for camera

Updated Examples:
- 12-basic-selection.md: Zero-config click selection
- 13-multi-selection.md: Proper contiguous Shift+Click selection
- 15-presence-tracking.md: Simplified with auto-click
- 16-hover-highlighting.md: Removed ~50 lines of raycasting code

Developer Experience:
- Vite plugin watches snippets/ and auto-rebuilds playground
- Full HMR support for snippet changes
- Console logging with emoji indicators (📝 changed, ➕ added, ➖ removed)

Breaking Changes: None (backwards compatible via legacy pointer ID)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: Max Carlson

WebSites/spacecraft-viewer/examples/index.html

@@ -16,10 +16,10 @@ The viewer provides a `state` object with selection methods:
 - `clearSelection()` - clears all selections
 
 ```js
-const { Viewer, THREE } = SpaceCraftViewer;
+const { Viewer } = SpaceCraftViewer;
 
 const canvas = document.getElementById('canvas');
-const viewer = new Viewer(canvas);
+const viewer = new Viewer(canvas); // Click selection enabled by default!
 
 // Sample data
 const items = Array.from({ length: 20 }, (_, i) => ({
@@ -36,43 +36,16 @@ viewer
     spacing: 3
   });
 
-// Setup raycasting for click selection
-const raycaster = new THREE.Raycaster();
-const mouse = new THREE.Vector2();
+// Click selection works automatically!
+// By default, clicking toggles selection
 
-canvas.addEventListener('click', (event) => {
-  const rect = canvas.getBoundingClientRect();
-
-  // Convert mouse position to normalized device coordinates (-1 to +1)
-  mouse.x = ((event.clientX - rect.left) / rect.width) * 2 - 1;
-  mouse.y = -((event.clientY - rect.top) / rect.height) * 2 + 1;
-
-  // Raycast from camera through mouse position
-  raycaster.setFromCamera(mouse, viewer.camera);
-
-  // Find intersected objects
-  const intersects = raycaster.intersectObjects(viewer.scene.children, true);
-
-  if (intersects.length > 0) {
-    // Find the first mesh with an itemId
-    for (const intersect of intersects) {
-      const itemId = intersect.object.userData.itemId;
-      if (itemId) {
-        // Clear previous selection and select clicked item
-        viewer.state.clearSelection();
-        viewer.state.selectItem(itemId);
-        console.log('Selected:', itemId);
-        break;
-      }
-    }
-  } else {
-    // Clicked empty space - clear selection
-    viewer.state.clearSelection();
-  }
+// Listen to click events
+viewer.on('item-clicked', ({ itemId }) => {
+  console.log('Clicked:', itemId);
 });
 
 // Listen to selection changes
-viewer.state.on('selection-changed', (selectedItems) => {
+viewer.on('selection-changed', (selectedItems) => {
   console.log('Selection changed:', Array.from(selectedItems));
 });
 

WebSites/spacecraft-viewer/examples/snippets/12-basic-selection.md

@@ -10,14 +10,21 @@ description: Select multiple items with Shift/Ctrl modifiers
 This example demonstrates multi-item selection using keyboard modifiers:
 - **Click** - Select single item (clears previous selection)
 - **Ctrl/Cmd + Click** - Toggle item in selection
-- **Shift + Click** - Add item to selection
+- **Shift + Click** - Select range from last selected item to clicked item
 - **Esc** - Clear all selections
 
 ```js
-const { Viewer, THREE } = SpaceCraftViewer;
+const { Viewer } = SpaceCraftViewer;
 
 const canvas = document.getElementById('canvas');
-const viewer = new Viewer(canvas);
+
+// Disable default click behavior, handle it manually
+const viewer = new Viewer(canvas, {
+  interaction: {
+    hover: true,  // Keep hover highlights
+    click: false  // Disable auto-toggle, we'll handle clicks manually
+  }
+});
 
 // Sample data
 const items = Array.from({ length: 30 }, (_, i) => ({
@@ -34,58 +41,55 @@ viewer
     spacing: 2.5
   });
 
-// Setup raycasting for click selection
-const raycaster = new THREE.Raycaster();
-const mouse = new THREE.Vector2();
+// Track modifier keys and last selected item
+let ctrlPressed = false;
+let shiftPressed = false;
+let lastSelectedItemId = null;
+
+document.addEventListener('keydown', (event) => {
+  if (event.key === 'Control' || event.key === 'Meta') ctrlPressed = true;
+  if (event.key === 'Shift') shiftPressed = true;
+  if (event.key === 'Escape') {
+    viewer.state.clearSelection();
+    lastSelectedItemId = null;
+  }
+});
 
-canvas.addEventListener('click', (event) => {
-  const rect = canvas.getBoundingClientRect();
+document.addEventListener('keyup', (event) => {
+  if (event.key === 'Control' || event.key === 'Meta') ctrlPressed = false;
+  if (event.key === 'Shift') shiftPressed = false;
+});
 
-  // Convert mouse position to normalized device coordinates
-  mouse.x = ((event.clientX - rect.left) / rect.width) * 2 - 1;
-  mouse.y = -((event.clientY - rect.top) / rect.height) * 2 + 1;
+// Handle clicks with modifier keys
+viewer.on('item-clicked', ({ itemId }) => {
+  if (ctrlPressed) {
+    // Ctrl/Cmd+Click: Toggle selection
+    viewer.state.toggleSelection(itemId);
+    lastSelectedItemId = itemId;
+  } else if (shiftPressed && lastSelectedItemId) {
+    // Shift+Click: Select range from last selected to current
+    const lastIndex = items.findIndex(item => item.id === lastSelectedItemId);
+    const currentIndex = items.findIndex(item => item.id === itemId);
 
-  // Raycast from camera
-  raycaster.setFromCamera(mouse, viewer.camera);
-  const intersects = raycaster.intersectObjects(viewer.scene.children, true);
+    if (lastIndex !== -1 && currentIndex !== -1) {
+      const start = Math.min(lastIndex, currentIndex);
+      const end = Math.max(lastIndex, currentIndex);
 
-  if (intersects.length > 0) {
-    // Find the first mesh with an itemId
-    for (const intersect of intersects) {
-      const itemId = intersect.object.userData.itemId;
-      if (itemId) {
-        // Check keyboard modifiers
-        if (event.ctrlKey || event.metaKey) {
-          // Ctrl/Cmd+Click: Toggle selection
-          viewer.state.toggleSelection(itemId);
-        } else if (event.shiftKey) {
-          // Shift+Click: Add to selection
-          viewer.state.selectItem(itemId);
-        } else {
-          // Plain click: Replace selection
-          viewer.state.clearSelection();
-          viewer.state.selectItem(itemId);
-        }
-        break;
+      // Select all items in range
+      for (let i = start; i <= end; i++) {
+        viewer.state.selectItem(items[i].id);
       }
     }
   } else {
-    // Clicked empty space - clear selection (unless modifier key)
-    if (!event.ctrlKey && !event.metaKey && !event.shiftKey) {
-      viewer.state.clearSelection();
-    }
-  }
-});
-
-// Keyboard shortcuts
-document.addEventListener('keydown', (event) => {
-  if (event.key === 'Escape') {
+    // Plain click: Replace selection
     viewer.state.clearSelection();
+    viewer.state.selectItem(itemId);
+    lastSelectedItemId = itemId;
   }
 });
 
 // Display selection count
-viewer.state.on('selection-changed', (selectedItems) => {
+viewer.on('selection-changed', (selectedItems) => {
   const count = selectedItems.size;
   console.log(`${count} item${count !== 1 ? 's' : ''} selected`);
 });

WebSites/spacecraft-viewer/examples/snippets/13-multi-selection.md

@@ -18,7 +18,7 @@ Open this example in multiple tabs with the same channel to see presence indicat
 - Presence state synchronization
 
 ```js
-const { Viewer, SupabaseTransport, THREE } = SpaceCraftViewer;
+const { Viewer, SupabaseTransport } = SpaceCraftViewer;
 const { getChannelFromUrl } = PlaygroundUtils;
 
 (async () => {
@@ -61,35 +61,16 @@ const { getChannelFromUrl } = PlaygroundUtils;
       spacing: 2.5
     });
 
-  // Setup raycasting for selection
-  const raycaster = new THREE.Raycaster();
-  const mouse = new THREE.Vector2();
-
-  canvas.addEventListener('click', (event) => {
-    const rect = canvas.getBoundingClientRect();
-    mouse.x = ((event.clientX - rect.left) / rect.width) * 2 - 1;
-    mouse.y = -((event.clientY - rect.top) / rect.height) * 2 + 1;
-
-    raycaster.setFromCamera(mouse, viewer.camera);
-    const intersects = raycaster.intersectObjects(viewer.scene.children, true);
-
-    if (intersects.length > 0) {
-      for (const intersect of intersects) {
-        const itemId = intersect.object.userData.itemId;
-        if (itemId) {
-          viewer.state.clearSelection();
-          viewer.state.selectItem(itemId);
-
-          // Broadcast selection to other users
-          transport.broadcast('user-selected', {
-            userId,
-            itemId,
-            timestamp: Date.now()
-          });
-          break;
-        }
-      }
-    }
+  // Click selection works automatically!
+  // Listen for clicks and broadcast to other users
+  viewer.on('item-clicked', ({ itemId }) => {
+    // Auto-selection happens automatically
+    // Broadcast selection to other users
+    transport.broadcast('user-selected', {
+      userId,
+      itemId,
+      timestamp: Date.now()
+    });
   });
 
   // Track other users' selections

WebSites/spacecraft-viewer/examples/snippets/15-presence-tracking.md

@@ -42,10 +42,10 @@ The visual feedback is updated automatically whenever `state.isDirty` is true, w
 Like selection, highlights can be synchronized across devices using a transport. The highlight state automatically syncs via StateSync when a transport is configured.
 
 ```js
-const { Viewer, THREE } = SpaceCraftViewer;
+const { Viewer } = SpaceCraftViewer;
 
 const canvas = document.getElementById('canvas');
-const viewer = new Viewer(canvas);
+const viewer = new Viewer(canvas); // Interaction enabled by default!
 
 // Sample data
 const items = Array.from({ length: 24 }, (_, i) => ({
@@ -62,81 +62,33 @@ viewer
     spacing: 2.5
   });
 
-// Setup raycasting for hover detection
-const raycaster = new THREE.Raycaster();
-const mouse = new THREE.Vector2();
-let lastHighlightedId = null;
-
-// Mousemove for hover highlighting
-canvas.addEventListener('mousemove', (event) => {
-  const rect = canvas.getBoundingClientRect();
-  mouse.x = ((event.clientX - rect.left) / rect.width) * 2 - 1;
-  mouse.y = -((event.clientY - rect.top) / rect.height) * 2 + 1;
-
-  raycaster.setFromCamera(mouse, viewer.camera);
-  const intersects = raycaster.intersectObjects(viewer.scene.children, true);
-
-  let hoveredId = null;
-
-  // Find the first intersected item
-  if (intersects.length > 0) {
-    for (const intersect of intersects) {
-      const itemId = intersect.object.userData.itemId;
-      if (itemId) {
-        hoveredId = itemId;
-        break;
-      }
-    }
-  }
-
-  // Update highlights only if hover changed
-  if (hoveredId !== lastHighlightedId) {
-    // Clear previous highlight
-    if (lastHighlightedId) {
-      viewer.state.unhighlightItem(lastHighlightedId);
-    }
+// Hover highlighting and click selection work automatically!
+// No manual raycasting needed.
 
-    // Set new highlight
-    if (hoveredId) {
-      viewer.state.highlightItem(hoveredId);
-    }
+// Listen to hover events
+viewer.on('item-hover-enter', ({ itemId }) => {
+  console.log('Hovered:', itemId);
+});
 
-    lastHighlightedId = hoveredId;
-  }
+viewer.on('item-hover-exit', ({ itemId }) => {
+  console.log('Unhovered:', itemId);
 });
 
-// Click for selection (independent of highlighting)
-canvas.addEventListener('click', (event) => {
-  const rect = canvas.getBoundingClientRect();
-  mouse.x = ((event.clientX - rect.left) / rect.width) * 2 - 1;
-  mouse.y = -((event.clientY - rect.top) / rect.height) * 2 + 1;
-
-  raycaster.setFromCamera(mouse, viewer.camera);
-  const intersects = raycaster.intersectObjects(viewer.scene.children, true);
-
-  if (intersects.length > 0) {
-    for (const intersect of intersects) {
-      const itemId = intersect.object.userData.itemId;
-      if (itemId) {
-        // Toggle selection
-        viewer.state.toggleSelection(itemId);
-        console.log('Toggled selection:', itemId);
-        break;
-      }
-    }
-  }
+// Listen to click events
+viewer.on('item-clicked', ({ itemId }) => {
+  console.log('Clicked:', itemId);
 });
 
 // Listen to highlight changes
-viewer.state.on('highlight-changed', (highlightedItems) => {
+viewer.on('highlight-changed', (highlightedItems) => {
   if (highlightedItems.size > 0) {
     const ids = Array.from(highlightedItems);
     console.log('Highlighted:', ids);
   }
 });
 
 // Listen to selection changes
-viewer.state.on('selection-changed', (selectedItems) => {
+viewer.on('selection-changed', (selectedItems) => {
   console.log('Selected:', Array.from(selectedItems));
 });