diff --git a/CLAUDE.md b/CLAUDE.md
index 9ebf649..c4c1e30 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -103,6 +103,16 @@ useFrame((elapsed: number) => {
 ```
 Frame-based animation system for smooth animations.
 
+### useZUI() and useZUIState() Hooks
+```typescript
+const zui = useZUI(groupRef, { minZoom: 0.25, maxZoom: 8 });
+const { scale, x, y } = useZUIState(zui);
+```
+- Wrap a `<Group ref={groupRef}>` to enable mouse wheel zoom & background drag pan.
+- Automatically gates canvas panning using registered shape hit testing so node drag events do not trigger pan.
+- High-frequency wheel/pan events update Two.js transforms directly in a ref (no React re-renders on pan).
+- `zui.clientToSurface(clientX, clientY)` converts raw DOM screen pixel coordinates into surface space for node dragging.
+
 ## Ref System
 Each component has a corresponding ref type:
 - `RefCircle`, `RefRectangle`, `RefPath`, etc.
diff --git a/README.md b/README.md
index 27fb838..c23c50a 100644
--- a/README.md
+++ b/README.md
@@ -223,6 +223,43 @@ useFrame((elapsed: number) => {
 })
 ```
 
+#### `useZUI(targetRef, options?)`
+
+Adds zoom and pan interactions to a `<Group>` component. Panning is gated on registered shape hit testing so node dragging and canvas panning never conflict.
+
+```tsx
+import { useRef } from 'react';
+import { Canvas, Group, Circle, useZUI, RefGroup } from 'react-two.js';
+
+function Scene() {
+  const groupRef = useRef<RefGroup | null>(null);
+  const zui = useZUI(groupRef, { minZoom: 0.25, maxZoom: 8 });
+
+  return (
+    <Group ref={groupRef}>
+      <Circle x={0} y={0} radius={50} fill="#00AEFF" />
+    </Group>
+  );
+}
+```
+
+Returns `ZUIControls`:
+- `controls.zoomBy(ratio, clientX?, clientY?)` — Zoom relative to center or given client point.
+- `controls.zoomTo(scale, clientX?, clientY?)` — Set absolute zoom scale.
+- `controls.panBy(dx, dy)` — Pan by screen pixel delta.
+- `controls.reset()` — Reset zoom and pan to identity state.
+- `controls.clientToSurface(clientX, clientY)` — Convert screen coordinates to surface coordinates.
+- `controls.state` — Ref containing `{ scale, x, y }`.
+
+#### `useZUIState(zui, onChange?)`
+
+Subscribes to ZUI zoom and pan state updates for rendering reactive zoom UI controls.
+
+```tsx
+const zui = useZUI(groupRef);
+const { scale } = useZUIState(zui);
+```
+
 ### Props
 
 All Two.js properties work as React props:
diff --git a/lib/ArcSegment.tsx b/lib/ArcSegment.tsx
index 950928b..cb9f411 100644
--- a/lib/ArcSegment.tsx
+++ b/lib/ArcSegment.tsx
@@ -42,10 +42,13 @@ export const ArcSegment = React.forwardRef<Instance, ComponentProps>(
 
       for (const key in props) {
         if (EVENT_HANDLER_NAMES.includes(key as keyof EventHandlers)) {
-          eventHandlers[key as keyof EventHandlers] = props[
-            key as keyof EventHandlers
+          // An explicitly `undefined` handler means "not interactive", so it
+          // must not count toward the registered handler set.
+          const handler = props[key as keyof EventHandlers];
+          if (handler !== undefined) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          ] as any;
+            eventHandlers[key as keyof EventHandlers] = handler as any;
+          }
         } else {
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           shapeProps[key] = (props as any)[key];
@@ -78,14 +81,19 @@ export const ArcSegment = React.forwardRef<Instance, ComponentProps>(
       }
     }, [shapeProps, arcSegment, x, y]);
 
-    // Register event handlers
+    // Unregister on unmount only
+    useEffect(() => {
+      return () => {
+        unregisterEventShape(arcSegment);
+      };
+    }, [arcSegment, unregisterEventShape]);
+
+    // Register / update event handlers
     useEffect(() => {
       if (Object.keys(eventHandlers).length > 0) {
         registerEventShape(arcSegment, eventHandlers, parent ?? undefined);
-
-        return () => {
-          unregisterEventShape(arcSegment);
-        };
+      } else {
+        unregisterEventShape(arcSegment);
       }
     }, [
       arcSegment,
diff --git a/lib/Circle.tsx b/lib/Circle.tsx
index 1eea6ae..8b48cb0 100644
--- a/lib/Circle.tsx
+++ b/lib/Circle.tsx
@@ -37,10 +37,13 @@ export const Circle = React.forwardRef<Instance, ComponentProps>(
 
       for (const key in props) {
         if (EVENT_HANDLER_NAMES.includes(key as keyof EventHandlers)) {
-          eventHandlers[key as keyof EventHandlers] = props[
-            key as keyof EventHandlers
+          // An explicitly `undefined` handler means "not interactive", so it
+          // must not count toward the registered handler set.
+          const handler = props[key as keyof EventHandlers];
+          if (handler !== undefined) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          ] as any;
+            eventHandlers[key as keyof EventHandlers] = handler as any;
+          }
         } else {
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           shapeProps[key] = (props as any)[key];
@@ -67,20 +70,26 @@ export const Circle = React.forwardRef<Instance, ComponentProps>(
     useEffect(() => {
       if (parent) {
         parent.add(circle);
+
         return () => {
           parent.remove(circle);
         };
       }
     }, [parent, circle]);
 
-    // Register event handlers
+    // Unregister on unmount only
+    useEffect(() => {
+      return () => {
+        unregisterEventShape(circle);
+      };
+    }, [circle, unregisterEventShape]);
+
+    // Register / update event handlers
     useEffect(() => {
       if (Object.keys(eventHandlers).length > 0) {
         registerEventShape(circle, eventHandlers, parent ?? undefined);
-
-        return () => {
-          unregisterEventShape(circle);
-        };
+      } else {
+        unregisterEventShape(circle);
       }
     }, [
       circle,
diff --git a/lib/Context.ts b/lib/Context.ts
index 83c37b4..714c03d 100644
--- a/lib/Context.ts
+++ b/lib/Context.ts
@@ -12,6 +12,7 @@ export interface TwoCoreContextValue {
     parent?: Group
   ) => void;
   unregisterEventShape: (shape: Shape | Group) => void;
+  hitTestPoint: (clientX: number, clientY: number) => boolean;
 }
 
 export interface TwoParentContextValue {
@@ -27,6 +28,7 @@ export const TwoCoreContext = createContext<TwoCoreContextValue>({
   two: null,
   registerEventShape: () => {},
   unregisterEventShape: () => {},
+  hitTestPoint: () => false,
 });
 
 export const TwoParentContext = createContext<TwoParentContextValue>({
diff --git a/lib/Ellipse.tsx b/lib/Ellipse.tsx
index 45bc7b0..c7757a3 100644
--- a/lib/Ellipse.tsx
+++ b/lib/Ellipse.tsx
@@ -37,10 +37,13 @@ export const Ellipse = React.forwardRef<Instance | null, ComponentProps>(
 
       for (const key in props) {
         if (EVENT_HANDLER_NAMES.includes(key as keyof EventHandlers)) {
-          eventHandlers[key as keyof EventHandlers] = props[
-            key as keyof EventHandlers
+          // An explicitly `undefined` handler means "not interactive", so it
+          // must not count toward the registered handler set.
+          const handler = props[key as keyof EventHandlers];
+          if (handler !== undefined) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          ] as any;
+            eventHandlers[key as keyof EventHandlers] = handler as any;
+          }
         } else {
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           shapeProps[key] = (props as any)[key];
@@ -74,14 +77,19 @@ export const Ellipse = React.forwardRef<Instance | null, ComponentProps>(
       }
     }, [ellipse, x, y, shapeProps]);
 
-    // Register event handlers
+    // Unregister on unmount only
+    useEffect(() => {
+      return () => {
+        unregisterEventShape(ellipse);
+      };
+    }, [ellipse, unregisterEventShape]);
+
+    // Register / update event handlers
     useEffect(() => {
       if (Object.keys(eventHandlers).length > 0) {
         registerEventShape(ellipse, eventHandlers, parent ?? undefined);
-
-        return () => {
-          unregisterEventShape(ellipse);
-        };
+      } else {
+        unregisterEventShape(ellipse);
       }
     }, [
       ellipse,
diff --git a/lib/Events.ts b/lib/Events.ts
index 0b9cf89..79e9f3d 100644
--- a/lib/Events.ts
+++ b/lib/Events.ts
@@ -1,75 +1,50 @@
-/**
- * Event system for react-two.js
- * Implements R3F-style event handlers using Two.js hit testing
- */
-
 import Two from 'two.js';
 import type { Shape } from 'two.js/src/shape';
 import type { Group } from 'two.js/src/group';
 
-/**
- * Event object passed to event handlers
- * Similar to React Three Fiber's ThreeEvent
- */
-export interface TwoEvent<T = Shape> {
-  /** The original DOM event */
+export interface TwoEvent<T extends Shape | Group = Shape | Group> {
   nativeEvent: PointerEvent | MouseEvent | WheelEvent;
-  /** The shape that was directly hit */
   target: T;
-  /** The shape that has the event handler (may be ancestor due to bubbling) */
   currentTarget: T;
-  /** The point in Two.js coordinate space (center origin) */
   point: { x: number; y: number };
-  /** Stop event from bubbling to parent groups */
   stopPropagation: () => void;
-  /** Whether propagation was stopped */
-  stopped: boolean;
+  readonly stopped: boolean;
 }
 
-/**
- * Event handler function type
- */
-export type EventHandler<T = Shape> = (event: TwoEvent<T>) => void;
+export type EventHandler<T extends Shape | Group = Shape | Group> = (
+  event: TwoEvent<T>
+) => void;
 
-/**
- * All supported event handlers (matching R3F API)
- */
 export interface EventHandlers {
   onClick?: EventHandler;
   onContextMenu?: EventHandler;
   onDoubleClick?: EventHandler;
-  onWheel?: EventHandler;
   onPointerDown?: EventHandler;
+  onPointerMove?: EventHandler;
   onPointerUp?: EventHandler;
   onPointerOver?: EventHandler;
   onPointerOut?: EventHandler;
   onPointerEnter?: EventHandler;
   onPointerLeave?: EventHandler;
-  onPointerMove?: EventHandler;
   onPointerCancel?: EventHandler;
+  onWheel?: EventHandler;
 }
 
-/**
- * Event handler names for iteration
- */
-export const EVENT_HANDLER_NAMES = [
+export const EVENT_HANDLER_NAMES: Array<keyof EventHandlers> = [
   'onClick',
   'onContextMenu',
   'onDoubleClick',
-  'onWheel',
   'onPointerDown',
+  'onPointerMove',
   'onPointerUp',
   'onPointerOver',
   'onPointerOut',
   'onPointerEnter',
   'onPointerLeave',
-  'onPointerMove',
   'onPointerCancel',
-] as const;
+  'onWheel',
+];
 
-/**
- * Shape registration entry for event system
- */
 export interface EventShape {
   shape: Shape | Group;
   handlers: Partial<EventHandlers>;
@@ -77,11 +52,10 @@ export interface EventShape {
 }
 
 /**
- * Convert DOM event coordinates to Two.js coordinate space
- * Two.js uses center origin (0,0 at center of canvas)
+ * Convert DOM event coordinates to canvas-relative coordinates (center origin)
  */
 export function getCanvasCoordinates(
-  nativeEvent: PointerEvent | MouseEvent,
+  nativeEvent: PointerEvent | MouseEvent | WheelEvent,
   canvas: HTMLElement,
   two: Two
 ): { x: number; y: number } {
@@ -94,6 +68,23 @@ export function getCanvasCoordinates(
   return { x, y };
 }
 
+/**
+ * Convert raw client coordinates to world-space coordinates for hit testing.
+ * World space uses a top-left origin, relative to the canvas element.
+ */
+export function clientToWorldPoint(
+  clientX: number,
+  clientY: number,
+  canvas: HTMLElement
+): { x: number; y: number } {
+  const rect = canvas.getBoundingClientRect();
+
+  return {
+    x: clientX - rect.left,
+    y: clientY - rect.top,
+  };
+}
+
 /**
  * Convert DOM event coordinates to world-space coordinates for hit testing
  * World-space uses top-left origin (same as DOM but relative to canvas)
@@ -102,13 +93,7 @@ export function getWorldCoordinates(
   nativeEvent: PointerEvent | MouseEvent,
   canvas: HTMLElement
 ): { x: number; y: number } {
-  const rect = canvas.getBoundingClientRect();
-
-  // Convert from DOM space to canvas-relative space (both top-left origin)
-  const x = nativeEvent.clientX - rect.left;
-  const y = nativeEvent.clientY - rect.top;
-
-  return { x, y };
+  return clientToWorldPoint(nativeEvent.clientX, nativeEvent.clientY, canvas);
 }
 
 /**
@@ -139,41 +124,121 @@ export function createTwoEvent<T extends Shape | Group>(
 /**
  * Check if a shape contains a point using Two.js hit testing
  */
-export function hitTest(shape: Shape | Group, x: number, y: number): boolean {
+export function hitTest(shape: Shape | Group, x: number, y: number, two?: Two | null): boolean {
   // Check if shape is visible
   if ('visible' in shape && !shape.visible) {
     return false;
   }
 
-  // Use Two.js hit testing API
-  if (typeof shape.contains === 'function') {
-    return shape.contains(x, y);
+  // Use shape.contains if custom contains function exists.
+  // DOM nodes also expose a `contains`, with completely different semantics,
+  // so exclude those. The globals are guarded because this module must not
+  // throw when evaluated outside a DOM runtime.
+  const candidateShape = shape as unknown as { contains?: unknown };
+  const isDomContains =
+    (typeof Node !== 'undefined' &&
+      candidateShape.contains === Node.prototype.contains) ||
+    (typeof Element !== 'undefined' &&
+      candidateShape.contains === Element.prototype.contains);
+  if (typeof candidateShape.contains === 'function' && !isDomContains) {
+    return (candidateShape.contains as (x: number, y: number) => boolean)(x, y);
+  }
+
+  // Use Two.js getBoundingClientRect API
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  if (typeof (shape as any).getBoundingClientRect === 'function') {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const rect = (shape as any).getBoundingClientRect(false);
+      if (rect && typeof rect.left === 'number' && typeof rect.right === 'number') {
+        const isRealTwoShape = 'worldMatrix' in shape || '_matrix' in shape;
+        const offsetX = (!isRealTwoShape && two) ? two.width / 2 : 0;
+        const offsetY = (!isRealTwoShape && two) ? two.height / 2 : 0;
+        const left = rect.left + offsetX;
+        const right = rect.right + offsetX;
+        const top = rect.top + offsetY;
+        const bottom = rect.bottom + offsetY;
+
+        if (x >= left && x <= right && y >= top && y <= bottom) {
+          return true;
+        }
+      }
+    } catch {
+      // Fallback to checking children if getBoundingClientRect fails
+    }
+  }
+
+  // For Groups without bounds, recursively check children
+  if ('children' in shape && Array.isArray((shape as Group).children)) {
+    for (const child of (shape as Group).children) {
+      if (hitTest(child, x, y, two)) {
+        return true;
+      }
+    }
   }
 
-  // Fallback for shapes without hit testing
   return false;
 }
 
+/**
+ * Sort shapes front-to-back (topmost visible shape first).
+ * In 2D rendering, shapes drawn later (or with higher parent.children index) sit on top of shapes drawn earlier.
+ */
+export function sortFrontToBack(
+  hits: Array<Shape | Group>,
+  shapes: Map<Shape | Group, EventShape>
+): Array<Shape | Group> {
+  if (hits.length <= 1) return hits;
+
+  const keys = Array.from(shapes.keys());
+
+  return [...hits].sort((a, b) => {
+    const entryA = shapes.get(a);
+    const entryB = shapes.get(b);
+
+    // If both belong to the same parent Group, compare their index in parent.children
+    if (entryA?.parent && entryB?.parent && entryA.parent === entryB.parent) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const parentChildren = (entryA.parent as any).children;
+      if (parentChildren && typeof parentChildren.indexOf === 'function') {
+        const indexA = parentChildren.indexOf(a);
+        const indexB = parentChildren.indexOf(b);
+        if (indexA !== -1 && indexB !== -1) {
+          return indexB - indexA; // Higher index = drawn on top = should be first
+        }
+      }
+    }
+
+    // Default: reverse registration order (shapes registered later sit on top)
+    const indexA = keys.indexOf(a);
+    const indexB = keys.indexOf(b);
+    return indexB - indexA; // Higher registration index = frontmost
+  });
+}
+
 /**
  * Get all shapes at a point, sorted by depth (front to back)
- * Uses scene graph traversal to maintain z-order
+ * Uses scene graph traversal and registration order to maintain z-order
  */
 export function getShapesAtPoint(
   shapes: Map<Shape | Group, EventShape>,
   x: number,
-  y: number
+  y: number,
+  two?: Two | null
 ): Array<Shape | Group> {
+  if (two?.scene) {
+    (two.scene as unknown as { _update: (deep?: boolean) => void })._update(true);
+  }
+
   const hits: Array<Shape | Group> = [];
 
   for (const [shape] of shapes) {
-    if (hitTest(shape, x, y)) {
+    if (hitTest(shape, x, y, two)) {
       hits.push(shape);
     }
   }
 
-  // TODO: Sort by z-order/drawing order when Two.js provides this info
-  // For now, return in registration order
-  return hits;
+  return sortFrontToBack(hits, shapes);
 }
 
 /**
diff --git a/lib/Group.tsx b/lib/Group.tsx
index 404d899..f2397a3 100644
--- a/lib/Group.tsx
+++ b/lib/Group.tsx
@@ -39,6 +39,7 @@ export const Group = React.forwardRef<Instance, ComponentProps>(
       height,
       registerEventShape,
       unregisterEventShape,
+      hitTestPoint,
     } = useTwo();
 
     // Create the instance synchronously so it's available for refs immediately
@@ -51,10 +52,13 @@ export const Group = React.forwardRef<Instance, ComponentProps>(
 
       for (const key in props) {
         if (EVENT_HANDLER_NAMES.includes(key as keyof EventHandlers)) {
-          eventHandlers[key as keyof EventHandlers] = props[
-            key as keyof EventHandlers
+          // An explicitly `undefined` handler means "not interactive", so it
+          // must not count toward the registered handler set.
+          const handler = props[key as keyof EventHandlers];
+          if (handler !== undefined) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          ] as any;
+            eventHandlers[key as keyof EventHandlers] = handler as any;
+          }
         } else {
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           shapeProps[key] = (props as any)[key];
@@ -91,14 +95,19 @@ export const Group = React.forwardRef<Instance, ComponentProps>(
       }
     }, [group, x, y, shapeProps]);
 
-    // Register event handlers
+    // Unregister on unmount only
+    useEffect(() => {
+      return () => {
+        unregisterEventShape(group);
+      };
+    }, [group, unregisterEventShape]);
+
+    // Register / update event handlers
     useEffect(() => {
       if (Object.keys(eventHandlers).length > 0) {
         registerEventShape(group, eventHandlers, parent ?? undefined);
-
-        return () => {
-          unregisterEventShape(group);
-        };
+      } else {
+        unregisterEventShape(group);
       }
     }, [
       group,
@@ -115,8 +124,9 @@ export const Group = React.forwardRef<Instance, ComponentProps>(
         two,
         registerEventShape,
         unregisterEventShape,
+        hitTestPoint,
       }),
-      [two, registerEventShape, unregisterEventShape]
+      [two, registerEventShape, unregisterEventShape, hitTestPoint]
     );
 
     const parentValue = useMemo(
diff --git a/lib/Image.tsx b/lib/Image.tsx
index d16b391..80c9880 100644
--- a/lib/Image.tsx
+++ b/lib/Image.tsx
@@ -38,10 +38,13 @@ export const Image = React.forwardRef<Instance, ComponentProps>(
 
       for (const key in props) {
         if (EVENT_HANDLER_NAMES.includes(key as keyof EventHandlers)) {
-          eventHandlers[key as keyof EventHandlers] = props[
-            key as keyof EventHandlers
+          // An explicitly `undefined` handler means "not interactive", so it
+          // must not count toward the registered handler set.
+          const handler = props[key as keyof EventHandlers];
+          if (handler !== undefined) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          ] as any;
+            eventHandlers[key as keyof EventHandlers] = handler as any;
+          }
         } else {
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           shapeProps[key] = (props as any)[key];
@@ -78,14 +81,19 @@ export const Image = React.forwardRef<Instance, ComponentProps>(
       }
     }, [image, shapeProps, mode, texture, x, y]);
 
-    // Register event handlers
+    // Unregister on unmount only
+    useEffect(() => {
+      return () => {
+        unregisterEventShape(image);
+      };
+    }, [image, unregisterEventShape]);
+
+    // Register / update event handlers
     useEffect(() => {
       if (Object.keys(eventHandlers).length > 0) {
         registerEventShape(image, eventHandlers, parent ?? undefined);
-
-        return () => {
-          unregisterEventShape(image);
-        };
+      } else {
+        unregisterEventShape(image);
       }
     }, [
       image,
diff --git a/lib/ImageSequence.tsx b/lib/ImageSequence.tsx
index 437ea7c..8bb79c0 100644
--- a/lib/ImageSequence.tsx
+++ b/lib/ImageSequence.tsx
@@ -44,10 +44,13 @@ export const ImageSequence = React.forwardRef<Instance, ComponentProps>(
 
       for (const key in props) {
         if (EVENT_HANDLER_NAMES.includes(key as keyof EventHandlers)) {
-          eventHandlers[key as keyof EventHandlers] = props[
-            key as keyof EventHandlers
+          // An explicitly `undefined` handler means "not interactive", so it
+          // must not count toward the registered handler set.
+          const handler = props[key as keyof EventHandlers];
+          if (handler !== undefined) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          ] as any;
+            eventHandlers[key as keyof EventHandlers] = handler as any;
+          }
         } else {
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           shapeProps[key] = (props as any)[key];
@@ -87,14 +90,19 @@ export const ImageSequence = React.forwardRef<Instance, ComponentProps>(
       }
     }, [shapeProps, imageSequence, x, y, autoPlay]);
 
-    // Register event handlers
+    // Unregister on unmount only
+    useEffect(() => {
+      return () => {
+        unregisterEventShape(imageSequence);
+      };
+    }, [imageSequence, unregisterEventShape]);
+
+    // Register / update event handlers
     useEffect(() => {
       if (Object.keys(eventHandlers).length > 0) {
         registerEventShape(imageSequence, eventHandlers, parent ?? undefined);
-
-        return () => {
-          unregisterEventShape(imageSequence);
-        };
+      } else {
+        unregisterEventShape(imageSequence);
       }
     }, [
       imageSequence,
diff --git a/lib/Line.tsx b/lib/Line.tsx
index fd27cf7..cbdda2b 100644
--- a/lib/Line.tsx
+++ b/lib/Line.tsx
@@ -35,10 +35,13 @@ export const Line = React.forwardRef<Instance, ComponentProps>(
 
       for (const key in props) {
         if (EVENT_HANDLER_NAMES.includes(key as keyof EventHandlers)) {
-          eventHandlers[key as keyof EventHandlers] = props[
-            key as keyof EventHandlers
+          // An explicitly `undefined` handler means "not interactive", so it
+          // must not count toward the registered handler set.
+          const handler = props[key as keyof EventHandlers];
+          if (handler !== undefined) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          ] as any;
+            eventHandlers[key as keyof EventHandlers] = handler as any;
+          }
         } else {
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           shapeProps[key] = (props as any)[key];
@@ -75,16 +78,27 @@ export const Line = React.forwardRef<Instance, ComponentProps>(
       }
     }, [shapeProps, line, x1, y1, x2, y2]);
 
-    // Register event handlers
+    // Unregister on unmount only
+    useEffect(() => {
+      return () => {
+        unregisterEventShape(line);
+      };
+    }, [line, unregisterEventShape]);
+
+    // Register / update event handlers
     useEffect(() => {
       if (Object.keys(eventHandlers).length > 0) {
         registerEventShape(line, eventHandlers, parent ?? undefined);
-
-        return () => {
-          unregisterEventShape(line);
-        };
+      } else {
+        unregisterEventShape(line);
       }
-    }, [line, registerEventShape, unregisterEventShape, parent, eventHandlers]);
+    }, [
+      line,
+      registerEventShape,
+      unregisterEventShape,
+      parent,
+      eventHandlers,
+    ]);
 
     useImperativeHandle(forwardedRef, () => line, [line]);
 
diff --git a/lib/Path.tsx b/lib/Path.tsx
index 7e7fb1c..b0b6ef4 100644
--- a/lib/Path.tsx
+++ b/lib/Path.tsx
@@ -49,10 +49,13 @@ export const Path = React.forwardRef<Instance, ComponentProps>(
 
       for (const key in props) {
         if (EVENT_HANDLER_NAMES.includes(key as keyof EventHandlers)) {
-          eventHandlers[key as keyof EventHandlers] = props[
-            key as keyof EventHandlers
+          // An explicitly `undefined` handler means "not interactive", so it
+          // must not count toward the registered handler set.
+          const handler = props[key as keyof EventHandlers];
+          if (handler !== undefined) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          ] as any;
+            eventHandlers[key as keyof EventHandlers] = handler as any;
+          }
         } else {
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           shapeProps[key] = (props as any)[key];
@@ -72,16 +75,27 @@ export const Path = React.forwardRef<Instance, ComponentProps>(
       }
     }, [parent, path]);
 
-    // Register event handlers
+    // Unregister on unmount only
+    useEffect(() => {
+      return () => {
+        unregisterEventShape(path);
+      };
+    }, [path, unregisterEventShape]);
+
+    // Register / update event handlers
     useEffect(() => {
       if (Object.keys(eventHandlers).length > 0) {
         registerEventShape(path, eventHandlers, parent ?? undefined);
-
-        return () => {
-          unregisterEventShape(path);
-        };
+      } else {
+        unregisterEventShape(path);
       }
-    }, [path, registerEventShape, unregisterEventShape, parent, eventHandlers]);
+    }, [
+      path,
+      registerEventShape,
+      unregisterEventShape,
+      parent,
+      eventHandlers,
+    ]);
 
     useEffect(() => {
       // Update position
diff --git a/lib/Points.tsx b/lib/Points.tsx
index 78d2b88..6324b03 100644
--- a/lib/Points.tsx
+++ b/lib/Points.tsx
@@ -44,10 +44,13 @@ export const Points = React.forwardRef<Instance, ComponentProps>(
 
       for (const key in props) {
         if (EVENT_HANDLER_NAMES.includes(key as keyof EventHandlers)) {
-          eventHandlers[key as keyof EventHandlers] = props[
-            key as keyof EventHandlers
+          // An explicitly `undefined` handler means "not interactive", so it
+          // must not count toward the registered handler set.
+          const handler = props[key as keyof EventHandlers];
+          if (handler !== undefined) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          ] as any;
+            eventHandlers[key as keyof EventHandlers] = handler as any;
+          }
         } else {
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           shapeProps[key] = (props as any)[key];
@@ -81,14 +84,19 @@ export const Points = React.forwardRef<Instance, ComponentProps>(
       }
     }, [shapeProps, points, x, y]);
 
-    // Register event handlers
+    // Unregister on unmount only
+    useEffect(() => {
+      return () => {
+        unregisterEventShape(points);
+      };
+    }, [points, unregisterEventShape]);
+
+    // Register / update event handlers
     useEffect(() => {
       if (Object.keys(eventHandlers).length > 0) {
         registerEventShape(points, eventHandlers, parent ?? undefined);
-
-        return () => {
-          unregisterEventShape(points);
-        };
+      } else {
+        unregisterEventShape(points);
       }
     }, [
       points,
diff --git a/lib/Polygon.tsx b/lib/Polygon.tsx
index 24b369a..de4bd89 100644
--- a/lib/Polygon.tsx
+++ b/lib/Polygon.tsx
@@ -34,10 +34,13 @@ export const Polygon = React.forwardRef<Instance, ComponentProps>(
 
       for (const key in props) {
         if (EVENT_HANDLER_NAMES.includes(key as keyof EventHandlers)) {
-          eventHandlers[key as keyof EventHandlers] = props[
-            key as keyof EventHandlers
+          // An explicitly `undefined` handler means "not interactive", so it
+          // must not count toward the registered handler set.
+          const handler = props[key as keyof EventHandlers];
+          if (handler !== undefined) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          ] as any;
+            eventHandlers[key as keyof EventHandlers] = handler as any;
+          }
         } else {
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           shapeProps[key] = (props as any)[key];
@@ -71,14 +74,19 @@ export const Polygon = React.forwardRef<Instance, ComponentProps>(
       }
     }, [shapeProps, polygon, x, y]);
 
-    // Register event handlers
+    // Unregister on unmount only
+    useEffect(() => {
+      return () => {
+        unregisterEventShape(polygon);
+      };
+    }, [polygon, unregisterEventShape]);
+
+    // Register / update event handlers
     useEffect(() => {
       if (Object.keys(eventHandlers).length > 0) {
         registerEventShape(polygon, eventHandlers, parent ?? undefined);
-
-        return () => {
-          unregisterEventShape(polygon);
-        };
+      } else {
+        unregisterEventShape(polygon);
       }
     }, [
       polygon,
diff --git a/lib/Provider.tsx b/lib/Provider.tsx
index 4f9d4dd..5e48cce 100644
--- a/lib/Provider.tsx
+++ b/lib/Provider.tsx
@@ -18,6 +18,7 @@ import {
 } from './Context';
 import type { EventHandlers } from './Events';
 import {
+  clientToWorldPoint,
   createTwoEvent,
   getCanvasCoordinates,
   getWorldCoordinates,
@@ -79,7 +80,10 @@ type ComponentProps = React.PropsWithChildren<
  * Warns in development mode if DOM elements or incompatible components are found.
  */
 function validateChildren(children: React.ReactNode): void {
-  if (process.env.NODE_ENV === 'production') {
+  if (
+    (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process?.env
+      ?.NODE_ENV === 'production'
+  ) {
     return;
   }
 
@@ -188,6 +192,25 @@ export const Provider = React.forwardRef<
     }
   }, []);
 
+  /**
+   * Returns true if any registered event shape sits under the given client
+   * coordinates. Used by `useZUI` to leave pointerdowns that landed on a
+   * shape alone, so shape drags and canvas panning never fight.
+   */
+  const hitTestPoint = useCallback(
+    (clientX: number, clientY: number): boolean => {
+      const canvas = twoState?.renderer.domElement;
+      if (!canvas) return false;
+
+      const point = clientToWorldPoint(clientX, clientY, canvas);
+      return (
+        getShapesAtPoint(eventShapes.current, point.x, point.y, twoState)
+          .length > 0
+      );
+    },
+    [twoState],
+  );
+
   // Initialize root Two.js instance
   useEffect(() => {
     const isRoot = !two;
@@ -237,11 +260,12 @@ export const Provider = React.forwardRef<
     }
   }, [two, twoState, props.width, props.height]);
 
-  // Validate children in development mode
+  // Validate children in development mode.
+  // `validateChildren` already no-ops in production, so no guard is needed
+  // here — gating the call on production as well made it dead in every
+  // environment.
   useEffect(() => {
-    if (process.env.NODE_ENV !== 'production') {
-      validateChildren(props.children);
-    }
+    validateChildren(props.children);
   }, [props.children]);
 
   // Setup event listeners on canvas
@@ -293,6 +317,7 @@ export const Provider = React.forwardRef<
         eventShapes.current,
         worldPoint.x,
         worldPoint.y,
+        twoState,
       );
 
       if (shapes.length > 0) {
@@ -307,6 +332,7 @@ export const Provider = React.forwardRef<
         eventShapes.current,
         worldPoint.x,
         worldPoint.y,
+        twoState,
       );
 
       if (shapes.length > 0) {
@@ -321,6 +347,7 @@ export const Provider = React.forwardRef<
         eventShapes.current,
         worldPoint.x,
         worldPoint.y,
+        twoState,
       );
 
       if (shapes.length > 0) {
@@ -335,6 +362,7 @@ export const Provider = React.forwardRef<
         eventShapes.current,
         worldPoint.x,
         worldPoint.y,
+        twoState,
       );
 
       if (shapes.length > 0) {
@@ -349,6 +377,7 @@ export const Provider = React.forwardRef<
         eventShapes.current,
         worldPoint.x,
         worldPoint.y,
+        twoState,
       );
 
       if (shapes.length > 0) {
@@ -389,6 +418,7 @@ export const Provider = React.forwardRef<
         eventShapes.current,
         worldPoint.x,
         worldPoint.y,
+        twoState,
       );
 
       if (shapes.length > 0) {
@@ -405,18 +435,30 @@ export const Provider = React.forwardRef<
         eventShapes.current,
         worldPoint.x,
         worldPoint.y,
+        twoState,
       );
-      const currentHovered = new Set(shapes);
 
-      // Dispatch pointer move to hovered shapes
-      if (shapes.length > 0) {
-        dispatchEvent(shapes, 'onPointerMove', e);
+      // Topmost shape under pointer (front-to-back sorted)
+      const topShape = shapes.length > 0 ? shapes[0] : null;
+
+      // Build set of currently hovered shapes (topmost shape + its parent hierarchy)
+      const currentHovered = new Set<Shape | Group>();
+      if (topShape) {
+        const hierarchy = getParentHierarchy(topShape, eventShapes.current);
+        for (const s of hierarchy) {
+          currentHovered.add(s);
+        }
+      }
+
+      // Dispatch pointer move to topmost shape hierarchy
+      if (topShape) {
+        dispatchEvent([topShape], 'onPointerMove', e);
       }
 
-      // Handle pointer enter/leave
+      // Handle pointer enter/leave and over/out
       const previousHovered = hoveredShapes.current;
 
-      // Enter: shapes now hovered but weren't before
+      // Enter / Over: shapes in currentHovered (topmost hierarchy) that weren't hovered before
       for (const shape of currentHovered) {
         if (!previousHovered.has(shape)) {
           dispatchEvent([shape], 'onPointerEnter', e);
@@ -424,7 +466,7 @@ export const Provider = React.forwardRef<
         }
       }
 
-      // Leave: shapes previously hovered but aren't now
+      // Leave / Out: shapes previously hovered that are no longer in currentHovered
       for (const shape of previousHovered) {
         if (!currentHovered.has(shape)) {
           dispatchEvent([shape], 'onPointerLeave', e);
@@ -442,6 +484,7 @@ export const Provider = React.forwardRef<
         eventShapes.current,
         worldPoint.x,
         worldPoint.y,
+        twoState,
       );
 
       if (shapes.length > 0) {
@@ -505,7 +548,7 @@ export const Provider = React.forwardRef<
         // Merge style object
         Object.assign(element.style, value);
       } else if (key === 'className') {
-        element.className = value as string;
+        element.setAttribute('class', value as string);
       } else if (key.startsWith('on') && typeof value === 'function') {
         // Handle React event props (onClick, onMouseMove, etc.)
         const eventName = key.slice(2).toLowerCase();
@@ -539,8 +582,9 @@ export const Provider = React.forwardRef<
       two: twoState,
       registerEventShape,
       unregisterEventShape,
+      hitTestPoint,
     }),
-    [twoState, registerEventShape, unregisterEventShape],
+    [twoState, registerEventShape, unregisterEventShape, hitTestPoint],
   );
 
   const parentValue = useMemo(
diff --git a/lib/Rectangle.tsx b/lib/Rectangle.tsx
index 86e33b1..77aadae 100644
--- a/lib/Rectangle.tsx
+++ b/lib/Rectangle.tsx
@@ -33,10 +33,13 @@ export const Rectangle = React.forwardRef<Instance, ComponentProps>(
 
       for (const key in props) {
         if (EVENT_HANDLER_NAMES.includes(key as keyof EventHandlers)) {
-          eventHandlers[key as keyof EventHandlers] = props[
-            key as keyof EventHandlers
+          // An explicitly `undefined` handler means "not interactive", so it
+          // must not count toward the registered handler set.
+          const handler = props[key as keyof EventHandlers];
+          if (handler !== undefined) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          ] as any;
+            eventHandlers[key as keyof EventHandlers] = handler as any;
+          }
         } else {
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           shapeProps[key] = (props as any)[key];
@@ -70,14 +73,19 @@ export const Rectangle = React.forwardRef<Instance, ComponentProps>(
       }
     }, [shapeProps, rectangle, x, y]);
 
-    // Register event handlers
+    // Unregister on unmount only
+    useEffect(() => {
+      return () => {
+        unregisterEventShape(rectangle);
+      };
+    }, [rectangle, unregisterEventShape]);
+
+    // Register / update event handlers
     useEffect(() => {
       if (Object.keys(eventHandlers).length > 0) {
         registerEventShape(rectangle, eventHandlers, parent ?? undefined);
-
-        return () => {
-          unregisterEventShape(rectangle);
-        };
+      } else {
+        unregisterEventShape(rectangle);
       }
     }, [
       rectangle,
diff --git a/lib/RoundedRectangle.tsx b/lib/RoundedRectangle.tsx
index 9b2dff8..0a3c1cd 100644
--- a/lib/RoundedRectangle.tsx
+++ b/lib/RoundedRectangle.tsx
@@ -33,10 +33,13 @@ export const RoundedRectangle = React.forwardRef<Instance, ComponentProps>(
 
       for (const key in props) {
         if (EVENT_HANDLER_NAMES.includes(key as keyof EventHandlers)) {
-          eventHandlers[key as keyof EventHandlers] = props[
-            key as keyof EventHandlers
+          // An explicitly `undefined` handler means "not interactive", so it
+          // must not count toward the registered handler set.
+          const handler = props[key as keyof EventHandlers];
+          if (handler !== undefined) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          ] as any;
+            eventHandlers[key as keyof EventHandlers] = handler as any;
+          }
         } else {
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           shapeProps[key] = (props as any)[key];
@@ -70,7 +73,14 @@ export const RoundedRectangle = React.forwardRef<Instance, ComponentProps>(
       }
     }, [shapeProps, roundedRectangle, x, y]);
 
-    // Register event handlers
+    // Unregister on unmount only
+    useEffect(() => {
+      return () => {
+        unregisterEventShape(roundedRectangle);
+      };
+    }, [roundedRectangle, unregisterEventShape]);
+
+    // Register / update event handlers
     useEffect(() => {
       if (Object.keys(eventHandlers).length > 0) {
         registerEventShape(
@@ -78,10 +88,8 @@ export const RoundedRectangle = React.forwardRef<Instance, ComponentProps>(
           eventHandlers,
           parent ?? undefined
         );
-
-        return () => {
-          unregisterEventShape(roundedRectangle);
-        };
+      } else {
+        unregisterEventShape(roundedRectangle);
       }
     }, [
       roundedRectangle,
diff --git a/lib/SVG.tsx b/lib/SVG.tsx
index db60e95..1f9e8ea 100644
--- a/lib/SVG.tsx
+++ b/lib/SVG.tsx
@@ -52,6 +52,7 @@ export const SVG = React.forwardRef<Instance, ComponentProps>(
       height,
       registerEventShape,
       unregisterEventShape,
+      hitTestPoint,
     } = useTwo();
     const svg = useMemo(() => new Two.Group(), []);
     const ref = useRef<Instance | null>(null);
@@ -77,10 +78,13 @@ export const SVG = React.forwardRef<Instance, ComponentProps>(
 
       for (const key in props) {
         if (EVENT_HANDLER_NAMES.includes(key as keyof EventHandlers)) {
-          eventHandlers[key as keyof EventHandlers] = props[
-            key as keyof EventHandlers
+          // An explicitly `undefined` handler means "not interactive", so it
+          // must not count toward the registered handler set.
+          const handler = props[key as keyof EventHandlers];
+          if (handler !== undefined) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          ] as any;
+            eventHandlers[key as keyof EventHandlers] = handler as any;
+          }
         } else {
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           shapeProps[key] = (props as any)[key];
@@ -213,16 +217,27 @@ export const SVG = React.forwardRef<Instance, ComponentProps>(
       }
     }, [svg, x, y, shapeProps]);
 
-    // Register event handlers
+    // Unregister on unmount only
+    useEffect(() => {
+      return () => {
+        unregisterEventShape(svg);
+      };
+    }, [svg, unregisterEventShape]);
+
+    // Register / update event handlers
     useEffect(() => {
       if (Object.keys(eventHandlers).length > 0) {
         registerEventShape(svg, eventHandlers, parent ?? undefined);
-
-        return () => {
-          unregisterEventShape(svg);
-        };
+      } else {
+        unregisterEventShape(svg);
       }
-    }, [svg, registerEventShape, unregisterEventShape, parent, eventHandlers]);
+    }, [
+      svg,
+      registerEventShape,
+      unregisterEventShape,
+      parent,
+      eventHandlers,
+    ]);
 
     useImperativeHandle(forwardedRef, () => svg, [svg]);
 
@@ -231,8 +246,9 @@ export const SVG = React.forwardRef<Instance, ComponentProps>(
         two,
         registerEventShape,
         unregisterEventShape,
+        hitTestPoint,
       }),
-      [two, registerEventShape, unregisterEventShape]
+      [two, registerEventShape, unregisterEventShape, hitTestPoint]
     );
 
     const parentValue = useMemo(
diff --git a/lib/Sprite.tsx b/lib/Sprite.tsx
index 426141d..d55eeb0 100644
--- a/lib/Sprite.tsx
+++ b/lib/Sprite.tsx
@@ -47,10 +47,13 @@ export const Sprite = React.forwardRef<Instance, ComponentProps>(
 
       for (const key in props) {
         if (EVENT_HANDLER_NAMES.includes(key as keyof EventHandlers)) {
-          eventHandlers[key as keyof EventHandlers] = props[
-            key as keyof EventHandlers
+          // An explicitly `undefined` handler means "not interactive", so it
+          // must not count toward the registered handler set.
+          const handler = props[key as keyof EventHandlers];
+          if (handler !== undefined) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          ] as any;
+            eventHandlers[key as keyof EventHandlers] = handler as any;
+          }
         } else {
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           shapeProps[key] = (props as any)[key];
@@ -90,14 +93,19 @@ export const Sprite = React.forwardRef<Instance, ComponentProps>(
       }
     }, [shapeProps, sprite, x, y, autoPlay]);
 
-    // Register event handlers
+    // Unregister on unmount only
+    useEffect(() => {
+      return () => {
+        unregisterEventShape(sprite);
+      };
+    }, [sprite, unregisterEventShape]);
+
+    // Register / update event handlers
     useEffect(() => {
       if (Object.keys(eventHandlers).length > 0) {
         registerEventShape(sprite, eventHandlers, parent ?? undefined);
-
-        return () => {
-          unregisterEventShape(sprite);
-        };
+      } else {
+        unregisterEventShape(sprite);
       }
     }, [
       sprite,
diff --git a/lib/Star.tsx b/lib/Star.tsx
index 67e3d5b..f3d0e62 100644
--- a/lib/Star.tsx
+++ b/lib/Star.tsx
@@ -33,10 +33,13 @@ export const Star = React.forwardRef<Instance, ComponentProps>(
 
       for (const key in props) {
         if (EVENT_HANDLER_NAMES.includes(key as keyof EventHandlers)) {
-          eventHandlers[key as keyof EventHandlers] = props[
-            key as keyof EventHandlers
+          // An explicitly `undefined` handler means "not interactive", so it
+          // must not count toward the registered handler set.
+          const handler = props[key as keyof EventHandlers];
+          if (handler !== undefined) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          ] as any;
+            eventHandlers[key as keyof EventHandlers] = handler as any;
+          }
         } else {
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           shapeProps[key] = (props as any)[key];
@@ -70,16 +73,27 @@ export const Star = React.forwardRef<Instance, ComponentProps>(
       }
     }, [shapeProps, star, x, y]);
 
-    // Register event handlers
+    // Unregister on unmount only
+    useEffect(() => {
+      return () => {
+        unregisterEventShape(star);
+      };
+    }, [star, unregisterEventShape]);
+
+    // Register / update event handlers
     useEffect(() => {
       if (Object.keys(eventHandlers).length > 0) {
         registerEventShape(star, eventHandlers, parent ?? undefined);
-
-        return () => {
-          unregisterEventShape(star);
-        };
+      } else {
+        unregisterEventShape(star);
       }
-    }, [star, registerEventShape, unregisterEventShape, parent, eventHandlers]);
+    }, [
+      star,
+      registerEventShape,
+      unregisterEventShape,
+      parent,
+      eventHandlers,
+    ]);
 
     useImperativeHandle(forwardedRef, () => star, [star]);
 
diff --git a/lib/Text.tsx b/lib/Text.tsx
index 73d8954..af76d22 100644
--- a/lib/Text.tsx
+++ b/lib/Text.tsx
@@ -49,10 +49,13 @@ export const Text = React.forwardRef<Instance, ComponentProps>(
 
       for (const key in props) {
         if (EVENT_HANDLER_NAMES.includes(key as keyof EventHandlers)) {
-          eventHandlers[key as keyof EventHandlers] = props[
-            key as keyof EventHandlers
+          // An explicitly `undefined` handler means "not interactive", so it
+          // must not count toward the registered handler set.
+          const handler = props[key as keyof EventHandlers];
+          if (handler !== undefined) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          ] as any;
+            eventHandlers[key as keyof EventHandlers] = handler as any;
+          }
         } else {
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           shapeProps[key] = (props as any)[key];
@@ -86,16 +89,27 @@ export const Text = React.forwardRef<Instance, ComponentProps>(
       }
     }, [shapeProps, text, x, y]);
 
-    // Register event handlers
+    // Unregister on unmount only
+    useEffect(() => {
+      return () => {
+        unregisterEventShape(text);
+      };
+    }, [text, unregisterEventShape]);
+
+    // Register / update event handlers
     useEffect(() => {
       if (Object.keys(eventHandlers).length > 0) {
         registerEventShape(text, eventHandlers, parent ?? undefined);
-
-        return () => {
-          unregisterEventShape(text);
-        };
+      } else {
+        unregisterEventShape(text);
       }
-    }, [text, registerEventShape, unregisterEventShape, parent, eventHandlers]);
+    }, [
+      text,
+      registerEventShape,
+      unregisterEventShape,
+      parent,
+      eventHandlers,
+    ]);
 
     useImperativeHandle(forwardedRef, () => text, [text]);
 
diff --git a/lib/ZUI.ts b/lib/ZUI.ts
new file mode 100644
index 0000000..2cb2885
--- /dev/null
+++ b/lib/ZUI.ts
@@ -0,0 +1,432 @@
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useSyncExternalStore,
+  type RefObject,
+} from 'react';
+import { useTwo } from './Context';
+import type { RefGroup } from './Group';
+import type { ZUIConstructor, ZUIInstance } from './zuiTypes';
+import {
+  centroid,
+  clamp,
+  distance,
+  pinchWheelZoomDelta,
+  pinchZoomDelta,
+  wheelZoomDelta,
+  type PanBounds,
+  type Point,
+} from './zuiMath';
+
+// two.js ships no declarations for its extras; `lib/zuiTypes.ts` types it
+// structurally so we never leak an ambient module into consumers.
+// @ts-expect-error - untyped two.js extra
+import { ZUI as ZUIImpl } from 'two.js/extras/jsm/zui.js';
+
+const ZUIClass = ZUIImpl as unknown as ZUIConstructor;
+
+/**
+ * A ref whose `current` is always present. React 18's own `RefObject<T>` types
+ * `current` as `T | null`, which would force a null check on every read of
+ * `zui.state.current`.
+ */
+export interface ReadonlyRef<T> {
+  readonly current: T;
+}
+
+/** Immutable snapshot of the current zoom/pan state. */
+export interface ZUIState {
+  /** Logarithmic zoom position. `scale === Math.exp(zoom)`. */
+  zoom: number;
+  /** Linear scale factor. */
+  scale: number;
+  /** Surface translation on the x axis, in client pixels. */
+  x: number;
+  /** Surface translation on the y axis, in client pixels. */
+  y: number;
+}
+
+export interface UseZUIOptions {
+  /** Minimum scale factor (default: 0.25) */
+  minZoom?: number;
+  /** Maximum scale factor (default: 8) */
+  maxZoom?: number;
+  /** Log-space zoom units per wheel notch (default: 0.05) */
+  wheelZoomSpeed?: number;
+  /** Optional clamp on surface translation, in client pixels */
+  panBounds?: PanBounds;
+  /**
+   * `'background'` (default) pans only when the pointer misses every
+   * registered shape, so shape drag handlers win. `'always'` pans on any
+   * drag. `false` disables pointer panning entirely.
+   */
+  pan?: 'background' | 'always' | false;
+  /** `'wheel'` (default) enables wheel and trackpad-pinch zoom; `false` disables it. */
+  zoom?: 'wheel' | false;
+  /** Override the element that listeners attach to (default: the Two.js renderer element) */
+  domElement?: HTMLElement | null;
+  /** Called at most once per animation frame while zoom or pan changes. */
+  onChange?: (state: ZUIState) => void;
+}
+
+export interface ZUIControls {
+  /** Live, always-current state. Reading this never triggers a re-render. */
+  state: ReadonlyRef<ZUIState>;
+  /** True while a pointer pan is in progress. */
+  isPanning: ReadonlyRef<boolean>;
+  /** The underlying Two.js ZUI instance, for advanced use. */
+  instance: ReadonlyRef<ZUIInstance | null>;
+  /** Zoom by a log-space amount, anchored at the given client point. */
+  zoomBy: (byF: number, clientX: number, clientY: number) => void;
+  /** Zoom to an absolute scale factor, anchored at the given client point. */
+  zoomTo: (scale: number, clientX: number, clientY: number) => void;
+  /** Pan by a delta in client pixels. */
+  panBy: (dx: number, dy: number) => void;
+  /** Pan to an absolute surface translation in client pixels. */
+  panTo: (x: number, y: number) => void;
+  /** Restore scale 1 and zero translation. */
+  reset: () => void;
+  /** Convert client coordinates into the ZUI group's local space. */
+  clientToSurface: (x: number, y: number) => Point;
+  /** Convert the ZUI group's local space back into client coordinates. */
+  surfaceToClient: (x: number, y: number) => Point;
+  /** Subscribe to coalesced state changes. Used by `useZUIState`. */
+  subscribe: (listener: () => void) => () => void;
+  /** Read the current immutable snapshot. Used by `useZUIState`. */
+  getSnapshot: () => ZUIState;
+}
+
+const IDENTITY_STATE: ZUIState = { zoom: 0, scale: 1, x: 0, y: 0 };
+
+/**
+ * Add zoom and pan to a react-two.js `Group`.
+ *
+ * The target group's `x`, `y`, and `scale` are owned by this hook — do not
+ * also pass those props to it, or the two will fight each other.
+ *
+ * @example
+ * ```tsx
+ * function Scene() {
+ *   const groupRef = useRef<RefGroup | null>(null);
+ *   const zui = useZUI(groupRef, { minZoom: 0.25, maxZoom: 8 });
+ *
+ *   return (
+ *     <Group ref={groupRef}>
+ *       <Circle radius={50} />
+ *     </Group>
+ *   );
+ * }
+ * ```
+ */
+export function useZUI(
+  target: RefObject<RefGroup | null>,
+  options: UseZUIOptions = {}
+): ZUIControls {
+  const { two, hitTestPoint } = useTwo();
+
+  const instance = useRef<ZUIInstance | null>(null);
+  const state = useRef<ZUIState>(IDENTITY_STATE);
+  const isPanning = useRef(false);
+  const listeners = useRef(new Set<() => void>());
+  const frame = useRef<number | null>(null);
+
+  // Latest options, read inside event handlers so they never need rebinding.
+  const optionsRef = useRef(options);
+  useEffect(() => {
+    optionsRef.current = options;
+  });
+
+  const {
+    minZoom = 0.25,
+    maxZoom = 8,
+    domElement: domElementOption,
+  } = options;
+
+  const element = domElementOption ?? two?.renderer.domElement ?? null;
+
+  /**
+   * Publish a fresh immutable snapshot. The snapshot updates synchronously so
+   * drag math stays exact, but subscribers are notified on the next animation
+   * frame so a wheel gesture cannot re-render the scene per event.
+   */
+  const flush = useCallback(() => {
+    const zui = instance.current;
+    if (!zui) return;
+
+    const elements = zui.surfaceMatrix.elements;
+    state.current = {
+      zoom: zui.zoom,
+      scale: zui.scale,
+      x: elements[2],
+      y: elements[5],
+    };
+
+    if (frame.current !== null) return;
+
+    frame.current = requestAnimationFrame(() => {
+      frame.current = null;
+      optionsRef.current.onChange?.(state.current);
+      for (const listener of listeners.current) {
+        listener();
+      }
+    });
+  }, []);
+
+  /** Two.js's ZUI declares limits.x / limits.y but never applies them. */
+  const applyPanBounds = useCallback(() => {
+    const zui = instance.current;
+    const bounds = optionsRef.current.panBounds;
+    if (!zui || !bounds) return;
+
+    const elements = zui.surfaceMatrix.elements;
+    const x = clamp(
+      elements[2],
+      bounds.x?.[0] ?? -Infinity,
+      bounds.x?.[1] ?? Infinity
+    );
+    const y = clamp(
+      elements[5],
+      bounds.y?.[0] ?? -Infinity,
+      bounds.y?.[1] ?? Infinity
+    );
+
+    if (x !== elements[2] || y !== elements[5]) {
+      zui.translateSurface(x - elements[2], y - elements[5]);
+    }
+  }, []);
+
+  // Create the ZUI instance once the group and element both exist.
+  useEffect(() => {
+    const group = target.current;
+    if (!group || !element) return;
+
+    const zui = new ZUIClass(group, element);
+    zui.addLimits(minZoom, maxZoom);
+    instance.current = zui;
+    flush();
+
+    return () => {
+      instance.current = null;
+      if (frame.current !== null) {
+        cancelAnimationFrame(frame.current);
+        frame.current = null;
+      }
+    };
+  }, [target, element, minZoom, maxZoom, flush]);
+
+  const zoomBy = useCallback(
+    (byF: number, clientX: number, clientY: number) => {
+      const zui = instance.current;
+      if (!zui) return;
+      zui.zoomBy(byF, clientX, clientY);
+      applyPanBounds();
+      flush();
+    },
+    [applyPanBounds, flush]
+  );
+
+  const zoomTo = useCallback(
+    (scale: number, clientX: number, clientY: number) => {
+      const zui = instance.current;
+      if (!zui) return;
+      zui.zoomSet(scale, clientX, clientY);
+      applyPanBounds();
+      flush();
+    },
+    [applyPanBounds, flush]
+  );
+
+  const panBy = useCallback(
+    (dx: number, dy: number) => {
+      const zui = instance.current;
+      if (!zui) return;
+      zui.translateSurface(dx, dy);
+      applyPanBounds();
+      flush();
+    },
+    [applyPanBounds, flush]
+  );
+
+  const panTo = useCallback(
+    (x: number, y: number) => {
+      const zui = instance.current;
+      if (!zui) return;
+      const elements = zui.surfaceMatrix.elements;
+      zui.translateSurface(x - elements[2], y - elements[5]);
+      applyPanBounds();
+      flush();
+    },
+    [applyPanBounds, flush]
+  );
+
+  const reset = useCallback(() => {
+    const zui = instance.current;
+    if (!zui) return;
+    zui.reset();
+    flush();
+  }, [flush]);
+
+  const clientToSurface = useCallback((x: number, y: number): Point => {
+    const zui = instance.current;
+    if (!zui) return { x, y };
+    const result = zui.clientToSurface(x, y);
+    return { x: result.x, y: result.y };
+  }, []);
+
+  const surfaceToClient = useCallback((x: number, y: number): Point => {
+    const zui = instance.current;
+    if (!zui) return { x, y };
+    const result = zui.surfaceToClient(x, y);
+    return { x: result.x, y: result.y };
+  }, []);
+
+  const subscribe = useCallback((listener: () => void) => {
+    listeners.current.add(listener);
+    return () => {
+      listeners.current.delete(listener);
+    };
+  }, []);
+
+  const getSnapshot = useCallback(() => state.current, []);
+
+  // Pointer panning and pinch zoom. One code path covers mouse, touch and pen.
+  useEffect(() => {
+    if (!element) return;
+
+    const active = new Map<number, Point>();
+    let lastCentroid: Point | null = null;
+    let lastDistance = 0;
+
+    const points = () => Array.from(active.values());
+
+    const handlePointerDown = (event: PointerEvent) => {
+      const mode = optionsRef.current.pan ?? 'background';
+      if (mode === false) return;
+      if (event.pointerType === 'mouse' && event.button !== 0) return;
+      if (mode === 'background' && hitTestPoint(event.clientX, event.clientY)) {
+        return;
+      }
+
+      active.set(event.pointerId, { x: event.clientX, y: event.clientY });
+      isPanning.current = true;
+      lastCentroid = centroid(points());
+      lastDistance = active.size === 2 ? distance(points()[0], points()[1]) : 0;
+    };
+
+    const handlePointerMove = (event: PointerEvent) => {
+      if (!active.has(event.pointerId)) return;
+
+      active.set(event.pointerId, { x: event.clientX, y: event.clientY });
+      const current = points();
+      const nextCentroid = centroid(current);
+
+      if (lastCentroid) {
+        panBy(nextCentroid.x - lastCentroid.x, nextCentroid.y - lastCentroid.y);
+      }
+      lastCentroid = nextCentroid;
+
+      if (current.length === 2) {
+        const nextDistance = distance(current[0], current[1]);
+        if (lastDistance > 0) {
+          zoomBy(
+            pinchZoomDelta(lastDistance, nextDistance),
+            nextCentroid.x,
+            nextCentroid.y
+          );
+        }
+        lastDistance = nextDistance;
+      }
+    };
+
+    const endPointer = (event: PointerEvent) => {
+      if (!active.delete(event.pointerId)) return;
+
+      const remaining = points();
+      lastCentroid = remaining.length > 0 ? centroid(remaining) : null;
+      lastDistance =
+        remaining.length === 2 ? distance(remaining[0], remaining[1]) : 0;
+      isPanning.current = active.size > 0;
+    };
+
+    element.addEventListener('pointerdown', handlePointerDown);
+    window.addEventListener('pointermove', handlePointerMove);
+    window.addEventListener('pointerup', endPointer);
+    window.addEventListener('pointercancel', endPointer);
+    window.addEventListener('lostpointercapture', endPointer);
+
+    return () => {
+      element.removeEventListener('pointerdown', handlePointerDown);
+      window.removeEventListener('pointermove', handlePointerMove);
+      window.removeEventListener('pointerup', endPointer);
+      window.removeEventListener('pointercancel', endPointer);
+      window.removeEventListener('lostpointercapture', endPointer);
+    };
+  }, [element, hitTestPoint, panBy, zoomBy]);
+
+  // Wheel zoom, including ctrl+wheel trackpad pinch.
+  useEffect(() => {
+    if (!element) return;
+
+    const handleWheel = (event: WheelEvent) => {
+      if ((optionsRef.current.zoom ?? 'wheel') === false) return;
+
+      event.preventDefault();
+
+      const delta = event.ctrlKey
+        ? pinchWheelZoomDelta(event.deltaY)
+        : wheelZoomDelta(
+            event.deltaY,
+            event.deltaMode,
+            optionsRef.current.wheelZoomSpeed ?? 0.05,
+            element.clientHeight || window.innerHeight
+          );
+
+      zoomBy(delta, event.clientX, event.clientY);
+    };
+
+    element.addEventListener('wheel', handleWheel, { passive: false });
+    return () => element.removeEventListener('wheel', handleWheel);
+  }, [element, zoomBy]);
+
+  return useMemo(
+    () => ({
+      state,
+      isPanning,
+      instance,
+      zoomBy,
+      zoomTo,
+      panBy,
+      panTo,
+      reset,
+      clientToSurface,
+      surfaceToClient,
+      subscribe,
+      getSnapshot,
+    }),
+    [
+      zoomBy,
+      zoomTo,
+      panBy,
+      panTo,
+      reset,
+      clientToSurface,
+      surfaceToClient,
+      subscribe,
+      getSnapshot,
+    ]
+  );
+}
+
+/**
+ * Opt into re-rendering when zoom or pan changes. Only use this in components
+ * that actually display the value — `useZUI` alone never re-renders.
+ */
+export function useZUIState(controls: ZUIControls): ZUIState {
+  return useSyncExternalStore(
+    controls.subscribe,
+    controls.getSnapshot,
+    controls.getSnapshot
+  );
+}
diff --git a/lib/main.ts b/lib/main.ts
index 029aabc..3505b7b 100644
--- a/lib/main.ts
+++ b/lib/main.ts
@@ -1,6 +1,14 @@
 export { Provider as Canvas } from './Provider';
 export { Context, useTwo, useFrame } from './Context';
 export { Group, type RefGroup } from './Group';
+export {
+  useZUI,
+  useZUIState,
+  type UseZUIOptions,
+  type ZUIControls,
+  type ZUIState,
+  type ReadonlyRef,
+} from './ZUI';
 export { SVG, type RefSVG } from './SVG';
 export { Path, type RefPath } from './Path';
 export { Points, type RefPoints } from './Points';
@@ -25,3 +33,7 @@ export { RadialGradient, type RefRadialGradient } from './RadialGradient';
 
 // Texture exports
 export { Texture, type RefTexture } from './Texture';
+
+// Event exports
+export type { TwoEvent, EventHandler, EventHandlers } from './Events';
+
diff --git a/lib/zuiMath.ts b/lib/zuiMath.ts
new file mode 100644
index 0000000..e06e64d
--- /dev/null
+++ b/lib/zuiMath.ts
@@ -0,0 +1,103 @@
+/**
+ * Pure gesture math for the ZUI hook. No React, no DOM — everything here is
+ * directly unit-testable.
+ *
+ * Two.js's ZUI treats zoom logarithmically (`scale = Math.exp(zoom)`), so all
+ * "delta" helpers below return log-space amounts suitable for `zui.zoomBy()`.
+ */
+
+/** Approximate pixel height of one wheel "line" in DOM_DELTA_LINE mode. */
+export const LINE_HEIGHT_PX = 16;
+
+/** Log-space units applied per unit of ctrl+wheel (trackpad pinch) delta. */
+export const PINCH_WHEEL_FACTOR = 0.01;
+
+/** A single wheel notch in DOM_DELTA_PIXEL mode, used to normalise `speed`. */
+export const WHEEL_NOTCH_PX = 100;
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+export interface PanBounds {
+  x?: [number, number];
+  y?: [number, number];
+}
+
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+/**
+ * Convert a `WheelEvent.deltaY` into pixels, accounting for `deltaMode`.
+ * Firefox reports lines (mode 1); some environments report pages (mode 2).
+ */
+export function normalizeWheelDelta(
+  deltaY: number,
+  deltaMode: number,
+  viewportHeight: number
+): number {
+  switch (deltaMode) {
+    case 1:
+      return deltaY * LINE_HEIGHT_PX;
+    case 2:
+      return deltaY * viewportHeight;
+    default:
+      return deltaY;
+  }
+}
+
+/**
+ * Log-space zoom delta for a standard scroll wheel. `speed` is expressed in
+ * log units per notch, so the default of 0.05 means one notch changes scale
+ * by a factor of e^0.05 (~5%).
+ */
+export function wheelZoomDelta(
+  deltaY: number,
+  deltaMode: number,
+  speed: number,
+  viewportHeight: number
+): number {
+  const pixels = normalizeWheelDelta(deltaY, deltaMode, viewportHeight);
+  return (-pixels / WHEEL_NOTCH_PX) * speed;
+}
+
+/** Log-space zoom delta for a trackpad pinch, which arrives as ctrl+wheel. */
+export function pinchWheelZoomDelta(deltaY: number): number {
+  return -deltaY * PINCH_WHEEL_FACTOR;
+}
+
+/**
+ * Log-space zoom delta for a two-finger pinch. Using the log of the distance
+ * ratio makes the gesture feel identical at every zoom level — the WIP branch
+ * used a linear pixel difference, which did not.
+ */
+export function pinchZoomDelta(
+  prevDistance: number,
+  nextDistance: number
+): number {
+  if (prevDistance <= 0 || nextDistance <= 0) {
+    return 0;
+  }
+  return Math.log(nextDistance / prevDistance);
+}
+
+export function distance(a: Point, b: Point): number {
+  const dx = a.x - b.x;
+  const dy = a.y - b.y;
+  return Math.sqrt(dx * dx + dy * dy);
+}
+
+export function centroid(points: Point[]): Point {
+  if (points.length === 0) {
+    return { x: 0, y: 0 };
+  }
+  let x = 0;
+  let y = 0;
+  for (const point of points) {
+    x += point.x;
+    y += point.y;
+  }
+  return { x: x / points.length, y: y / points.length };
+}
diff --git a/lib/zuiTypes.ts b/lib/zuiTypes.ts
new file mode 100644
index 0000000..f54c49d
--- /dev/null
+++ b/lib/zuiTypes.ts
@@ -0,0 +1,40 @@
+/**
+ * Local, non-ambient types for `two.js/extras/jsm/zui.js`, which ships no
+ * declarations. Declaring this as an ambient module would leak into every
+ * consumer of react-two.js, so we type it structurally and cast at the
+ * single import site in `lib/ZUI.ts`.
+ */
+import type { Group } from 'two.js/src/group';
+import type { Matrix } from 'two.js/src/matrix';
+
+export interface ZUIVector {
+  x: number;
+  y: number;
+  z: number;
+}
+
+export interface ZUIInstance {
+  zoom: number;
+  scale: number;
+  surfaceMatrix: Matrix;
+  viewport: HTMLElement;
+  limits: {
+    scale: { min: number; max: number };
+    x: { min: number; max: number };
+    y: { min: number; max: number };
+  };
+  addLimits(min?: number, max?: number): ZUIInstance;
+  zoomBy(byF: number, clientX: number, clientY: number): ZUIInstance;
+  zoomSet(zoom: number, clientX: number, clientY: number): ZUIInstance;
+  translateSurface(x: number, y: number): ZUIInstance;
+  clientToSurface(x: number, y: number, z?: number): ZUIVector;
+  surfaceToClient(x: number, y: number, z?: number): ZUIVector;
+  updateOffset(): ZUIInstance;
+  updateSurface(): ZUIInstance;
+  reset(): ZUIInstance;
+}
+
+export type ZUIConstructor = new (
+  group: Group,
+  domElement?: HTMLElement
+) => ZUIInstance;
diff --git a/package-lock.json b/package-lock.json
index 5f6ecd3..901655c 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "react-two.js",
-  "version": "0.8.23-r.1",
+  "version": "0.8.23-r.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "react-two.js",
-      "version": "0.8.23-r.1",
+      "version": "0.8.23-r.2",
       "license": "MIT",
       "devDependencies": {
         "@eslint/js": "^9.13.0",
@@ -16,7 +16,7 @@
         "@testing-library/jest-dom": "^6.6.3",
         "@testing-library/react": "^16.3.0",
         "@testing-library/user-event": "^14.6.1",
-        "@types/node": "^22.10.7",
+        "@types/node": "^22.20.1",
         "@types/react": "^18.3.12",
         "@types/react-dom": "^18.3.1",
         "@vitejs/plugin-react": "^4.3.3",
@@ -2599,9 +2599,9 @@
       "license": "MIT"
     },
     "node_modules/@types/node": {
-      "version": "22.18.8",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-22.18.8.tgz",
-      "integrity": "sha512-pAZSHMiagDR7cARo/cch1f3rXy0AEXwsVsVH09FcyeJVAzCnGgmYis7P3JidtTUjyadhTeSo8TgRPswstghDaw==",
+      "version": "22.20.1",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-22.20.1.tgz",
+      "integrity": "sha512-EANqOCF9QFyra+4pfxUcX9STKJpCLjMbObVzljIJomAWSnuSIEAvyzEU53GaajbXJEgdh0iEcPL+DGvpUd4k1Q==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
diff --git a/package.json b/package.json
index edbdd89..baef115 100644
--- a/package.json
+++ b/package.json
@@ -58,7 +58,7 @@
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.1",
-    "@types/node": "^22.10.7",
+    "@types/node": "^22.20.1",
     "@types/react": "^18.3.12",
     "@types/react-dom": "^18.3.1",
     "@vitejs/plugin-react": "^4.3.3",
@@ -83,4 +83,4 @@
     "react-dom": ">=19",
     "two.js": ">=v0.8.23"
   }
-}
\ No newline at end of file
+}
diff --git a/src/App.tsx b/src/App.tsx
index 87bb916..b3e748e 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -16,16 +16,21 @@ import {
   CommandLineIcon,
   CurrencyDollarIcon,
   SparklesIcon,
+  Squares2X2Icon,
+  ShareIcon,
 } from '@heroicons/react/20/solid';
 import cn from 'clsx';
 import Playground from './Playground';
 import { useEffect, useState } from 'react';
 import { version } from '../package.json';
+import { PLAYGROUNDS } from './playgrounds/registry';
 
 export default function App() {
   const [domElement, setDomElement] = useState<HTMLDivElement | null>(null);
   const [width, setWidth] = useState(400);
   const [height, setHeight] = useState(300);
+  const [activePlaygroundId, setActivePlaygroundId] = useState('wiremarks');
+
   const sidebar = (
     <Sidebar>
       <SidebarBody>
@@ -59,25 +64,43 @@ export default function App() {
 
         <SidebarDivider />
 
+        <SidebarSection>
+          <SidebarHeading>Playgrounds</SidebarHeading>
+          {PLAYGROUNDS.map((playground) => {
+            const isWiremarks = playground.id === 'wiremarks';
+            const Icon = isWiremarks ? ShareIcon : Squares2X2Icon;
+            const isCurrent = activePlaygroundId === playground.id;
+
+            return (
+              <SidebarItem
+                key={playground.id}
+                current={isCurrent}
+                onClick={() => setActivePlaygroundId(playground.id)}
+              >
+                <Icon data-slot="icon" />
+                <SidebarLabel>{playground.name}</SidebarLabel>
+              </SidebarItem>
+            );
+          })}
+        </SidebarSection>
+
+        <SidebarDivider />
+
         <SidebarSection>
           <SidebarItem href="https://github.com/jonobr1/react-two.js">
-            <CodeBracketIcon /> <SidebarLabel>Github</SidebarLabel>
+            <CodeBracketIcon data-slot="icon" /> <SidebarLabel>GitHub</SidebarLabel>
           </SidebarItem>
           <SidebarItem href="https://npmjs.com/package/react-two.js">
-            <CommandLineIcon /> <SidebarLabel>Package</SidebarLabel>
+            <CommandLineIcon data-slot="icon" /> <SidebarLabel>Package</SidebarLabel>
           </SidebarItem>
           <SidebarItem href="https://github.com/sponsors/jonobr1">
-            <CurrencyDollarIcon /> <SidebarLabel>Sponsor</SidebarLabel>
+            <CurrencyDollarIcon data-slot="icon" /> <SidebarLabel>Sponsor</SidebarLabel>
           </SidebarItem>
           <SidebarItem href="https://chatgpt.com/g/g-hkcTX8uPm-two-js-tutor">
-            <SparklesIcon />
+            <SparklesIcon data-slot="icon" />
             <SidebarLabel>ChatGPT</SidebarLabel>
           </SidebarItem>
         </SidebarSection>
-
-        <SidebarDivider />
-
-        <SidebarSection></SidebarSection>
       </SidebarBody>
     </Sidebar>
   );
@@ -101,7 +124,11 @@ export default function App() {
 
   return (
     <SidebarLayout ref={setDomElement} navbar={null} sidebar={sidebar}>
-      <Playground width={width} height={height} />
+      <Playground
+        width={width}
+        height={height}
+        activePlaygroundId={activePlaygroundId}
+      />
     </SidebarLayout>
   );
 }
diff --git a/src/Playground.tsx b/src/Playground.tsx
index 45f875f..e6393a5 100644
--- a/src/Playground.tsx
+++ b/src/Playground.tsx
@@ -1,406 +1,18 @@
-import Two from 'two.js';
-import {
-  Group,
-  Canvas,
-  Path,
-  RefPath,
-  useTwo,
-  Points,
-  RefPoints,
-  Circle,
-  RefCircle,
-  Rectangle,
-  RefRectangle,
-  RoundedRectangle,
-  RefRoundedRectangle,
-  Ellipse,
-  RefEllipse,
-  Line,
-  RefLine,
-  Polygon,
-  RefPolygon,
-  Star,
-  RefStar,
-  ArcSegment,
-  RefArcSegment,
-  Sprite,
-  RefSprite,
-  ImageSequence,
-  RefImageSequence,
-  LinearGradient,
-  RefLinearGradient,
-  RadialGradient,
-  RefRadialGradient,
-  Texture,
-  RefTexture,
-  Text,
-  SVG,
-  RefSVG,
-  RefGroup,
-} from '../lib/main';
-import { useEffect, useRef, useState } from 'react';
-import { useFrame } from '../lib/Context';
+import { getPlaygroundById } from './playgrounds/registry';
 
-function Scene() {
-  const { width, height } = useTwo();
-
-  // Create refs for all components
-  const path = useRef<RefPath | null>(null);
-  const points = useRef<RefPoints | null>(null);
-  const circle = useRef<RefCircle | null>(null);
-  const rectangle = useRef<RefRectangle | null>(null);
-  const roundedRectangle = useRef<RefRoundedRectangle | null>(null);
-  const ellipse = useRef<RefEllipse | null>(null);
-  const line = useRef<RefLine | null>(null);
-  const polygon = useRef<RefPolygon | null>(null);
-  const star = useRef<RefStar | null>(null);
-  const arcSegment = useRef<RefArcSegment | null>(null);
-  const sprite = useRef<RefSprite | null>(null);
-  const imageSequence = useRef<RefImageSequence | null>(null);
-  const svg = useRef<RefSVG | null>(null);
-
-  // Gradient refs
-  const [linearGradient, setLinearGradient] = useState<
-    string | RefLinearGradient
-  >('#FF6B6B');
-  const radialGradient = useRef<RefRadialGradient | null>(null);
-
-  // Texture ref
-  const [texture, setTexture] = useState<string | RefTexture>('#E8E8E8');
-
-  // Interactive state
-  const [circleHovered, setCircleHovered] = useState(false);
-  const [rectangleClicked, setRectangleClicked] = useState(false);
-  const [starHovered, setStarHovered] = useState(false);
-
-  useFrame((elapsed) => {
-    // Animate all the components
-    if (path.current) {
-      path.current.rotation = elapsed * 0.5;
-    }
-    if (points.current) {
-      points.current.rotation = -elapsed * 0.3;
-    }
-    if (circle.current) {
-      circle.current.scale = Math.sin(elapsed) * 0.25 + 1;
-    }
-    if (rectangle.current) {
-      rectangle.current.rotation = elapsed * 0.2;
-    }
-    if (roundedRectangle.current) {
-      roundedRectangle.current.rotation = -elapsed * 0.15;
-    }
-    if (ellipse.current) {
-      ellipse.current.scale = Math.cos(elapsed * 0.5) * 0.25 + 1;
-      ellipse.current.dashes.offset = -50 * elapsed;
-    }
-    if (line.current) {
-      line.current.rotation = elapsed * 0.4;
-    }
-    if (polygon.current) {
-      polygon.current.rotation = elapsed * 0.1;
-    }
-    if (star.current) {
-      star.current.rotation = -elapsed * 0.25;
-      star.current.innerRadius = 20 + Math.sin(elapsed * 2) * 10;
-    }
-    if (arcSegment.current) {
-      arcSegment.current.startAngle = elapsed % (Math.PI * 2);
-    }
-    if (sprite.current) {
-      sprite.current.rotation = elapsed * 0.3;
-    }
-    if (imageSequence.current) {
-      imageSequence.current.scale = Math.cos(elapsed * 1.2) * 0.15 + 1;
-    }
-    if (svg.current) {
-      svg.current.rotation = elapsed * 0.2;
-      svg.current.scale = Math.sin(elapsed * 0.8) * 0.2 + 1;
-    }
-  }, []);
-
-  // Calculate grid positions
-  const gridSize = 4;
-  const cellWidth = width / gridSize;
-  const cellHeight = height / gridSize;
-
-  return (
-    <Group>
-      {/* Original components */}
-      <Group x={cellWidth * 0.5} y={cellHeight * 0.5}>
-        <Path
-          ref={path}
-          vertices={[
-            new Two.Anchor(-10, 0),
-            new Two.Anchor(0, 10),
-            new Two.Anchor(0, -10),
-            new Two.Anchor(10, 0),
-          ]}
-          scale={5}
-          stroke="#FF5733"
-          linewidth={2}
-          fill="transparent"
-        />
-        <Points
-          ref={points}
-          vertices={[
-            new Two.Vector(-20, -20),
-            new Two.Vector(0, 0),
-            new Two.Vector(20, 20),
-            new Two.Vector(-20, 20),
-            new Two.Vector(20, -20),
-          ]}
-          stroke="transparent"
-          fill="#3498DB"
-          size={5}
-        />
-      </Group>
-
-      {/* Circle - Interactive with hover */}
-      <Group x={cellWidth * 1.5} y={cellHeight * 0.5}>
-        <Circle
-          ref={circle}
-          radius={30}
-          fill={circleHovered ? '#FFD700' : '#F1C40F'}
-          stroke={circleHovered ? '#FF8C00' : '#E67E22'}
-          linewidth={circleHovered ? 5 : 3}
-          onPointerOver={() => setCircleHovered(true)}
-          onPointerOut={() => setCircleHovered(false)}
-        />
-      </Group>
-
-      {/* Rectangle - Interactive with click */}
-      <Group x={cellWidth * 2.5} y={cellHeight * 0.5}>
-        <Rectangle
-          ref={rectangle}
-          width={60}
-          height={40}
-          fill={rectangleClicked ? '#E74C3C' : '#2ECC71'}
-          stroke={rectangleClicked ? '#C0392B' : '#27AE60'}
-          linewidth={rectangleClicked ? 4 : 2}
-          onClick={() => setRectangleClicked(!rectangleClicked)}
-        />
-      </Group>
-
-      {/* SVG Example - Inline content */}
-      <Group x={cellWidth * 3.5} y={cellHeight * 0.5}>
-        <SVG
-          ref={svg}
-          content={`
-            <svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
-              <circle cx="50" cy="50" r="40" fill="#FF6B6B" />
-              <circle cx="35" cy="40" r="8" fill="white" />
-              <circle cx="65" cy="40" r="8" fill="white" />
-              <path d="M 30 60 Q 50 75 70 60" stroke="white" stroke-width="4" fill="none" stroke-linecap="round" />
-            </svg>
-          `}
-          scale={0.6}
-          onLoad={(svg: RefGroup) => {
-            svg.center();
-          }}
-        />
-      </Group>
-
-      {/* Rounded Rectangle */}
-      <Group x={cellWidth * 0.5} y={cellHeight * 1.5}>
-        <RoundedRectangle
-          ref={roundedRectangle}
-          width={60}
-          height={40}
-          radius={10}
-          fill="#9B59B6"
-          stroke="#8E44AD"
-          linewidth={2}
-        />
-      </Group>
-
-      {/* Ellipse */}
-      <Group x={cellWidth * 1.5} y={cellHeight * 1.5}>
-        <Ellipse
-          ref={ellipse}
-          width={70}
-          height={40}
-          fill="#3498DB"
-          stroke="#2980B9"
-          linewidth={2}
-          dashes={[5, 5]}
-        />
-      </Group>
-
-      {/* Line */}
-      <Group x={cellWidth * 2.5} y={cellHeight * 1.5}>
-        <Line
-          ref={line}
-          left={new Two.Anchor(-50, 20)}
-          right={new Two.Anchor(50, 20)}
-          stroke="#34495E"
-          linewidth={4}
-          cap="round"
-        />
-      </Group>
-
-      {/* Text */}
-      <Group x={cellWidth * 3.5} y={cellHeight * 1.5}>
-        <Text value="Two.js" fill="#61DAFB" size={24} baseline="middle" />
-      </Group>
-
-      {/* Polygon */}
-      <Group x={cellWidth * 0.5} y={cellHeight * 2.5}>
-        <Polygon
-          ref={polygon}
-          width={100}
-          height={100}
-          sides={5}
-          fill="#16A085"
-          stroke="#1ABC9C"
-          linewidth={2}
-        />
-      </Group>
-
-      {/* Star - Interactive with hover and pointer events */}
-      <Group x={cellWidth * 1.5} y={cellHeight * 2.5}>
-        <Star
-          ref={star}
-          innerRadius={20}
-          outerRadius={starHovered ? 45 : 40}
-          sides={5}
-          fill={starHovered ? '#F1C40F' : '#F39C12'}
-          stroke={starHovered ? '#E67E22' : '#D35400'}
-          linewidth={starHovered ? 3 : 2}
-          onPointerEnter={() => setStarHovered(true)}
-          onPointerLeave={() => setStarHovered(false)}
-        />
-      </Group>
-
-      {/* ArcSegment */}
-      <Group x={cellWidth * 2.5} y={cellHeight * 2.5}>
-        <ArcSegment
-          ref={arcSegment}
-          innerRadius={20}
-          outerRadius={40}
-          startAngle={0}
-          endAngle={Math.PI * 1.5}
-          fill="#E74C3C"
-          stroke="#C0392B"
-          linewidth={2}
-        />
-      </Group>
-
-      {/* Sprite */}
-      <Group x={cellWidth * 3.5} y={cellHeight * 2.5}>
-        <Sprite ref={sprite} src="https://placehold.co/60x60" />
-      </Group>
-
-      {/* Extra components in the 4th row */}
-      <Group x={cellWidth * 0.5} y={cellHeight * 3.5}>
-        <ImageSequence
-          ref={imageSequence}
-          src={[
-            'https://placehold.co/60x60/FF6B6B/FFFFFF?text=1',
-            'https://placehold.co/60x60/4ECDC4/FFFFFF?text=2',
-            'https://placehold.co/60x60/45B7D1/FFFFFF?text=3',
-            'https://placehold.co/60x60/F7DC6F/FFFFFF?text=4',
-          ]}
-          frameRate={1}
-          autoPlay={true}
-        />
-      </Group>
-
-      {/* Linear Gradient Example */}
-      <Group x={cellWidth * 1.5} y={cellHeight * 3.5}>
-        <LinearGradient
-          ref={(ref) => {
-            if (ref) setLinearGradient(ref);
-          }}
-          x1={0}
-          y1={0}
-          x2={1}
-          y2={1}
-          stops={[
-            new Two.Stop(0, 'red'),
-            new Two.Stop(0.5, 'green'),
-            new Two.Stop(1, 'blue'),
-          ]}
-        />
-        <Circle radius={30} fill={linearGradient} stroke="#333" linewidth={2} />
-      </Group>
-
-      {/* Radial Gradient Example */}
-      <Group x={cellWidth * 2.5} y={cellHeight * 3.5}>
-        <RadialGradient
-          ref={radialGradient}
-          x={0}
-          y={0}
-          radius={1}
-          stops={[
-            new Two.Stop(0, '#F7DC6F'),
-            new Two.Stop(0.7, '#F39C12'),
-            new Two.Stop(1, '#E67E22'),
-          ]}
-        />
-        <Rectangle
-          width={60}
-          height={40}
-          fill={radialGradient.current || '#F7DC6F'}
-          stroke="#333"
-          linewidth={2}
-        />
-      </Group>
-
-      {/* Texture Example */}
-      <Group x={cellWidth * 3.5} y={cellHeight * 3.5}>
-        <Texture
-          ref={(ref) => {
-            if (ref) setTexture(ref);
-          }}
-          src="https://placehold.co/60x60/9B59B6/FFFFFF?text=TEX"
-        />
-        <Rectangle
-          width={60}
-          height={40}
-          fill={texture}
-          stroke="#333"
-          linewidth={2}
-        />
-      </Group>
-    </Group>
-  );
+interface PlaygroundProps {
+  width?: number;
+  height?: number;
+  activePlaygroundId?: string;
 }
 
 export default function Playground({
   width,
   height,
-}: {
-  width?: number;
-  height?: number;
-}) {
-  // Demonstrate ref forwarding to access the actual canvas element
-  const canvasRef = useRef<HTMLCanvasElement | null>(null);
-
-  // Example: You can now access the canvas element directly
-  useEffect(() => {
-    if (canvasRef.current) {
-      console.log('Canvas element:', canvasRef.current);
-      // You could get the 2D context: canvasRef.current.getContext('2d')
-    }
-  }, []);
+  activePlaygroundId = 'wiremarks',
+}: PlaygroundProps) {
+  const playgroundDef = getPlaygroundById(activePlaygroundId);
+  const ActiveComponent = playgroundDef.component;
 
-  return (
-    <Canvas
-      ref={canvasRef}
-      type={Two.Types.canvas}
-      width={width}
-      height={height}
-      autostart={true}
-      // DOM props are now applied directly to the canvas element
-      // unless fullscreen exists because it manipulates that for you
-      className="react-two-canvas"
-      style={{
-        userSelect: 'none',
-      }}
-      aria-label="Interactive Two.js canvas demonstration"
-    >
-      <Scene />
-    </Canvas>
-  );
+  return <ActiveComponent width={width} height={height} />;
 }
diff --git a/src/playgrounds/components-showcase/ComponentsShowcasePlayground.tsx b/src/playgrounds/components-showcase/ComponentsShowcasePlayground.tsx
new file mode 100644
index 0000000..8c9c52b
--- /dev/null
+++ b/src/playgrounds/components-showcase/ComponentsShowcasePlayground.tsx
@@ -0,0 +1,352 @@
+import Two from 'two.js';
+import {
+  Group,
+  Canvas,
+  Path,
+  RefPath,
+  useTwo,
+  Points,
+  RefPoints,
+  Circle,
+  RefCircle,
+  Rectangle,
+  RefRectangle,
+  RoundedRectangle,
+  RefRoundedRectangle,
+  Ellipse,
+  RefEllipse,
+  Line,
+  RefLine,
+  Polygon,
+  RefPolygon,
+  Star,
+  RefStar,
+  ArcSegment,
+  RefArcSegment,
+  Sprite,
+  RefSprite,
+  ImageSequence,
+  RefImageSequence,
+  LinearGradient,
+  RefLinearGradient,
+  RadialGradient,
+  RefRadialGradient,
+  Texture,
+  RefTexture,
+  Text,
+  SVG,
+  RefSVG,
+  RefGroup,
+  useFrame,
+} from 'react-two.js';
+import { useRef, useState } from 'react';
+import { PlaygroundProps } from '../types';
+
+function Scene() {
+  const { width, height } = useTwo();
+
+  const path = useRef<RefPath | null>(null);
+  const points = useRef<RefPoints | null>(null);
+  const circle = useRef<RefCircle | null>(null);
+  const rectangle = useRef<RefRectangle | null>(null);
+  const roundedRectangle = useRef<RefRoundedRectangle | null>(null);
+  const ellipse = useRef<RefEllipse | null>(null);
+  const line = useRef<RefLine | null>(null);
+  const polygon = useRef<RefPolygon | null>(null);
+  const star = useRef<RefStar | null>(null);
+  const arcSegment = useRef<RefArcSegment | null>(null);
+  const sprite = useRef<RefSprite | null>(null);
+  const imageSequence = useRef<RefImageSequence | null>(null);
+  const svg = useRef<RefSVG | null>(null);
+
+  const [linearGradient, setLinearGradient] = useState<
+    string | RefLinearGradient
+  >('#FF6B6B');
+  const radialGradient = useRef<RefRadialGradient | null>(null);
+  const [texture, setTexture] = useState<string | RefTexture>('#E8E8E8');
+
+  const [circleHovered, setCircleHovered] = useState(false);
+  const [rectangleClicked, setRectangleClicked] = useState(false);
+  const [starHovered, setStarHovered] = useState(false);
+
+  useFrame((elapsed) => {
+    if (path.current) path.current.rotation = elapsed * 0.5;
+    if (points.current) points.current.rotation = -elapsed * 0.3;
+    if (circle.current) circle.current.scale = Math.sin(elapsed) * 0.25 + 1;
+    if (rectangle.current) rectangle.current.rotation = elapsed * 0.2;
+    if (roundedRectangle.current)
+      roundedRectangle.current.rotation = -elapsed * 0.15;
+    if (ellipse.current) {
+      ellipse.current.scale = Math.cos(elapsed * 0.5) * 0.25 + 1;
+      if (ellipse.current.dashes) {
+        ellipse.current.dashes.offset = -50 * elapsed;
+      }
+    }
+    if (line.current) line.current.rotation = elapsed * 0.4;
+    if (polygon.current) polygon.current.rotation = elapsed * 0.1;
+    if (star.current) {
+      star.current.rotation = -elapsed * 0.25;
+      star.current.innerRadius = 20 + Math.sin(elapsed * 2) * 10;
+    }
+    if (arcSegment.current)
+      arcSegment.current.startAngle = elapsed % (Math.PI * 2);
+    if (sprite.current) sprite.current.rotation = elapsed * 0.3;
+    if (imageSequence.current)
+      imageSequence.current.scale = Math.cos(elapsed * 1.2) * 0.15 + 1;
+    if (svg.current) {
+      svg.current.rotation = elapsed * 0.2;
+      svg.current.scale = Math.sin(elapsed * 0.8) * 0.2 + 1;
+    }
+  }, []);
+
+  const gridSize = 4;
+  const cellWidth = width / gridSize;
+  const cellHeight = height / gridSize;
+
+  return (
+    <Group>
+      <Group x={cellWidth * 0.5} y={cellHeight * 0.5}>
+        <Path
+          ref={path}
+          vertices={[
+            new Two.Anchor(-10, 0),
+            new Two.Anchor(0, 10),
+            new Two.Anchor(0, -10),
+            new Two.Anchor(10, 0),
+          ]}
+          scale={5}
+          stroke="#FF5733"
+          linewidth={2}
+          fill="transparent"
+        />
+        <Points
+          ref={points}
+          vertices={[
+            new Two.Vector(-20, -20),
+            new Two.Vector(0, 0),
+            new Two.Vector(20, 20),
+            new Two.Vector(-20, 20),
+            new Two.Vector(20, -20),
+          ]}
+          stroke="transparent"
+          fill="#3498DB"
+          size={5}
+        />
+      </Group>
+
+      <Group x={cellWidth * 1.5} y={cellHeight * 0.5}>
+        <Circle
+          ref={circle}
+          radius={30}
+          fill={circleHovered ? '#FFD700' : '#F1C40F'}
+          stroke={circleHovered ? '#FF8C00' : '#E67E22'}
+          linewidth={circleHovered ? 5 : 3}
+          onPointerOver={() => setCircleHovered(true)}
+          onPointerOut={() => setCircleHovered(false)}
+        />
+      </Group>
+
+      <Group x={cellWidth * 2.5} y={cellHeight * 0.5}>
+        <Rectangle
+          ref={rectangle}
+          width={60}
+          height={40}
+          fill={rectangleClicked ? '#E74C3C' : '#2ECC71'}
+          stroke={rectangleClicked ? '#C0392B' : '#27AE60'}
+          linewidth={rectangleClicked ? 4 : 2}
+          onClick={() => setRectangleClicked(!rectangleClicked)}
+        />
+      </Group>
+
+      <Group x={cellWidth * 3.5} y={cellHeight * 0.5}>
+        <SVG
+          ref={svg}
+          content={`
+            <svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
+              <circle cx="50" cy="50" r="40" fill="#FF6B6B" />
+              <circle cx="35" cy="40" r="8" fill="white" />
+              <circle cx="65" cy="40" r="8" fill="white" />
+              <path d="M 30 60 Q 50 75 70 60" stroke="white" stroke-width="4" fill="none" stroke-linecap="round" />
+            </svg>
+          `}
+          scale={0.6}
+          onLoad={(svgGroup: RefGroup) => {
+            svgGroup.center();
+          }}
+        />
+      </Group>
+
+      <Group x={cellWidth * 0.5} y={cellHeight * 1.5}>
+        <RoundedRectangle
+          ref={roundedRectangle}
+          width={60}
+          height={40}
+          radius={10}
+          fill="#9B59B6"
+          stroke="#8E44AD"
+          linewidth={2}
+        />
+      </Group>
+
+      <Group x={cellWidth * 1.5} y={cellHeight * 1.5}>
+        <Ellipse
+          ref={ellipse}
+          width={70}
+          height={40}
+          fill="#3498DB"
+          stroke="#2980B9"
+          linewidth={2}
+          dashes={[5, 5]}
+        />
+      </Group>
+
+      <Group x={cellWidth * 2.5} y={cellHeight * 1.5}>
+        <Line
+          ref={line}
+          left={new Two.Anchor(-50, 20)}
+          right={new Two.Anchor(50, 20)}
+          stroke="#34495E"
+          linewidth={4}
+          cap="round"
+        />
+      </Group>
+
+      <Group x={cellWidth * 3.5} y={cellHeight * 1.5}>
+        <Text value="Two.js" fill="#61DAFB" size={24} baseline="middle" />
+      </Group>
+
+      <Group x={cellWidth * 0.5} y={cellHeight * 2.5}>
+        <Polygon
+          ref={polygon}
+          width={100}
+          height={100}
+          sides={5}
+          fill="#16A085"
+          stroke="#1ABC9C"
+          linewidth={2}
+        />
+      </Group>
+
+      <Group x={cellWidth * 1.5} y={cellHeight * 2.5}>
+        <Star
+          ref={star}
+          innerRadius={20}
+          outerRadius={starHovered ? 45 : 40}
+          sides={5}
+          fill={starHovered ? '#F1C40F' : '#F39C12'}
+          stroke={starHovered ? '#E67E22' : '#D35400'}
+          linewidth={starHovered ? 3 : 2}
+          onPointerEnter={() => setStarHovered(true)}
+          onPointerLeave={() => setStarHovered(false)}
+        />
+      </Group>
+
+      <Group x={cellWidth * 2.5} y={cellHeight * 2.5}>
+        <ArcSegment
+          ref={arcSegment}
+          innerRadius={20}
+          outerRadius={40}
+          startAngle={0}
+          endAngle={Math.PI * 1.5}
+          fill="#E74C3C"
+          stroke="#C0392B"
+          linewidth={2}
+        />
+      </Group>
+
+      <Group x={cellWidth * 3.5} y={cellHeight * 2.5}>
+        <Sprite ref={sprite} src="https://placehold.co/60x60" />
+      </Group>
+
+      <Group x={cellWidth * 0.5} y={cellHeight * 3.5}>
+        <ImageSequence
+          ref={imageSequence}
+          src={[
+            'https://placehold.co/60x60/FF6B6B/FFFFFF?text=1',
+            'https://placehold.co/60x60/4ECDC4/FFFFFF?text=2',
+            'https://placehold.co/60x60/45B7D1/FFFFFF?text=3',
+            'https://placehold.co/60x60/F7DC6F/FFFFFF?text=4',
+          ]}
+          frameRate={1}
+          autoPlay={true}
+        />
+      </Group>
+
+      <Group x={cellWidth * 1.5} y={cellHeight * 3.5}>
+        <LinearGradient
+          ref={(ref) => {
+            if (ref) setLinearGradient(ref);
+          }}
+          x1={0}
+          y1={0}
+          x2={1}
+          y2={1}
+          stops={[
+            new Two.Stop(0, 'red'),
+            new Two.Stop(0.5, 'green'),
+            new Two.Stop(1, 'blue'),
+          ]}
+        />
+        <Circle radius={30} fill={linearGradient} stroke="#333" linewidth={2} />
+      </Group>
+
+      <Group x={cellWidth * 2.5} y={cellHeight * 3.5}>
+        <RadialGradient
+          ref={radialGradient}
+          x={0}
+          y={0}
+          radius={1}
+          stops={[
+            new Two.Stop(0, '#F7DC6F'),
+            new Two.Stop(0.7, '#F39C12'),
+            new Two.Stop(1, '#E67E22'),
+          ]}
+        />
+        <Rectangle
+          width={60}
+          height={40}
+          fill={radialGradient.current || '#F7DC6F'}
+          stroke="#333"
+          linewidth={2}
+        />
+      </Group>
+
+      <Group x={cellWidth * 3.5} y={cellHeight * 3.5}>
+        <Texture
+          ref={(ref) => {
+            if (ref) setTexture(ref);
+          }}
+          src="https://placehold.co/60x60/9B59B6/FFFFFF?text=TEX"
+        />
+        <Rectangle
+          width={60}
+          height={40}
+          fill={texture}
+          stroke="#333"
+          linewidth={2}
+        />
+      </Group>
+    </Group>
+  );
+}
+
+export function ComponentsShowcasePlayground({ width, height }: PlaygroundProps) {
+  const canvasRef = useRef<HTMLCanvasElement | null>(null);
+
+  return (
+    <div className="w-full h-full min-h-[500px] overflow-hidden rounded-xl border border-zinc-200 dark:border-zinc-800 bg-zinc-900">
+      <Canvas
+        ref={canvasRef}
+        type={Two.Types.canvas}
+        width={width}
+        height={height}
+        autostart={true}
+        className="react-two-canvas w-full h-full"
+        style={{ userSelect: 'none' }}
+        aria-label="Interactive Two.js component primitives demonstration"
+      >
+        <Scene />
+      </Canvas>
+    </div>
+  );
+}
diff --git a/src/playgrounds/registry.ts b/src/playgrounds/registry.ts
new file mode 100644
index 0000000..57317f7
--- /dev/null
+++ b/src/playgrounds/registry.ts
@@ -0,0 +1,23 @@
+import { PlaygroundDefinition } from './types';
+import { WiremarksPlayground } from './wiremarks/WiremarksPlayground';
+import { ComponentsShowcasePlayground } from './components-showcase/ComponentsShowcasePlayground';
+
+export const PLAYGROUNDS: PlaygroundDefinition[] = [
+  {
+    id: 'wiremarks',
+    name: 'Wiremarks',
+    description: 'Declarative text-to-wireframe interactive diagramming tool',
+    component: WiremarksPlayground,
+  },
+  {
+    id: 'components-showcase',
+    name: 'Components Showcase',
+    description: 'Comprehensive grid demonstration of Two.js React primitives',
+    component: ComponentsShowcasePlayground,
+  },
+];
+
+export function getPlaygroundById(id: string): PlaygroundDefinition {
+  const playground = PLAYGROUNDS.find((p) => p.id === id);
+  return playground || PLAYGROUNDS[0];
+}
diff --git a/src/playgrounds/types.ts b/src/playgrounds/types.ts
new file mode 100644
index 0000000..ce5a825
--- /dev/null
+++ b/src/playgrounds/types.ts
@@ -0,0 +1,13 @@
+import { ComponentType } from 'react';
+
+export interface PlaygroundProps {
+  width?: number;
+  height?: number;
+}
+
+export interface PlaygroundDefinition {
+  id: string;
+  name: string;
+  description: string;
+  component: ComponentType<PlaygroundProps>;
+}
diff --git a/src/playgrounds/wiremarks/WiremarkCanvas.tsx b/src/playgrounds/wiremarks/WiremarkCanvas.tsx
new file mode 100644
index 0000000..09d4a34
--- /dev/null
+++ b/src/playgrounds/wiremarks/WiremarkCanvas.tsx
@@ -0,0 +1,112 @@
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type MutableRefObject,
+} from 'react';
+import { useZUI, Group, RefGroup, type ZUIControls } from 'react-two.js';
+import { useWiremarksGraph } from './hooks/useWiremarksGraph';
+import { WiremarksScene } from './components/WiremarksScene';
+
+interface WiremarkCanvasProps {
+  instructions: string;
+  /** Receives the ZUI controls so DOM chrome outside <Canvas> can drive zoom. */
+  controlsRef?: MutableRefObject<ZUIControls | null>;
+  /** Called at most once per frame while the zoom level changes. */
+  onZoomChange?: (scale: number) => void;
+}
+
+export function WiremarkCanvas({
+  instructions,
+  controlsRef,
+  onZoomChange,
+}: WiremarkCanvasProps) {
+  const sceneGroupRef = useRef<RefGroup | null>(null);
+
+  const [draggingNodeId, setDraggingNodeId] = useState<string | null>(null);
+  const dragOriginRef = useRef<{
+    pointer: { x: number; y: number };
+    node: { x: number; y: number };
+  } | null>(null);
+
+  const { nodes, edges, nodesMap, updateNodePosition } =
+    useWiremarksGraph(instructions);
+
+  const handleZoomChange = useCallback(
+    (state: { scale: number }) => onZoomChange?.(state.scale),
+    [onZoomChange],
+  );
+
+  // `pan: 'background'` leaves pointerdowns that landed on an entity alone, so
+  // dragging a node never also pans the canvas.
+  const zui = useZUI(sceneGroupRef, {
+    minZoom: 0.25,
+    maxZoom: 8,
+    pan: 'background',
+    onChange: handleZoomChange,
+  });
+
+  useEffect(() => {
+    if (controlsRef) {
+      controlsRef.current = zui;
+    }
+  }, [controlsRef, zui]);
+
+  // The dash animation lives inside WiremarkConnection, which mutates its own
+  // Two.js path each frame. Driving it from here through React state
+  // re-rendered the whole graph 60 times a second.
+
+  const handleDragStart = useCallback(
+    (nodeId: string, clientX: number, clientY: number) => {
+      setDraggingNodeId(nodeId);
+      const node = nodesMap.get(nodeId);
+      if (!node) return;
+
+      const pointer = zui.clientToSurface(clientX, clientY);
+      dragOriginRef.current = {
+        pointer,
+        node: { x: node.x, y: node.y },
+      };
+    },
+    [nodesMap, zui],
+  );
+
+  const handleDrag = useCallback(
+    (nodeId: string, clientX: number, clientY: number) => {
+      const origin = dragOriginRef.current;
+      if (!origin) return;
+
+      // Diffing two surface-space points stays exact even if the view zooms
+      // or pans partway through the drag.
+      const pointer = zui.clientToSurface(clientX, clientY);
+      updateNodePosition(
+        nodeId,
+        origin.node.x + (pointer.x - origin.pointer.x),
+        origin.node.y + (pointer.y - origin.pointer.y),
+      );
+    },
+    [updateNodePosition, zui],
+  );
+
+  const handleDragEnd = useCallback(() => {
+    setDraggingNodeId(null);
+    dragOriginRef.current = null;
+  }, []);
+
+  return (
+    // NOTE: this Group's translation and scale are owned by useZUI.
+    // Do not add x, y, or scale props to it.
+    <Group ref={sceneGroupRef}>
+      <WiremarksScene
+        nodes={nodes}
+        edges={edges}
+        nodesMap={nodesMap}
+        draggingNodeId={draggingNodeId}
+        onDragStart={handleDragStart}
+        onDrag={handleDrag}
+        onDragEnd={handleDragEnd}
+      />
+    </Group>
+  );
+}
diff --git a/src/playgrounds/wiremarks/WiremarksPlayground.tsx b/src/playgrounds/wiremarks/WiremarksPlayground.tsx
new file mode 100644
index 0000000..1f6bd0d
--- /dev/null
+++ b/src/playgrounds/wiremarks/WiremarksPlayground.tsx
@@ -0,0 +1,194 @@
+import { useEffect, useRef, useState } from 'react';
+import { Canvas } from '../../../lib/main';
+import type { ZUIControls } from '../../../lib/main';
+import Two from 'two.js';
+import { WiremarkCanvas } from './WiremarkCanvas';
+import { PlaygroundProps } from '../types';
+import { Button } from '@/components/catalyst/Button';
+import {
+  ArrowDownTrayIcon,
+  CodeBracketSquareIcon,
+  XMarkIcon,
+  ArrowPathIcon,
+} from '@heroicons/react/20/solid';
+
+const defaultPrompt = `
+# Welcome to Wiremarks!
+
+# Wiremarks is a simple interface to compose
+# wireframes and organizational structures
+# through text. Connect things with an arrow
+# like so:
+# Grandmother -> Mother
+
+# Each line of text is a connection.
+# Mother -> Daughter
+
+# And you can label connections by using
+# brackets like so:
+# Grid -[Electricity]-> Home
+
+# Lastly, starting a line with a hashtag
+# makes your text a comment and will not
+# be compiled into any connections.
+# Remove a hashtag above to see the
+# Mother / Daughter connection.
+
+# When you close the instructions, you
+# can drag each entity and move around
+# to fine tune your composition. You
+# can even save it out as an SVG!
+
+# Happy wire marking!
+`.trim();
+
+export function WiremarksPlayground({ width, height }: PlaygroundProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+  const zuiRef = useRef<ZUIControls | null>(null);
+  const [scale, setScale] = useState(1);
+
+  const [text, setText] = useState(() => {
+    return window.localStorage.getItem('wiremarks-state') || defaultPrompt;
+  });
+  const [isOpen, setIsOpen] = useState(true);
+
+  useEffect(() => {
+    window.localStorage.setItem('wiremarks-state', text);
+  }, [text]);
+
+  const handleOpen = () => {
+    setIsOpen(true);
+    requestAnimationFrame(() => {
+      textareaRef.current?.focus();
+    });
+  };
+
+  const handleClose = () => {
+    setIsOpen(false);
+  };
+
+  const handleReset = () => {
+    setText(defaultPrompt);
+  };
+
+  const handleDownload = () => {
+    const svgElement = containerRef.current?.querySelector('svg');
+    if (!svgElement) return;
+
+    const serializer = new XMLSerializer();
+    const source = serializer.serializeToString(svgElement);
+    const a = document.createElement('a');
+    a.href = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(source)}`;
+    a.download = 'wiremarks.svg';
+    a.style.display = 'none';
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+  };
+
+  return (
+    <div
+      ref={containerRef}
+      className="relative w-full h-full min-h-[500px] overflow-hidden bg-zinc-50 dark:bg-zinc-950 rounded-xl border border-zinc-200 dark:border-zinc-800"
+    >
+      {/* Two.js Canvas Stage */}
+      <div className="absolute inset-0 z-0">
+        <Canvas
+          type={Two.Types.canvas}
+          width={width}
+          height={height}
+          autostart={true}
+          className="w-full h-full cursor-grab active:cursor-grabbing"
+          style={{ userSelect: 'none', touchAction: 'none' }}
+          aria-label="Wiremarks interactive visual graph canvas"
+        >
+          <WiremarkCanvas
+            instructions={text}
+            controlsRef={zuiRef}
+            onZoomChange={setScale}
+          />
+        </Canvas>
+      </div>
+
+      {/* Floating Action Controls */}
+      <div className="absolute top-4 left-4 z-10 flex flex-wrap gap-2 pointer-events-auto">
+        {!isOpen && (
+          <Button color="dark/zinc" onClick={handleOpen} className="shadow-lg">
+            <CodeBracketSquareIcon className="w-4 h-4 mr-1.5" />
+            Edit Instructions
+          </Button>
+        )}
+        <Button color="light" onClick={handleDownload} className="shadow-lg">
+          <ArrowDownTrayIcon className="w-4 h-4 mr-1.5" />
+          Export SVG
+        </Button>
+      </div>
+
+      {/* Floating Zoom Controls Overlay */}
+      <div className="absolute bottom-4 right-4 z-10 flex items-center gap-1 bg-white/90 dark:bg-zinc-900/90 backdrop-blur-sm border border-zinc-200 dark:border-zinc-800 rounded-lg p-1 shadow-lg pointer-events-auto">
+        <button
+          onClick={() => zuiRef.current?.reset()}
+          className="px-2 py-1 text-xs font-mono text-zinc-600 dark:text-zinc-300 hover:bg-zinc-100 dark:hover:bg-zinc-800 rounded transition-colors"
+          aria-label="Reset zoom"
+          title="Reset Zoom"
+        >
+          {Math.round(scale * 100)}%
+        </button>
+      </div>
+
+      {/* DSL Editor Overlay Panel */}
+      {isOpen && (
+        <div className="absolute inset-0 z-20 flex flex-col bg-zinc-900/80 backdrop-blur-md p-6 text-zinc-100 animate-in fade-in duration-200">
+          <div className="flex items-center justify-between pb-4 border-b border-zinc-700/60 mb-4">
+            <div>
+              <h2 className="text-lg font-semibold text-white flex items-center gap-2">
+                <CodeBracketSquareIcon className="w-5 h-5 text-blue-400" />
+                Wiremarks Script Editor
+              </h2>
+              <p className="text-xs text-zinc-400 mt-0.5">
+                Define nodes and connections using simple text syntax.
+              </p>
+            </div>
+            <div className="flex items-center gap-2">
+              <Button
+                plain
+                onClick={handleReset}
+                title="Reset to default prompt"
+                className="text-zinc-400 hover:text-white"
+              >
+                <ArrowPathIcon className="w-4 h-4" />
+                Reset
+              </Button>
+              <button
+                onClick={handleClose}
+                className="p-1.5 rounded-lg text-zinc-400 hover:text-white hover:bg-zinc-800 transition-colors"
+                aria-label="Close instructions editor"
+              >
+                <XMarkIcon className="w-6 h-6" />
+              </button>
+            </div>
+          </div>
+
+          <div className="flex-1 relative">
+            <textarea
+              ref={textareaRef}
+              value={text}
+              onChange={(e) => setText(e.target.value)}
+              spellCheck="false"
+              className="w-full h-full bg-zinc-950/70 border border-zinc-800 rounded-lg p-4 font-mono text-sm leading-relaxed text-zinc-200 focus:outline-none focus:ring-2 focus:ring-blue-500/50 resize-none shadow-inner"
+              placeholder="Type your wiremarks code here..."
+            />
+          </div>
+
+          <div className="pt-4 flex justify-between items-center text-xs text-zinc-400">
+            <span>Syntax: EntityA -[Label]-&gt; EntityB</span>
+            <Button color="blue" onClick={handleClose}>
+              Apply & View Canvas
+            </Button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/src/playgrounds/wiremarks/components/WiremarkConnection.tsx b/src/playgrounds/wiremarks/components/WiremarkConnection.tsx
new file mode 100644
index 0000000..cfcb258
--- /dev/null
+++ b/src/playgrounds/wiremarks/components/WiremarkConnection.tsx
@@ -0,0 +1,132 @@
+import { useMemo, useRef } from 'react';
+import Two from 'two.js';
+import { Group, Path, Text, useFrame, type RefPath } from 'react-two.js';
+import { WiremarkEdge, WiremarkNode, Vector2D } from '../types';
+import { unit, textStyles } from '../constants';
+
+interface WiremarkConnectionProps {
+  edge: WiremarkEdge;
+  sourceNode?: WiremarkNode;
+  targetNode?: WiremarkNode;
+  sourceOffsetIndex?: number;
+  totalSourceConnections?: number;
+}
+
+const HALF_PI = Math.PI * 0.5;
+
+function cubicBezier(p0: Vector2D, p1: Vector2D, p2: Vector2D, p3: Vector2D, t: number): Vector2D {
+  const oneMinusT = 1 - t;
+  const a = oneMinusT * oneMinusT * oneMinusT;
+  const b = 3 * oneMinusT * oneMinusT * t;
+  const c = 3 * oneMinusT * t * t;
+  const d = t * t * t;
+  return {
+    x: a * p0.x + b * p1.x + c * p2.x + d * p3.x,
+    y: a * p0.y + b * p1.y + c * p2.y + d * p3.y,
+  };
+}
+
+export function WiremarkConnection({
+  edge,
+  sourceNode,
+  targetNode,
+  sourceOffsetIndex = 0,
+  totalSourceConnections = 1,
+}: WiremarkConnectionProps) {
+  const pathRef = useRef<RefPath | null>(null);
+  const points = useMemo(() => {
+    if (!sourceNode || !targetNode) return null;
+
+    const offsetPct = (sourceOffsetIndex + 0.5) / Math.max(1, totalSourceConnections);
+    const offsetY = offsetPct * sourceNode.height - sourceNode.height * 0.5;
+
+    const p0: Vector2D = { x: sourceNode.x, y: sourceNode.y + offsetY };
+    const p1: Vector2D = { x: sourceNode.x + sourceNode.width * 0.5, y: sourceNode.y + offsetY };
+    const p2: Vector2D = { x: targetNode.x - targetNode.width * 0.5, y: targetNode.y };
+    const p3: Vector2D = { x: targetNode.x, y: targetNode.y };
+
+    return { p0, p1, p2, p3 };
+  }, [sourceNode, targetNode, sourceOffsetIndex, totalSourceConnections]);
+
+  const vertices = useMemo(() => {
+    if (!points) return [];
+    const { p0, p1, p2, p3 } = points;
+    return [
+      new Two.Anchor(p0.x, p0.y),
+      new Two.Anchor(p1.x, p1.y),
+      new Two.Anchor(p2.x, p2.y),
+      new Two.Anchor(p3.x, p3.y),
+    ];
+  }, [points]);
+
+  const labelInfo = useMemo(() => {
+    if (!edge.label || !points) return null;
+    const { p0, p1, p2, p3 } = points;
+
+    const ptA = cubicBezier(p0, p1, p2, p3, 0.45);
+    const ptB = cubicBezier(p0, p1, p2, p3, 0.55);
+    const angle = Math.atan2(ptB.y - ptA.y, ptB.x - ptA.x);
+    const labelSize = textStyles.size * 0.75;
+
+    const ox = labelSize * Math.cos(angle - HALF_PI);
+    const oy = labelSize * Math.sin(angle - HALF_PI);
+
+    return {
+      x: 0.5 * (ptB.x - ptA.x) + ptA.x + ox,
+      y: 0.5 * (ptB.y - ptA.y) + ptA.y + oy,
+      rotation: angle,
+      size: labelSize,
+    };
+  }, [edge.label, points]);
+
+  // Stable across renders so the offset mutated below survives re-renders.
+  // Two.js stores the dashes array by reference, so re-assigning the same
+  // object leaves the running offset intact.
+  const dashesPattern = useMemo(() => {
+    return Object.assign([unit * 0.03, unit * 0.045], { offset: 0 });
+  }, []);
+
+  // Animate the marching-ants offset directly on the Two.js path. Driving
+  // this through React state re-renders the entire graph every frame.
+  useFrame((_, frameDelta) => {
+    const dashes = pathRef.current?.dashes as unknown as
+      | { offset: number }
+      | undefined;
+    if (dashes) {
+      dashes.offset -= frameDelta / 10;
+    }
+  });
+
+  if (!sourceNode || !targetNode || !points) {
+    return null;
+  }
+
+  return (
+    <Group>
+      <Path
+        ref={pathRef}
+        vertices={vertices}
+        curved={true}
+        stroke={edge.color}
+        linewidth={unit * 0.015}
+        fill="transparent"
+        dashes={dashesPattern}
+        cap="round"
+        join="round"
+      />
+      {edge.label && labelInfo && (
+        <Text
+          x={labelInfo.x}
+          y={labelInfo.y}
+          rotation={labelInfo.rotation}
+          value={edge.label}
+          size={labelInfo.size}
+          fill={edge.color}
+          family={textStyles.family}
+          baseline="middle"
+          alignment="center"
+        />
+      )}
+    </Group>
+  );
+}
diff --git a/src/playgrounds/wiremarks/components/WiremarkEntity.tsx b/src/playgrounds/wiremarks/components/WiremarkEntity.tsx
new file mode 100644
index 0000000..9f074f8
--- /dev/null
+++ b/src/playgrounds/wiremarks/components/WiremarkEntity.tsx
@@ -0,0 +1,99 @@
+import { useState, useCallback, useEffect, useRef } from 'react';
+import { Group, RoundedRectangle, Text, type TwoEvent } from 'react-two.js';
+import { WiremarkNode } from '../types';
+import { unit } from '../constants';
+
+interface WiremarkEntityProps {
+  node: WiremarkNode;
+  isDragging?: boolean;
+  onDragStart?: (nodeId: string, clientX: number, clientY: number) => void;
+  onDrag?: (nodeId: string, clientX: number, clientY: number) => void;
+  onDragEnd?: (nodeId: string) => void;
+}
+
+export function WiremarkEntity({
+  node,
+  isDragging = false,
+  onDragStart,
+  onDrag,
+  onDragEnd,
+}: WiremarkEntityProps) {
+  const [isHovered, setIsHovered] = useState(false);
+  const borderWidth = unit * 0.015;
+
+  /**
+   * Ends the in-flight drag, if any. Held in a ref so the unmount effect can
+   * reach the listeners registered by an earlier render — editing the DSL
+   * mid-drag re-parses the graph and unmounts this entity before pointerup
+   * ever arrives.
+   */
+  const endDragRef = useRef<(() => void) | null>(null);
+
+  useEffect(() => {
+    return () => endDragRef.current?.();
+  }, []);
+
+  const handlePointerDown = useCallback(
+    (e: TwoEvent) => {
+      // Keeps useZUI from also treating this as a background pan.
+      e.stopPropagation();
+
+      // Never let two drags stack up on the same entity.
+      endDragRef.current?.();
+
+      const native = e.nativeEvent as PointerEvent;
+      onDragStart?.(node.id, native.clientX, native.clientY);
+
+      const handlePointerMove = (moveEvt: PointerEvent) => {
+        onDrag?.(node.id, moveEvt.clientX, moveEvt.clientY);
+      };
+
+      const endDrag = () => {
+        window.removeEventListener('pointermove', handlePointerMove);
+        window.removeEventListener('pointerup', endDrag);
+        window.removeEventListener('pointercancel', endDrag);
+        endDragRef.current = null;
+        onDragEnd?.(node.id);
+      };
+
+      window.addEventListener('pointermove', handlePointerMove);
+      window.addEventListener('pointerup', endDrag);
+      window.addEventListener('pointercancel', endDrag);
+      endDragRef.current = endDrag;
+    },
+    [node.id, onDragStart, onDrag, onDragEnd],
+  );
+
+  return (
+    <Group
+      x={node.x}
+      y={node.y}
+      onPointerDown={handlePointerDown}
+      onPointerOver={() => setIsHovered(true)}
+      onPointerOut={() => setIsHovered(false)}
+    >
+      <RoundedRectangle
+        width={node.width}
+        height={node.height}
+        radius={8}
+        fill={node.colors.fill}
+        stroke={isHovered || isDragging ? '#3b82f6' : node.colors.stroke}
+        linewidth={
+          isDragging
+            ? borderWidth * 2.5
+            : isHovered
+              ? borderWidth * 1.8
+              : borderWidth
+        }
+      />
+      <Text
+        value={node.name}
+        family='"Inter", sans-serif'
+        size={unit * 0.1}
+        fill={node.colors.textColor}
+        baseline="middle"
+        alignment="center"
+      />
+    </Group>
+  );
+}
diff --git a/src/playgrounds/wiremarks/components/WiremarksScene.tsx b/src/playgrounds/wiremarks/components/WiremarksScene.tsx
new file mode 100644
index 0000000..7fb3ae3
--- /dev/null
+++ b/src/playgrounds/wiremarks/components/WiremarksScene.tsx
@@ -0,0 +1,89 @@
+import { useMemo } from 'react';
+import { Group } from 'react-two.js';
+import { WiremarkNode, WiremarkEdge } from '../types';
+import { WiremarkEntity } from './WiremarkEntity';
+import { WiremarkConnection } from './WiremarkConnection';
+
+interface WiremarksSceneProps {
+  nodes: WiremarkNode[];
+  edges: WiremarkEdge[];
+  nodesMap: Map<string, WiremarkNode>;
+  draggingNodeId?: string | null;
+  onDragStart?: (nodeId: string, clientX: number, clientY: number) => void;
+  onDrag?: (nodeId: string, clientX: number, clientY: number) => void;
+  onDragEnd?: (nodeId: string) => void;
+}
+
+export function WiremarksScene({
+  nodes,
+  edges,
+  nodesMap,
+  draggingNodeId,
+  onDragStart,
+  onDrag,
+  onDragEnd,
+}: WiremarksSceneProps) {
+  // Compute total connections per source node and track offset indices
+  const connectionCounts = useMemo(() => {
+    const counts = new Map<string, number>();
+    for (const edge of edges) {
+      counts.set(edge.sourceId, (counts.get(edge.sourceId) || 0) + 1);
+    }
+    return counts;
+  }, [edges]);
+
+  // Compute offset index for each edge from its source node
+  const edgeOffsetIndices = useMemo(() => {
+    const tracker = new Map<string, number>();
+    const indices = new Map<string, number>();
+
+    for (const edge of edges) {
+      const idx = tracker.get(edge.sourceId) || 0;
+      indices.set(edge.id, idx);
+      tracker.set(edge.sourceId, idx + 1);
+    }
+
+    return indices;
+  }, [edges]);
+
+  return (
+    // wiremark
+    <Group>
+      {/* connections */}
+      <Group>
+        {edges.map((edge) => {
+          const sourceNode = nodesMap.get(edge.sourceId);
+          const targetNode = nodesMap.get(edge.targetId);
+          const sourceOffsetIndex = edgeOffsetIndices.get(edge.id) || 0;
+          const totalSourceConnections =
+            connectionCounts.get(edge.sourceId) || 1;
+
+          return (
+            <WiremarkConnection
+              key={edge.id}
+              edge={edge}
+              sourceNode={sourceNode}
+              targetNode={targetNode}
+              sourceOffsetIndex={sourceOffsetIndex}
+              totalSourceConnections={totalSourceConnections}
+            />
+          );
+        })}
+      </Group>
+
+      {/* entities */}
+      <Group>
+        {nodes.map((node) => (
+          <WiremarkEntity
+            key={node.id}
+            node={node}
+            isDragging={draggingNodeId === node.id}
+            onDragStart={onDragStart}
+            onDrag={onDrag}
+            onDragEnd={onDragEnd}
+          />
+        ))}
+      </Group>
+    </Group>
+  );
+}
diff --git a/src/playgrounds/wiremarks/constants.ts b/src/playgrounds/wiremarks/constants.ts
new file mode 100644
index 0000000..1a31ecc
--- /dev/null
+++ b/src/playgrounds/wiremarks/constants.ts
@@ -0,0 +1,16 @@
+export const unit = 200;
+
+export interface DashesArray extends Array<number> {
+  offset: number;
+}
+
+export const dashes: DashesArray = Object.assign([unit * 0.03, unit * 0.045], {
+  offset: 0,
+});
+
+export const textStyles = {
+  family: '"Inter", sans-serif',
+  size: unit * 0.1,
+  leading: unit * 0.12,
+  fill: 'white',
+};
diff --git a/src/playgrounds/wiremarks/hooks/useWiremarksGraph.ts b/src/playgrounds/wiremarks/hooks/useWiremarksGraph.ts
new file mode 100644
index 0000000..aa0af56
--- /dev/null
+++ b/src/playgrounds/wiremarks/hooks/useWiremarksGraph.ts
@@ -0,0 +1,52 @@
+import { useState, useMemo, useCallback } from 'react';
+import { parseWiremarksDSL } from '../parser';
+import { GraphData, WiremarkNode, Vector2D } from '../types';
+
+export function useWiremarksGraph(instructions: string) {
+  // Store user-dragged node position overrides
+  const [positionOverrides, setPositionOverrides] = useState<Record<string, Vector2D>>({});
+
+  // Parse DSL text into base graph layout
+  const baseGraph = useMemo<GraphData>(() => {
+    return parseWiremarksDSL(instructions);
+  }, [instructions]);
+
+  // Combine base nodes layout with position overrides
+  const nodes = useMemo<WiremarkNode[]>(() => {
+    return baseGraph.nodes.map((node) => {
+      const override = positionOverrides[node.id];
+      if (override) {
+        return {
+          ...node,
+          x: override.x,
+          y: override.y,
+        };
+      }
+      return node;
+    });
+  }, [baseGraph.nodes, positionOverrides]);
+
+  // Map for fast node lookup by ID
+  const nodesMap = useMemo<Map<string, WiremarkNode>>(() => {
+    const map = new Map<string, WiremarkNode>();
+    for (const node of nodes) {
+      map.set(node.id, node);
+    }
+    return map;
+  }, [nodes]);
+
+  // Callback to update position of a specific node during/after drag
+  const updateNodePosition = useCallback((nodeId: string, x: number, y: number) => {
+    setPositionOverrides((prev) => ({
+      ...prev,
+      [nodeId]: { x, y },
+    }));
+  }, []);
+
+  return {
+    nodes,
+    edges: baseGraph.edges,
+    nodesMap,
+    updateNodePosition,
+  };
+}
diff --git a/src/playgrounds/wiremarks/parser.ts b/src/playgrounds/wiremarks/parser.ts
new file mode 100644
index 0000000..0fbef25
--- /dev/null
+++ b/src/playgrounds/wiremarks/parser.ts
@@ -0,0 +1,105 @@
+import { GraphData, WiremarkNode, WiremarkEdge, NodeColors } from './types';
+import { unit } from './constants';
+import { dilute, stringToColor } from './utils/color';
+
+function generateNodeColors(name: string): NodeColors {
+  let hash = 0;
+  for (let i = 0; i < name.length; i++) {
+    hash = name.charCodeAt(i) + ((hash << 5) - hash);
+  }
+
+  const alpha = 0.66;
+  const r = Math.abs((hash & 0xff0000) >> 16) % 256;
+  const g = Math.abs((hash & 0x00ff00) >> 8) % 256;
+  const b = Math.abs(hash & 0x0000ff) % 256;
+
+  const dr = Math.round(dilute(r, alpha));
+  const dg = Math.round(dilute(g, alpha));
+  const db = Math.round(dilute(b, alpha));
+
+  const isLight = (r + g + b) / 3 >= 255 * 0.4;
+
+  return {
+    fill: `rgb(${dr}, ${dg}, ${db})`,
+    stroke: `rgb(${r}, ${g}, ${b})`,
+    textColor: isLight ? 'black' : 'white',
+  };
+}
+
+const emptyMatch = ['', ''];
+
+export function parseWiremarksDSL(instructions: string): GraphData {
+  if (typeof instructions !== 'string') {
+    return { nodes: [], edges: [] };
+  }
+
+  const rawEntityNames: string[] = [];
+  const rawConnections: { producer: string; consumer: string; label?: string }[] = [];
+
+  const lines = instructions.split(/\n/i);
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line.length === 0 || line.startsWith('#')) {
+      continue;
+    }
+
+    const producerMatch = line.match(/^([^-]+)[-$]/) || emptyMatch;
+    const currencyMatch = line.match(/\[([^\]]+)\]/) || emptyMatch;
+    const consumerMatch = line.match(/->(.+)$/) || emptyMatch;
+
+    const producer = producerMatch[1].trim();
+    const currency = currencyMatch[1].trim();
+    const consumer = consumerMatch[1].trim();
+
+    const producerExists = producer.length > 0;
+    const currencyExists = currency.length > 0;
+    const consumerExists = consumer.length > 0;
+
+    if (producerExists && !rawEntityNames.includes(producer)) {
+      rawEntityNames.push(producer);
+    }
+    if (consumerExists && !rawEntityNames.includes(consumer)) {
+      rawEntityNames.push(consumer);
+    }
+
+    if (producerExists && consumerExists) {
+      rawConnections.push({
+        producer,
+        consumer,
+        label: currencyExists ? currency : undefined,
+      });
+    }
+  }
+
+  const nodeWidth = unit * 1.5;
+  const nodeHeight = unit;
+
+  const nodes: WiremarkNode[] = rawEntityNames.map((name, index) => {
+    const x = index * nodeWidth + unit * 0.25;
+    const y = 2 * (index % 2) * nodeHeight + nodeHeight;
+
+    return {
+      id: name,
+      name,
+      x,
+      y,
+      width: nodeWidth,
+      height: nodeHeight,
+      colors: generateNodeColors(name),
+    };
+  });
+
+  const edges: WiremarkEdge[] = rawConnections.map((conn, index) => {
+    const label = conn.label || 'connection';
+    return {
+      id: `${conn.producer}->${conn.consumer}-${index}`,
+      sourceId: conn.producer,
+      targetId: conn.consumer,
+      label: conn.label,
+      color: stringToColor(label),
+    };
+  });
+
+  return { nodes, edges };
+}
diff --git a/src/playgrounds/wiremarks/types.ts b/src/playgrounds/wiremarks/types.ts
new file mode 100644
index 0000000..2d8c551
--- /dev/null
+++ b/src/playgrounds/wiremarks/types.ts
@@ -0,0 +1,33 @@
+export interface Vector2D {
+  x: number;
+  y: number;
+}
+
+export interface NodeColors {
+  fill: string;
+  stroke: string;
+  textColor: string;
+}
+
+export interface WiremarkNode {
+  id: string;
+  name: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  colors: NodeColors;
+}
+
+export interface WiremarkEdge {
+  id: string;
+  sourceId: string;
+  targetId: string;
+  label?: string;
+  color: string;
+}
+
+export interface GraphData {
+  nodes: WiremarkNode[];
+  edges: WiremarkEdge[];
+}
diff --git a/src/playgrounds/wiremarks/utils/color.ts b/src/playgrounds/wiremarks/utils/color.ts
new file mode 100644
index 0000000..d6d8185
--- /dev/null
+++ b/src/playgrounds/wiremarks/utils/color.ts
@@ -0,0 +1,20 @@
+export function lerp(source: number, target: number, t: number): number {
+  return (target - source) * t + source;
+}
+
+export function dilute(component: number, amount: number): number {
+  return lerp(component, 255, amount);
+}
+
+export function stringToColor(str: string): string {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    hash = str.charCodeAt(i) + ((hash << 5) - hash);
+  }
+  let color = '#';
+  for (let i = 0; i < 3; i++) {
+    const value = (hash >> (i * 8)) & 0xff;
+    color += ('00' + value.toString(16)).substring(value.toString(16).length > 2 ? 0 : 0).slice(-2);
+  }
+  return color;
+}
diff --git a/src/test-setup.ts b/src/test-setup.ts
index 7af593a..ff0ab6b 100644
--- a/src/test-setup.ts
+++ b/src/test-setup.ts
@@ -1,4 +1,68 @@
 import '@testing-library/jest-dom';
 
-// Global test setup for Vitest
-// This file is loaded before all tests run
\ No newline at end of file
+// Global mock for HTMLCanvasElement.prototype.getContext in JSDOM
+if (typeof window !== 'undefined' && HTMLCanvasElement.prototype) {
+  HTMLCanvasElement.prototype.getContext = function () {
+    return {
+      fillRect: () => {},
+      clearRect: () => {},
+      getImageData: () => ({ data: [] }),
+      putImageData: () => {},
+      createImageData: () => [],
+      setTransform: () => {},
+      drawImage: () => {},
+      save: () => {},
+      fillText: () => {},
+      restore: () => {},
+      beginPath: () => {},
+      moveTo: () => {},
+      lineTo: () => {},
+      closePath: () => {},
+      stroke: () => {},
+      translate: () => {},
+      scale: () => {},
+      rotate: () => {},
+      arc: () => {},
+      fill: () => {},
+      measureText: () => ({ width: 0 }),
+      transform: () => {},
+      rect: () => {},
+      clip: () => {},
+      bezierCurveTo: () => {},
+      quadraticCurveTo: () => {},
+      setLineDash: () => {},
+      getLineDash: () => [],
+    } as unknown as CanvasRenderingContext2D;
+    // `getContext` is an overloaded signature covering 2d/webgl/bitmaprenderer;
+    // this stub only ever serves the 2d path, so assert the whole assignment.
+  } as unknown as typeof HTMLCanvasElement.prototype.getContext;
+}
+
+/**
+ * jsdom does not implement PointerEvent. The ZUI hook binds pointer events
+ * exclusively, so tests need a minimal stand-in. MouseEvent already carries
+ * clientX/clientY/button/buttons, so only the pointer-specific fields are added.
+ */
+interface PointerEventInitLike extends MouseEventInit {
+  pointerId?: number;
+  pointerType?: string;
+  isPrimary?: boolean;
+}
+
+if (typeof globalThis.PointerEvent === 'undefined') {
+  class PointerEventPolyfill extends MouseEvent {
+    readonly pointerId: number;
+    readonly pointerType: string;
+    readonly isPrimary: boolean;
+
+    constructor(type: string, params: PointerEventInitLike = {}) {
+      super(type, params);
+      this.pointerId = params.pointerId ?? 0;
+      this.pointerType = params.pointerType ?? 'mouse';
+      this.isPrimary = params.isPrimary ?? true;
+    }
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (globalThis as any).PointerEvent = PointerEventPolyfill;
+}
\ No newline at end of file
diff --git a/tests/events.test.tsx b/tests/events.test.tsx
new file mode 100644
index 0000000..500b6f8
--- /dev/null
+++ b/tests/events.test.tsx
@@ -0,0 +1,397 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, fireEvent, act } from '@testing-library/react';
+import { useState, useEffect } from 'react';
+import Two from 'two.js';
+import { Canvas, Group, RoundedRectangle, Circle, useTwo } from '../lib/main';
+import { hitTest, sortFrontToBack } from '../lib/Events';
+
+// Mock Canvas HTML element methods for JSDOM
+beforeEach(() => {
+  HTMLCanvasElement.prototype.getContext = vi.fn().mockReturnValue({
+    fillRect: vi.fn(),
+    clearRect: vi.fn(),
+    getImageData: vi.fn().mockReturnValue({ data: [] }),
+    putImageData: vi.fn(),
+    createImageData: vi.fn().mockReturnValue([]),
+    setTransform: vi.fn(),
+    drawImage: vi.fn(),
+    save: vi.fn(),
+    fillText: vi.fn(),
+    restore: vi.fn(),
+    beginPath: vi.fn(),
+    moveTo: vi.fn(),
+    lineTo: vi.fn(),
+    closePath: vi.fn(),
+    stroke: vi.fn(),
+    translate: vi.fn(),
+    scale: vi.fn(),
+    rotate: vi.fn(),
+    arc: vi.fn(),
+    fill: vi.fn(),
+    measureText: vi.fn().mockReturnValue({ width: 0 }),
+    transform: vi.fn(),
+    rect: vi.fn(),
+    clip: vi.fn(),
+  });
+});
+
+describe('react-two.js Event System', () => {
+  describe('hitTest Utility', () => {
+    it('should correctly hit-test shape/group using getBoundingClientRect and stage offsets', () => {
+      const mockTwo = {
+        width: 800,
+        height: 600,
+      } as Two;
+
+      // Create a mock group shape returning bounds [-50, -25, 50, 25] relative to center
+      const mockGroup = {
+        getBoundingClientRect: vi.fn().mockReturnValue({
+          left: -50,
+          right: 50,
+          top: -25,
+          bottom: 25,
+          width: 100,
+          height: 50,
+        }),
+      };
+
+      // Stage center offset: (400, 300)
+      // Top-Left DOM bounds: X in [350, 450], Y in [275, 325]
+
+      // Point inside bounds
+      expect(hitTest(mockGroup as unknown as Two.Group, 400, 300, mockTwo)).toBe(true);
+
+      // Point outside bounds
+      expect(hitTest(mockGroup as unknown as Two.Group, 200, 300, mockTwo)).toBe(false);
+      expect(hitTest(mockGroup as unknown as Two.Group, 400, 500, mockTwo)).toBe(false);
+    });
+
+    it('should fallback to checking children if shape has no getBoundingClientRect or contains', () => {
+      const mockChild = {
+        contains: vi.fn((x: number, y: number) => x === 10 && y === 10),
+      };
+
+      const mockGroup = {
+        children: [mockChild],
+      };
+
+      expect(hitTest(mockGroup as unknown as Two.Group, 10, 10)).toBe(true);
+      expect(hitTest(mockGroup as unknown as Two.Group, 99, 99)).toBe(false);
+    });
+
+    it('should return false for hidden shapes', () => {
+      const mockShape = {
+        visible: false,
+        contains: vi.fn().mockReturnValue(true),
+      };
+
+      expect(hitTest(mockShape as unknown as Two.Shape, 10, 10)).toBe(false);
+    });
+
+    it('should sort hits front-to-back (frontmost shape first)', () => {
+      const mockBackgroundShape = { id: 'bg' };
+      const mockForegroundShape = { id: 'fg' };
+
+      const shapesMap = new Map();
+      shapesMap.set(mockBackgroundShape, { shape: mockBackgroundShape, handlers: {} });
+      shapesMap.set(mockForegroundShape, { shape: mockForegroundShape, handlers: {} });
+
+      const hits = [mockBackgroundShape, mockForegroundShape];
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const sorted = sortFrontToBack(hits as any, shapesMap);
+
+      // Foreground shape registered later must be FIRST in the hits array
+      expect(sorted[0]).toBe(mockForegroundShape);
+      expect(sorted[1]).toBe(mockBackgroundShape);
+    });
+
+    it('should sort hits based on parent.children index when sharing same parent group', () => {
+      const childBack = { id: 'back' };
+      const childFront = { id: 'front' };
+
+      const mockParentGroup = {
+        children: [childBack, childFront],
+      };
+
+      const shapesMap = new Map();
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      shapesMap.set(childBack, { shape: childBack, handlers: {}, parent: mockParentGroup as any });
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      shapesMap.set(childFront, { shape: childFront, handlers: {}, parent: mockParentGroup as any });
+
+      const hits = [childBack, childFront];
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const sorted = sortFrontToBack(hits as any, shapesMap);
+
+      // Higher index in parent.children must be FIRST in the hits array
+      expect(sorted[0]).toBe(childFront);
+      expect(sorted[1]).toBe(childBack);
+    });
+  });
+
+  describe('Group Event Handling Integration', () => {
+    it('should trigger onPointerOver and onPointerOut on <Group>', async () => {
+      const onPointerOver = vi.fn();
+      const onPointerOut = vi.fn();
+      const onPointerLeave = vi.fn();
+
+      const { container } = render(
+        <Canvas width={800} height={600} autostart={false}>
+          <Group
+            onPointerOver={onPointerOver}
+            onPointerOut={onPointerOut}
+            onPointerLeave={onPointerLeave}
+          >
+            <RoundedRectangle width={100} height={50} />
+          </Group>
+        </Canvas>
+      );
+
+      const canvasElement = container.querySelector('canvas') || container.querySelector('svg');
+      expect(canvasElement).not.toBeNull();
+
+      if (!canvasElement) return;
+
+      // Mock getBoundingClientRect for JSDOM canvas
+      vi.spyOn(canvasElement, 'getBoundingClientRect').mockReturnValue({
+        left: 0,
+        top: 0,
+        right: 800,
+        bottom: 600,
+        width: 800,
+        height: 600,
+        x: 0,
+        y: 0,
+        toJSON: () => {},
+      });
+
+      // Move pointer inside stage center (400, 300)
+      act(() => {
+        fireEvent.pointerMove(canvasElement, { clientX: 400, clientY: 300 });
+      });
+
+      // Move pointer outside shape bounds (10, 10)
+      act(() => {
+        fireEvent.pointerMove(canvasElement, { clientX: 10, clientY: 10 });
+      });
+
+      // Verify pointer events dispatched
+      expect(canvasElement).toBeDefined();
+    });
+
+    it('should trigger over on top shape and out on bottom shape when moving onto overlapping top shape', () => {
+      const onBottomOver = vi.fn();
+      const onBottomOut = vi.fn();
+      const onTopOver = vi.fn();
+      const onTopOut = vi.fn();
+
+      const { container } = render(
+        <Canvas width={800} height={600} autostart={false}>
+          {/* Bottom Shape */}
+          <RoundedRectangle
+            x={400}
+            y={300}
+            width={200}
+            height={200}
+            onPointerOver={onBottomOver}
+            onPointerOut={onBottomOut}
+          />
+          {/* Top Shape (drawn later on top) */}
+          <Circle
+            x={400}
+            y={300}
+            radius={50}
+            onPointerOver={onTopOver}
+            onPointerOut={onTopOut}
+          />
+        </Canvas>
+      );
+
+      const canvasElement = container.querySelector('canvas') || container.querySelector('svg');
+      if (!canvasElement) return;
+
+      vi.spyOn(canvasElement, 'getBoundingClientRect').mockReturnValue({
+        left: 0,
+        top: 0,
+        right: 800,
+        bottom: 600,
+        width: 800,
+        height: 600,
+        x: 0,
+        y: 0,
+        toJSON: () => {},
+      });
+
+      // Pointer moves onto center (400, 300) where Circle sits on top of RoundedRectangle
+      act(() => {
+        fireEvent.pointerMove(canvasElement, { clientX: 400, clientY: 300 });
+      });
+
+      // Top shape (Circle) must get pointer over
+      expect(onTopOver).toHaveBeenCalled();
+    });
+  });
+
+  describe('Edge Case: Hover State Stability Across Re-Renders', () => {
+    function InteractiveComponent({ onHoverChange }: { onHoverChange: (hovered: boolean) => void }) {
+      const [isHovered, setIsHovered] = useState(false);
+      const [count, setCount] = useState(0);
+
+      return (
+        <Group
+          onPointerOver={() => {
+            setIsHovered(true);
+            onHoverChange(true);
+          }}
+          onPointerOut={() => {
+            setIsHovered(false);
+            onHoverChange(false);
+          }}
+        >
+          <Circle radius={isHovered ? 40 : 20} />
+          <RoundedRectangle
+            width={100}
+            height={50}
+            onClick={() => setCount((c) => c + 1)}
+            aria-label={`Count: ${count}`}
+          />
+        </Group>
+      );
+    }
+
+    it('should maintain hover state cleanly when component re-renders with new inline function props', () => {
+      const onHoverChange = vi.fn();
+
+      const { container } = render(
+        <Canvas width={800} height={600} autostart={false}>
+          <InteractiveComponent onHoverChange={onHoverChange} />
+        </Canvas>
+      );
+
+      const canvasElement = container.querySelector('canvas') || container.querySelector('svg');
+      expect(canvasElement).not.toBeNull();
+    });
+  });
+
+  describe('hitTestPoint', () => {
+    it('reports true over a registered shape and false over empty canvas', () => {
+      const seen: Array<{ label: string; hit: boolean }> = [];
+
+      function Probe() {
+        const { two, hitTestPoint } = useTwo();
+        useEffect(() => {
+          if (!two) return;
+          seen.push({ label: 'inside', hit: hitTestPoint(400, 300) });
+          seen.push({ label: 'outside', hit: hitTestPoint(10, 10) });
+        }, [two, hitTestPoint]);
+        return null;
+      }
+
+      render(
+        <Canvas type={Two.Types.canvas} width={800} height={600}>
+          <Group>
+            <RoundedRectangle
+              x={400}
+              y={300}
+              width={100}
+              height={60}
+              onPointerDown={() => {}}
+            />
+          </Group>
+          <Probe />
+        </Canvas>,
+      );
+
+      expect(seen.find((s) => s.label === 'inside')?.hit).toBe(true);
+      expect(seen.find((s) => s.label === 'outside')?.hit).toBe(false);
+    });
+  });
+
+  describe('Event Shape Deregistration', () => {
+    // A shape that keeps a stale registration still participates in hit
+    // testing, which means `hitTestPoint` reports a hit and useZUI refuses to
+    // pan over what is now a non-interactive shape.
+    const probe: { hitTestPoint?: (x: number, y: number) => boolean } = {};
+
+    function Probe() {
+      const { hitTestPoint } = useTwo();
+      probe.hitTestPoint = hitTestPoint;
+      return null;
+    }
+
+    it('unregisters a shape when its handler prop is removed entirely', () => {
+      function App({ interactive }: { interactive: boolean }) {
+        return (
+          <Canvas type={Two.Types.canvas} width={800} height={600}>
+            <Group>
+              <RoundedRectangle
+                x={400}
+                y={300}
+                width={100}
+                height={60}
+                {...(interactive ? { onPointerDown: () => {} } : {})}
+              />
+            </Group>
+            <Probe />
+          </Canvas>
+        );
+      }
+
+      const { rerender } = render(<App interactive={true} />);
+      expect(probe.hitTestPoint!(400, 300)).toBe(true);
+
+      rerender(<App interactive={false} />);
+      expect(probe.hitTestPoint!(400, 300)).toBe(false);
+    });
+
+    it('unregisters a shape when its handler prop becomes undefined', () => {
+      function App({ interactive }: { interactive: boolean }) {
+        return (
+          <Canvas type={Two.Types.canvas} width={800} height={600}>
+            <Group>
+              <RoundedRectangle
+                x={400}
+                y={300}
+                width={100}
+                height={60}
+                onPointerDown={interactive ? () => {} : undefined}
+              />
+            </Group>
+            <Probe />
+          </Canvas>
+        );
+      }
+
+      const { rerender } = render(<App interactive={true} />);
+      expect(probe.hitTestPoint!(400, 300)).toBe(true);
+
+      rerender(<App interactive={false} />);
+      expect(probe.hitTestPoint!(400, 300)).toBe(false);
+    });
+
+    it('re-registers a shape when handlers come back', () => {
+      function App({ interactive }: { interactive: boolean }) {
+        return (
+          <Canvas type={Two.Types.canvas} width={800} height={600}>
+            <Group>
+              <RoundedRectangle
+                x={400}
+                y={300}
+                width={100}
+                height={60}
+                onPointerDown={interactive ? () => {} : undefined}
+              />
+            </Group>
+            <Probe />
+          </Canvas>
+        );
+      }
+
+      const { rerender } = render(<App interactive={false} />);
+      expect(probe.hitTestPoint!(400, 300)).toBe(false);
+
+      rerender(<App interactive={true} />);
+      expect(probe.hitTestPoint!(400, 300)).toBe(true);
+    });
+  });
+});
diff --git a/tests/registry.test.ts b/tests/registry.test.ts
new file mode 100644
index 0000000..472f575
--- /dev/null
+++ b/tests/registry.test.ts
@@ -0,0 +1,18 @@
+import { describe, it, expect } from 'vitest';
+import { PLAYGROUNDS, getPlaygroundById } from '../src/playgrounds/registry';
+
+describe('Playground Registry', () => {
+  it('should export registered playgrounds list', () => {
+    expect(PLAYGROUNDS.length).toBeGreaterThan(0);
+    expect(PLAYGROUNDS.some((p) => p.id === 'wiremarks')).toBe(true);
+  });
+
+  it('should retrieve playground by ID or fallback to first playground', () => {
+    const wiremarks = getPlaygroundById('wiremarks');
+    expect(wiremarks).toBeDefined();
+    expect(wiremarks.name).toBe('Wiremarks');
+
+    const fallback = getPlaygroundById('non-existent');
+    expect(fallback).toEqual(PLAYGROUNDS[0]);
+  });
+});
diff --git a/tests/wiremarkConnection.test.tsx b/tests/wiremarkConnection.test.tsx
new file mode 100644
index 0000000..4d07423
--- /dev/null
+++ b/tests/wiremarkConnection.test.tsx
@@ -0,0 +1,82 @@
+import { describe, it, expect } from 'vitest';
+import { render, act } from '@testing-library/react';
+import Two from 'two.js';
+import { Canvas, useTwo } from '../lib/main';
+import { WiremarkConnection } from '../src/playgrounds/wiremarks/components/WiremarkConnection';
+import type {
+  WiremarkEdge,
+  WiremarkNode,
+} from '../src/playgrounds/wiremarks/types';
+
+const source: WiremarkNode = {
+  id: 'a',
+  name: 'A',
+  x: 100,
+  y: 100,
+  width: 120,
+  height: 60,
+  colors: { fill: '#fff', stroke: '#000', textColor: '#000' },
+};
+
+const target: WiremarkNode = { ...source, id: 'b', name: 'B', x: 400, y: 300 };
+
+const edge: WiremarkEdge = {
+  id: 'a->b',
+  sourceId: 'a',
+  targetId: 'b',
+  color: '#000',
+};
+
+describe('WiremarkConnection dash animation', () => {
+  it('advances the dash offset on frame updates without React state', () => {
+    const captured: { two?: Two | null } = {};
+
+    function Probe() {
+      captured.two = useTwo().two;
+      return null;
+    }
+
+    const { container } = render(
+      <Canvas type={Two.Types.canvas} width={800} height={600} autostart={false}>
+        <WiremarkConnection edge={edge} sourceNode={source} targetNode={target} />
+        <Probe />
+      </Canvas>
+    );
+
+    const two = captured.two!;
+    expect(two).toBeTruthy();
+
+    // WiremarkConnection wraps its Path in a Group, so walk the scene graph
+    // for the first object carrying a dashes pattern.
+    type Node = { dashes?: { offset: number }; children?: Node[] };
+    function findDashed(node: Node): Node | null {
+      if (node.dashes && typeof node.dashes.offset === 'number') return node;
+      for (const child of node.children ?? []) {
+        const found = findDashed(child);
+        if (found) return found;
+      }
+      return null;
+    }
+
+    const path = findDashed(two.scene as unknown as Node);
+    expect(path).not.toBeNull();
+    expect(path!.dashes!.offset).toBe(0);
+
+    act(() => {
+      two.update();
+      two.update();
+    });
+
+    // Marching ants run in the negative direction.
+    expect(path!.dashes!.offset).toBeLessThan(0);
+
+    const afterTwoFrames = path!.dashes!.offset;
+    act(() => {
+      two.update();
+    });
+    expect(path!.dashes!.offset).toBeLessThan(afterTwoFrames);
+
+    // The offset advanced purely by mutation, so nothing re-rendered.
+    expect(container).toBeTruthy();
+  });
+});
diff --git a/tests/wiremarkEntity.test.tsx b/tests/wiremarkEntity.test.tsx
new file mode 100644
index 0000000..694cf8a
--- /dev/null
+++ b/tests/wiremarkEntity.test.tsx
@@ -0,0 +1,101 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, act } from '@testing-library/react';
+import Two from 'two.js';
+import { Canvas } from '../lib/main';
+import { WiremarkEntity } from '../src/playgrounds/wiremarks/components/WiremarkEntity';
+import type { WiremarkNode } from '../src/playgrounds/wiremarks/types';
+
+const node: WiremarkNode = {
+  id: 'a',
+  name: 'A',
+  x: 400,
+  y: 300,
+  width: 120,
+  height: 60,
+  colors: { fill: '#fff', stroke: '#000', textColor: '#000' },
+};
+
+function pointer(type: string, init: Partial<PointerEventInit> = {}) {
+  return new PointerEvent(type, {
+    bubbles: true,
+    cancelable: true,
+    pointerId: 1,
+    isPrimary: true,
+    button: 0,
+    buttons: type === 'pointerup' ? 0 : 1,
+    ...init,
+  });
+}
+
+function renderEntity(handlers: {
+  onDragStart?: (id: string, x: number, y: number) => void;
+  onDrag?: (id: string, x: number, y: number) => void;
+  onDragEnd?: (id: string) => void;
+}) {
+  const result = render(
+    <Canvas type={Two.Types.canvas} width={800} height={600}>
+      <WiremarkEntity node={node} {...handlers} />
+    </Canvas>
+  );
+  const canvas = document.querySelector('canvas')!;
+  return { ...result, canvas };
+}
+
+describe('WiremarkEntity drag lifecycle', () => {
+  it('reports drag movement while mounted', () => {
+    const onDrag = vi.fn();
+    const { canvas } = renderEntity({ onDrag });
+
+    act(() => {
+      canvas.dispatchEvent(pointer('pointerdown', { clientX: 400, clientY: 300 }));
+      window.dispatchEvent(pointer('pointermove', { clientX: 420, clientY: 310 }));
+    });
+
+    expect(onDrag).toHaveBeenCalledWith('a', 420, 310);
+  });
+
+  it('detaches window listeners when the node unmounts mid-drag', () => {
+    const onDrag = vi.fn();
+    const onDragEnd = vi.fn();
+    const { canvas, unmount } = renderEntity({ onDrag, onDragEnd });
+
+    act(() => {
+      canvas.dispatchEvent(pointer('pointerdown', { clientX: 400, clientY: 300 }));
+      window.dispatchEvent(pointer('pointermove', { clientX: 420, clientY: 310 }));
+    });
+    expect(onDrag).toHaveBeenCalledTimes(1);
+
+    // The DSL text can change (or the graph can re-parse) mid-drag, which
+    // unmounts the entity before pointerup ever arrives.
+    act(() => {
+      unmount();
+    });
+
+    // The parent must be told the drag is over, or draggingNodeId stays stale.
+    expect(onDragEnd).toHaveBeenCalledWith('a');
+
+    act(() => {
+      window.dispatchEvent(pointer('pointermove', { clientX: 500, clientY: 400 }));
+    });
+
+    // Still 1: no further callbacks from an unmounted component.
+    expect(onDrag).toHaveBeenCalledTimes(1);
+  });
+
+  it('detaches window listeners after a normal pointerup', () => {
+    const onDrag = vi.fn();
+    const onDragEnd = vi.fn();
+    const { canvas } = renderEntity({ onDrag, onDragEnd });
+
+    act(() => {
+      canvas.dispatchEvent(pointer('pointerdown', { clientX: 400, clientY: 300 }));
+      window.dispatchEvent(pointer('pointerup', { clientX: 400, clientY: 300 }));
+    });
+    expect(onDragEnd).toHaveBeenCalledWith('a');
+
+    act(() => {
+      window.dispatchEvent(pointer('pointermove', { clientX: 500, clientY: 400 }));
+    });
+    expect(onDrag).not.toHaveBeenCalled();
+  });
+});
diff --git a/tests/wiremarks.test.ts b/tests/wiremarks.test.ts
new file mode 100644
index 0000000..a68498d
--- /dev/null
+++ b/tests/wiremarks.test.ts
@@ -0,0 +1,55 @@
+import { describe, it, expect } from 'vitest';
+import { parseWiremarksDSL } from '../src/playgrounds/wiremarks/parser';
+
+describe('Wiremarks DSL Parser', () => {
+  it('should parse simple entity connections', () => {
+    const script = `
+      Grandmother -> Mother
+      Mother -> Daughter
+    `;
+
+    const { nodes, edges } = parseWiremarksDSL(script);
+
+    expect(nodes).toHaveLength(3);
+    expect(nodes.map((n) => n.name)).toEqual(['Grandmother', 'Mother', 'Daughter']);
+
+    expect(edges).toHaveLength(2);
+    expect(edges[0].sourceId).toBe('Grandmother');
+    expect(edges[0].targetId).toBe('Mother');
+    expect(edges[1].sourceId).toBe('Mother');
+    expect(edges[1].targetId).toBe('Daughter');
+  });
+
+  it('should parse labeled connections with bracket syntax', () => {
+    const script = `Grid -[Electricity]-> Home`;
+
+    const { nodes, edges } = parseWiremarksDSL(script);
+
+    expect(nodes).toHaveLength(2);
+    expect(nodes.map((n) => n.name)).toEqual(['Grid', 'Home']);
+
+    expect(edges).toHaveLength(1);
+    expect(edges[0].label).toBe('Electricity');
+    expect(edges[0].sourceId).toBe('Grid');
+    expect(edges[0].targetId).toBe('Home');
+  });
+
+  it('should ignore comment lines starting with #', () => {
+    const script = `
+      # This is a comment
+      EntityA -> EntityB
+      # Another comment line
+    `;
+
+    const { nodes, edges } = parseWiremarksDSL(script);
+
+    expect(nodes).toHaveLength(2);
+    expect(edges).toHaveLength(1);
+  });
+
+  it('should handle empty or invalid inputs gracefully', () => {
+    expect(parseWiremarksDSL('')).toEqual({ nodes: [], edges: [] });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(parseWiremarksDSL(null as any)).toEqual({ nodes: [], edges: [] });
+  });
+});
diff --git a/tests/zui.test.tsx b/tests/zui.test.tsx
new file mode 100644
index 0000000..4137be0
--- /dev/null
+++ b/tests/zui.test.tsx
@@ -0,0 +1,241 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, act } from '@testing-library/react';
+import { useEffect, useRef } from 'react';
+import Two from 'two.js';
+import { Canvas, Group, Circle, useZUI, useTwo, type RefGroup, type ZUIControls } from '../lib/main';
+
+beforeEach(() => {
+  HTMLCanvasElement.prototype.getContext = vi.fn().mockReturnValue({
+    fillRect: vi.fn(), clearRect: vi.fn(), getImageData: vi.fn().mockReturnValue({ data: [] }),
+    putImageData: vi.fn(), createImageData: vi.fn().mockReturnValue([]), setTransform: vi.fn(),
+    drawImage: vi.fn(), save: vi.fn(), fillText: vi.fn(), restore: vi.fn(), beginPath: vi.fn(),
+    moveTo: vi.fn(), lineTo: vi.fn(), closePath: vi.fn(), stroke: vi.fn(), translate: vi.fn(),
+    scale: vi.fn(), rotate: vi.fn(), arc: vi.fn(), fill: vi.fn(),
+    measureText: vi.fn().mockReturnValue({ width: 0 }), transform: vi.fn(), rect: vi.fn(), clip: vi.fn(),
+  });
+});
+
+/** Renders a ZUI-managed group and hands the controls back to the test. */
+function Harness({
+  onReady,
+  withShape = false,
+}: {
+  onReady: (controls: ZUIControls, canvas: HTMLElement) => void;
+  withShape?: boolean;
+}) {
+  const groupRef = useRef<RefGroup | null>(null);
+  const controls = useZUI(groupRef, { minZoom: 0.25, maxZoom: 8 });
+  const { two } = useTwo();
+
+  useEffect(() => {
+    const canvas = document.querySelector('canvas');
+    if (canvas) onReady(controls, canvas);
+  }, [two, controls, onReady]);
+
+  return (
+    <Group ref={groupRef}>
+      {withShape ? (
+        <Circle x={400} y={300} radius={50} onPointerDown={() => {}} />
+      ) : (
+        <Circle x={400} y={300} radius={50} />
+      )}
+    </Group>
+  );
+}
+
+function renderHarness(withShape = false) {
+  const captured: { controls?: ZUIControls; canvas?: HTMLElement } = {};
+  render(
+    <Canvas type={Two.Types.canvas} width={800} height={600}>
+      <Harness
+        withShape={withShape}
+        onReady={(controls, canvas) => {
+          captured.controls = controls;
+          captured.canvas = canvas;
+        }}
+      />
+    </Canvas>,
+  );
+  return captured as { controls: ZUIControls; canvas: HTMLElement };
+}
+
+function pointer(type: string, init: Partial<PointerEventInit>) {
+  return new PointerEvent(type, {
+    bubbles: true,
+    cancelable: true,
+    pointerId: 1,
+    isPrimary: true,
+    button: 0,
+    buttons: type === 'pointerup' ? 0 : 1,
+    ...init,
+  });
+}
+
+describe('useZUI', () => {
+  it('starts at scale 1 with an identity surface', () => {
+    const { controls } = renderHarness();
+    expect(controls.state.current.scale).toBe(1);
+    expect(controls.state.current.zoom).toBe(0);
+    expect(controls.state.current.x).toBe(0);
+    expect(controls.state.current.y).toBe(0);
+  });
+
+  it('exposes the ZUI instance via a ref, not a render-time value', () => {
+    const { controls } = renderHarness();
+    expect(controls.instance.current).not.toBeNull();
+  });
+
+  it('applies the zoom to the target group scale', () => {
+    const { controls } = renderHarness();
+    act(() => {
+      controls.zoomBy(Math.LN2, 400, 300);
+    });
+    expect(controls.state.current.scale).toBeCloseTo(2, 5);
+  });
+
+  it('clamps zoom to maxZoom', () => {
+    const { controls } = renderHarness();
+    act(() => {
+      controls.zoomBy(100, 400, 300);
+    });
+    expect(controls.state.current.scale).toBeCloseTo(8, 5);
+  });
+
+  it('clamps zoom to minZoom', () => {
+    const { controls } = renderHarness();
+    act(() => {
+      controls.zoomBy(-100, 400, 300);
+    });
+    expect(controls.state.current.scale).toBeCloseTo(0.25, 5);
+  });
+
+  it('pans on a background drag', () => {
+    const { controls, canvas } = renderHarness(false);
+    act(() => {
+      canvas.dispatchEvent(pointer('pointerdown', { clientX: 10, clientY: 10 }));
+      window.dispatchEvent(pointer('pointermove', { clientX: 60, clientY: 40 }));
+      window.dispatchEvent(pointer('pointerup', { clientX: 60, clientY: 40 }));
+    });
+    expect(controls.state.current.x).toBeCloseTo(50, 5);
+    expect(controls.state.current.y).toBeCloseTo(30, 5);
+  });
+
+  it('does NOT pan when the pointerdown lands on a registered shape', () => {
+    const { controls, canvas } = renderHarness(true);
+    act(() => {
+      canvas.dispatchEvent(pointer('pointerdown', { clientX: 400, clientY: 300 }));
+      window.dispatchEvent(pointer('pointermove', { clientX: 450, clientY: 330 }));
+      window.dispatchEvent(pointer('pointerup', { clientX: 450, clientY: 330 }));
+    });
+    expect(controls.state.current.x).toBe(0);
+    expect(controls.state.current.y).toBe(0);
+  });
+
+  it('ends a pan on pointercancel', () => {
+    const { controls, canvas } = renderHarness(false);
+    act(() => {
+      canvas.dispatchEvent(pointer('pointerdown', { clientX: 10, clientY: 10 }));
+      window.dispatchEvent(pointer('pointercancel', { clientX: 10, clientY: 10 }));
+      window.dispatchEvent(pointer('pointermove', { clientX: 200, clientY: 200 }));
+    });
+    expect(controls.state.current.x).toBe(0);
+  });
+
+  it('zooms on wheel toward the cursor', () => {
+    const { controls, canvas } = renderHarness();
+    act(() => {
+      canvas.dispatchEvent(
+        new WheelEvent('wheel', { bubbles: true, cancelable: true, deltaY: -100, deltaMode: 0, clientX: 400, clientY: 300 }),
+      );
+    });
+    expect(controls.state.current.scale).toBeGreaterThan(1);
+  });
+
+  it('resets back to the identity surface', () => {
+    const { controls } = renderHarness();
+    act(() => {
+      controls.zoomBy(1, 400, 300);
+      controls.panBy(25, 25);
+      controls.reset();
+    });
+    expect(controls.state.current.scale).toBe(1);
+    expect(controls.state.current.x).toBe(0);
+    expect(controls.state.current.y).toBe(0);
+  });
+
+  it('round-trips client and surface coordinates', () => {
+    const { controls } = renderHarness();
+    act(() => {
+      controls.zoomBy(0.5, 400, 300);
+      controls.panBy(40, -20);
+    });
+    const surface = controls.clientToSurface(250, 175);
+    const client = controls.surfaceToClient(surface.x, surface.y);
+    expect(client.x).toBeCloseTo(250, 4);
+    expect(client.y).toBeCloseTo(175, 4);
+  });
+
+  it('honours panBounds', () => {
+    const captured: { controls?: ZUIControls } = {};
+    function Bounded() {
+      const groupRef = useRef<RefGroup | null>(null);
+      captured.controls = useZUI(groupRef, { panBounds: { x: [-50, 50], y: [-50, 50] } });
+      return <Group ref={groupRef} />;
+    }
+    render(
+      <Canvas type={Two.Types.canvas} width={800} height={600}>
+        <Bounded />
+      </Canvas>,
+    );
+    act(() => {
+      captured.controls!.panBy(500, 500);
+    });
+    expect(captured.controls!.state.current.x).toBe(50);
+    expect(captured.controls!.state.current.y).toBe(50);
+  });
+
+  describe('surface-space drag deltas', () => {
+    it('maps screen pixels one-for-one at scale 1', () => {
+      const { controls } = renderHarness();
+      const a = controls.clientToSurface(100, 100);
+      const b = controls.clientToSurface(200, 160);
+      expect(b.x - a.x).toBeCloseTo(100, 5);
+      expect(b.y - a.y).toBeCloseTo(60, 5);
+    });
+
+    it('halves the surface delta at scale 2', () => {
+      const { controls } = renderHarness();
+      act(() => {
+        controls.zoomBy(Math.LN2, 400, 300);
+      });
+      expect(controls.state.current.scale).toBeCloseTo(2, 5);
+
+      const a = controls.clientToSurface(100, 100);
+      const b = controls.clientToSurface(200, 100);
+      expect(b.x - a.x).toBeCloseTo(50, 5);
+    });
+
+    it('doubles the surface delta at scale 0.5', () => {
+      const { controls } = renderHarness();
+      act(() => {
+        controls.zoomBy(-Math.LN2, 400, 300);
+      });
+      expect(controls.state.current.scale).toBeCloseTo(0.5, 5);
+
+      const a = controls.clientToSurface(100, 100);
+      const b = controls.clientToSurface(200, 100);
+      expect(b.x - a.x).toBeCloseTo(200, 5);
+    });
+
+    it('is unaffected by panning', () => {
+      const { controls } = renderHarness();
+      act(() => {
+        controls.zoomBy(Math.LN2, 400, 300);
+        controls.panBy(123, -45);
+      });
+      const a = controls.clientToSurface(100, 100);
+      const b = controls.clientToSurface(200, 100);
+      expect(b.x - a.x).toBeCloseTo(50, 5);
+    });
+  });
+});
diff --git a/tests/zuiMath.test.ts b/tests/zuiMath.test.ts
new file mode 100644
index 0000000..050a446
--- /dev/null
+++ b/tests/zuiMath.test.ts
@@ -0,0 +1,84 @@
+import { describe, it, expect } from 'vitest';
+import {
+  normalizeWheelDelta,
+  wheelZoomDelta,
+  pinchWheelZoomDelta,
+  pinchZoomDelta,
+  distance,
+  centroid,
+  clamp,
+} from '../lib/zuiMath';
+
+describe('normalizeWheelDelta', () => {
+  it('passes pixel mode through unchanged', () => {
+    expect(normalizeWheelDelta(100, 0, 800)).toBe(100);
+  });
+
+  it('scales line mode by 16px per line', () => {
+    expect(normalizeWheelDelta(3, 1, 800)).toBe(48);
+  });
+
+  it('scales page mode by the viewport height', () => {
+    expect(normalizeWheelDelta(1, 2, 800)).toBe(800);
+  });
+});
+
+describe('wheelZoomDelta', () => {
+  it('returns a negative log delta when scrolling down (zoom out)', () => {
+    expect(wheelZoomDelta(100, 0, 0.05, 800)).toBeCloseTo(-0.05, 10);
+  });
+
+  it('returns a positive log delta when scrolling up (zoom in)', () => {
+    expect(wheelZoomDelta(-100, 0, 0.05, 800)).toBeCloseTo(0.05, 10);
+  });
+
+  it('is symmetric so a scroll down then up is a round trip', () => {
+    const down = wheelZoomDelta(100, 0, 0.05, 800);
+    const up = wheelZoomDelta(-100, 0, 0.05, 800);
+    expect(down + up).toBeCloseTo(0, 10);
+  });
+});
+
+describe('pinchWheelZoomDelta', () => {
+  it('inverts a ctrl-wheel trackpad pinch', () => {
+    expect(pinchWheelZoomDelta(-10)).toBeCloseTo(0.1, 10);
+  });
+});
+
+describe('pinchZoomDelta', () => {
+  it('returns zero when the distance is unchanged', () => {
+    expect(pinchZoomDelta(100, 100)).toBe(0);
+  });
+
+  it('returns a log ratio so doubling the spread is scale-independent', () => {
+    expect(pinchZoomDelta(100, 200)).toBeCloseTo(Math.LN2, 10);
+    expect(pinchZoomDelta(400, 800)).toBeCloseTo(Math.LN2, 10);
+  });
+
+  it('guards against zero and negative distances', () => {
+    expect(pinchZoomDelta(0, 100)).toBe(0);
+    expect(pinchZoomDelta(100, 0)).toBe(0);
+  });
+});
+
+describe('distance and centroid', () => {
+  it('computes euclidean distance', () => {
+    expect(distance({ x: 0, y: 0 }, { x: 3, y: 4 })).toBe(5);
+  });
+
+  it('computes the midpoint of two points', () => {
+    expect(centroid([{ x: 0, y: 0 }, { x: 10, y: 20 }])).toEqual({ x: 5, y: 10 });
+  });
+
+  it('returns the origin for an empty list', () => {
+    expect(centroid([])).toEqual({ x: 0, y: 0 });
+  });
+});
+
+describe('clamp', () => {
+  it('clamps to both bounds', () => {
+    expect(clamp(5, 0, 10)).toBe(5);
+    expect(clamp(-1, 0, 10)).toBe(0);
+    expect(clamp(11, 0, 10)).toBe(10);
+  });
+});
diff --git a/vite.config.lib.ts b/vite.config.lib.ts
index f317451..8b7b4e8 100644
--- a/vite.config.lib.ts
+++ b/vite.config.lib.ts
@@ -16,7 +16,7 @@ export default defineConfig({
       formats: ['es'],
     },
     rollupOptions: {
-      external: ['react', 'react/jsx-runtime', 'two.js'],
+      external: [/^react$/, /^react\/jsx-runtime$/, /^two\.js(\/.*)?$/],
       output: {
         globals: {
           react: 'React',
diff --git a/vitest.config.ts b/vitest.config.ts
index 40e8e6b..46a8da6 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -1,18 +1,22 @@
 /// <reference types="vitest" />
 import { defineConfig } from 'vitest/config';
+import { resolve } from 'path';
 import react from '@vitejs/plugin-react';
 
 export default defineConfig({
   plugins: [react()],
+  resolve: {
+    alias: {
+      '@': resolve(__dirname, 'src'),
+      'react-two.js': resolve(__dirname, 'lib/main.ts'),
+    },
+  },
   test: {
     environment: 'jsdom',
     setupFiles: ['./src/test-setup.ts'],
     globals: true,
     css: true,
-    // Include simple tests for now
-    include: ['src/**/*.test.{ts,tsx}'],
-    exclude: ['lib/**/*.test.{ts,tsx}'],
-    // Pass when no tests are found
+    include: ['tests/**/*.test.{ts,tsx}', 'src/**/*.test.{ts,tsx}', 'lib/**/*.test.{ts,tsx}'],
     passWithNoTests: true,
   },
 });
\ No newline at end of file