feat: add plugin system

.gitignore

@@ -1,5 +1,6 @@
+.claude
 .scratch
 dist
 types
 node_modules
-packed/
+packed/

LICENSE

@@ -19,3 +19,30 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+================================================================================
+
+This project is based on @react-three/fiber (https://github.com/pmndrs/react-three-fiber)
+Original
+
+MIT License
+
+Copyright (c) 2019-2025 Poimandres
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package.json

@@ -72,7 +72,9 @@
     }
   },
   "dependencies": {
+    "@solid-primitives/map": "^0.7.2",
     "@solid-primitives/resize-observer": "^2.0.25",
+    "@solid-primitives/set": "^0.7.2",
     "debounce": "^2.1.0"
   },
   "devDependencies": {

playground/App.tsx

@@ -1,13 +1,15 @@
 import { A, Route, Router } from "@solidjs/router"
 import type { ParentProps } from "solid-js"
 import * as THREE from "three"
-import { Canvas, createT, Entity } from "../src/index.ts"
+import { createT, Entity } from "../src/index.ts"
 import { EnvironmentExample } from "./examples/EnvironmentExample.tsx"
+import { PluginExample } from "./examples/PluginExample.tsx"
 import { PortalExample } from "./examples/PortalExample.tsx"
 import { SolarExample } from "./examples/SolarExample.tsx"
+import { VanillaExample } from "./examples/VanillaExample.tsx"
 import "./index.css"
 
-const T = createT(THREE)
+const { T, Canvas } = createT({ ...THREE, Entity })
 
 function Layout(props: ParentProps) {
   return (
@@ -67,6 +69,28 @@ function Layout(props: ParentProps) {
         >
           Environment
         </A>
+        <A
+          href="/plugin"
+          style={{
+            color: "white",
+            "text-decoration": "none",
+            padding: "5px 10px",
+            display: "block",
+          }}
+        >
+          Plugins
+        </A>
+        <A
+          href="/vanilla"
+          style={{
+            color: "white",
+            "text-decoration": "none",
+            padding: "5px 10px",
+            display: "block",
+          }}
+        >
+          Vanilla
+        </A>
       </nav>
       {props.children}
     </>
@@ -79,6 +103,8 @@ export function App() {
       <Route path="/simple-solar" component={SolarExample} />
       <Route path="/portal" component={PortalExample} />
       <Route path="/environment" component={EnvironmentExample} />
+      <Route path="/plugin" component={PluginExample} />
+      <Route path="/vanilla" component={VanillaExample} />
       <Route
         path="/"
         component={() => (
@@ -87,7 +113,7 @@ export function App() {
             scene={{ background: [1, 0, 0] }}
             style={{ width: "100vw", height: "100vh" }}
           >
-            <Entity from={THREE.Group}>
+            <Entity from={THREE.Group} position={[0, 0, 0]}>
               <T.Mesh>
                 <T.BoxGeometry />
                 <T.MeshBasicMaterial color="gray" />

playground/controls/OrbitControls.tsx

@@ -1,4 +1,4 @@
-import { createEffect, createMemo, onCleanup, type Ref } from "solid-js"
+import { createEffect, createMemo, onCleanup } from "solid-js"
 import type { Event } from "three"
 import { OrbitControls as ThreeOrbitControls } from "three-stdlib"
 import { useFrame, useThree, type S3 } from "../../src/index.ts"
@@ -7,7 +7,6 @@ import { whenEffect } from "../../src/utils/conditionals.ts"
 import { processProps } from "./process-props.ts"
 
 export interface OrbitControlsProps extends S3.Props<typeof ThreeOrbitControls> {
-  ref?: Ref<ThreeOrbitControls>
   camera?: S3.CameraKind
   domElement?: HTMLElement
   enableDamping?: boolean

playground/examples/EnvironmentExample.tsx

@@ -1,11 +1,15 @@
+import { createSignal } from "solid-js"
 import * as THREE from "three"
-import { Resource } from "../../src/components.tsx"
-import { Canvas, createT } from "../../src/index.ts"
+import { createT, EventPlugin, Resource } from "../../src/index.ts"
 import { OrbitControls } from "../controls/OrbitControls.tsx"
 
-const T = createT(THREE)
+const { T, Canvas } = createT(THREE, [EventPlugin])
 
 export function EnvironmentExample() {
+  const [position, setPosition] = createSignal(0)
+
+  setInterval(() => setPosition(position => position + 1), 500)
+
   return (
     <Canvas
       style={{ width: "100vw", height: "100vh" }}
@@ -16,6 +20,10 @@ export function EnvironmentExample() {
       onPointerEnter={event => console.debug("canvas pointer enter", event)}
     >
       <OrbitControls />
+      <T.Mesh position={new THREE.Vector3(position(), 0, 0)}>
+        <T.BoxGeometry args={[1, 0.5, 128, 32]} />
+        <T.MeshBasicMaterial color="red" />
+      </T.Mesh>
       <T.Mesh>
         <T.TorusKnotGeometry args={[1, 0.5, 128, 32]} />
         <T.MeshStandardMaterial metalness={1} roughness={0} color="white">

playground/examples/PluginExample.tsx

@@ -0,0 +1,121 @@
+import * as THREE from "three"
+import type { Meta } from "types.ts"
+import {
+  createT,
+  Entity,
+  EventPlugin,
+  plugin,
+  Resource,
+  useFrame,
+  useThree,
+} from "../../src/index.ts"
+import { OrbitControls } from "../controls/OrbitControls.tsx"
+
+// LookAt plugin - works for all Object3D elements
+const LookAtPlugin = plugin([THREE.Object3D], element => {
+  return {
+    lookAt: (target: THREE.Object3D | [number, number, number]) => {
+      useFrame(() => {
+        if (Array.isArray(target)) {
+          element.lookAt(...target)
+        } else {
+          element.lookAt(target.position)
+        }
+      })
+    },
+  }
+})
+
+// Shake plugin - works for both Camera and Light elements using array syntax
+const ShakePlugin = plugin([THREE.Camera, THREE.DirectionalLight, THREE.Mesh], element => ({
+  shake: (intensity = 0.1) => {
+    const originalPosition = element.position.clone()
+    useFrame(() => {
+      element.position.x = originalPosition.x + (Math.random() - 0.5) * intensity
+      element.position.y = originalPosition.y + (Math.random() - 0.5) * intensity
+      element.position.z = originalPosition.z + (Math.random() - 0.5) * intensity
+    })
+  },
+}))
+
+// Custom filter plugin - works for objects with a 'material' property using type guard
+const MaterialPlugin = plugin(
+  (element: any): element is THREE.Mesh =>
+    element instanceof THREE.Mesh && element.material !== undefined,
+  element => ({
+    highlight: (color: string = "yellow") => {
+      const material = element.material as THREE.MeshBasicMaterial
+      material.color.set(color)
+    },
+    setColor: (color: string) => {
+      const material = element.material as THREE.MeshBasicMaterial
+      material.color.setHex(parseInt(color.replace("#", ""), 16))
+    },
+  }),
+)
+
+// Global plugin - applies to all elements using single argument
+const GlobalPlugin: {
+  (element: THREE.Material): { log(message: number): void }
+  (element: THREE.Mesh): { log(message: string): void }
+} = plugin(element => ({
+  log: (message: string | number) => {
+    console.info(`[${element.constructor.name}] ${message}`)
+  },
+}))
+
+const { T, Canvas } = createT(THREE, [
+  LookAtPlugin,
+  ShakePlugin,
+  EventPlugin,
+  MaterialPlugin,
+  GlobalPlugin,
+])
+
+export function PluginExample() {
+  let cubeRef: Meta<THREE.Mesh>
+  let cameraRef: Meta<THREE.PerspectiveCamera>
+
+  return (
+    <Canvas
+      style={{ width: "100vw", height: "100vh" }}
+      defaultCamera={{ position: new THREE.Vector3(0, 0, 5) }}
+      contexts={[EventPlugin]}
+      onClickMissed={() => console.info("missed!")}
+    >
+      <OrbitControls />
+      <Entity from={THREE.Mesh} />
+      {/* Mesh with lookAt (from LookAtPlugin) and material methods (from MaterialPlugin) */}
+      <T.Mesh
+        ref={cubeRef!}
+        position={[0, 0, 0]}
+        highlight="red"
+        lookAt={useThree().currentCamera}
+        log="Mesh rendered!"
+        shake={0.1}
+        onClick={event => console.info("clicked mesh!")}
+      >
+        <T.TorusKnotGeometry args={[1, 0.5, 128, 32]} />
+        <T.MeshStandardMaterial metalness={1} roughness={0} color="white">
+          <Resource
+            loader={THREE.CubeTextureLoader}
+            attach="envMap"
+            path="https://rawcdn.githack.com/mrdoob/three.js/54ac263593c81b669ca9a089491ddd9e240427d2/examples/textures/cube/Bridge2/"
+            url={["posx.jpg", "negx.jpg", "posy.jpg", "negy.jpg", "posz.jpg", "negz.jpg"]}
+          />
+        </T.MeshStandardMaterial>
+      </T.Mesh>
+      <Entity
+        from={THREE.Mesh}
+        highlight="red"
+        position={new THREE.Vector3()}
+        plugins={[MaterialPlugin] as const}
+      />
+      {/* Camera with shake (from ShakePlugin) */}
+      <T.PerspectiveCamera ref={cameraRef!} position={[10, 10, 10]} shake={0.05} />
+
+      <T.DirectionalLight position={[5, 5, 5]} intensity={1} />
+      <T.AmbientLight intensity={0.5} />
+    </Canvas>
+  )
+}

playground/examples/PortalExample.tsx

@@ -1,7 +1,7 @@
 import * as THREE from "three"
-import { Canvas, createT, Entity, Portal } from "../../src/index.ts"
+import { createT, Entity, EventPlugin, Portal } from "../../src/index.ts"
 
-const T = createT(THREE)
+const { T, Canvas } = createT(THREE, [EventPlugin])
 
 export function PortalExample() {
   const group = new THREE.Group()