@realitycollective/threejs-interactions 0.1.0-preview.3 → 0.1.0-preview.5

package/CHANGELOG.md

@@ -8,6 +8,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ### Added
 
+- `verify:pack` now lints the shape of what ships: publint over every package directory, with warnings counted as errors, and attw (Are The Types Wrong) over every packed tarball, resolving the published types under node10, node16 and bundler resolution. `cjs-resolves-to-esm` is ignored by design, because every package is ESM-only and a require() caller is expected to use a dynamic import. Both run offline on the tarballs the script already builds; `publint` and `@arethetypeswrong/cli` are dev dependencies. The script stays identical across the Reality Collective repositories.
 - `@realitycollective/webxr-interactions` - engine-free core: interactables and interactors, the behaviour set (`press` including latching, `pulse`, `hinge`, `dial`, `slide`, `grab` in poseOnly and native modes, `tossScore`), gaze (`required` gating and dwell-to-press), the runtime/binder with hints > poke > ray targeting, hysteresis and lifecycle, capability negotiation with a visible `behaviourDisabled` outcome, events as the only outbound pathway, and feedback intents (haptics and audio remain the client's, with `routeHapticsToProvider` as an explicit opt-in).
 - `@realitycollective/threejs-interactions` - the default standalone adapter: raw WebXR (`XRSession` sources, hand joints, select/squeeze plus gamepad analog, haptic pulse), three.js hit-testing and transform ports, and a desktop mouse fallback. No framework required.
 - `@realitycollective/iwsdk-interactions` - Meta IWSDK adapter: player-rig poses and stateful gamepads as the provider, IWSDK's own targeting (`Pressed` / `Grabbed` tags) forwarded as pre-resolved hints, and native grab fulfilment when the app enables IWSDK grabbing/physics. One-call `registerInteractions(world)` setup.
@@ -22,6 +23,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ### Changed
 
+- `@types/three` is pinned to `0.181.0` across the workspace (root `overrides`), the typings for the super-three 0.181 the workspace runs. `@iwsdk/core` carries its own `@types/three` dependency, and without the pin the tree held two copies, whose structurally identical classes are mutually unassignable in TypeScript. One copy, matching the runtime, is the rule in every Reality Collective repository that hosts IWSDK.
 - Every provider reports presence through `capabilities.presence`, the required key `@realitycollective/webxr-input` 0.1.1 adds to `InputCapabilities`. The class-level `supportsPresence` field the four adapters carried while that key was unpublished is gone. This fixes a client-visible defect on the IWSDK adapter, which built its capabilities without a `presence` key at all: an app that read `capabilities.presence` saw false and hid a feature that worked. The value each provider reports is the one its own field computed - always true on IWSDK, true once Babylon has built a visual to hide, true on three.js once a model is registered, and always false on XR Blocks.
 - `@realitycollective/threejs-interactions` - `registerVisual` and the new `unregisterVisual` now re-derive capabilities and notify `onCapabilitiesChanged`. Presence on this adapter is genuinely conditional: your app builds its own hand and controller models, so `capabilities.presence` is false until you hand the first one over and false again once you take the last one back.
 - The Input 0.1.1 types replace the local stand-ins that were waiting on them. `InputSourceSnapshot` now carries `linearVelocity` and `angularVelocity` itself, so the `InputSourceSnapshotWithVelocity` alias is gone; the local `poseVelocity` is gone in favour of the shipped `velocityBetween`; and the per-adapter `PresenceTarget` and `PresenceModality` declarations are gone. `PresenceModality` now comes from the contracts, and a presence target is written as the contract writes it, `Handedness | "all"`. All three names were re-exported from these packages and are removed from that surface.
@@ -33,11 +35,21 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 - `@realitycollective/iwsdk-interactions` targets **IWSDK 0.5.x**. Its peer range is now `>=0.5.0 <0.6.0` and it is developed and tested against `@iwsdk/core` 0.5.3. The adapter is source-compatible with 0.4.x and needed no code change, but 0.5 is the only line exercised, so it is the only line supported. Every symbol and runtime member the provider uses is present in both, and it already reads `world.input.xr.gamepads` rather than the accessor 0.5 deprecates.
 - `demos/playground` no longer compiles UIKitML at build time. `@iwsdk/vite-plugin-uikitml` was discontinued at 0.4.2 and only ever did `JSON.stringify(parse(source))`, so the panel is served as `.uikitml` from `public/ui/` and parsed on load. The demo drops that plugin, and its station markup uses `rgba()` rather than `background-opacity`, which the 0.5 parser removed.
+- `@realitycollective/iwsdk-interactions` - the approximate hit tester the bridge keeps for gaze and poke targeting resolves each registered entity's world position once per frame instead of on every query. The core asks it five questions a frame (a poke and a ray test per side, plus the gaze ray) and each one walked every entity's parent chain again through `getWorldPosition`; the bridge now calls `beginFrame()` before the runtime ticks and the five answers come from one resolution. Measured 3.6x to 4x faster on the tester in the gate-1 benchmarks, 32 us to 9 us a frame at 50 entities on desktop, with the same answers. Its ray test also no longer allocates a tuple per entity per query.
+- `@realitycollective/threejs-interactions` - `ThreeHitTester` uses three-mesh-bvh when the app has installed its prototype hooks, which IWSDK does by default: geometries are given a bounds tree as they are registered and the raycaster asks for the first hit only, so a ray against a detailed mesh costs microseconds instead of the near-millisecond a plain triangle walk takes. `three-mesh-bvh` is declared as an optional peer; without it the plain raycast is used and the README explains collider proxies. The roots list handed to the raycaster and the intersections array are now reused between calls rather than built per call, and `hitProximity` reads each object's position and scale straight off its world matrix after one matrix update instead of two updates and a decompose, measured 4x faster at 50 registered objects.
+- `@realitycollective/webxr-interactions` - `onSample`, `getSource` and the pointer bridge document the snapshot ownership rule `@realitycollective/webxr-input` 0.1.3 states: a snapshot handed over is the receiver's to keep and is never written to again. The velocity tracker and the pointer bridge already relied on it.
 
 ### Deprecated
 
 - `@realitycollective/webxr-interactions` - `InteractionRuntime.onSourcesSampled` is deprecated in favour of `onSample`. They are the same stream, and since `InputSourceSnapshot` carries the velocity fields itself the two signatures are now identical, so only one name is needed. Nothing is removed: existing callers keep working and the method will go in a later major release.
 
+### Fixed
+
+- `@realitycollective/iwsdk-interactions` imported three.js's `Vector3`, `Quaternion` and `Matrix4`, and IWSDK's `InputComponent`, through `@iwsdk/core`, which only provides them by `export * from 'three'` and `export * from '@iwsdk/xr-input'`. That resolves in node and in every demo, and fails a consumer whose Vite config excludes `three` from dependency optimization, which any app that transforms three's source does: esbuild cannot enumerate a star re-export it is not bundling, and the dev server stops with `No matching export in "@iwsdk/core" for import "Vector3"`, a message that names neither the package nor the cause. The provider, the transform port and `registerInteractions` now import from `three` and `@iwsdk/xr-input`, both declared as peer dependencies (`three >=0.170.0`, the range the three.js adapter carries; `@iwsdk/xr-input >=0.5.0 <0.6.0`, the range of `@iwsdk/core`, which installs it). The Anatomy Atlas XR client reported the failure against the UI Extensions adapter; the estate sweep found the same import here.
+- `@realitycollective/xrblocks-interactions` imported `InteractionRuntime` from `@realitycollective/threejs-interactions`, which only re-exports it from `@realitycollective/webxr-interactions`. It now imports from the package that defines it, which it already depended on. Found by the new import-surface gate.
+- Two gates, shared with every Reality Collective repository. `packages/webxr-interactions/test/import-surface.test.ts` runs `scripts/import-surface.mjs` over every published package and fails an import of a name that a dependency only re-exports from another package, and any bare import of a package the manifest does not declare. `packages/iwsdk-interactions/test/prebundle.test.ts` runs the dependency optimizer of every bundler `scripts/release.config.json` names (`scripts/prebundle-check.mjs`) over the adapter next to `@iwsdk/core`, once with defaults and once with every package `@iwsdk/core` re-exports wholesale excluded, so the consumer path is exercised on every `npm test`. It runs on **Vite 7 and Vite 8**, because this fault belongs to a bundler rather than to bundling: Vite 7 optimizes with esbuild, which requires every named import to be statically enumerable and so rejects a name behind an external `export *`, while Vite 8 optimizes with rolldown, which resolves the same import lazily through a namespace object and accepts it. Testing only one of them would say nothing about consumers on the other. The versions under test are ordinary devDependencies installed under npm aliases, `vite-7` and `vite-8`, the same mechanism the workspace already uses for `three`; add an entry to `prebundle.bundlers` to support another. Each run also feeds the optimizer a **deliberately broken copy** of the adapter, carrying one extra module that imports a name the host only re-exports wholesale, and asserts the bundler's verdict matches that bundler's `detectsStarHops` flag. The probed name is discovered from the host's own surface rather than hard-coded, so it stays valid as that surface changes. This is what stops the check becoming decoration: on a permissive bundler a gate that can only pass reports safety it never verified, and the suite now fails if a bundler's strictness moves in either direction, or if no supported bundler can detect the fault at all. Transpiling uses the TypeScript compiler the repository already builds with, so no bundler is a hidden requirement of the harness itself. Both were red before this fix.
+- `@realitycollective/threejs-interactions` - `ThreeHitTester.hitProximity` reported the object's world scale as the hit `point`. The bounding-radius lookup reused the scratch vector holding the world position, so a box at (2, 1, -3) came back with `point: [1, 1, 1]`. The core only reads the id, so targeting was unaffected; anything reading `point` from a proximity hit on three.js or XR Blocks got the wrong answer.
+
 ### Notes
 
 - All five packages depend on `@realitycollective/webxr-input`, released independently from the [WebXR-Input](https://github.com/realitycollective/WebXR-Input) repository. That package must be published before this one.

package/README.md

@@ -13,7 +13,7 @@ It re-exports everything from [`@realitycollective/webxr-interactions`](https://
 | Layer | Detail |
 | --- | --- |
 | **Input** | Raw WebXR, the browser's own XR API: controllers, hand joints, trigger and grip pressure, and haptic pulses |
-| **Hit-testing** | three.js raycasting against your scene graph |
+| **Hit-testing** | three.js raycasting against your scene graph, through three-mesh-bvh when your app installs it |
 | **Movement** | Moves and rotates three.js objects for grab, hinge, dial and slide |
 | **Desktop** | A mouse fallback, so the same scene is testable without a headset |
 | **Presence** | Show and hide the user's own hand and controller models, once you have registered them |
@@ -53,10 +53,33 @@ renderer.setAnimationLoop(() => {
 });
 ```
 
-## Peer dependency
+## Hit-testing detailed meshes
+
+three.js tests every triangle of a mesh once a ray enters its bounding sphere, so a detailed model registered as an interactable costs the raycast close to a millisecond per ray on a desktop, and the runtime casts up to three rays a frame (one per controller, one for gaze). Two ways round it, and they combine.
+
+**Install three-mesh-bvh.** The adapter declares it as an optional peer. Install it and add its prototype hooks once at startup; the hit tester then builds a bounds tree for every geometry it registers and asks the raycaster for the first hit only, so the same ray costs microseconds. IWSDK installs these hooks itself, so an IWSDK app has nothing to do.
+
+```ts
+import { BufferGeometry, Mesh } from "three";
+import { acceleratedRaycast, computeBoundsTree, disposeBoundsTree } from "three-mesh-bvh";
+
+BufferGeometry.prototype.computeBoundsTree = computeBoundsTree;
+BufferGeometry.prototype.disposeBoundsTree = disposeBoundsTree;
+Mesh.prototype.raycast = acceleratedRaycast;
+```
+
+The tree lives on the geometry for as long as the geometry does. The adapter never removes it, so a geometry shared between interactables is built once, and a geometry you discard takes its tree with it.
+
+**Register a collider proxy.** Register a low-poly stand-in (a box, a sphere, a simplified hull) as the interactable object, and parent the detailed model to it or move both from the same transform. The proxy is what the ray and the poke test see; the model is what the player sees.
+
+Poke targeting (`hitProximity`) is a sphere test on each registered object's world position and bounding-sphere radius, so it costs the same whatever the mesh.
+
+## Peer dependencies
 
 `three >= 0.170.0`. The Reality Collective demos pin the `super-three@0.181` fork that Meta's IWSDK mandates; stock three.js works equally well for this adapter.
 
+`three-mesh-bvh >= 0.9.14`, optional. See the section above.
+
 ## Live demo
 
 The interaction playground - the full station set, mouse-capable on desktop, VR button for headsets: **[webxr-interactions.pages.dev](https://webxr-interactions.pages.dev)**

package/dist/hit-tester.d.ts

@@ -3,6 +3,18 @@
  * three.js objects. Ray hits use a Raycaster over the registered roots
  * (recursive); proximity uses world-position distance minus an
  * approximate bounding radius, good enough for poke targets.
+ *
+ * Detailed meshes are the cost to watch. three.js tests every triangle of
+ * a mesh once a ray enters its bounding sphere, so a 20k-triangle
+ * interactable costs close to a millisecond per ray. When the app has
+ * installed three-mesh-bvh's prototype hooks -
+ * `BufferGeometry.prototype.computeBoundsTree` and
+ * `Mesh.prototype.raycast = acceleratedRaycast`, which IWSDK does for you -
+ * the tester builds a bounds tree for every geometry it registers and asks
+ * the raycaster for the first hit only, so the same ray costs microseconds.
+ * Without the hooks it falls back to the plain raycast, and a detailed
+ * interactable should be registered through a low-poly collider proxy
+ * instead (see the README).
  */
 import { type Object3D } from "three";
 import type { RayTuple, Vec3Tuple } from "@realitycollective/webxr-input";
@@ -10,15 +22,17 @@ import type { HitTester, InteractableHit } from "@realitycollective/webxr-intera
 export declare class ThreeHitTester implements HitTester {
     private readonly roots;
     private readonly byObject;
+    /** `roots` as the array the raycaster takes, rebuilt only when the set changes. */
+    private rootList;
     private readonly raycaster;
-    private readonly v;
-    private readonly w;
-    private readonly sphere;
+    /** Reused between calls; three.js appends into it and sorts it. */
+    private readonly intersections;
+    constructor();
     register(id: string, object: Object3D): void;
     unregister(id: string): void;
     getObject(id: string): Object3D | undefined;
     hitRay(ray: RayTuple): InteractableHit | null;
     hitProximity(point: Vec3Tuple, radius: number): InteractableHit | null;
+    private objects;
     private ownerOf;
-    private boundingRadius;
 }

package/dist/hit-tester.js

@@ -3,24 +3,55 @@
  * three.js objects. Ray hits use a Raycaster over the registered roots
  * (recursive); proximity uses world-position distance minus an
  * approximate bounding radius, good enough for poke targets.
+ *
+ * Detailed meshes are the cost to watch. three.js tests every triangle of
+ * a mesh once a ray enters its bounding sphere, so a 20k-triangle
+ * interactable costs close to a millisecond per ray. When the app has
+ * installed three-mesh-bvh's prototype hooks -
+ * `BufferGeometry.prototype.computeBoundsTree` and
+ * `Mesh.prototype.raycast = acceleratedRaycast`, which IWSDK does for you -
+ * the tester builds a bounds tree for every geometry it registers and asks
+ * the raycaster for the first hit only, so the same ray costs microseconds.
+ * Without the hooks it falls back to the plain raycast, and a detailed
+ * interactable should be registered through a low-poly collider proxy
+ * instead (see the README).
  */
-import { Raycaster, Sphere, Vector3 } from "three";
+import { Raycaster } from "three";
 export class ThreeHitTester {
     roots = new Map();
     byObject = new WeakMap();
+    /** `roots` as the array the raycaster takes, rebuilt only when the set changes. */
+    rootList = null;
     raycaster = new Raycaster();
-    v = new Vector3();
-    w = new Vector3();
-    sphere = new Sphere();
+    /** Reused between calls; three.js appends into it and sorts it. */
+    intersections = [];
+    constructor() {
+        // Read by three-mesh-bvh's accelerated raycast, ignored by the stock one.
+        this.raycaster.firstHitOnly = true;
+    }
     register(id, object) {
+        this.unregister(id);
+        object.traverse((child) => {
+            const geometry = child.geometry;
+            // `disposeBoundsTree` leaves null behind, a never-built geometry has
+            // undefined: both mean there is no tree to use.
+            if (geometry &&
+                typeof geometry.computeBoundsTree === "function" &&
+                (geometry.boundsTree === undefined || geometry.boundsTree === null)) {
+                geometry.computeBoundsTree();
+            }
+        });
         this.roots.set(id, object);
         this.byObject.set(object, id);
+        this.rootList = null;
     }
     unregister(id) {
         const object = this.roots.get(id);
-        if (object)
-            this.byObject.delete(object);
+        if (!object)
+            return;
+        this.byObject.delete(object);
         this.roots.delete(id);
+        this.rootList = null;
     }
     getObject(id) {
         return this.roots.get(id);
@@ -28,10 +59,11 @@ export class ThreeHitTester {
     hitRay(ray) {
         if (this.roots.size === 0)
             return null;
-        this.raycaster.ray.origin.set(...ray.origin);
-        this.raycaster.ray.direction.set(...ray.direction);
-        const objects = [...this.roots.values()];
-        const intersections = this.raycaster.intersectObjects(objects, true);
+        this.raycaster.ray.origin.set(ray.origin[0], ray.origin[1], ray.origin[2]);
+        this.raycaster.ray.direction.set(ray.direction[0], ray.direction[1], ray.direction[2]);
+        const intersections = this.intersections;
+        intersections.length = 0;
+        this.raycaster.intersectObjects(this.objects(), true, intersections);
         for (const intersection of intersections) {
             const id = this.ownerOf(intersection.object);
             if (id !== null) {
@@ -45,21 +77,26 @@ export class ThreeHitTester {
         return null;
     }
     hitProximity(point, radius) {
-        this.v.set(...point);
         let best = null;
         for (const [id, object] of this.roots) {
-            object.getWorldPosition(this.w);
-            const surfaceDistance = Math.max(0, this.w.distanceTo(this.v) - this.boundingRadius(object));
+            // One matrix update per object, then position and scale straight off
+            // the world matrix: the last column is the translation and the length
+            // of each of the first three columns is that axis's scale.
+            object.updateWorldMatrix(true, false);
+            const e = object.matrixWorld.elements;
+            const scale = Math.max(Math.hypot(e[0], e[1], e[2]), Math.hypot(e[4], e[5], e[6]), Math.hypot(e[8], e[9], e[10]));
+            const surfaceDistance = Math.max(0, Math.hypot(e[12] - point[0], e[13] - point[1], e[14] - point[2]) - radiusOf(object) * scale);
             if (surfaceDistance <= radius && (best === null || surfaceDistance < best.distance)) {
-                best = {
-                    interactableId: id,
-                    distance: surfaceDistance,
-                    point: [this.w.x, this.w.y, this.w.z],
-                };
+                best = { interactableId: id, distance: surfaceDistance, point: [e[12], e[13], e[14]] };
             }
         }
         return best;
     }
+    objects() {
+        if (this.rootList === null)
+            this.rootList = [...this.roots.values()];
+        return this.rootList;
+    }
     ownerOf(object) {
         let current = object;
         while (current) {
@@ -70,18 +107,14 @@ export class ThreeHitTester {
         }
         return null;
     }
-    boundingRadius(object) {
-        const geometry = object.geometry;
-        if (geometry) {
-            if (!geometry.boundingSphere)
-                geometry.computeBoundingSphere();
-            if (geometry.boundingSphere) {
-                this.sphere.copy(geometry.boundingSphere);
-                const scale = object.getWorldScale(this.w);
-                return this.sphere.radius * Math.max(scale.x, scale.y, scale.z);
-            }
-        }
+}
+/** Bounding-sphere radius of the object's own geometry in local units, or 0 for a plain group. */
+function radiusOf(object) {
+    const geometry = object.geometry;
+    if (!geometry)
         return 0;
-    }
+    if (!geometry.boundingSphere)
+        geometry.computeBoundingSphere();
+    return geometry.boundingSphere?.radius ?? 0;
 }
 //# sourceMappingURL=hit-tester.js.map

package/dist/hit-tester.js.map

@@ -1 +1 @@
-{"version":3,"file":"hit-tester.js","sourceRoot":"","sources":["../src/hit-tester.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAA4B,MAAM,OAAO,CAAC;AAI7E,MAAM,OAAO,cAAc;IACR,KAAK,GAAG,IAAI,GAAG,EAAoB,CAAC;IACpC,QAAQ,GAAG,IAAI,OAAO,EAAoB,CAAC;IAC3C,SAAS,GAAG,IAAI,SAAS,EAAE,CAAC;IAC5B,CAAC,GAAG,IAAI,OAAO,EAAE,CAAC;IAClB,CAAC,GAAG,IAAI,OAAO,EAAE,CAAC;IAClB,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;IAEvC,QAAQ,CAAC,EAAU,EAAE,MAAgB;QACnC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QAC3B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAChC,CAAC;IAED,UAAU,CAAC,EAAU;QACnB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClC,IAAI,MAAM;YAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC;IAED,SAAS,CAAC,EAAU;QAClB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED,MAAM,CAAC,GAAa;QAClB,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACvC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;QAC7C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC;QACnD,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QACzC,MAAM,aAAa,GAAG,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACrE,KAAK,MAAM,YAAY,IAAI,aAAa,EAAE,CAAC;YACzC,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;YAC7C,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;gBAChB,OAAO;oBACL,cAAc,EAAE,EAAE;oBAClB,QAAQ,EAAE,YAAY,CAAC,QAAQ;oBAC/B,KAAK,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;iBAC1E,CAAC;YACJ,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,YAAY,CAAC,KAAgB,EAAE,MAAc;QAC3C,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;QACrB,IAAI,IAAI,GAA2B,IAAI,CAAC;QACxC,KAAK,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACtC,MAAM,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAChC,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,CAC9B,CAAC,EACD,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CACxD,CAAC;YACF,IAAI,eAAe,IAAI,MAAM,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,eAAe,GAAG,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACpF,IAAI,GAAG;oBACL,cAAc,EAAE,EAAE;oBAClB,QAAQ,EAAE,eAAe;oBACzB,KAAK,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;iBACtC,CAAC;YACJ,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,OAAO,CAAC,MAAgB;QAC9B,IAAI,OAAO,GAAoB,MAAM,CAAC;QACtC,OAAO,OAAO,EAAE,CAAC;YACf,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACtC,IAAI,EAAE,KAAK,SAAS;gBAAE,OAAO,EAAE,CAAC;YAChC,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;QAC3B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,cAAc,CAAC,MAAgB;QACrC,MAAM,QAAQ,GAAI,MAAe,CAAC,QAAQ,CAAC;QAC3C,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,CAAC,QAAQ,CAAC,cAAc;gBAAE,QAAQ,CAAC,qBAAqB,EAAE,CAAC;YAC/D,IAAI,QAAQ,CAAC,cAAc,EAAE,CAAC;gBAC5B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;gBAC1C,MAAM,KAAK,GAAG,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBAC3C,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;YAClE,CAAC;QACH,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC;CACF","sourcesContent":["/**\n * ThreeHitTester - resolves core ray/proximity queries against registered\n * three.js objects. Ray hits use a Raycaster over the registered roots\n * (recursive); proximity uses world-position distance minus an\n * approximate bounding radius, good enough for poke targets.\n */\nimport { Raycaster, Sphere, Vector3, type Object3D, type Mesh } from \"three\";\nimport type { RayTuple, Vec3Tuple } from \"@realitycollective/webxr-input\";\nimport type { HitTester, InteractableHit } from \"@realitycollective/webxr-interactions\";\n\nexport class ThreeHitTester implements HitTester {\n  private readonly roots = new Map<string, Object3D>();\n  private readonly byObject = new WeakMap<Object3D, string>();\n  private readonly raycaster = new Raycaster();\n  private readonly v = new Vector3();\n  private readonly w = new Vector3();\n  private readonly sphere = new Sphere();\n\n  register(id: string, object: Object3D): void {\n    this.roots.set(id, object);\n    this.byObject.set(object, id);\n  }\n\n  unregister(id: string): void {\n    const object = this.roots.get(id);\n    if (object) this.byObject.delete(object);\n    this.roots.delete(id);\n  }\n\n  getObject(id: string): Object3D | undefined {\n    return this.roots.get(id);\n  }\n\n  hitRay(ray: RayTuple): InteractableHit | null {\n    if (this.roots.size === 0) return null;\n    this.raycaster.ray.origin.set(...ray.origin);\n    this.raycaster.ray.direction.set(...ray.direction);\n    const objects = [...this.roots.values()];\n    const intersections = this.raycaster.intersectObjects(objects, true);\n    for (const intersection of intersections) {\n      const id = this.ownerOf(intersection.object);\n      if (id !== null) {\n        return {\n          interactableId: id,\n          distance: intersection.distance,\n          point: [intersection.point.x, intersection.point.y, intersection.point.z],\n        };\n      }\n    }\n    return null;\n  }\n\n  hitProximity(point: Vec3Tuple, radius: number): InteractableHit | null {\n    this.v.set(...point);\n    let best: InteractableHit | null = null;\n    for (const [id, object] of this.roots) {\n      object.getWorldPosition(this.w);\n      const surfaceDistance = Math.max(\n        0,\n        this.w.distanceTo(this.v) - this.boundingRadius(object),\n      );\n      if (surfaceDistance <= radius && (best === null || surfaceDistance < best.distance)) {\n        best = {\n          interactableId: id,\n          distance: surfaceDistance,\n          point: [this.w.x, this.w.y, this.w.z],\n        };\n      }\n    }\n    return best;\n  }\n\n  private ownerOf(object: Object3D): string | null {\n    let current: Object3D | null = object;\n    while (current) {\n      const id = this.byObject.get(current);\n      if (id !== undefined) return id;\n      current = current.parent;\n    }\n    return null;\n  }\n\n  private boundingRadius(object: Object3D): number {\n    const geometry = (object as Mesh).geometry;\n    if (geometry) {\n      if (!geometry.boundingSphere) geometry.computeBoundingSphere();\n      if (geometry.boundingSphere) {\n        this.sphere.copy(geometry.boundingSphere);\n        const scale = object.getWorldScale(this.w);\n        return this.sphere.radius * Math.max(scale.x, scale.y, scale.z);\n      }\n    }\n    return 0;\n  }\n}\n"]}
+{"version":3,"file":"hit-tester.js","sourceRoot":"","sources":["../src/hit-tester.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,SAAS,EAAoE,MAAM,OAAO,CAAC;AAkBpG,MAAM,OAAO,cAAc;IACR,KAAK,GAAG,IAAI,GAAG,EAAoB,CAAC;IACpC,QAAQ,GAAG,IAAI,OAAO,EAAoB,CAAC;IAC5D,mFAAmF;IAC3E,QAAQ,GAAsB,IAAI,CAAC;IAC1B,SAAS,GAAG,IAAI,SAAS,EAAE,CAAC;IAC7C,mEAAmE;IAClD,aAAa,GAAmB,EAAE,CAAC;IAEpD;QACE,0EAA0E;QACzE,IAAI,CAAC,SAAwC,CAAC,YAAY,GAAG,IAAI,CAAC;IACrE,CAAC;IAED,QAAQ,CAAC,EAAU,EAAE,MAAgB;QACnC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QACpB,MAAM,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,EAAE;YACxB,MAAM,QAAQ,GAAI,KAAc,CAAC,QAA0D,CAAC;YAC5F,qEAAqE;YACrE,gDAAgD;YAChD,IACE,QAAQ;gBACR,OAAO,QAAQ,CAAC,iBAAiB,KAAK,UAAU;gBAChD,CAAC,QAAQ,CAAC,UAAU,KAAK,SAAS,IAAI,QAAQ,CAAC,UAAU,KAAK,IAAI,CAAC,EACnE,CAAC;gBACD,QAAQ,CAAC,iBAAiB,EAAE,CAAC;YAC/B,CAAC;QACH,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QAC3B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAC9B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;IACvB,CAAC;IAED,UAAU,CAAC,EAAU;QACnB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClC,IAAI,CAAC,MAAM;YAAE,OAAO;QACpB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC7B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;IACvB,CAAC;IAED,SAAS,CAAC,EAAU;QAClB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED,MAAM,CAAC,GAAa;QAClB,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACvC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3E,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;QACvF,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;QACzC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC;QACzB,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC;QACrE,KAAK,MAAM,YAAY,IAAI,aAAa,EAAE,CAAC;YACzC,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;YAC7C,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;gBAChB,OAAO;oBACL,cAAc,EAAE,EAAE;oBAClB,QAAQ,EAAE,YAAY,CAAC,QAAQ;oBAC/B,KAAK,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;iBAC1E,CAAC;YACJ,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,YAAY,CAAC,KAAgB,EAAE,MAAc;QAC3C,IAAI,IAAI,GAA2B,IAAI,CAAC;QACxC,KAAK,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACtC,qEAAqE;YACrE,sEAAsE;YACtE,2DAA2D;YAC3D,MAAM,CAAC,iBAAiB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YACtC,MAAM,CAAC,GAAG,MAAM,CAAC,WAAW,CAAC,QAA2B,CAAC;YACzD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CACpB,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAC5B,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAC5B,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAC9B,CAAC;YACF,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,CAC9B,CAAC,EACD,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,KAAK,CAC5F,CAAC;YACF,IAAI,eAAe,IAAI,MAAM,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,eAAe,GAAG,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACpF,IAAI,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,QAAQ,EAAE,eAAe,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;YACzF,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,OAAO;QACb,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI;YAAE,IAAI,CAAC,QAAQ,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QACrE,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAEO,OAAO,CAAC,MAAgB;QAC9B,IAAI,OAAO,GAAoB,MAAM,CAAC;QACtC,OAAO,OAAO,EAAE,CAAC;YACf,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACtC,IAAI,EAAE,KAAK,SAAS;gBAAE,OAAO,EAAE,CAAC;YAChC,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;QAC3B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAED,kGAAkG;AAClG,SAAS,QAAQ,CAAC,MAAgB;IAChC,MAAM,QAAQ,GAAI,MAAe,CAAC,QAAsC,CAAC;IACzE,IAAI,CAAC,QAAQ;QAAE,OAAO,CAAC,CAAC;IACxB,IAAI,CAAC,QAAQ,CAAC,cAAc;QAAE,QAAQ,CAAC,qBAAqB,EAAE,CAAC;IAC/D,OAAO,QAAQ,CAAC,cAAc,EAAE,MAAM,IAAI,CAAC,CAAC;AAC9C,CAAC","sourcesContent":["/**\n * ThreeHitTester - resolves core ray/proximity queries against registered\n * three.js objects. Ray hits use a Raycaster over the registered roots\n * (recursive); proximity uses world-position distance minus an\n * approximate bounding radius, good enough for poke targets.\n *\n * Detailed meshes are the cost to watch. three.js tests every triangle of\n * a mesh once a ray enters its bounding sphere, so a 20k-triangle\n * interactable costs close to a millisecond per ray. When the app has\n * installed three-mesh-bvh's prototype hooks -\n * `BufferGeometry.prototype.computeBoundsTree` and\n * `Mesh.prototype.raycast = acceleratedRaycast`, which IWSDK does for you -\n * the tester builds a bounds tree for every geometry it registers and asks\n * the raycaster for the first hit only, so the same ray costs microseconds.\n * Without the hooks it falls back to the plain raycast, and a detailed\n * interactable should be registered through a low-poly collider proxy\n * instead (see the README).\n */\nimport { Raycaster, type BufferGeometry, type Intersection, type Mesh, type Object3D } from \"three\";\nimport type { RayTuple, Vec3Tuple } from \"@realitycollective/webxr-input\";\nimport type { HitTester, InteractableHit } from \"@realitycollective/webxr-interactions\";\n\n/** What three-mesh-bvh adds to a geometry once its prototype hooks are installed. */\ninterface BvhGeometryLike {\n  boundsTree?: unknown;\n  computeBoundsTree?: () => void;\n}\n\n/** A `Matrix4` always holds sixteen numbers; the type says so for indexed reads. */\ntype Matrix4Elements = [\n  number, number, number, number,\n  number, number, number, number,\n  number, number, number, number,\n  number, number, number, number,\n];\n\nexport class ThreeHitTester implements HitTester {\n  private readonly roots = new Map<string, Object3D>();\n  private readonly byObject = new WeakMap<Object3D, string>();\n  /** `roots` as the array the raycaster takes, rebuilt only when the set changes. */\n  private rootList: Object3D[] | null = null;\n  private readonly raycaster = new Raycaster();\n  /** Reused between calls; three.js appends into it and sorts it. */\n  private readonly intersections: Intersection[] = [];\n\n  constructor() {\n    // Read by three-mesh-bvh's accelerated raycast, ignored by the stock one.\n    (this.raycaster as { firstHitOnly?: boolean }).firstHitOnly = true;\n  }\n\n  register(id: string, object: Object3D): void {\n    this.unregister(id);\n    object.traverse((child) => {\n      const geometry = (child as Mesh).geometry as (BufferGeometry & BvhGeometryLike) | undefined;\n      // `disposeBoundsTree` leaves null behind, a never-built geometry has\n      // undefined: both mean there is no tree to use.\n      if (\n        geometry &&\n        typeof geometry.computeBoundsTree === \"function\" &&\n        (geometry.boundsTree === undefined || geometry.boundsTree === null)\n      ) {\n        geometry.computeBoundsTree();\n      }\n    });\n    this.roots.set(id, object);\n    this.byObject.set(object, id);\n    this.rootList = null;\n  }\n\n  unregister(id: string): void {\n    const object = this.roots.get(id);\n    if (!object) return;\n    this.byObject.delete(object);\n    this.roots.delete(id);\n    this.rootList = null;\n  }\n\n  getObject(id: string): Object3D | undefined {\n    return this.roots.get(id);\n  }\n\n  hitRay(ray: RayTuple): InteractableHit | null {\n    if (this.roots.size === 0) return null;\n    this.raycaster.ray.origin.set(ray.origin[0], ray.origin[1], ray.origin[2]);\n    this.raycaster.ray.direction.set(ray.direction[0], ray.direction[1], ray.direction[2]);\n    const intersections = this.intersections;\n    intersections.length = 0;\n    this.raycaster.intersectObjects(this.objects(), true, intersections);\n    for (const intersection of intersections) {\n      const id = this.ownerOf(intersection.object);\n      if (id !== null) {\n        return {\n          interactableId: id,\n          distance: intersection.distance,\n          point: [intersection.point.x, intersection.point.y, intersection.point.z],\n        };\n      }\n    }\n    return null;\n  }\n\n  hitProximity(point: Vec3Tuple, radius: number): InteractableHit | null {\n    let best: InteractableHit | null = null;\n    for (const [id, object] of this.roots) {\n      // One matrix update per object, then position and scale straight off\n      // the world matrix: the last column is the translation and the length\n      // of each of the first three columns is that axis's scale.\n      object.updateWorldMatrix(true, false);\n      const e = object.matrixWorld.elements as Matrix4Elements;\n      const scale = Math.max(\n        Math.hypot(e[0], e[1], e[2]),\n        Math.hypot(e[4], e[5], e[6]),\n        Math.hypot(e[8], e[9], e[10]),\n      );\n      const surfaceDistance = Math.max(\n        0,\n        Math.hypot(e[12] - point[0], e[13] - point[1], e[14] - point[2]) - radiusOf(object) * scale,\n      );\n      if (surfaceDistance <= radius && (best === null || surfaceDistance < best.distance)) {\n        best = { interactableId: id, distance: surfaceDistance, point: [e[12], e[13], e[14]] };\n      }\n    }\n    return best;\n  }\n\n  private objects(): Object3D[] {\n    if (this.rootList === null) this.rootList = [...this.roots.values()];\n    return this.rootList;\n  }\n\n  private ownerOf(object: Object3D): string | null {\n    let current: Object3D | null = object;\n    while (current) {\n      const id = this.byObject.get(current);\n      if (id !== undefined) return id;\n      current = current.parent;\n    }\n    return null;\n  }\n}\n\n/** Bounding-sphere radius of the object's own geometry in local units, or 0 for a plain group. */\nfunction radiusOf(object: Object3D): number {\n  const geometry = (object as Mesh).geometry as BufferGeometry | undefined;\n  if (!geometry) return 0;\n  if (!geometry.boundingSphere) geometry.computeBoundingSphere();\n  return geometry.boundingSphere?.radius ?? 0;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@realitycollective/threejs-interactions",
-  "version": "0.1.0-preview.3",
+  "version": "0.1.0-preview.5",
   "description": "The default, standalone engine adapter for the Reality Collective Interaction Extensions: raw WebXR (the browser's OpenXR binding - XRSession, XRInputSource, select/squeeze, hand joints) plus three.js hit-testing and transform ports, with a desktop mouse fallback. No framework required. Re-exports the @realitycollective/webxr-interactions core.",
   "keywords": [
     "realitycollective",
@@ -34,13 +34,20 @@
   },
   "dependencies": {
     "@realitycollective/webxr-input": "^0.1.1",
-    "@realitycollective/webxr-interactions": "^0.1.0-preview.3"
+    "@realitycollective/webxr-interactions": "^0.1.0-preview.5"
   },
   "peerDependencies": {
-    "three": ">=0.170.0"
+    "three": ">=0.170.0",
+    "three-mesh-bvh": ">=0.9.14"
+  },
+  "peerDependenciesMeta": {
+    "three-mesh-bvh": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "three": "npm:super-three@0.181.0",
+    "three-mesh-bvh": "^0.9.14",
     "@types/three": "*"
   },
   "repository": {