@threlte/xr 1.5.4 → 1.6.0

package/dist/components/Controller.svelte

@@ -3,13 +3,10 @@
 -->
 <script lang="ts">
   import { T, useThrelte } from '@threlte/core'
-  import { controllers } from '../hooks/useController.svelte.js'
-  import {
-    isHandTracking,
-    pointerState,
-    teleportState,
-    controllerEvents
-  } from '../internal/state.svelte.js'
+  import { useController } from '../hooks/useController.svelte.js'
+  import { pointerState, teleportState } from '../internal/state.svelte.js'
+  import { addSubscriber } from '../internal/inputSources.svelte.js'
+  import { useXROrigin } from '../hooks/useXROrigin.svelte.js'
   import type { XRControllerEvents } from '../types.js'
   import PointerCursor from './internal/PointerCursor.svelte'
   import ShortRay from './internal/ShortRay.svelte'
@@ -71,63 +68,68 @@
   }: Props = $props()
 
   const { scene } = useThrelte()
-
-  const handedness = $derived<'left' | 'right'>(left ? 'left' : right ? 'right' : (hand ?? 'left'))
+  const xrOrigin = useXROrigin()
+  const attachTarget = $derived(xrOrigin.current ?? scene)
+  const handedness: 'left' | 'right' = left ? 'left' : right ? 'right' : (hand ?? 'left')
+  const controller = useController(handedness)
 
   $effect.pre(() => {
-    const key = handedness
-    controllerEvents[key] = {
-      onconnected,
-      ondisconnected,
-      onselect,
-      onselectend,
-      onselectstart,
-      onsqueeze,
-      onsqueezeend,
-      onsqueezestart
-    }
-
-    return () => {
-      controllerEvents[key] = undefined
-    }
+    return addSubscriber({
+      type: 'controller',
+      handedness,
+      callbacks: {
+        onconnected,
+        ondisconnected,
+        onselect,
+        onselectend,
+        onselectstart,
+        onsqueeze,
+        onsqueezeend,
+        onsqueezestart
+      }
+    })
   })
 
-  const xrController = $derived(controllers[handedness])
-  const grip = $derived(xrController?.grip)
-  const targetRay = $derived(xrController?.targetRay)
-  const model = $derived(xrController?.model)
-  const hasPointerControls = $derived(pointerState[handedness].enabled)
-  const hasTeleportControls = $derived(teleportState[handedness].enabled)
+  const grip = $derived($controller?.grip)
+  const targetRay = $derived($controller?.targetRay)
+  const model = $derived($controller?.model)
+  const hasPointerControls = $derived.by(() =>
+    handedness === 'left' ? pointerState.left.enabled : pointerState.right.enabled
+  )
+  const hasTeleportControls = $derived.by(() =>
+    handedness === 'left' ? teleportState.left.enabled : teleportState.right.enabled
+  )
 </script>
 
-{#if !isHandTracking.current}
-  {#if grip}
-    <T
-      is={grip}
-      attach={scene}
-    >
-      {#if children}
-        {@render children?.()}
-      {:else}
-        <T is={model} />
-      {/if}
-
-      {@render gripSnippet?.()}
-    </T>
-  {/if}
-
-  {#if targetRay}
-    <T is={targetRay}>
-      {@render targetRaySnippet?.()}
+{#if grip}
+  <T
+    is={grip}
+    attach={attachTarget}
+  >
+    {#if children}
+      {@render children?.()}
+    {:else}
+      <T is={model} />
+    {/if}
+
+    {@render gripSnippet?.()}
+  </T>
+{/if}
 
-      {#if hasPointerControls || hasTeleportControls}
-        <ShortRay
-          {handedness}
-          children={pointerRaySnippet}
-        />
-      {/if}
-    </T>
-  {/if}
+{#if targetRay}
+  <T
+    is={targetRay}
+    attach={attachTarget}
+  >
+    {@render targetRaySnippet?.()}
+
+    {#if hasPointerControls || hasTeleportControls}
+      <ShortRay
+        {handedness}
+        children={pointerRaySnippet}
+      />
+    {/if}
+  </T>
 {/if}
 
 {#if hasPointerControls}

package/dist/components/Hand.svelte

@@ -2,8 +2,9 @@
   import { Group } from 'three'
   import { T, useThrelte, useTask, useStage } from '@threlte/core'
   import type { XRHandEvents } from '../types.js'
-  import { isHandTracking, handEvents } from '../internal/state.svelte.js'
-  import { hands } from '../hooks/useHand.svelte.js'
+  import { addSubscriber } from '../internal/inputSources.svelte.js'
+  import { useHand } from '../hooks/useHand.svelte.js'
+  import { useXROrigin } from '../hooks/useXROrigin.svelte.js'
   import type { Snippet } from 'svelte'
 
   type Props = {
@@ -46,23 +47,23 @@
   }: Props = $props()
 
   const { scene, renderer, renderStage } = useThrelte()
-
-  const handedness = $derived<'left' | 'right'>(left ? 'left' : right ? 'right' : (hand ?? 'left'))
+  const xrOrigin = useXROrigin()
+  const attachTarget = $derived(xrOrigin.current ?? scene)
+  const handedness: 'left' | 'right' = left ? 'left' : right ? 'right' : (hand ?? 'left')
+  const handStore = useHand(handedness)
 
   $effect.pre(() => {
-    const key = handedness
-    handEvents[key] = {
-      onconnected,
-      ondisconnected,
-      onpinchend,
-      onpinchstart
-    }
-
-    return () => {
-      handEvents[key] = undefined
-    }
+    return addSubscriber({
+      type: 'hand',
+      handedness,
+      callbacks: { onconnected, ondisconnected, onpinchend, onpinchstart }
+    })
   })
 
+  const xrHand = $derived($handStore)
+  const inputSource = $derived(xrHand?.inputSource)
+  const model = $derived(xrHand?.model)
+
   const stage = useStage(Symbol('xr-hand-stage'), { before: renderStage })
 
   const group = new Group()
@@ -94,22 +95,15 @@
     },
     {
       stage,
-      running: () =>
-        isHandTracking.current &&
-        (wrist !== undefined || children !== undefined) &&
-        inputSource !== undefined
+      running: () => inputSource !== undefined && (wrist !== undefined || children !== undefined)
     }
   )
-
-  const xrHand = $derived(hands[handedness])
-  const inputSource = $derived(xrHand?.inputSource)
-  const model = $derived(xrHand?.model)
 </script>
 
-{#if xrHand?.hand && isHandTracking.current}
+{#if xrHand?.hand}
   <T
     is={xrHand.hand}
-    attach={scene}
+    attach={attachTarget}
   >
     {#if children === undefined}
       <T is={model} />
@@ -117,16 +111,17 @@
   </T>
 
   {#if targetRay !== undefined}
-    <T is={xrHand.targetRay}>
+    <T
+      is={xrHand.targetRay}
+      attach={attachTarget}
+    >
       {@render targetRay()}
     </T>
   {/if}
-{/if}
 
-{#if isHandTracking.current}
   <T
     is={group}
-    attach={scene}
+    attach={attachTarget}
   >
     {@render wrist?.()}
     {@render children?.()}

package/dist/components/XR.svelte

@@ -17,6 +17,17 @@ This should be placed within a Threlte `<Canvas />`.
 ```
 
 -->
+<script
+  module
+  lang="ts"
+>
+  declare global {
+    interface XRSystem {
+      offerSession?: XRSystem['requestSession']
+    }
+  }
+</script>
+
 <script lang="ts">
   import type { EventListener, WebXRManager, Event as ThreeEvent } from 'three'
   import type { XRHandModelFactory } from 'three/examples/jsm/webxr/XRHandModelFactory.js'
@@ -24,16 +35,30 @@ This should be placed within a Threlte `<Canvas />`.
   import { untrack, type Snippet } from 'svelte'
   import { useThrelte } from '@threlte/core'
   import {
-    isHandTracking,
     isPresenting,
+    lastSessionRequest,
+    pointerIntersection,
     referenceSpaceType,
     session,
+    teleportIntersection,
     xr
   } from '../internal/state.svelte.js'
   import { setupRaf } from '../internal/setupRaf.svelte.js'
   import { setupHeadset } from '../internal/setupHeadset.svelte.js'
-  import { setupControllers } from '../internal/setupControllers.js'
-  import { setupHands } from '../internal/setupHands.js'
+  import { setupInputSources } from '../internal/setupInputSources.js'
+  import { dispatchXRInputSourceEvent } from '../internal/inputSources.svelte.js'
+  import { defaultFeatures } from '../internal/defaultFeatures.js'
+  import { getXRSessionOptions } from '../lib/getXRSessionOptions.js'
+  import { toggleXRSession } from '../lib/toggleXRSession.js'
+
+  const INPUT_SOURCE_EVENTS = [
+    'select',
+    'selectstart',
+    'selectend',
+    'squeeze',
+    'squeezestart',
+    'squeezeend'
+  ] as const
 
   interface Props {
     /**
@@ -81,6 +106,23 @@ This should be placed within a Threlte `<Canvas />`.
 
     /** Called when the session frame rate changes. */
     onframeratechange?: (event: XRSessionEvent) => void
+
+    /**
+     * Auto-enter a session when the OS grants one without an explicit request
+     * (e.g. when the user puts on a headset). Pass `false` to disable, or an
+     * array of modes to restrict which modes are eligible.
+     * @default true
+     */
+    enterGrantedSession?: boolean | XRSessionMode[]
+
+    /**
+     * Pre-offer a session via `navigator.xr.offerSession` so the browser can
+     * show its own entry UI (e.g. Vision Pro). When `true`, offers AR if
+     * supported, otherwise VR. Pass a specific mode to restrict. Pass `false`
+     * to disable.
+     * @default true
+     */
+    offerSession?: boolean | XRSessionMode
   }
 
   let {
@@ -92,6 +134,8 @@ This should be placed within a Threlte `<Canvas />`.
     onvisibilitychange,
     oninputsourceschange,
     onframeratechange,
+    enterGrantedSession = true,
+    offerSession = true,
     fallback,
     children,
     handFactory,
@@ -102,25 +146,21 @@ This should be placed within a Threlte `<Canvas />`.
 
   setupRaf()
   setupHeadset()
-  setupControllers(controllerFactory)
-  setupHands(handFactory)
+  const bindInputSources = setupInputSources(controllerFactory, handFactory)
 
   const handleSessionStart: EventListener<object, 'sessionstart', WebXRManager> = (event) => {
     isPresenting.current = true
-    const currentSession = renderer.xr.getSession()
-    if (currentSession !== null) {
-      isHandTracking.current = Array.from(currentSession.inputSources).some(
-        (source) => source.hand !== undefined
-      )
-    }
     onsessionstart?.(event)
   }
 
   const handleSessionEnd = (event: XRSessionEvent) => {
     onsessionend?.(event)
     isPresenting.current = false
-    isHandTracking.current = false
     session.current = undefined
+    pointerIntersection.left = undefined
+    pointerIntersection.right = undefined
+    teleportIntersection.left = undefined
+    teleportIntersection.right = undefined
   }
 
   const handleVisibilityChange = (event: XRSessionEvent) => {
@@ -128,7 +168,6 @@ This should be placed within a Threlte `<Canvas />`.
   }
 
   const handleInputSourcesChange = (event: XRInputSourcesChangeEvent) => {
-    isHandTracking.current = Object.values(event.session.inputSources).some((source) => source.hand)
     oninputsourceschange?.(event)
   }
 
@@ -136,23 +175,37 @@ This should be placed within a Threlte `<Canvas />`.
     onframeratechange?.(event)
   }
 
+  const handleXRInputEvent = (event: XRInputSourceEvent) => {
+    dispatchXRInputSourceEvent(event)
+  }
+
   $effect(() => {
     const currentSession = session.current
 
     if (currentSession === undefined) {
+      bindInputSources(undefined)
       return
     }
 
+    bindInputSources(currentSession)
+
     currentSession.addEventListener('visibilitychange', handleVisibilityChange)
     currentSession.addEventListener('inputsourceschange', handleInputSourcesChange)
     currentSession.addEventListener('frameratechange', handleFramerateChange)
     currentSession.addEventListener('end', handleSessionEnd)
+    for (const type of INPUT_SOURCE_EVENTS) {
+      currentSession.addEventListener(type, handleXRInputEvent)
+    }
 
     return () => {
       currentSession.removeEventListener('visibilitychange', handleVisibilityChange)
       currentSession.removeEventListener('inputsourceschange', handleInputSourcesChange)
       currentSession.removeEventListener('frameratechange', handleFramerateChange)
       currentSession.removeEventListener('end', handleSessionEnd)
+      for (const type of INPUT_SOURCE_EVENTS) {
+        currentSession.removeEventListener(type, handleXRInputEvent)
+      }
+      bindInputSources(undefined)
     }
   })
 
@@ -170,8 +223,6 @@ This should be placed within a Threlte `<Canvas />`.
   })
 
   $effect.pre(() => {
-    const currentSession = session.current
-
     xr.current = renderer.xr
     renderer.xr.enabled = true
     renderer.xr.addEventListener('sessionstart', handleSessionStart)
@@ -182,7 +233,9 @@ This should be placed within a Threlte `<Canvas />`.
       renderer.xr.removeEventListener('sessionstart', handleSessionStart)
 
       // if unmounted while presenting (e.g. due to sveltekit navigation), end the session
-      currentSession?.end()
+      untrack(() => session.current)
+        ?.end()
+        .catch(() => {})
     }
   })
 
@@ -204,6 +257,83 @@ This should be placed within a Threlte `<Canvas />`.
     renderer.xr.setReferenceSpaceType(referenceSpace)
     referenceSpaceType.current = referenceSpace
   })
+
+  $effect.pre(() => {
+    if (enterGrantedSession === false) return
+
+    const allowed: XRSessionMode[] = Array.isArray(enterGrantedSession)
+      ? enterGrantedSession
+      : ['immersive-ar', 'immersive-vr']
+
+    const listener = async () => {
+      // Prefer to replay whatever mode + sessionInit the app entered with last.
+      if (lastSessionRequest.mode !== undefined && allowed.includes(lastSessionRequest.mode)) {
+        toggleXRSession(lastSessionRequest.mode, lastSessionRequest.sessionInit, 'enter').catch(
+          () => {}
+        )
+        return
+      }
+
+      for (const mode of allowed) {
+        if (await navigator.xr?.isSessionSupported(mode).catch(() => false)) {
+          toggleXRSession(mode, { ...defaultFeatures }, 'enter').catch(() => {})
+          return
+        }
+      }
+    }
+
+    navigator.xr?.addEventListener('sessiongranted', listener)
+    return () => {
+      navigator.xr?.removeEventListener('sessiongranted', listener)
+    }
+  })
+
+  $effect.pre(() => {
+    if (navigator.xr === undefined) return
+    if (offerSession === false) return
+    if (!('offerSession' in navigator.xr)) return
+    if (session.current !== undefined) return
+    const manager = xr.current
+    if (manager === undefined) return
+
+    let cancelled = false
+
+    const run = async () => {
+      let mode: XRSessionMode
+      if (offerSession === true) {
+        const arSupported = await navigator.xr
+          ?.isSessionSupported('immersive-ar')
+          .catch(() => false)
+        mode = arSupported ? 'immersive-ar' : 'immersive-vr'
+      } else {
+        mode = offerSession
+      }
+
+      const init = getXRSessionOptions(
+        referenceSpaceType.current,
+        lastSessionRequest.sessionInit,
+        defaultFeatures
+      )
+
+      try {
+        const nextSession = await navigator.xr?.offerSession?.(mode, init)
+        if (!nextSession || cancelled) return
+        await manager.setSession(nextSession)
+        if (cancelled) return
+        lastSessionRequest.mode = mode
+        lastSessionRequest.sessionInit = init
+        session.current = nextSession
+      } catch {
+        // user declined or offer was rejected
+      }
+    }
+
+    run()
+
+    return () => {
+      cancelled = true
+    }
+  })
 </script>
 
 {#if isPresenting.current}

package/dist/components/XR.svelte.d.ts

@@ -1,3 +1,8 @@
+declare global {
+    interface XRSystem {
+        offerSession?: XRSystem['requestSession'];
+    }
+}
 import type { WebXRManager, Event as ThreeEvent } from 'three';
 import type { XRHandModelFactory } from 'three/examples/jsm/webxr/XRHandModelFactory.js';
 import type { XRControllerModelFactory } from 'three/examples/jsm/webxr/XRControllerModelFactory.js';
@@ -38,6 +43,21 @@ interface Props {
     oninputsourceschange?: (event: XRSessionEvent) => void;
     /** Called when the session frame rate changes. */
     onframeratechange?: (event: XRSessionEvent) => void;
+    /**
+     * Auto-enter a session when the OS grants one without an explicit request
+     * (e.g. when the user puts on a headset). Pass `false` to disable, or an
+     * array of modes to restrict which modes are eligible.
+     * @default true
+     */
+    enterGrantedSession?: boolean | XRSessionMode[];
+    /**
+     * Pre-offer a session via `navigator.xr.offerSession` so the browser can
+     * show its own entry UI (e.g. Vision Pro). When `true`, offers AR if
+     * supported, otherwise VR. Pass a specific mode to restrict. Pass `false`
+     * to disable.
+     * @default true
+     */
+    offerSession?: boolean | XRSessionMode;
 }
 /**
  * `<XR />` is a WebXR manager that configures your scene for XR rendering and interaction.

package/dist/components/XROrigin.svelte

@@ -0,0 +1,82 @@
+<!--
+@component `<XROrigin />` represents the position of the XR user's feet. The XR
+camera (headset) is parented to this group, and any `<Controller>` / `<Hand>`
+components nested inside attach here instead of the scene root. Transforming
+the origin (position, rotation, scale) transforms the user in the scene —
+useful for teleportation, dolly rigs, and resizing the user.
+
+Only one `<XROrigin>` may be mounted within a given `<XR>`.
+
+```svelte
+<XROrigin position={[0, 0, 5]} rotation.y={Math.PI}>
+  <Controller left />
+  <Controller right />
+  <Hand left />
+  <Hand right />
+</XROrigin>
+```
+
+Without an `<XROrigin>`, controllers and hands continue to attach to the
+scene root (existing behaviour, unchanged).
+-->
+<script lang="ts">
+  import { Group } from 'three'
+  import { T, useThrelte, type Props } from '@threlte/core'
+  import type { Snippet } from 'svelte'
+  import { useXROrigin } from '../hooks/useXROrigin.svelte.js'
+  import { isPresenting } from '../internal/state.svelte.js'
+
+  interface XROriginProps extends Props<Group> {
+    ref?: Group
+    children?: Snippet<[{ ref: Group }]>
+  }
+
+  let { ref = $bindable(), children, ...rest }: XROriginProps = $props()
+
+  const { camera, scene } = useThrelte()
+
+  const group = new Group()
+  const origin = useXROrigin()
+
+  $effect.pre(() => {
+    if (origin.current !== undefined && origin.current !== group) {
+      console.warn(
+        'Only one <XROrigin> may be mounted within a single <XR>. The newer instance will take over.'
+      )
+    }
+
+    origin.current = group
+    return () => {
+      if (origin.current === group) {
+        origin.current = undefined
+      }
+    }
+  })
+
+  // Parent the active scene camera to this group so its `parent.matrixWorld`
+  // reflects our transform. Three's `WebXRManager` reads `camera.parent` (where
+  // `camera` is the camera passed to `renderer.render(scene, camera)`) — NOT
+  // `renderer.xr.getCamera().parent` — when composing the XR view matrices, so
+  // reparenting the XR camera itself has no effect. When this component
+  // unmounts (or the active camera changes) the camera returns to its previous
+  // parent so non-XR rendering keeps working.
+  $effect.pre(() => {
+    if (!isPresenting.current) return
+
+    const userCamera = $camera
+    const previousParent = userCamera.parent ?? scene
+    group.add(userCamera)
+
+    return () => {
+      previousParent.add(userCamera)
+    }
+  })
+</script>
+
+<T
+  is={group}
+  bind:ref
+  {...rest}
+>
+  {@render children?.({ ref: group })}
+</T>

package/dist/components/XROrigin.svelte.d.ts

@@ -0,0 +1,33 @@
+import { Group } from 'three';
+import { type Props } from '@threlte/core';
+import type { Snippet } from 'svelte';
+interface XROriginProps extends Props<Group> {
+    ref?: Group;
+    children?: Snippet<[{
+        ref: Group;
+    }]>;
+}
+/**
+ * `<XROrigin />` represents the position of the XR user's feet. The XR
+ * camera (headset) is parented to this group, and any `<Controller>` / `<Hand>`
+ * components nested inside attach here instead of the scene root. Transforming
+ * the origin (position, rotation, scale) transforms the user in the scene —
+ * useful for teleportation, dolly rigs, and resizing the user.
+ *
+ * Only one `<XROrigin>` may be mounted within a given `<XR>`.
+ *
+ * ```svelte
+ * <XROrigin position={[0, 0, 5]} rotation.y={Math.PI}>
+ * <Controller left />
+ * <Controller right />
+ * <Hand left />
+ * <Hand right />
+ * </XROrigin>
+ * ```
+ *
+ * Without an `<XROrigin>`, controllers and hands continue to attach to the
+ * scene root (existing behaviour, unchanged).
+ */
+declare const XrOrigin: import("svelte").Component<XROriginProps, {}, "ref">;
+type XrOrigin = ReturnType<typeof XrOrigin>;
+export default XrOrigin;

package/dist/components/internal/Cursor.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-  import { Color, DoubleSide, RawShaderMaterial, type ColorRepresentation } from 'three'
+  import { Color, DoubleSide, ShaderMaterial, type ColorRepresentation } from 'three'
   import { T } from '@threlte/core'
 
   interface Props {
@@ -11,10 +11,6 @@
   const { color = new Color('white'), size = 0.03, thickness = 0.035 }: Props = $props()
 
   const vertexShader = `
-    uniform mat4 projectionMatrix;
-    uniform mat4 modelViewMatrix;
-    attribute vec2 uv;
-    attribute vec3 position;
     varying vec2 vUv;
     void main() {
       vUv = uv;
@@ -23,14 +19,13 @@
   `
 
   const fragmentShader = `
-    precision mediump float;
     uniform float thickness;
     uniform vec3 color;
     varying vec2 vUv;
     void main() {
-      float radius = 0.1;
-      float dist = length(vUv - vec2(0.5));
-      float alpha = 1.0 - step(thickness, abs(distance(vUv, vec2(0.5)) - 0.25));
+      float d = abs(distance(vUv, vec2(0.5)) - 0.25);
+      float edge = fwidth(d);
+      float alpha = 1.0 - smoothstep(thickness - edge, thickness + edge, d);
       gl_FragColor = vec4(color, alpha);
     }
   `
@@ -40,7 +35,7 @@
     color: { value: color }
   }
 
-  const shaderMaterial = new RawShaderMaterial({
+  const shaderMaterial = new ShaderMaterial({
     vertexShader,
     fragmentShader,
     uniforms,