feat(xr)!: XR as a plugin — solid-three/xr (xrEvents + controller capture + createXR/useXR)

[bigmistqke]

Builds on the core event system — pointer capture + the object/currentObject API (#69) and the typed dispatch event (#72).

Summary

Externalizes XR into a solid-three/xr entry built on the plugin seam (#67) — XR is no longer baked into core:

• xrEvents() plugin + controller source — XR controllers become pointer sources through the same eventRegistry, dispatching onXRSelectStart/End + onXRSqueezeStart/End to the ray-hit mesh, enriched with { controller, inputSource, handedness }.
• Pointer capture for controllers — start events are capturable: a handler may setPointerCapture() to grab the hit object, and the paired end event delivers to it (the controller ray reprojected onto the drag plane) then releases — XR has no OS lostpointercapture, so the source releases itself. Captures register in the global captureRegistry, so reactive hasPointerCapture() works in XR too.
• Typed XR payload — XRControllerExtra is declared once and feeds both dispatch<XRControllerExtra>(…) and XRThreeEvent = ThreeEvent<XRInputSourceEvent> & XRControllerExtra (on refactor(events): type the dispatched event (drop the any bag) #72's typed dispatch), so the supplied payload and the handler type can't drift.
• EventRegistry — refcounted eventRegistry membership behind one module: register(object) → cleanup lists an object once however many handlers it bears, and an onVacated subscription fires on a genuine unmount (deferred past a same-tick reactive re-register). The DOM source and the XR plugin both register through it.
• createXR/useXR move into solid-three/xr (new package export + tsup entry).
• build: point ./testing types at the emitted dist/testing.d.ts.

Breaking change

createXR/useXR move from the core entry to solid-three/xr.

Test plan

• pnpm lint + pnpm build green; ./xr entry emits (dist/xr.*).
• Browser suite green — 223 passed, incl. XR dispatch to the ray-hit mesh, typed onXR* handlers, the capture test (off-ray select delivery + release), and the EventRegistry unit tests.

[pkg-pr-new]

• solid-three-demo

  npm i https://pkg.pr.new/solid-three@65
  

commit: 3b9d257

[bigmistqke]

Hooking up the XR plugin

Pass xrEvents() to the element namespace, drive the session with createXR, and your meshes receive the typed onXR* handlers:

import * as THREE from "three"
import { Show } from "solid-js"
import { Canvas, createT } from "solid-three"
import { createXR, xrEvents } from "solid-three/xr"

// Opt in once, at the namespace. T.* elements now accept the typed onXR* props.
const T = createT(THREE, [xrEvents()])

export default function App() {
  const xr = createXR()

  return (
    <>
      {/* DOM button, outside the Canvas — the click is the user gesture that enters the session. */}
      <button onClick={() => xr.enter("immersive-vr")}>Enter VR</button>
      <Show when={xr.isPresenting()}>
        <button onClick={() => xr.exit()}>Exit VR</button>
      </Show>

      <Canvas ref={xr.connect}>
        <T.Mesh
          position={[0, 1.5, -2]}
          onXRSelectStart={event => {
            // trigger pressed while a controller's ray is on this mesh
            console.log("select", event.handedness, event.intersection.point)
          }}
          onXRSelectEnd={() => console.log("select released")}
          onXRSqueezeStart={event => {
            event.intersection.object.scale.multiplyScalar(1.2) // grip squeezed
          }}
        >
          <T.BoxGeometry />
          <T.MeshStandardMaterial color="hotpink" />
        </T.Mesh>
        <T.AmbientLight intensity={0.5} />
      </Canvas>
    </>
  )
}

The handlers

onXRSelectStart, onXRSelectEnd, onXRSqueezeStart, onXRSqueezeEnd — each (event: XRThreeEvent) => void. They bubble up the hit chain and honor event.stopPropagation(), just like the pointer events.

Grabbing with capture

Inside onXRSelectStart / onXRSqueezeStart, call event.setPointerCapture() to grab the hit object for the gesture — the paired …End then delivers to that object even if the controller ray has drifted off it (reprojected onto a drag plane), and releases automatically:

<T.Mesh
  onXRSelectStart={e => e.setPointerCapture()}
  onXRSelectEnd={() => console.log("released")}
/>

Captures register globally, so reactive hasPointerCapture(mesh) reflects an XR grab too — handy for highlight-while-held visuals.

XRThreeEvent payload

field	type	what it is
controller	Object3D	the controller's targetRay space (its matrixWorld aimed the ray)
inputSource	XRInputSource | undefined	the source that fired the event
handedness	XRHandedness | undefined	"left" / "right" / "none"
object	Object3D	the closest hit (intersections[0].object); 3D analogue of a DOM target
currentObject	Object3D | undefined	the node the handler is firing on as the event bubbles; 3D analogue of currentTarget
intersection	Intersection	the ray hit — point, distance, face, …
…plus		the usual ThreeEvent fields: nativeEvent, stopPropagation(), intersections

Per-element opt-in

If you'd rather not opt in the whole namespace, pass the plugin to a single <Entity>:

import { Entity } from "solid-three"
import { xrEvents } from "solid-three/xr"

<Entity object={myMesh} plugins={[xrEvents()]} onXRSqueezeStart={event => { /* … */ }} />

Wiring is automatic and refcounted: the first onXR*-bearing element in a <Canvas> registers itself for raycasting and stands up the controller source once per context; everything tears down with the Canvas (and on sessionend).

[bigmistqke]

Splitting this into three reviewable, independently-green PRs that land as three squash-merged commits on next-cleanup:

1. Act 1 — source-agnostic pointer system → refactor(events)!: source-agnostic pointer system (Pointer + EventRaycaster + DOMPointerManager) #66 (open)
2. Act 2 — plugin system (follows once refactor(events)!: source-agnostic pointer system (Pointer + EventRaycaster + DOMPointerManager) #66 merges)
3. Act 3 — XR as a plugin — this PR, rebased to show only the XR slice once Acts 1+2 land.

Drafting until then.