feat: stack-based store.camera, Resource-component, remove store.pointer

- Extract raycaster implementations into separate module
- Add EventRaycaster interface with CursorRaycaster and CenterRaycaster
    - EventRaycaster extends Raycaster with an update(event)-method
- Remove store.pointer and instead let it be handled by the passed Raycaster
- Pass context to internal event-utilities instead of using useContext
- Fix circular import: move useProps from hooks.ts to props.ts
- Improve type definitions and remove unused internal context properties
- Rename canvasProps.camera to canvasProps.defaultCamera
- Rename store.camera to store.currentCamera
- Use stack to represent currentCamera
    - store.currentCamera is cameraStack.peek() ?? props.defaultCamera
    - store.setCurrentCamera pushes camera to stack and returns function to remove camera from stack

Author: bigmistqke

src/canvas.tsx

@@ -1,11 +1,5 @@
-import {
-  type JSX,
-  type ParentProps,
-  type Ref,
-  createRenderEffect,
-  onCleanup,
-  onMount,
-} from "solid-js"
+import { createResizeObserver } from "@solid-primitives/resize-observer"
+import { onMount, type JSX, type ParentProps, type Ref } from "solid-js"
 import {
   Camera,
   OrthographicCamera,
@@ -15,15 +9,18 @@ import {
   WebGLRenderer,
 } from "three"
 import { createThree } from "./create-three.tsx"
-import type { EventHandlers, Props } from "./types.ts"
+import type { EventRaycaster } from "./raycasters.tsx"
+import type { Context, EventHandlers, Props } from "./types.ts"
 
 /**
  * Props for the Canvas component, which initializes the Three.js rendering context and acts as the root for your 3D scene.
  */
 export interface CanvasProps extends ParentProps<Partial<EventHandlers>> {
   class?: string
   /** Configuration for the camera used in the scene. */
-  camera?: Partial<Props<PerspectiveCamera> | Props<OrthographicCamera>> | Camera
+  defaultCamera?: Partial<Props<PerspectiveCamera> | Props<OrthographicCamera>> | Camera
+  /** Configuration for the Scene instance. */
+  scene?: Partial<Props<Scene>> | Scene
   /** Element to render while the main content is loading asynchronously.  */
   fallback?: JSX.Element
   /** Options for the WebGLRenderer or a function returning a customized renderer. */
@@ -34,10 +31,8 @@ export interface CanvasProps extends ParentProps<Partial<EventHandlers>> {
   /** Toggles between Orthographic and Perspective camera. */
   orthographic?: boolean
   /** Configuration for the Raycaster used for mouse and pointer events. */
-  raycaster?: Partial<Props<Raycaster>> | Raycaster
-  ref?: Ref<HTMLDivElement>
-  /** Configuration for the Scene instance. */
-  scene?: Partial<Props<Scene>> | Scene
+  raycaster?: Partial<Props<EventRaycaster>> | EventRaycaster | Raycaster
+  ref?: Ref<Context>
   /** Custom CSS styles for the canvas container. */
   style?: JSX.CSSProperties
   /** Enables and configures shadows in the scene. */
@@ -68,32 +63,22 @@ export function Canvas(props: ParentProps<CanvasProps>) {
     const context = createThree(canvas, props)
 
     // Resize observer for the canvas to adjust camera and renderer on size change
-    function onResize() {
+    createResizeObserver(container, function onResize() {
       const { width, height } = container.getBoundingClientRect()
       context.gl.setSize(width, height)
       context.gl.setPixelRatio(globalThis.devicePixelRatio)
 
-      if (context.camera instanceof OrthographicCamera) {
-        context.camera.left = width / -2
-        context.camera.right = width / 2
-        context.camera.top = height / 2
-        context.camera.bottom = height / -2
+      if (context.currentCamera instanceof OrthographicCamera) {
+        context.currentCamera.left = width / -2
+        context.currentCamera.right = width / 2
+        context.currentCamera.top = height / 2
+        context.currentCamera.bottom = height / -2
       } else {
-        context.camera.aspect = width / height
+        context.currentCamera.aspect = width / height
       }
 
-      context.camera.updateProjectionMatrix()
+      context.currentCamera.updateProjectionMatrix()
       context.render(performance.now())
-    }
-    const observer = new ResizeObserver(onResize)
-    observer.observe(container)
-    onResize()
-    onCleanup(() => observer.disconnect())
-
-    // Assign ref
-    createRenderEffect(() => {
-      if (props.ref instanceof Function) props.ref(container)
-      else props.ref = container
     })
   })
 
@@ -105,12 +90,13 @@ export function Canvas(props: ParentProps<CanvasProps>) {
         width: "100%",
         height: "100%",
         overflow: "hidden",
+        contain: "strict",
         display: "flex",
         ...props.style,
       }}
       class={props.class}
     >
-      <canvas ref={canvas!} style={{ width: "100%", height: "100%" }} />
+      <canvas ref={canvas!} />
     </div>
   )
 }

src/components.tsx

@@ -1,17 +1,22 @@
 import {
+  type Accessor,
   type JSX,
+  type JSXElement,
   type ParentProps,
+  Show,
   createMemo,
   createRenderEffect,
+  createResource,
   mergeProps,
   splitProps,
 } from "solid-js"
 import { Object3D } from "three"
 import { threeContext, useThree } from "./hooks.ts"
 import { manageSceneGraph, useProps } from "./props.ts"
-import type { Constructor, Instance, Overwrite, Props } from "./types.ts"
+import type { Constructor, Instance, Loader, Overwrite, Props } from "./types.ts"
 import { type InstanceFromConstructor } from "./types.ts"
-import { augment, autodispose, isConstructor, isInstance, withContext } from "./utils.ts"
+import { augment, autodispose, isConstructor, isInstance, load, withContext } from "./utils.ts"
+import { whenMemo } from "./utils/conditionals.ts"
 
 /**********************************************************************************/
 /*                                                                                */
@@ -68,7 +73,7 @@ export const Portal = (props: PortalProps) => {
 type EntityProps<T extends object | Constructor<object>> = Overwrite<
   Props<T>,
   {
-    from: T
+    from: T | undefined
   }
 >
 /**
@@ -82,14 +87,52 @@ type EntityProps<T extends object | Constructor<object>> = Overwrite<
  */
 export function Entity<T extends object | Constructor<object>>(props: EntityProps<T>) {
   const [config, rest] = splitProps(props, ["from", "args"])
-  const memo = createMemo(() => {
-    return augment(
-      isConstructor(config.from)
-        ? autodispose(new config.from(...(config.args ?? [])))
-        : config.from,
-      { props },
-    ) as Instance<T>
-  })
+  const memo = whenMemo(
+    () => config.from,
+    from => {
+      const instance = augment(
+        isConstructor(from) ? autodispose(new from(...(config.args ?? []))) : from,
+        {
+          props,
+        },
+      ) as Instance<T>
+      return instance
+    },
+  )
   useProps(memo, rest)
   return memo as unknown as JSX.Element
 }
+
+/**********************************************************************************/
+/*                                                                                */
+/*                                     Resource                                   */
+/*                                                                                */
+/**********************************************************************************/
+
+type ResourceProps<TSource, TResult extends object> = Omit<Props<TResult>, "children"> & {
+  loader: new () => Loader<TSource, TResult>
+  url: TSource
+  path?: string
+  children?: (result: Accessor<TResult>) => JSXElement
+}
+
+export function Resource<TSource, TResult extends object>(props: ResourceProps<TSource, TResult>) {
+  const [config, rest] = splitProps(props, ["loader", "path", "url"])
+  const loader = createMemo(() => new config.loader())
+  const [resource] = createResource(
+    () => [config.url, loader(), config.path] as const,
+    ([url, loader, path]) => {
+      loader.setPath?.(path ?? "")
+      return load(loader, url) as Promise<TResult>
+    },
+  )
+  return (
+    <Show
+      when={"children" in props && resource()}
+      // @ts-expect-error FIXME
+      fallback={<Entity from={resource()} {...rest} />}
+    >
+      {resource => props.children?.(resource)}
+    </Show>
+  )
+}

src/create-events.ts

@@ -1,5 +1,4 @@
 import { Object3D, type Intersection } from "three"
-import type { CanvasProps } from "./canvas.tsx"
 import { $S3C } from "./constants.ts"
 import type { Context, EventName, Instance, ThreeEvent } from "./types.ts"
 import { isInstance } from "./utils.ts"
@@ -97,14 +96,11 @@ function createThreeEvent<TEvent extends Event>(
 function raycast<TNativeEvent extends MouseEvent | WheelEvent>(
   context: Context,
   registry: Object3D[],
-  nativeEvent: TNativeEvent,
+  event: TNativeEvent,
 ): Intersection<Instance<Object3D>>[] {
-  context.setPointer(pointer => {
-    pointer.x = (nativeEvent.offsetX / context.bounds.width) * 2 - 1
-    pointer.y = -(nativeEvent.offsetY / context.bounds.height) * 2 + 1
-    return pointer
-  })
-  context.raycaster.setFromCamera(context.pointer, context.camera)
+  if ("update" in context.raycaster) {
+    context.raycaster.update(event, context)
+  }
 
   const nodeSet = new Set<Object3D>()
   const visitedSet = new Set<Object3D>()
@@ -138,7 +134,6 @@ function raycast<TNativeEvent extends MouseEvent | WheelEvent>(
 function createMissableEventRegistry(
   type: "onClick" | "onDoubleClick" | "onContextMenu",
   context: Context,
-  props: CanvasProps,
 ) {
   const registry = createRegistry<Object3D>()
 
@@ -169,13 +164,11 @@ function createMissableEventRegistry(
     // Call the respective canvas event-handler
     // if event propagated all the way down
     if (!event.stopped) {
-      props[type]?.(event)
+      context.props[type]?.(event)
     }
 
     // Phase #2 - Raycast remaining missed objects
     for (const remainingObject of missedObjects) {
-      // Perform raycast on unvisited missed objects
-      context.raycaster.setFromCamera(context.pointer, context.camera)
       const intersections = context.raycaster.intersectObject(remainingObject, true)
 
       // Bubble down intersections
@@ -202,7 +195,7 @@ function createMissableEventRegistry(
     }
 
     if (visitedObjects.size > 0) {
-      props[`${type}Missed`]?.(missedEvent)
+      context.props[`${type}Missed`]?.(missedEvent)
     }
   })
 
@@ -226,7 +219,7 @@ function createMissableEventRegistry(
  *    - `onPointerMove`
  *    - `onPointerLeave`
  */
-function createHoverEventRegistry(type: "Mouse" | "Pointer", context: Context, props: CanvasProps) {
+function createHoverEventRegistry(type: "Mouse" | "Pointer", context: Context) {
   const registry = createRegistry<Object3D>()
   let hoveredSet = new Set<Object3D>()
   let intersections: Intersection<Instance<Object3D>>[] = []
@@ -254,7 +247,7 @@ function createHoverEventRegistry(type: "Mouse" | "Pointer", context: Context, p
     }
 
     if (hoveredCanvas === false) {
-      props[`on${type}Enter`]?.(enterEvent)
+      context.props[`on${type}Enter`]?.(enterEvent)
       hoveredCanvas = true
     }
 
@@ -282,7 +275,7 @@ function createHoverEventRegistry(type: "Mouse" | "Pointer", context: Context, p
     }
 
     if (!moveEvent.stopped) {
-      props[`on${type}Move`]?.(moveEvent)
+      context.props[`on${type}Move`]?.(moveEvent)
     }
 
     // Handle leave-event
@@ -299,7 +292,7 @@ function createHoverEventRegistry(type: "Mouse" | "Pointer", context: Context, p
 
   context.canvas.addEventListener(eventNameMap[`on${type}Leave`], nativeEvent => {
     const leaveEvent = createThreeEvent(nativeEvent, false)
-    props[`on${type}Leave`]?.(leaveEvent)
+    context.props[`on${type}Leave`]?.(leaveEvent)
     hoveredCanvas = false
 
     for (const object of hoveredSet) {
@@ -330,7 +323,6 @@ function createHoverEventRegistry(type: "Mouse" | "Pointer", context: Context, p
 function createDefaultEventRegistry(
   type: "onMouseDown" | "onMouseUp" | "onPointerDown" | "onPointerUp" | "onWheel",
   context: Context,
-  props: CanvasProps,
   options?: AddEventListenerOptions,
 ) {
   const registry = createRegistry<Object3D>()
@@ -356,7 +348,7 @@ function createDefaultEventRegistry(
 
       if (!event.stopped) {
         // @ts-expect-error TODO: fix type-error
-        props[type]?.(event)
+        context.props[type]?.(event)
       }
     },
     options,
@@ -374,27 +366,27 @@ function createDefaultEventRegistry(
 /**
  * Initializes and manages event handling for all `Instance<Object3D>`.
  */
-export function createEvents(context: Context, props: CanvasProps) {
+export function createEvents(context: Context) {
   // onMouseMove/onMouseEnter/onMouseLeave
-  const hoverMouseRegistry = createHoverEventRegistry("Mouse", context, props)
+  const hoverMouseRegistry = createHoverEventRegistry("Mouse", context)
   // onPointerMove/onPointerEnter/onPointerLeave
-  const hoverPointerRegistry = createHoverEventRegistry("Pointer", context, props)
+  const hoverPointerRegistry = createHoverEventRegistry("Pointer", context)
 
   // onClick/onClickMissed
-  const missableClickRegistry = createMissableEventRegistry("onClick", context, props)
+  const missableClickRegistry = createMissableEventRegistry("onClick", context)
   // onContextMenu/onContextMenuMissed
-  const missableContextMenuRegistry = createMissableEventRegistry("onContextMenu", context, props)
+  const missableContextMenuRegistry = createMissableEventRegistry("onContextMenu", context)
   // onDoubleClick/onDoubleClickMissed
-  const missableDoubleClickRegistry = createMissableEventRegistry("onDoubleClick", context, props)
+  const missableDoubleClickRegistry = createMissableEventRegistry("onDoubleClick", context)
 
   // Default mouse-events
-  const mouseDownRegistry = createDefaultEventRegistry("onMouseDown", context, props)
-  const mouseUpRegistry = createDefaultEventRegistry("onMouseUp", context, props)
+  const mouseDownRegistry = createDefaultEventRegistry("onMouseDown", context)
+  const mouseUpRegistry = createDefaultEventRegistry("onMouseUp", context)
   // Default pointer-events
-  const pointerDownRegistry = createDefaultEventRegistry("onPointerDown", context, props)
-  const pointerUpRegistry = createDefaultEventRegistry("onPointerUp", context, props)
+  const pointerDownRegistry = createDefaultEventRegistry("onPointerDown", context)
+  const pointerUpRegistry = createDefaultEventRegistry("onPointerUp", context)
   // Default wheel-event
-  const wheelRegistry = createDefaultEventRegistry("onWheel", context, props, { passive: true })
+  const wheelRegistry = createDefaultEventRegistry("onWheel", context, { passive: true })
 
   return {
     /**