@realitycollective/babylon-interactions 0.1.0-preview.2

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+Change log for the Reality Collective WebXR Interaction Extensions packages. All five packages are versioned and released together; the version below is the one carried by the `v<version>` release tag.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Preview builds are not listed separately. The entry for a version accumulates while its previews are published, and is dated when that version is released.
+
+## [0.1.0]
+
+### Added
+
+- `@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.
+- `@realitycollective/xrblocks-interactions` - EXPERIMENTAL Google XR Blocks adapter, structurally typed against xrblocks v0.20.0 (`Input.getFrame()` ray sources and direct touches, pooled structs copied, no haptics upstream).
+- `demos/playground` - the standalone interaction playground: the full station set from one portable `InteractionDescriptor`, with client-side audio cues, opt-in controller haptics and client-side toss ballistics.
+- `@realitycollective/webxr-interactions` - per-source velocity. `VelocityTracker` differentiates the grip poses the runtime already samples into linear and angular velocity, and the runtime runs one by default (`velocity: false` turns it off, `{ smoothing }` averages it). A source on its first frame, or one that reappears after dropping out, reports no velocity rather than a jump from its last known pose, and a provider that supplies its own velocity keeps it. Read it from `runtime.onSample(...)` or `runtime.getSource(id)`. `poseVelocity` and `clampDeadzone` join the math helpers.
+- `@realitycollective/webxr-interactions` - `routeAudioToSink`, the audio counterpart to `routeHapticsToProvider`: an opt-in that plays the cues named in a map through a client-supplied sink. Cues absent from the map are ignored, so an app sonifies only the moments it has sounds for.
+- `@realitycollective/iwsdk-interactions` and `@realitycollective/threejs-interactions` - presence control. `setPresenceVisible(target, visible)` shows and hides the hand and controller visuals per side; the IWSDK adapter adds `setPresenceModality(mode)` to force hands or controllers over the automatic choice, and the three.js adapter takes the app's own models through `registerVisual(handedness, root)`. Each provider reports `supportsPresence`; the XR Blocks adapter reports false, since XR Blocks exposes no way to hide its visuals.
+- `@realitycollective/threejs-interactions` - native WebXR pose velocity. Where the browser reports `linearVelocity` or `angularVelocity` with a grip pose (or with the wrist joint a hand falls back to), the provider passes it through on the snapshot and the core's tracker leaves it alone; where it does not, the tracker derives velocity from consecutive poses as before. The desktop mouse source synthesises nothing: its grip rides the camera ray, so the derived velocity is camera motion, and hand mechanics should be gated on `handedness !== "none"`.
+- `@realitycollective/babylon-interactions` - a Babylon.js adapter, the fourth engine. It reads a `WebXRDefaultExperience` (controllers, motion controller trigger and squeeze, hand-tracking joints, session manager) for input, with `scene.onPointerObservable` as the desktop fallback, haptics through the motion controller's `pulse`, and presence over the visuals Babylon builds - motion controller root meshes and hand meshes. Babylon picks the visual per input source, so there is no modality switch. Hit-testing is a sphere test over registered nodes, with an optional `pickWithRay` hook for mesh-accurate targeting; the transform port moves, rotates and scales Babylon nodes from rest. Structurally typed against the Babylon API rather than importing `@babylonjs/core`, as the XR Blocks adapter is, so an upstream release cannot break the install - and so the whole adapter is covered headlessly by structural fakes. Written against the documented Babylon 7 API and not yet exercised against a real Babylon runtime.
+- Tests for `@realitycollective/iwsdk-interactions`, which had none. `@iwsdk/core` imports headlessly in node, so the provider is covered against a structural fake world with no module mocking, and a parity suite instantiates all three providers and checks each one implements the whole `InputProvider` contract. The package's coverage ratchet moves off zero, and the other three ratchets rise to the floor they now measure.
+
+### Changed
+
+- `@realitycollective/iwsdk-interactions` - `pulse` resolves the side from the handedness recorded while sampling, rather than parsing the source id. Parsing the id remains the fallback for an id the provider did not produce.
+
+- `@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.
+
+### 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.
+- The interaction packages themselves carry no IWSDK coupling beyond the adapter: `webxr-interactions` is engine-free, and `threejs-interactions` and `xrblocks-interactions` peer only on three.js.
+
+[0.1.0]: https://github.com/realitycollective/WebXR-Interactions/commits/main

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Reality Collective
+
+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/README.md

@@ -0,0 +1,70 @@
+# @realitycollective/babylon-interactions
+
+The Babylon.js adapter for the Reality Collective Interaction Extensions. It feeds a Babylon WebXR experience into the [`@realitycollective/webxr-interactions`](https://www.npmjs.com/package/@realitycollective/webxr-interactions) core.
+
+```sh
+npm install @realitycollective/babylon-interactions
+```
+
+It re-exports everything from the core, so this is the only interaction package your app needs.
+
+> **Not yet exercised against a real Babylon runtime.** The adapter is written against the documented Babylon 7 API and covered by structural fakes. Treat it as a preview until it has run in a Babylon app.
+
+## What it binds
+
+| Layer | Detail |
+| --- | --- |
+| **Input** | `WebXRDefaultExperience`: controllers, motion controller components (trigger, squeeze), hand-tracking joints, and the session manager for what is live |
+| **Hit-testing** | A sphere test over registered nodes, or your own `scene.pickWithRay` through the `pickWithRay` hook |
+| **Movement** | Moves, rotates and scales Babylon nodes for grab, hinge, dial and slide |
+| **Desktop** | `scene.onPointerObservable` as a pointer fallback, so the same scene is testable without a headset |
+| **Haptics** | Through the motion controller's `pulse` |
+| **No @babylonjs/core dependency** | It matches the shape of the Babylon API in TypeScript rather than importing Babylon, so an upstream release cannot break your install |
+
+## Usage
+
+```ts
+import { createBabylonInteractions } from "@realitycollective/babylon-interactions";
+
+const xr = await scene.createDefaultXRExperienceAsync();
+const interactions = createBabylonInteractions({ scene, xr, attachToScene: true });
+
+interactions.register({ id: "button", behaviours: [{ kind: "press" }] }, buttonMesh);
+interactions.runtime.onEvent((event) => console.log(event.type));
+```
+
+`attachToScene` drives the update loop from `scene.onBeforeRenderObservable` and the engine's frame delta. Leave it off and call `interactions.update(dtSeconds)` from your own loop.
+
+For mesh-accurate targeting, hand the adapter your own pick:
+
+```ts
+interactions.setPickWithRay((origin, direction, maxDistance) => {
+  const info = scene.pickWithRay(new Ray(Vector3.FromArray(origin), Vector3.FromArray(direction), maxDistance));
+  return info?.hit && info.pickedPoint
+    ? { mesh: info.pickedMesh, distance: info.distance, point: info.pickedPoint.asArray() as [number, number, number] }
+    : null;
+});
+```
+
+## Things to know
+
+- **Forward is +Z.** Babylon is left-handed, so a controller ray points down +Z where three.js and raw WebXR point down -Z. A scene that sets `useRightHandedSystem` faces -Z instead; the adapter reads that flag at construction and flips. The adapter handles this; it matters if you compare rays with another adapter's.
+- **Rotations need a quaternion.** A node whose `rotationQuaternion` is null is still driven by Euler angles. Set `node.rotationQuaternion = Quaternion.Identity()` before registering it, or pass `createQuaternion` to `register`, otherwise the first rotation write stores a plain object that Babylon cannot use.
+- **Presence** shows and hides what Babylon built: motion controller root meshes and hand meshes. Babylon picks the visual per input source, so there is no hands/controllers switch - `setPresenceModality` always returns false.
+- **Desktop grip.** The pointer fallback puts its grip one metre along the pointer ray, matching the three.js adapter, so grab, hinge, dial and slide follow the cursor on desktop. Set `desktopGripDistance` near the distance of the things being manipulated; at 0 the grip sits on the camera and a drag reports camera motion only.
+
+## Peer dependency
+
+None. Babylon is matched structurally, not imported, so any Babylon version whose objects carry these members works.
+
+## Live demo
+
+The interaction playground - the three.js build of the same station set: **[webxr-interactions.pages.dev](https://webxr-interactions.pages.dev)**
+
+## Documentation
+
+See the [repository README](https://github.com/realitycollective/WebXR-Interactions#readme).
+
+## License
+
+MIT - see [LICENSE](./LICENSE).

package/dist/babylon-types.d.ts

@@ -0,0 +1,220 @@
+/**
+ * The shape of the Babylon.js API this adapter reads, written out here
+ * rather than imported.
+ *
+ * `@babylonjs/core` is NOT a dependency of this package, in the same way
+ * the XR Blocks adapter does not depend on `xrblocks`. Babylon ships one
+ * large package on a fast release train, and an adapter that imported it
+ * would drag a version choice into every consumer and break on an upstream
+ * rename. Matching the shape instead means an app installs whatever Babylon
+ * it already uses and passes its objects straight in.
+ *
+ * The trade for that is honesty about provenance: these declarations were
+ * written from the Babylon 7 documentation, not verified against an
+ * installed package, so members a version might not carry are optional and
+ * read defensively. Nothing here is required to be a Babylon object - a
+ * plain object with the same members works, which is what the tests use.
+ *
+ * Coordinates: Babylon is LEFT-handed and a node's forward is +Z, where
+ * three.js and raw WebXR use -Z. That difference is applied in one place
+ * (`nodeForward`) so it is stated once.
+ */
+import type { PoseTuple, QuatTuple, Vec3Tuple } from "@realitycollective/webxr-input";
+/** Structural slice of Babylon's `Vector3`. */
+export interface BabylonVector3Like {
+    x: number;
+    y: number;
+    z: number;
+}
+/** Structural slice of Babylon's `Quaternion`. */
+export interface BabylonQuaternionLike {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}
+/** Structural slice of Babylon's `Ray`. */
+export interface BabylonRayLike {
+    origin: BabylonVector3Like;
+    direction: BabylonVector3Like;
+}
+/**
+ * Structural slice of Babylon's `Observable<T>`. The observer handle is
+ * opaque - it is only ever handed straight back to `remove`.
+ */
+export interface BabylonObservableLike<T> {
+    add(callback: (eventData: T) => void): unknown;
+    remove(observer: unknown): boolean;
+}
+/**
+ * Structural slice of Babylon's `TransformNode`, plus the one member
+ * `AbstractMesh` adds that this adapter reads (`isVisible`).
+ *
+ * `parent` is `unknown` on purpose: Babylon types it as `Nullable<Node>`,
+ * and `Node` carries none of the transform members, so anything narrower
+ * would refuse a real Babylon node. Read it through `parentOf`.
+ */
+export interface BabylonTransformNodeLike {
+    position: BabylonVector3Like;
+    rotationQuaternion?: BabylonQuaternionLike | null;
+    scaling?: BabylonVector3Like;
+    parent?: unknown;
+    getAbsolutePosition(): BabylonVector3Like;
+    absoluteRotationQuaternion?: BabylonQuaternionLike;
+    computeWorldMatrix?(force?: boolean): unknown;
+    setEnabled?(value: boolean): void;
+    isEnabled?(checkAncestors?: boolean): boolean;
+    isVisible?: boolean;
+}
+/** Structural slice of Babylon's `Camera`. */
+export interface BabylonCameraLike {
+    globalPosition?: BabylonVector3Like;
+    absoluteRotation?: BabylonQuaternionLike;
+    position?: BabylonVector3Like;
+    getForwardRay?(length?: number): BabylonRayLike;
+}
+/** Structural slice of Babylon's `Engine` - only the frame delta is read. */
+export interface BabylonEngineLike {
+    getDeltaTime(): number;
+}
+/** Structural slice of Babylon's `PickingInfo`. */
+export interface BabylonPickingInfoLike {
+    hit?: boolean;
+    distance?: number;
+    pickedPoint?: BabylonVector3Like | null;
+    pickedMesh?: BabylonTransformNodeLike | null;
+    ray?: BabylonRayLike | null;
+}
+/**
+ * Structural slice of Babylon's `PointerInfo`. `type` is one of the
+ * `PointerEventTypes` constants - see {@link POINTER_EVENT_TYPES}.
+ */
+export interface BabylonPointerInfoLike {
+    type: number;
+    event?: {
+        clientX?: number;
+        clientY?: number;
+        button?: number;
+    };
+    pickInfo?: BabylonPickingInfoLike | null;
+}
+/**
+ * The `PointerEventTypes` values this adapter reacts to. Babylon defines
+ * them as one bit per event; these three are unchanged across 5, 6 and 7.
+ */
+export declare const POINTER_EVENT_TYPES: {
+    readonly down: 1;
+    readonly up: 2;
+    readonly move: 4;
+};
+/** Structural slice of Babylon's `Scene`. */
+export interface BabylonSceneLike {
+    /**
+     * Babylon defaults to a left-handed system with forward +Z. A scene that
+     * sets this flag is right-handed and its nodes face -Z; the adapter reads
+     * it once at construction.
+     */
+    useRightHandedSystem?: boolean;
+    onBeforeRenderObservable?: BabylonObservableLike<unknown>;
+    onPointerObservable?: BabylonObservableLike<BabylonPointerInfoLike>;
+    pick?(x: number, y: number): BabylonPickingInfoLike | null;
+    activeCamera?: BabylonCameraLike | null;
+    getEngine?(): BabylonEngineLike;
+}
+/** Structural slice of one `WebXRControllerComponent` reading. */
+export interface BabylonMotionControllerComponentLike {
+    value?: number;
+    pressed?: boolean;
+}
+/** Structural slice of Babylon's `WebXRAbstractMotionController`. */
+export interface BabylonMotionControllerLike {
+    getComponentOfType?(type: string): BabylonMotionControllerComponentLike | null;
+    getMainComponent?(): BabylonMotionControllerComponentLike | null;
+    pulse?(value: number, duration: number): Promise<unknown>;
+    rootMesh?: BabylonTransformNodeLike | null;
+}
+/** Structural slice of Babylon's `WebXRInputSource`. */
+export interface BabylonXRControllerLike {
+    uniqueId: string;
+    inputSource: {
+        handedness?: string;
+        hand?: unknown;
+        gamepad?: {
+            hapticActuators?: readonly unknown[];
+        } | null;
+    };
+    pointer: BabylonTransformNodeLike;
+    grip?: BabylonTransformNodeLike | null;
+    motionController?: BabylonMotionControllerLike | null;
+    onMotionControllerInitObservable?: BabylonObservableLike<unknown>;
+}
+/** Structural slice of Babylon's `WebXRInput`. */
+export interface BabylonXRInputLike {
+    controllers: readonly BabylonXRControllerLike[];
+    onControllerAddedObservable?: BabylonObservableLike<BabylonXRControllerLike>;
+    onControllerRemovedObservable?: BabylonObservableLike<BabylonXRControllerLike>;
+}
+/** Structural slice of one tracked hand from the hand-tracking feature. */
+export interface BabylonXRHandLike {
+    getJointMesh?(jointName: string): BabylonTransformNodeLike | null | undefined;
+    handMesh?: BabylonTransformNodeLike | null;
+}
+/**
+ * Structural slice of `WebXRHandTracking`, the feature the features manager
+ * registers under `"xr-hand-tracking"`.
+ */
+export interface BabylonHandTrackingLike {
+    getHandByControllerId(id: string): BabylonXRHandLike | null | undefined;
+}
+/** Structural slice of Babylon's `WebXRDefaultExperience`. */
+export interface BabylonXRExperienceLike {
+    baseExperience?: {
+        sessionManager?: {
+            session?: unknown;
+            onXRSessionInit?: BabylonObservableLike<unknown>;
+            onXRSessionEnded?: BabylonObservableLike<unknown>;
+        };
+        featuresManager?: {
+            getEnabledFeature(featureName: string): unknown;
+        };
+    };
+    input?: BabylonXRInputLike;
+}
+/** The name Babylon registers hand tracking under in the features manager. */
+export declare const HAND_TRACKING_FEATURE = "xr-hand-tracking";
+/** Index fingertip joint, as WebXR and Babylon both spell it. */
+export declare const INDEX_TIP_JOINT = "index-finger-tip";
+/** Copy a Babylon vector into a tuple. */
+export declare function toVec3(v: BabylonVector3Like | null | undefined): Vec3Tuple | null;
+/** Copy a Babylon quaternion into a tuple, defaulting to identity. */
+export declare function toQuat(q: BabylonQuaternionLike | null | undefined): QuatTuple;
+/** Write a tuple into an existing Babylon vector, in place. */
+export declare function writeVec3(target: BabylonVector3Like, value: Vec3Tuple): void;
+/** Write a tuple into an existing Babylon quaternion, in place. */
+export declare function writeQuat(target: BabylonQuaternionLike, value: QuatTuple): void;
+/** A node's world pose: absolute position and absolute rotation. */
+export declare function nodeWorldPose(node: BabylonTransformNodeLike): PoseTuple;
+/**
+ * The world-space forward axis for a scene: +Z in Babylon's default
+ * left-handed system, the opposite of three.js and of a raw WebXR target
+ * ray, and -Z when the scene sets `useRightHandedSystem`.
+ */
+export declare function defaultForward(rightHanded?: boolean): Vec3Tuple;
+/**
+ * A node's forward direction in world space, honouring the scene's
+ * handedness (see {@link defaultForward}).
+ */
+export declare function nodeForward(node: BabylonTransformNodeLike, rightHanded?: boolean): Vec3Tuple;
+/**
+ * The parent of a node, when it is one this adapter can read a world pose
+ * from. Babylon types `parent` as `Node`, which has no transform, so a
+ * parent that is a bone or a bare node reports null and the caller treats
+ * the node as unparented.
+ */
+export declare function parentOf(node: BabylonTransformNodeLike): BabylonTransformNodeLike | null;
+/**
+ * Is this node currently showing? A node the app disabled or hid is not a
+ * hit-test candidate. Absent members mean yes - a fake, or a build that does
+ * not carry them, should not silently drop out of targeting.
+ */
+export declare function nodeShowing(node: BabylonTransformNodeLike): boolean;

package/dist/babylon-types.js

@@ -0,0 +1,92 @@
+import { vApplyQuat } from "@realitycollective/webxr-interactions";
+/**
+ * The `PointerEventTypes` values this adapter reacts to. Babylon defines
+ * them as one bit per event; these three are unchanged across 5, 6 and 7.
+ */
+export const POINTER_EVENT_TYPES = {
+    down: 1,
+    up: 2,
+    move: 4,
+};
+/** The name Babylon registers hand tracking under in the features manager. */
+export const HAND_TRACKING_FEATURE = "xr-hand-tracking";
+/** Index fingertip joint, as WebXR and Babylon both spell it. */
+export const INDEX_TIP_JOINT = "index-finger-tip";
+// ---------------------------------------------------------------------------
+// Conversions. Everything below turns Babylon-shaped objects into the core's
+// tuples, or writes tuples back IN PLACE.
+//
+// In place is deliberate. Babylon caches the previous position/rotation and
+// recomputes the world matrix when the live values differ, so mutating
+// `node.position.x` is seen. Replacing `node.position` with a plain object is
+// not just missed, it breaks Babylon, which calls Vector3 methods on it.
+// ---------------------------------------------------------------------------
+/** Copy a Babylon vector into a tuple. */
+export function toVec3(v) {
+    return v ? [v.x, v.y, v.z] : null;
+}
+/** Copy a Babylon quaternion into a tuple, defaulting to identity. */
+export function toQuat(q) {
+    return q ? [q.x, q.y, q.z, q.w] : [0, 0, 0, 1];
+}
+/** Write a tuple into an existing Babylon vector, in place. */
+export function writeVec3(target, value) {
+    target.x = value[0];
+    target.y = value[1];
+    target.z = value[2];
+}
+/** Write a tuple into an existing Babylon quaternion, in place. */
+export function writeQuat(target, value) {
+    target.x = value[0];
+    target.y = value[1];
+    target.z = value[2];
+    target.w = value[3];
+}
+/** A node's world pose: absolute position and absolute rotation. */
+export function nodeWorldPose(node) {
+    return {
+        position: toVec3(node.getAbsolutePosition()) ?? [0, 0, 0],
+        quaternion: toQuat(node.absoluteRotationQuaternion),
+    };
+}
+/**
+ * The world-space forward axis for a scene: +Z in Babylon's default
+ * left-handed system, the opposite of three.js and of a raw WebXR target
+ * ray, and -Z when the scene sets `useRightHandedSystem`.
+ */
+export function defaultForward(rightHanded = false) {
+    return [0, 0, rightHanded ? -1 : 1];
+}
+/**
+ * A node's forward direction in world space, honouring the scene's
+ * handedness (see {@link defaultForward}).
+ */
+export function nodeForward(node, rightHanded = false) {
+    return vApplyQuat(defaultForward(rightHanded), toQuat(node.absoluteRotationQuaternion));
+}
+/**
+ * The parent of a node, when it is one this adapter can read a world pose
+ * from. Babylon types `parent` as `Node`, which has no transform, so a
+ * parent that is a bone or a bare node reports null and the caller treats
+ * the node as unparented.
+ */
+export function parentOf(node) {
+    const parent = node.parent;
+    if (!parent || typeof parent !== "object")
+        return null;
+    const candidate = parent;
+    return typeof candidate.getAbsolutePosition === "function"
+        ? parent
+        : null;
+}
+/**
+ * Is this node currently showing? A node the app disabled or hid is not a
+ * hit-test candidate. Absent members mean yes - a fake, or a build that does
+ * not carry them, should not silently drop out of targeting.
+ */
+export function nodeShowing(node) {
+    if (node.isVisible === false)
+        return false;
+    return node.isEnabled ? node.isEnabled() !== false : true;
+}
+//# sourceMappingURL=babylon-types.js.map

package/dist/babylon-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"babylon-types.js","sourceRoot":"","sources":["../src/babylon-types.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,UAAU,EAAE,MAAM,uCAAuC,CAAC;AAqFnE;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,IAAI,EAAE,CAAC;IACP,EAAE,EAAE,CAAC;IACL,IAAI,EAAE,CAAC;CACC,CAAC;AA+EX,8EAA8E;AAC9E,MAAM,CAAC,MAAM,qBAAqB,GAAG,kBAAkB,CAAC;AAExD,iEAAiE;AACjE,MAAM,CAAC,MAAM,eAAe,GAAG,kBAAkB,CAAC;AAElD,8EAA8E;AAC9E,6EAA6E;AAC7E,0CAA0C;AAC1C,EAAE;AACF,4EAA4E;AAC5E,uEAAuE;AACvE,8EAA8E;AAC9E,yEAAyE;AACzE,8EAA8E;AAE9E,0CAA0C;AAC1C,MAAM,UAAU,MAAM,CAAC,CAAwC;IAC7D,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACpC,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,MAAM,CAAC,CAA2C;IAChE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,SAAS,CAAC,MAA0B,EAAE,KAAgB;IACpE,MAAM,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACpB,MAAM,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACpB,MAAM,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;AACtB,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,SAAS,CAAC,MAA6B,EAAE,KAAgB;IACvE,MAAM,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACpB,MAAM,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACpB,MAAM,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACpB,MAAM,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;AACtB,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,aAAa,CAAC,IAA8B;IAC1D,OAAO;QACL,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,mBAAmB,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACzD,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,0BAA0B,CAAC;KACpD,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,WAAW,GAAG,KAAK;IAChD,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,IAA8B,EAAE,WAAW,GAAG,KAAK;IAC7E,OAAO,UAAU,CAAC,cAAc,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC,CAAC;AAC1F,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,IAA8B;IACrD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC3B,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACvD,MAAM,SAAS,GAAG,MAA2C,CAAC;IAC9D,OAAO,OAAO,SAAS,CAAC,mBAAmB,KAAK,UAAU;QACxD,CAAC,CAAE,MAAmC;QACtC,CAAC,CAAC,IAAI,CAAC;AACX,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,IAA8B;IACxD,IAAI,IAAI,CAAC,SAAS,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IAC3C,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5D,CAAC","sourcesContent":["/**\n * The shape of the Babylon.js API this adapter reads, written out here\n * rather than imported.\n *\n * `@babylonjs/core` is NOT a dependency of this package, in the same way\n * the XR Blocks adapter does not depend on `xrblocks`. Babylon ships one\n * large package on a fast release train, and an adapter that imported it\n * would drag a version choice into every consumer and break on an upstream\n * rename. Matching the shape instead means an app installs whatever Babylon\n * it already uses and passes its objects straight in.\n *\n * The trade for that is honesty about provenance: these declarations were\n * written from the Babylon 7 documentation, not verified against an\n * installed package, so members a version might not carry are optional and\n * read defensively. Nothing here is required to be a Babylon object - a\n * plain object with the same members works, which is what the tests use.\n *\n * Coordinates: Babylon is LEFT-handed and a node's forward is +Z, where\n * three.js and raw WebXR use -Z. That difference is applied in one place\n * (`nodeForward`) so it is stated once.\n */\nimport type { PoseTuple, QuatTuple, Vec3Tuple } from \"@realitycollective/webxr-input\";\nimport { vApplyQuat } from \"@realitycollective/webxr-interactions\";\n\n/** Structural slice of Babylon's `Vector3`. */\nexport interface BabylonVector3Like {\n  x: number;\n  y: number;\n  z: number;\n}\n\n/** Structural slice of Babylon's `Quaternion`. */\nexport interface BabylonQuaternionLike {\n  x: number;\n  y: number;\n  z: number;\n  w: number;\n}\n\n/** Structural slice of Babylon's `Ray`. */\nexport interface BabylonRayLike {\n  origin: BabylonVector3Like;\n  direction: BabylonVector3Like;\n}\n\n/**\n * Structural slice of Babylon's `Observable<T>`. The observer handle is\n * opaque - it is only ever handed straight back to `remove`.\n */\nexport interface BabylonObservableLike<T> {\n  add(callback: (eventData: T) => void): unknown;\n  remove(observer: unknown): boolean;\n}\n\n/**\n * Structural slice of Babylon's `TransformNode`, plus the one member\n * `AbstractMesh` adds that this adapter reads (`isVisible`).\n *\n * `parent` is `unknown` on purpose: Babylon types it as `Nullable<Node>`,\n * and `Node` carries none of the transform members, so anything narrower\n * would refuse a real Babylon node. Read it through `parentOf`.\n */\nexport interface BabylonTransformNodeLike {\n  position: BabylonVector3Like;\n  rotationQuaternion?: BabylonQuaternionLike | null;\n  scaling?: BabylonVector3Like;\n  parent?: unknown;\n  getAbsolutePosition(): BabylonVector3Like;\n  absoluteRotationQuaternion?: BabylonQuaternionLike;\n  computeWorldMatrix?(force?: boolean): unknown;\n  setEnabled?(value: boolean): void;\n  isEnabled?(checkAncestors?: boolean): boolean;\n  isVisible?: boolean;\n}\n\n/** Structural slice of Babylon's `Camera`. */\nexport interface BabylonCameraLike {\n  globalPosition?: BabylonVector3Like;\n  absoluteRotation?: BabylonQuaternionLike;\n  position?: BabylonVector3Like;\n  getForwardRay?(length?: number): BabylonRayLike;\n}\n\n/** Structural slice of Babylon's `Engine` - only the frame delta is read. */\nexport interface BabylonEngineLike {\n  getDeltaTime(): number;\n}\n\n/** Structural slice of Babylon's `PickingInfo`. */\nexport interface BabylonPickingInfoLike {\n  hit?: boolean;\n  distance?: number;\n  pickedPoint?: BabylonVector3Like | null;\n  pickedMesh?: BabylonTransformNodeLike | null;\n  ray?: BabylonRayLike | null;\n}\n\n/**\n * Structural slice of Babylon's `PointerInfo`. `type` is one of the\n * `PointerEventTypes` constants - see {@link POINTER_EVENT_TYPES}.\n */\nexport interface BabylonPointerInfoLike {\n  type: number;\n  event?: { clientX?: number; clientY?: number; button?: number };\n  pickInfo?: BabylonPickingInfoLike | null;\n}\n\n/**\n * The `PointerEventTypes` values this adapter reacts to. Babylon defines\n * them as one bit per event; these three are unchanged across 5, 6 and 7.\n */\nexport const POINTER_EVENT_TYPES = {\n  down: 1,\n  up: 2,\n  move: 4,\n} as const;\n\n/** Structural slice of Babylon's `Scene`. */\nexport interface BabylonSceneLike {\n  /**\n   * Babylon defaults to a left-handed system with forward +Z. A scene that\n   * sets this flag is right-handed and its nodes face -Z; the adapter reads\n   * it once at construction.\n   */\n  useRightHandedSystem?: boolean;\n  onBeforeRenderObservable?: BabylonObservableLike<unknown>;\n  onPointerObservable?: BabylonObservableLike<BabylonPointerInfoLike>;\n  pick?(x: number, y: number): BabylonPickingInfoLike | null;\n  activeCamera?: BabylonCameraLike | null;\n  getEngine?(): BabylonEngineLike;\n}\n\n/** Structural slice of one `WebXRControllerComponent` reading. */\nexport interface BabylonMotionControllerComponentLike {\n  value?: number;\n  pressed?: boolean;\n}\n\n/** Structural slice of Babylon's `WebXRAbstractMotionController`. */\nexport interface BabylonMotionControllerLike {\n  getComponentOfType?(type: string): BabylonMotionControllerComponentLike | null;\n  getMainComponent?(): BabylonMotionControllerComponentLike | null;\n  pulse?(value: number, duration: number): Promise<unknown>;\n  rootMesh?: BabylonTransformNodeLike | null;\n}\n\n/** Structural slice of Babylon's `WebXRInputSource`. */\nexport interface BabylonXRControllerLike {\n  uniqueId: string;\n  inputSource: {\n    handedness?: string;\n    hand?: unknown;\n    gamepad?: { hapticActuators?: readonly unknown[] } | null;\n  };\n  pointer: BabylonTransformNodeLike;\n  grip?: BabylonTransformNodeLike | null;\n  motionController?: BabylonMotionControllerLike | null;\n  onMotionControllerInitObservable?: BabylonObservableLike<unknown>;\n}\n\n/** Structural slice of Babylon's `WebXRInput`. */\nexport interface BabylonXRInputLike {\n  controllers: readonly BabylonXRControllerLike[];\n  onControllerAddedObservable?: BabylonObservableLike<BabylonXRControllerLike>;\n  onControllerRemovedObservable?: BabylonObservableLike<BabylonXRControllerLike>;\n}\n\n/** Structural slice of one tracked hand from the hand-tracking feature. */\nexport interface BabylonXRHandLike {\n  getJointMesh?(jointName: string): BabylonTransformNodeLike | null | undefined;\n  handMesh?: BabylonTransformNodeLike | null;\n}\n\n/**\n * Structural slice of `WebXRHandTracking`, the feature the features manager\n * registers under `\"xr-hand-tracking\"`.\n */\nexport interface BabylonHandTrackingLike {\n  getHandByControllerId(id: string): BabylonXRHandLike | null | undefined;\n}\n\n/** Structural slice of Babylon's `WebXRDefaultExperience`. */\nexport interface BabylonXRExperienceLike {\n  baseExperience?: {\n    sessionManager?: {\n      session?: unknown;\n      onXRSessionInit?: BabylonObservableLike<unknown>;\n      onXRSessionEnded?: BabylonObservableLike<unknown>;\n    };\n    featuresManager?: { getEnabledFeature(featureName: string): unknown };\n  };\n  input?: BabylonXRInputLike;\n}\n\n/** The name Babylon registers hand tracking under in the features manager. */\nexport const HAND_TRACKING_FEATURE = \"xr-hand-tracking\";\n\n/** Index fingertip joint, as WebXR and Babylon both spell it. */\nexport const INDEX_TIP_JOINT = \"index-finger-tip\";\n\n// ---------------------------------------------------------------------------\n// Conversions. Everything below turns Babylon-shaped objects into the core's\n// tuples, or writes tuples back IN PLACE.\n//\n// In place is deliberate. Babylon caches the previous position/rotation and\n// recomputes the world matrix when the live values differ, so mutating\n// `node.position.x` is seen. Replacing `node.position` with a plain object is\n// not just missed, it breaks Babylon, which calls Vector3 methods on it.\n// ---------------------------------------------------------------------------\n\n/** Copy a Babylon vector into a tuple. */\nexport function toVec3(v: BabylonVector3Like | null | undefined): Vec3Tuple | null {\n  return v ? [v.x, v.y, v.z] : null;\n}\n\n/** Copy a Babylon quaternion into a tuple, defaulting to identity. */\nexport function toQuat(q: BabylonQuaternionLike | null | undefined): QuatTuple {\n  return q ? [q.x, q.y, q.z, q.w] : [0, 0, 0, 1];\n}\n\n/** Write a tuple into an existing Babylon vector, in place. */\nexport function writeVec3(target: BabylonVector3Like, value: Vec3Tuple): void {\n  target.x = value[0];\n  target.y = value[1];\n  target.z = value[2];\n}\n\n/** Write a tuple into an existing Babylon quaternion, in place. */\nexport function writeQuat(target: BabylonQuaternionLike, value: QuatTuple): void {\n  target.x = value[0];\n  target.y = value[1];\n  target.z = value[2];\n  target.w = value[3];\n}\n\n/** A node's world pose: absolute position and absolute rotation. */\nexport function nodeWorldPose(node: BabylonTransformNodeLike): PoseTuple {\n  return {\n    position: toVec3(node.getAbsolutePosition()) ?? [0, 0, 0],\n    quaternion: toQuat(node.absoluteRotationQuaternion),\n  };\n}\n\n/**\n * The world-space forward axis for a scene: +Z in Babylon's default\n * left-handed system, the opposite of three.js and of a raw WebXR target\n * ray, and -Z when the scene sets `useRightHandedSystem`.\n */\nexport function defaultForward(rightHanded = false): Vec3Tuple {\n  return [0, 0, rightHanded ? -1 : 1];\n}\n\n/**\n * A node's forward direction in world space, honouring the scene's\n * handedness (see {@link defaultForward}).\n */\nexport function nodeForward(node: BabylonTransformNodeLike, rightHanded = false): Vec3Tuple {\n  return vApplyQuat(defaultForward(rightHanded), toQuat(node.absoluteRotationQuaternion));\n}\n\n/**\n * The parent of a node, when it is one this adapter can read a world pose\n * from. Babylon types `parent` as `Node`, which has no transform, so a\n * parent that is a bone or a bare node reports null and the caller treats\n * the node as unparented.\n */\nexport function parentOf(node: BabylonTransformNodeLike): BabylonTransformNodeLike | null {\n  const parent = node.parent;\n  if (!parent || typeof parent !== \"object\") return null;\n  const candidate = parent as Partial<BabylonTransformNodeLike>;\n  return typeof candidate.getAbsolutePosition === \"function\"\n    ? (parent as BabylonTransformNodeLike)\n    : null;\n}\n\n/**\n * Is this node currently showing? A node the app disabled or hid is not a\n * hit-test candidate. Absent members mean yes - a fake, or a build that does\n * not carry them, should not silently drop out of targeting.\n */\nexport function nodeShowing(node: BabylonTransformNodeLike): boolean {\n  if (node.isVisible === false) return false;\n  return node.isEnabled ? node.isEnabled() !== false : true;\n}\n"]}

package/dist/hit-tester.d.ts

@@ -0,0 +1,57 @@
+/**
+ * BabylonHitTester - resolves the core's ray and proximity queries against
+ * registered Babylon nodes.
+ *
+ * The default test needs no Babylon raycaster: each registered node carries
+ * a radius, and a query is a sphere test against the node's absolute
+ * position. That is the same model the IWSDK adapter uses, and it is enough
+ * for buttons, levers, dials and grabbables, which are small next to the
+ * distance they are pointed at from.
+ *
+ * An app that wants mesh-accurate picking supplies `pickWithRay`, typically
+ * a one-line wrapper over `scene.pickWithRay`. Whatever mesh it returns is
+ * mapped back to an interactable id through the registration map, walking up
+ * parents so a pick on a child mesh still resolves to the registered root.
+ */
+import type { RayTuple, Vec3Tuple } from "@realitycollective/webxr-input";
+import { type HitTester, type InteractableHit } from "@realitycollective/webxr-interactions";
+import { type BabylonTransformNodeLike } from "./babylon-types.js";
+/** What an app's mesh-accurate pick reports back. */
+export interface BabylonPickResult {
+    /** The node that was hit. Mapped to an interactable through registration. */
+    mesh: BabylonTransformNodeLike | null | undefined;
+    /** Distance from the ray origin, in metres. */
+    distance: number;
+    /** World-space hit point. */
+    point: Vec3Tuple;
+}
+/**
+ * A mesh-accurate pick supplied by the app - `scene.pickWithRay` with a Ray
+ * built from these arguments. Return null for a miss.
+ */
+export type BabylonPickWithRay = (origin: Vec3Tuple, direction: Vec3Tuple, maxDistance: number) => BabylonPickResult | null;
+export interface BabylonHitTesterOptions {
+    /** Targeting radius for a node registered without one. Default 0.1 m. */
+    defaultRadius?: number;
+    /** Ray length handed to `pickWithRay`, in metres. Default 100. */
+    maxRayDistance?: number;
+    /** Optional mesh-accurate pick. Absent, the sphere test is used. */
+    pickWithRay?: BabylonPickWithRay;
+}
+export declare class BabylonHitTester implements HitTester {
+    private readonly entries;
+    private readonly byNode;
+    private readonly defaultRadius;
+    private readonly maxRayDistance;
+    private pickWithRay;
+    constructor(options?: BabylonHitTesterOptions);
+    /** Supply or replace the mesh-accurate pick after construction. */
+    setPickWithRay(pick: BabylonPickWithRay | null): void;
+    register(id: string, node: BabylonTransformNodeLike, radius?: number): void;
+    unregister(id: string): void;
+    getNode(id: string): BabylonTransformNodeLike | undefined;
+    hitRay(ray: RayTuple): InteractableHit | null;
+    hitProximity(point: Vec3Tuple, radius: number): InteractableHit | null;
+    /** The registered interactable a picked node belongs to, if any. */
+    private ownerOf;
+}

package/dist/hit-tester.js

@@ -0,0 +1,90 @@
+import { rayPointDistance, } from "@realitycollective/webxr-interactions";
+import { nodeShowing, parentOf, toVec3 } from "./babylon-types.js";
+const DEFAULT_RADIUS = 0.1;
+const DEFAULT_MAX_RAY_DISTANCE = 100;
+export class BabylonHitTester {
+    entries = new Map();
+    byNode = new Map();
+    defaultRadius;
+    maxRayDistance;
+    pickWithRay;
+    constructor(options = {}) {
+        this.defaultRadius = options.defaultRadius ?? DEFAULT_RADIUS;
+        this.maxRayDistance = options.maxRayDistance ?? DEFAULT_MAX_RAY_DISTANCE;
+        this.pickWithRay = options.pickWithRay ?? null;
+    }
+    /** Supply or replace the mesh-accurate pick after construction. */
+    setPickWithRay(pick) {
+        this.pickWithRay = pick;
+    }
+    register(id, node, radius) {
+        this.unregister(id);
+        this.entries.set(id, { node, radius: radius ?? this.defaultRadius });
+        this.byNode.set(node, id);
+    }
+    unregister(id) {
+        const entry = this.entries.get(id);
+        if (entry)
+            this.byNode.delete(entry.node);
+        this.entries.delete(id);
+    }
+    getNode(id) {
+        return this.entries.get(id)?.node;
+    }
+    hitRay(ray) {
+        // An app-supplied pick REPLACES the sphere test for rays - it does not
+        // sit in front of it. A miss, or a hit on scenery, is the answer: the
+        // app's own pick already said what the ray reached first, and testing
+        // spheres behind it would target something the ray never got to.
+        // Proximity queries stay on the sphere test either way.
+        if (this.pickWithRay) {
+            const picked = this.pickWithRay(ray.origin, ray.direction, this.maxRayDistance);
+            if (!picked?.mesh)
+                return null;
+            const id = this.ownerOf(picked.mesh);
+            return id === null
+                ? null
+                : { interactableId: id, distance: picked.distance, point: picked.point };
+        }
+        let best = null;
+        for (const [id, { node, radius }] of this.entries) {
+            if (!nodeShowing(node))
+                continue;
+            const point = toVec3(node.getAbsolutePosition());
+            if (!point)
+                continue;
+            const { distance, t } = rayPointDistance(ray, point);
+            if (t > 0 && distance <= radius && (best === null || t < best.distance)) {
+                best = { interactableId: id, distance: t, point };
+            }
+        }
+        return best;
+    }
+    hitProximity(point, radius) {
+        let best = null;
+        for (const [id, { node, radius: targetRadius }] of this.entries) {
+            if (!nodeShowing(node))
+                continue;
+            const at = toVec3(node.getAbsolutePosition());
+            if (!at)
+                continue;
+            const distance = Math.hypot(at[0] - point[0], at[1] - point[1], at[2] - point[2]) - targetRadius;
+            if (distance <= radius && (best === null || distance < best.distance)) {
+                best = { interactableId: id, distance: Math.max(0, distance), point: at };
+            }
+        }
+        return best;
+    }
+    /** The registered interactable a picked node belongs to, if any. */
+    ownerOf(node) {
+        let current = node;
+        while (current) {
+            const id = this.byNode.get(current);
+            if (id !== undefined)
+                return id;
+            current = parentOf(current);
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=hit-tester.js.map

package/dist/hit-tester.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hit-tester.js","sourceRoot":"","sources":["../src/hit-tester.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * BabylonHitTester - resolves the core's ray and proximity queries against\n * registered Babylon nodes.\n *\n * The default test needs no Babylon raycaster: each registered node carries\n * a radius, and a query is a sphere test against the node's absolute\n * position. That is the same model the IWSDK adapter uses, and it is enough\n * for buttons, levers, dials and grabbables, which are small next to the\n * distance they are pointed at from.\n *\n * An app that wants mesh-accurate picking supplies `pickWithRay`, typically\n * a one-line wrapper over `scene.pickWithRay`. Whatever mesh it returns is\n * mapped back to an interactable id through the registration map, walking up\n * parents so a pick on a child mesh still resolves to the registered root.\n */\nimport type { RayTuple, Vec3Tuple } from \"@realitycollective/webxr-input\";\nimport {\n  rayPointDistance,\n  type HitTester,\n  type InteractableHit,\n} from \"@realitycollective/webxr-interactions\";\nimport { nodeShowing, parentOf, toVec3, type BabylonTransformNodeLike } from \"./babylon-types.js\";\n\n/** What an app's mesh-accurate pick reports back. */\nexport interface BabylonPickResult {\n  /** The node that was hit. Mapped to an interactable through registration. */\n  mesh: BabylonTransformNodeLike | null | undefined;\n  /** Distance from the ray origin, in metres. */\n  distance: number;\n  /** World-space hit point. */\n  point: Vec3Tuple;\n}\n\n/**\n * A mesh-accurate pick supplied by the app - `scene.pickWithRay` with a Ray\n * built from these arguments. Return null for a miss.\n */\nexport type BabylonPickWithRay = (\n  origin: Vec3Tuple,\n  direction: Vec3Tuple,\n  maxDistance: number,\n) => BabylonPickResult | null;\n\nexport interface BabylonHitTesterOptions {\n  /** Targeting radius for a node registered without one. Default 0.1 m. */\n  defaultRadius?: number;\n  /** Ray length handed to `pickWithRay`, in metres. Default 100. */\n  maxRayDistance?: number;\n  /** Optional mesh-accurate pick. Absent, the sphere test is used. */\n  pickWithRay?: BabylonPickWithRay;\n}\n\nconst DEFAULT_RADIUS = 0.1;\nconst DEFAULT_MAX_RAY_DISTANCE = 100;\n\nexport class BabylonHitTester implements HitTester {\n  private readonly entries = new Map<string, { node: BabylonTransformNodeLike; radius: number }>();\n  private readonly byNode = new Map<BabylonTransformNodeLike, string>();\n  private readonly defaultRadius: number;\n  private readonly maxRayDistance: number;\n  private pickWithRay: BabylonPickWithRay | null;\n\n  constructor(options: BabylonHitTesterOptions = {}) {\n    this.defaultRadius = options.defaultRadius ?? DEFAULT_RADIUS;\n    this.maxRayDistance = options.maxRayDistance ?? DEFAULT_MAX_RAY_DISTANCE;\n    this.pickWithRay = options.pickWithRay ?? null;\n  }\n\n  /** Supply or replace the mesh-accurate pick after construction. */\n  setPickWithRay(pick: BabylonPickWithRay | null): void {\n    this.pickWithRay = pick;\n  }\n\n  register(id: string, node: BabylonTransformNodeLike, radius?: number): void {\n    this.unregister(id);\n    this.entries.set(id, { node, radius: radius ?? this.defaultRadius });\n    this.byNode.set(node, id);\n  }\n\n  unregister(id: string): void {\n    const entry = this.entries.get(id);\n    if (entry) this.byNode.delete(entry.node);\n    this.entries.delete(id);\n  }\n\n  getNode(id: string): BabylonTransformNodeLike | undefined {\n    return this.entries.get(id)?.node;\n  }\n\n  hitRay(ray: RayTuple): InteractableHit | null {\n    // An app-supplied pick REPLACES the sphere test for rays - it does not\n    // sit in front of it. A miss, or a hit on scenery, is the answer: the\n    // app's own pick already said what the ray reached first, and testing\n    // spheres behind it would target something the ray never got to.\n    // Proximity queries stay on the sphere test either way.\n    if (this.pickWithRay) {\n      const picked = this.pickWithRay(ray.origin, ray.direction, this.maxRayDistance);\n      if (!picked?.mesh) return null;\n      const id = this.ownerOf(picked.mesh);\n      return id === null\n        ? null\n        : { interactableId: id, distance: picked.distance, point: picked.point };\n    }\n\n    let best: InteractableHit | null = null;\n    for (const [id, { node, radius }] of this.entries) {\n      if (!nodeShowing(node)) continue;\n      const point = toVec3(node.getAbsolutePosition());\n      if (!point) continue;\n      const { distance, t } = rayPointDistance(ray, point);\n      if (t > 0 && distance <= radius && (best === null || t < best.distance)) {\n        best = { interactableId: id, distance: t, point };\n      }\n    }\n    return best;\n  }\n\n  hitProximity(point: Vec3Tuple, radius: number): InteractableHit | null {\n    let best: InteractableHit | null = null;\n    for (const [id, { node, radius: targetRadius }] of this.entries) {\n      if (!nodeShowing(node)) continue;\n      const at = toVec3(node.getAbsolutePosition());\n      if (!at) continue;\n      const distance =\n        Math.hypot(at[0] - point[0], at[1] - point[1], at[2] - point[2]) - targetRadius;\n      if (distance <= radius && (best === null || distance < best.distance)) {\n        best = { interactableId: id, distance: Math.max(0, distance), point: at };\n      }\n    }\n    return best;\n  }\n\n  /** The registered interactable a picked node belongs to, if any. */\n  private ownerOf(node: BabylonTransformNodeLike): string | null {\n    let current: BabylonTransformNodeLike | null = node;\n    while (current) {\n      const id = this.byNode.get(current);\n      if (id !== undefined) return id;\n      current = parentOf(current);\n    }\n    return null;\n  }\n}\n"]}