refactor: rename Instance to Meta and add priority-based frame listeners

- Rename Instance type to Meta throughout codebase for clarity
- Rename InstanceFromConstructor to InstanceOf for consistency
- Add priority and stage options to useFrame hook
- Implement sorted priority system for frame listeners (before/after render stages)
- Use binary search for efficient priority insertion
- Fix useProps to handle undefined objects gracefully

Author: bigmistqke

package.json

@@ -6,6 +6,7 @@
     "type": "git",
     "url": "git+https://github.com/solidjs-community/solid-three.git"
   },
+  "type": "module",
   "module": "./dist/index/index.js",
   "main": "./dist/index/index.js",
   "types": "./dist/index/index.d.ts",
@@ -112,6 +113,5 @@
         "./dist/testing/index.d.ts"
       ]
     }
-  },
-  "type": "module"
+  }
 }

playground/examples/SolarExample.tsx

@@ -1,5 +1,5 @@
 import { createEffect, createMemo, createSignal, Show, type ParentProps, type Ref } from "solid-js"
-import type { Instance } from "src/types.ts"
+import type { Meta } from "src/types.ts"
 import * as THREE from "three"
 import { Canvas, createT, Entity, useFrame } from "../../src/index.ts"
 import { OrbitControls } from "../controls/OrbitControls.tsx"
@@ -66,7 +66,7 @@ function CelestialBody(
   }>,
 ) {
   const [hovered, setHovered] = createSignal(false)
-  let ref: Instance<THREE.Mesh> = null!
+  let ref: Meta<THREE.Mesh> = null!
 
   createEffect(() => {
     if (!props.orbit) return

src/components.tsx

@@ -13,8 +13,8 @@ import {
 import { Object3D } from "three"
 import { threeContext, useThree } from "./hooks.ts"
 import { manageSceneGraph, useProps } from "./props.ts"
-import type { Constructor, Instance, Loader, Overwrite, Props } from "./types.ts"
-import { type InstanceFromConstructor } from "./types.ts"
+import type { Constructor, Loader, Meta, Overwrite, Props } from "./types.ts"
+import { type InstanceOf } from "./types.ts"
 import { augment, autodispose, isConstructor, isInstance, load, withContext } from "./utils.ts"
 import { whenMemo } from "./utils/conditionals.ts"
 
@@ -25,7 +25,7 @@ import { whenMemo } from "./utils/conditionals.ts"
 /**********************************************************************************/
 
 type PortalProps = ParentProps<{
-  element?: InstanceFromConstructor<Object3D> | Instance<Object3D>
+  element?: InstanceOf<Object3D> | Meta<Object3D>
 }>
 /**
  * A component for placing its children outside the regular `solid-three` scene graph managed by Solid's reactive system.
@@ -40,7 +40,7 @@ export const Portal = (props: PortalProps) => {
   const scene = createMemo(() => {
     return props.element
       ? isInstance(props.element)
-        ? (props.element as Instance<Object3D>)
+        ? (props.element as Meta<Object3D>)
         : augment(props.element, { props: {} })
       : context.scene
   })
@@ -49,7 +49,7 @@ export const Portal = (props: PortalProps) => {
     // @ts-expect-error TODO: fix type-error
     manageSceneGraph(scene(), () =>
       withContext(
-        () => props.children as unknown as Instance | Instance[],
+        () => props.children as unknown as Meta | Meta[],
         // @ts-expect-error TODO: fix type-error
         threeContext,
         mergeProps(context, {
@@ -74,6 +74,7 @@ type EntityProps<T extends object | Constructor<object>> = Overwrite<
   Props<T>,
   {
     from: T | undefined
+    children?: JSXElement
   }
 >
 /**
@@ -95,7 +96,7 @@ export function Entity<T extends object | Constructor<object>>(props: EntityProp
         {
           props,
         },
-      ) as Instance<T>
+      ) as Meta<T>
       return instance
     },
   )

src/create-events.ts

@@ -1,6 +1,6 @@
 import { Object3D, type Intersection } from "three"
 import { $S3C } from "./constants.ts"
-import type { Context, EventName, Instance, ThreeEvent } from "./types.ts"
+import type { Context, EventName, Meta, ThreeEvent } from "./types.ts"
 import { isInstance } from "./utils.ts"
 
 const eventNameMap = {
@@ -97,7 +97,7 @@ function raycast<TNativeEvent extends MouseEvent | WheelEvent>(
   context: Context,
   registry: Object3D[],
   event: TNativeEvent,
-): Intersection<Instance<Object3D>>[] {
+): Intersection<Meta<Object3D>>[] {
   if ("update" in context.raycaster) {
     context.raycaster.update(event, context)
   }
@@ -222,7 +222,7 @@ function createMissableEventRegistry(
 function createHoverEventRegistry(type: "Mouse" | "Pointer", context: Context) {
   const registry = createRegistry<Object3D>()
   let hoveredSet = new Set<Object3D>()
-  let intersections: Intersection<Instance<Object3D>>[] = []
+  let intersections: Intersection<Meta<Object3D>>[] = []
   let hoveredCanvas = false
 
   context.canvas.addEventListener(eventNameMap[`on${type}Move`], nativeEvent => {
@@ -395,7 +395,7 @@ export function createEvents(context: Context) {
      * @param object - The 3D object to register.
      * @param type - The type of event the object should listen for.
      */
-    addEventListener(object: Instance<Object3D>, type: EventName) {
+    addEventListener(object: Meta<Object3D>, type: EventName) {
       switch (type) {
         // Missable Events
         case "onClick":

src/create-three.tsx

@@ -3,6 +3,7 @@ import {
   createEffect,
   createMemo,
   createRenderEffect,
+  createRoot,
   mergeProps,
   onCleanup,
 } from "solid-js"
@@ -29,9 +30,10 @@ import { frameContext, threeContext } from "./hooks.ts"
 import { eventContext } from "./internal-context.ts"
 import { manageSceneGraph, useProps } from "./props.ts"
 import { CursorRaycaster, type EventRaycaster } from "./raycasters.tsx"
-import type { CameraKind, Context } from "./types.ts"
+import type { CameraKind, Context, FrameListener, FrameListenerCallback } from "./types.ts"
 import {
   augment,
+  binarySearch,
   defaultProps,
   getCurrentViewport,
   removeElementFromArray,
@@ -54,15 +56,55 @@ export function createThree(canvas: HTMLCanvasElement, props: CanvasProps) {
   /*                                                                                */
   /**********************************************************************************/
 
-  type FrameListener = (context: Context, delta: number, frame?: XRFrame) => void
+  const frameListeners = {
+    before: {
+      map: new Map<number, FrameListenerCallback[]>(),
+      priorities: [] as number[], // Keep this sorted
+    },
+    after: {
+      map: new Map<number, FrameListenerCallback[]>(),
+      priorities: [] as number[],
+    },
+  }
+
+  const addFrameListener: FrameListener = (callback, options) => {
+    return createRoot(dispose => {
+      createRenderEffect(() => {
+        const { stage = "before", priority = 0 } = options ?? {}
+
+        const listeners = frameListeners[stage]
+
+        let array = listeners.map.get(priority)
+
+        if (!array) {
+          array = []
+          listeners.map.set(priority, array)
+          const index = binarySearch(listeners.priorities, priority)
+          listeners.priorities.splice(index, 0, priority)
+        }
+
+        array.push(callback)
 
-  const frameListeners: FrameListener[] = []
-  // Adds a callback to be called on each frame
-  function addFrameListener(callback: FrameListener) {
-    frameListeners.push(callback)
-    const cleanup = () => removeElementFromArray(frameListeners, callback)
-    onCleanup(cleanup)
-    return cleanup
+        onCleanup(() => {
+          removeElementFromArray(array, callback)
+          if (array.length === 0) {
+            listeners.map.delete(priority)
+            listeners.priorities.splice(listeners.priorities.indexOf(priority), 1)
+          }
+        })
+      })
+
+      return dispose
+    })
+  }
+
+  function updateFrameListeners(stage: "before" | "after", delta: number, frame?: XRFrame) {
+    for (const priority of frameListeners[stage].priorities) {
+      const callbacks = frameListeners[stage].map.get(priority)!
+      for (const callback of callbacks) {
+        callback(context, delta, frame)
+      }
+    }
   }
 
   /**********************************************************************************/
@@ -100,6 +142,7 @@ export function createThree(canvas: HTMLCanvasElement, props: CanvasProps) {
   /**********************************************************************************/
 
   let pendingRenderRequest: number | undefined
+
   function render(timestamp: number, frame?: XRFrame) {
     if (!context.gl) {
       return
@@ -108,8 +151,11 @@ export function createThree(canvas: HTMLCanvasElement, props: CanvasProps) {
       context.clock.elapsedTime = timestamp
     }
     pendingRenderRequest = undefined
+
+    const delta = context.clock.getDelta()
+    updateFrameListeners("before", delta, frame)
     context.gl.render(context.scene, context.currentCamera)
-    frameListeners.forEach(listener => listener(context, context.clock.getDelta(), frame))
+    updateFrameListeners("after", delta, frame)
   }
   function requestRender() {
     if (pendingRenderRequest) return

src/data-structure/augmented-stack.ts

@@ -1,11 +1,11 @@
 import type { Accessor } from "solid-js"
-import type { Instance } from "src/types.ts"
+import type { Meta } from "src/types.ts"
 import { augment } from "../utils.ts"
 import { Stack } from "./stack.ts"
 
 /** A generic stack data structure. It augments each value before pushing it onto the stack. */
 export class AugmentedStack<T> {
-  #stack = new Stack<Instance<T>>(null!)
+  #stack = new Stack<Meta<T>>(null!)
   constructor(public name: string) {
     this.#stack.name = name
   }

src/hooks.ts

@@ -1,14 +1,13 @@
 import { type Accessor, createContext, useContext } from "solid-js"
-import type { Context } from "./types"
+import type { Context, FrameListener } from "./types"
 
 /**********************************************************************************/
 /*                                                                                */
 /*                                    Use Frame                                   */
 /*                                                                                */
 /**********************************************************************************/
 
-type FrameContext = (callback: (context: Context, delta: number, frame?: XRFrame) => void) => void
-export const frameContext = createContext<FrameContext>()
+export const frameContext = createContext<FrameListener>()
 
 /**
  * Hook to register a callback that will be executed on each animation frame within the `<Canvas/>` component.
@@ -17,12 +16,12 @@ export const frameContext = createContext<FrameContext>()
  * @param callback - The callback function to be executed on each frame.
  * @throws Throws an error if used outside of the Canvas component context.
  */
-export const useFrame = (callback: (context: Context, delta: number, frame?: XRFrame) => void) => {
+export const useFrame: FrameListener = (callback, options) => {
   const addFrameListener = useContext(frameContext)
   if (!addFrameListener) {
     throw new Error("S3: Hooks can only be used within the Canvas component!")
   }
-  addFrameListener(callback)
+  return addFrameListener(callback, options)
 }
 
 /**********************************************************************************/

src/internal-context.ts

@@ -1,6 +1,6 @@
 import { type JSX, createContext, useContext } from "solid-js"
 import { Object3D } from "three"
-import type { EventName, Instance } from "./types.ts"
+import type { EventName, Meta } from "./types.ts"
 
 /**
  * Registers an event listener for an `AugmentedElement` to the nearest Canvas component up the component tree.
@@ -10,15 +10,14 @@ import type { EventName, Instance } from "./types.ts"
  * @param type - The type of event to listen for (e.g., 'click', 'mouseenter').
  * @throws Throws an error if used outside of the Canvas component context.
  */
-export const addToEventListeners = (object: Instance<Object3D>, type: EventName) => {
+export const addToEventListeners = (object: Meta<Object3D>, type: EventName) => {
   const addToEventListeners = useContext(eventContext)
   if (!addToEventListeners) {
     throw new Error("S3: Hooks can only be used within the Canvas component!")
   }
   return addToEventListeners(object, type)
 }
-export const eventContext =
-  createContext<(object: Instance<Object3D>, type: EventName) => () => void>()
+export const eventContext = createContext<(object: Meta<Object3D>, type: EventName) => () => void>()
 
 /**
  * This function facilitates the rendering of JSX elements outside the normal scene