@realitycollective/babylon-interactions 0.1.0-preview.2

package/dist/host.d.ts

@@ -0,0 +1,49 @@
+/**
+ * createBabylonInteractions - one-call setup for the Babylon adapter.
+ *
+ * ```ts
+ * const interactions = createBabylonInteractions({ scene, xr, attachToScene: true });
+ * interactions.register({ id: "button", behaviours: [{ kind: "press" }] }, buttonMesh);
+ * interactions.runtime.onEvent((event) => console.log(event.type));
+ * ```
+ *
+ * With `attachToScene` the render loop drives itself from
+ * `scene.onBeforeRenderObservable` and the engine's own frame delta.
+ * Without it, call `update(dt)` yourself with seconds.
+ */
+import { InteractionRuntime, type DwellConfig, type InteractableDescriptor } from "@realitycollective/webxr-interactions";
+import type { BabylonTransformNodeLike } from "./babylon-types.js";
+import { BabylonHitTester, type BabylonHitTesterOptions, type BabylonPickWithRay } from "./hit-tester.js";
+import { BabylonTransformPort, type BabylonTransformPortOptions } from "./transform-port.js";
+import { BabylonInputProvider, type BabylonProviderOptions } from "./provider.js";
+export interface BabylonInteractionsOptions extends BabylonProviderOptions, BabylonHitTesterOptions {
+    dwellDefaults?: DwellConfig;
+    /**
+     * Drive `update(dt)` from `scene.onBeforeRenderObservable`, using the
+     * engine's frame delta in seconds. Default false - the app calls
+     * `update` from its own loop.
+     */
+    attachToScene?: boolean;
+}
+export interface BabylonRegisterOptions extends BabylonTransformPortOptions {
+    /** Targeting radius for the sphere hit-tester. Default 0.1 m. */
+    targetRadius?: number;
+}
+export declare class BabylonInteractions {
+    readonly runtime: InteractionRuntime;
+    readonly provider: BabylonInputProvider;
+    readonly hitTester: BabylonHitTester;
+    private readonly ports;
+    private detachScene;
+    constructor(options: BabylonInteractionsOptions);
+    /** Supply or replace the app's mesh-accurate pick. */
+    setPickWithRay(pick: BabylonPickWithRay | null): void;
+    /** Register an interactable with its Babylon node. */
+    register(descriptor: InteractableDescriptor, node: BabylonTransformNodeLike, options?: BabylonRegisterOptions): BabylonTransformPort;
+    unregister(id: string): void;
+    getPort(id: string): BabylonTransformPort | undefined;
+    update(dt: number): void;
+    dispose(): void;
+    private attachToScene;
+}
+export declare function createBabylonInteractions(options: BabylonInteractionsOptions): BabylonInteractions;

package/dist/host.js

@@ -0,0 +1,86 @@
+/**
+ * createBabylonInteractions - one-call setup for the Babylon adapter.
+ *
+ * ```ts
+ * const interactions = createBabylonInteractions({ scene, xr, attachToScene: true });
+ * interactions.register({ id: "button", behaviours: [{ kind: "press" }] }, buttonMesh);
+ * interactions.runtime.onEvent((event) => console.log(event.type));
+ * ```
+ *
+ * With `attachToScene` the render loop drives itself from
+ * `scene.onBeforeRenderObservable` and the engine's own frame delta.
+ * Without it, call `update(dt)` yourself with seconds.
+ */
+import { InteractionRuntime, } from "@realitycollective/webxr-interactions";
+import { BabylonHitTester, } from "./hit-tester.js";
+import { BabylonTransformPort } from "./transform-port.js";
+import { BabylonInputProvider } from "./provider.js";
+/** Longest frame the scene-attached loop will report, in seconds. */
+const MAX_FRAME_SECONDS = 0.1;
+export class BabylonInteractions {
+    runtime;
+    provider;
+    hitTester;
+    ports = new Map();
+    detachScene = null;
+    constructor(options) {
+        this.provider = new BabylonInputProvider(options);
+        this.hitTester = new BabylonHitTester(options);
+        this.runtime = new InteractionRuntime({
+            provider: this.provider,
+            hitTester: this.hitTester,
+            ...(options.dwellDefaults ? { dwellDefaults: options.dwellDefaults } : {}),
+        });
+        if (options.attachToScene)
+            this.attachToScene(options);
+    }
+    /** Supply or replace the app's mesh-accurate pick. */
+    setPickWithRay(pick) {
+        this.hitTester.setPickWithRay(pick);
+    }
+    /** Register an interactable with its Babylon node. */
+    register(descriptor, node, options = {}) {
+        const port = new BabylonTransformPort(node, options.createQuaternion ? { createQuaternion: options.createQuaternion } : {});
+        this.ports.set(descriptor.id, port);
+        this.hitTester.register(descriptor.id, node, options.targetRadius);
+        this.runtime.registerInteractable(descriptor, { transform: port });
+        return port;
+    }
+    unregister(id) {
+        this.runtime.unregisterInteractable(id);
+        this.hitTester.unregister(id);
+        this.ports.delete(id);
+    }
+    getPort(id) {
+        return this.ports.get(id);
+    }
+    update(dt) {
+        this.runtime.update(dt);
+    }
+    dispose() {
+        this.detachScene?.();
+        this.detachScene = null;
+        this.runtime.dispose();
+        this.provider.dispose();
+    }
+    attachToScene(options) {
+        const observable = options.scene.onBeforeRenderObservable;
+        if (!observable)
+            return;
+        const engine = options.scene.getEngine?.();
+        const observer = observable.add(() => {
+            // Babylon reports the frame delta in milliseconds. A long frame - a tab
+            // that was backgrounded, a slow first frame - is clamped so behaviours
+            // integrate over a sane step rather than jumping.
+            const ms = engine?.getDeltaTime() ?? 0;
+            this.update(Math.min(MAX_FRAME_SECONDS, Math.max(0, ms / 1000)));
+        });
+        this.detachScene = () => {
+            observable.remove(observer);
+        };
+    }
+}
+export function createBabylonInteractions(options) {
+    return new BabylonInteractions(options);
+}
+//# sourceMappingURL=host.js.map

package/dist/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * createBabylonInteractions - one-call setup for the Babylon adapter.\n *\n * ```ts\n * const interactions = createBabylonInteractions({ scene, xr, attachToScene: true });\n * interactions.register({ id: \"button\", behaviours: [{ kind: \"press\" }] }, buttonMesh);\n * interactions.runtime.onEvent((event) => console.log(event.type));\n * ```\n *\n * With `attachToScene` the render loop drives itself from\n * `scene.onBeforeRenderObservable` and the engine's own frame delta.\n * Without it, call `update(dt)` yourself with seconds.\n */\nimport {\n  InteractionRuntime,\n  type DwellConfig,\n  type InteractableDescriptor,\n} from \"@realitycollective/webxr-interactions\";\nimport type { BabylonTransformNodeLike } from \"./babylon-types.js\";\nimport {\n  BabylonHitTester,\n  type BabylonHitTesterOptions,\n  type BabylonPickWithRay,\n} from \"./hit-tester.js\";\nimport { BabylonTransformPort, type BabylonTransformPortOptions } from \"./transform-port.js\";\nimport { BabylonInputProvider, type BabylonProviderOptions } from \"./provider.js\";\n\nexport interface BabylonInteractionsOptions\n  extends BabylonProviderOptions,\n    BabylonHitTesterOptions {\n  dwellDefaults?: DwellConfig;\n  /**\n   * Drive `update(dt)` from `scene.onBeforeRenderObservable`, using the\n   * engine's frame delta in seconds. Default false - the app calls\n   * `update` from its own loop.\n   */\n  attachToScene?: boolean;\n}\n\nexport interface BabylonRegisterOptions extends BabylonTransformPortOptions {\n  /** Targeting radius for the sphere hit-tester. Default 0.1 m. */\n  targetRadius?: number;\n}\n\n/** Longest frame the scene-attached loop will report, in seconds. */\nconst MAX_FRAME_SECONDS = 0.1;\n\nexport class BabylonInteractions {\n  readonly runtime: InteractionRuntime;\n  readonly provider: BabylonInputProvider;\n  readonly hitTester: BabylonHitTester;\n  private readonly ports = new Map<string, BabylonTransformPort>();\n  private detachScene: (() => void) | null = null;\n\n  constructor(options: BabylonInteractionsOptions) {\n    this.provider = new BabylonInputProvider(options);\n    this.hitTester = new BabylonHitTester(options);\n    this.runtime = new InteractionRuntime({\n      provider: this.provider,\n      hitTester: this.hitTester,\n      ...(options.dwellDefaults ? { dwellDefaults: options.dwellDefaults } : {}),\n    });\n    if (options.attachToScene) this.attachToScene(options);\n  }\n\n  /** Supply or replace the app's mesh-accurate pick. */\n  setPickWithRay(pick: BabylonPickWithRay | null): void {\n    this.hitTester.setPickWithRay(pick);\n  }\n\n  /** Register an interactable with its Babylon node. */\n  register(\n    descriptor: InteractableDescriptor,\n    node: BabylonTransformNodeLike,\n    options: BabylonRegisterOptions = {},\n  ): BabylonTransformPort {\n    const port = new BabylonTransformPort(\n      node,\n      options.createQuaternion ? { createQuaternion: options.createQuaternion } : {},\n    );\n    this.ports.set(descriptor.id, port);\n    this.hitTester.register(descriptor.id, node, options.targetRadius);\n    this.runtime.registerInteractable(descriptor, { transform: port });\n    return port;\n  }\n\n  unregister(id: string): void {\n    this.runtime.unregisterInteractable(id);\n    this.hitTester.unregister(id);\n    this.ports.delete(id);\n  }\n\n  getPort(id: string): BabylonTransformPort | undefined {\n    return this.ports.get(id);\n  }\n\n  update(dt: number): void {\n    this.runtime.update(dt);\n  }\n\n  dispose(): void {\n    this.detachScene?.();\n    this.detachScene = null;\n    this.runtime.dispose();\n    this.provider.dispose();\n  }\n\n  private attachToScene(options: BabylonInteractionsOptions): void {\n    const observable = options.scene.onBeforeRenderObservable;\n    if (!observable) return;\n    const engine = options.scene.getEngine?.();\n    const observer = observable.add(() => {\n      // Babylon reports the frame delta in milliseconds. A long frame - a tab\n      // that was backgrounded, a slow first frame - is clamped so behaviours\n      // integrate over a sane step rather than jumping.\n      const ms = engine?.getDeltaTime() ?? 0;\n      this.update(Math.min(MAX_FRAME_SECONDS, Math.max(0, ms / 1000)));\n    });\n    this.detachScene = () => {\n      observable.remove(observer);\n    };\n  }\n}\n\nexport function createBabylonInteractions(\n  options: BabylonInteractionsOptions,\n): BabylonInteractions {\n  return new BabylonInteractions(options);\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @realitycollective/babylon-interactions - the Babylon.js engine adapter:
+ * Babylon WebXR input, sphere or app-supplied hit-testing, and transform
+ * ports over Babylon nodes. The core is re-exported wholesale, so apps
+ * depend on exactly this package.
+ *
+ * Structurally typed against the Babylon API rather than importing
+ * `@babylonjs/core`, in the same way as the XR Blocks adapter, so an
+ * upstream release cannot break the install.
+ */
+export * from "@realitycollective/webxr-interactions";
+export * from "./babylon-types.js";
+export * from "./provider.js";
+export * from "./hit-tester.js";
+export * from "./transform-port.js";
+export * from "./host.js";

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * @realitycollective/babylon-interactions - the Babylon.js engine adapter:
+ * Babylon WebXR input, sphere or app-supplied hit-testing, and transform
+ * ports over Babylon nodes. The core is re-exported wholesale, so apps
+ * depend on exactly this package.
+ *
+ * Structurally typed against the Babylon API rather than importing
+ * `@babylonjs/core`, in the same way as the XR Blocks adapter, so an
+ * upstream release cannot break the install.
+ */
+export * from "@realitycollective/webxr-interactions";
+export * from "./babylon-types.js";
+export * from "./provider.js";
+export * from "./hit-tester.js";
+export * from "./transform-port.js";
+export * from "./host.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,cAAc,uCAAuC,CAAC;AAEtD,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,WAAW,CAAC","sourcesContent":["/**\n * @realitycollective/babylon-interactions - the Babylon.js engine adapter:\n * Babylon WebXR input, sphere or app-supplied hit-testing, and transform\n * ports over Babylon nodes. The core is re-exported wholesale, so apps\n * depend on exactly this package.\n *\n * Structurally typed against the Babylon API rather than importing\n * `@babylonjs/core`, in the same way as the XR Blocks adapter, so an\n * upstream release cannot break the install.\n */\nexport * from \"@realitycollective/webxr-interactions\";\n\nexport * from \"./babylon-types.js\";\nexport * from \"./provider.js\";\nexport * from \"./hit-tester.js\";\nexport * from \"./transform-port.js\";\nexport * from \"./host.js\";\n"]}

package/dist/provider.d.ts

@@ -0,0 +1,113 @@
+/**
+ * BabylonInputProvider - the Babylon.js input provider.
+ *
+ * Reads a `WebXRDefaultExperience`: its `input.controllers` for poses and
+ * motion-controller components, its session manager for what is live, and
+ * the hand-tracking feature for fingertip joints. Falls back to the scene's
+ * own pointer (`scene.onPointerObservable`) when no immersive session is
+ * running, so the same scene is usable in a flat browser.
+ *
+ * Nothing here imports `@babylonjs/core` - see `babylon-types.ts`.
+ *
+ * Capabilities are derived from the LIVE session, never from the requested
+ * configuration, and are re-published on session start, session end and
+ * controller add/remove.
+ */
+import { type HeadPose, type InputCapabilities, type InputProvider, type InputSourceSnapshot, type Unsubscribe } from "@realitycollective/webxr-input";
+import { type BabylonCameraLike, type BabylonSceneLike, type BabylonXRExperienceLike } from "./babylon-types.js";
+export interface BabylonProviderOptions {
+    /**
+     * The `WebXRDefaultExperience` (or anything with the same surface).
+     * Omit it, or pass null, for a desktop-only app: the provider then only
+     * ever reports the scene pointer.
+     */
+    xr?: BabylonXRExperienceLike | null;
+    /** The scene. Supplies the pointer fallback, the camera and the engine. */
+    scene: BabylonSceneLike;
+    /** Head pose camera. Defaults to `scene.activeCamera`. */
+    camera?: BabylonCameraLike | null;
+    /**
+     * Metres along the pointer ray at which the desktop fallback places its
+     * synthetic grip pose. Default 1 metre, matching the three.js adapter, so
+     * grab, hinge, dial and slide follow the cursor on desktop. Set it near
+     * the distance of the things being manipulated; at 0 the grip sits on the
+     * camera and a mouse drag reports camera motion only.
+     */
+    desktopGripDistance?: number;
+}
+/** Which side's visual a presence call targets. `"all"` is both. */
+export type PresenceTarget = "left" | "right" | "none" | "all";
+/**
+ * Which family of visuals presence shows. Babylon chooses this per input
+ * source, so this provider reports every mode as unavailable.
+ */
+export type PresenceModality = "hands" | "controllers" | "auto";
+/** The desktop pointer source's id - stable for the life of the page. */
+export declare const DESKTOP_SOURCE_ID = "babylon-pointer";
+export declare class BabylonInputProvider implements InputProvider {
+    private readonly options;
+    private capabilities;
+    private readonly capsListeners;
+    private readonly sourceListeners;
+    /** id -> handedness + controller, recorded while sampling, read by pulse. */
+    private readonly sampled;
+    private readonly detach;
+    private readonly gripDistance;
+    /** Read once from `scene.useRightHandedSystem`; flips forward to -Z. */
+    private readonly rightHanded;
+    private readonly pointer;
+    constructor(options: BabylonProviderOptions);
+    private attachPointer;
+    private onPointer;
+    private attachSession;
+    /** The live XR session, or null when none is running. */
+    private session;
+    private controllers;
+    /** The hand-tracking feature, when the app enabled it. */
+    private handTracking;
+    private handFor;
+    private refreshCapabilities;
+    getCapabilities(): InputCapabilities;
+    onCapabilitiesChanged(listener: (c: InputCapabilities) => void): Unsubscribe;
+    onSourcesChanged(listener: () => void): Unsubscribe;
+    sample(): readonly InputSourceSnapshot[];
+    /**
+     * The desktop pointer, shaped like the three.js adapter's mouse fallback:
+     * one source, `handedness: "none"`, `kind: "pointer2d"`.
+     */
+    private samplePointer;
+    /** Pick the scene at the last known cursor position for a ray. */
+    private pickRay;
+    private camera;
+    getHeadPose(): HeadPose;
+    /**
+     * Babylon routes haptics through the motion controller rather than the
+     * gamepad actuator, so a source with no motion controller cannot pulse
+     * even when the gamepad reports an actuator.
+     */
+    pulse(sourceId: string, intensity: number, durationMs: number): boolean;
+    /**
+     * True when Babylon has built at least one visual this provider can hide:
+     * a motion controller root mesh, or a hand mesh from the hand-tracking
+     * feature. Becomes `capabilities.presence` at
+     * `@realitycollective/webxr-input` 0.1.1.
+     */
+    get supportsPresence(): boolean;
+    /**
+     * Show or hide the visuals Babylon built for the targeted sides. Returns
+     * false when the target has nothing to show or hide. `"none"` targets no
+     * side, so it reports whether presence is usable at all without changing
+     * anything.
+     */
+    setPresenceVisible(target: PresenceTarget, visible: boolean): boolean;
+    /**
+     * Always false. Babylon picks the visual per input source - a controller
+     * gets its motion-controller model, a tracked hand gets the hand mesh -
+     * and exposes no switch between the two. IWSDK builds both families, so
+     * its adapter implements this.
+     */
+    setPresenceModality(_mode: PresenceModality): boolean;
+    /** Every node that represents this controller on screen. */
+    private visualsFor;
+    dispose(): void;
+}

package/dist/provider.js

@@ -0,0 +1,371 @@
+/**
+ * BabylonInputProvider - the Babylon.js input provider.
+ *
+ * Reads a `WebXRDefaultExperience`: its `input.controllers` for poses and
+ * motion-controller components, its session manager for what is live, and
+ * the hand-tracking feature for fingertip joints. Falls back to the scene's
+ * own pointer (`scene.onPointerObservable`) when no immersive session is
+ * running, so the same scene is usable in a flat browser.
+ *
+ * Nothing here imports `@babylonjs/core` - see `babylon-types.ts`.
+ *
+ * Capabilities are derived from the LIVE session, never from the requested
+ * configuration, and are re-published on session start, session end and
+ * controller add/remove.
+ */
+import { NO_CAPABILITIES, } from "@realitycollective/webxr-input";
+import { HAND_TRACKING_FEATURE, INDEX_TIP_JOINT, POINTER_EVENT_TYPES, nodeForward, defaultForward, nodeWorldPose, toQuat, toVec3, } from "./babylon-types.js";
+/** Trigger, then the main component, then nothing. */
+const TRIGGER_COMPONENT = "trigger";
+const SQUEEZE_COMPONENT = "squeeze";
+/** The desktop pointer source's id - stable for the life of the page. */
+export const DESKTOP_SOURCE_ID = "babylon-pointer";
+export class BabylonInputProvider {
+    options;
+    capabilities;
+    capsListeners = new Set();
+    sourceListeners = new Set();
+    /** id -> handedness + controller, recorded while sampling, read by pulse. */
+    sampled = new Map();
+    detach = [];
+    gripDistance;
+    /** Read once from `scene.useRightHandedSystem`; flips forward to -Z. */
+    rightHanded;
+    pointer = { down: false, x: 0, y: 0, ray: null };
+    constructor(options) {
+        this.options = options;
+        this.gripDistance = options.desktopGripDistance ?? 1;
+        this.rightHanded = options.scene.useRightHandedSystem === true;
+        this.capabilities = { ...NO_CAPABILITIES, headPose: true, gaze: true };
+        this.attachPointer();
+        this.attachSession();
+        this.refreshCapabilities();
+    }
+    // -- wiring -------------------------------------------------------------------
+    attachPointer() {
+        const observable = this.options.scene.onPointerObservable;
+        if (!observable)
+            return;
+        const observer = observable.add((info) => this.onPointer(info));
+        this.detach.push(() => {
+            observable.remove(observer);
+        });
+    }
+    onPointer(info) {
+        const event = info.event;
+        if (event?.clientX !== undefined)
+            this.pointer.x = event.clientX;
+        if (event?.clientY !== undefined)
+            this.pointer.y = event.clientY;
+        // Babylon hands the pick it already did for this event; reuse it rather
+        // than picking the scene a second time on the next sample.
+        const ray = info.pickInfo?.ray;
+        if (ray) {
+            this.pointer.ray = {
+                origin: toVec3(ray.origin) ?? [0, 0, 0],
+                direction: toVec3(ray.direction) ?? defaultForward(this.rightHanded),
+            };
+        }
+        // Only the primary button selects. Babylon reports it as button 0, the
+        // same numbering as a DOM PointerEvent.
+        if (info.type === POINTER_EVENT_TYPES.down && (event?.button ?? 0) === 0) {
+            this.pointer.down = true;
+        }
+        if (info.type === POINTER_EVENT_TYPES.up && (event?.button ?? 0) === 0) {
+            this.pointer.down = false;
+        }
+    }
+    attachSession() {
+        const manager = this.options.xr?.baseExperience?.sessionManager;
+        const input = this.options.xr?.input;
+        const republish = () => {
+            this.refreshCapabilities();
+            for (const listener of [...this.sourceListeners])
+                listener();
+        };
+        const subscribe = (observable, handler) => {
+            if (!observable)
+                return;
+            const observer = observable.add(() => handler());
+            this.detach.push(() => {
+                observable.remove(observer);
+            });
+        };
+        subscribe(manager?.onXRSessionInit, republish);
+        subscribe(manager?.onXRSessionEnded, () => {
+            this.sampled.clear();
+            republish();
+        });
+        subscribe(input?.onControllerAddedObservable, republish);
+        subscribe(input?.onControllerRemovedObservable, republish);
+    }
+    // -- capabilities -------------------------------------------------------------
+    /** The live XR session, or null when none is running. */
+    session() {
+        return this.options.xr?.baseExperience?.sessionManager?.session ?? null;
+    }
+    controllers() {
+        return this.options.xr?.input?.controllers ?? [];
+    }
+    /** The hand-tracking feature, when the app enabled it. */
+    handTracking() {
+        const manager = this.options.xr?.baseExperience?.featuresManager;
+        if (!manager)
+            return null;
+        const feature = manager.getEnabledFeature(HAND_TRACKING_FEATURE);
+        if (!feature || typeof feature !== "object")
+            return null;
+        const candidate = feature;
+        return typeof candidate.getHandByControllerId === "function"
+            ? feature
+            : null;
+    }
+    handFor(controller) {
+        return this.handTracking()?.getHandByControllerId(controller.uniqueId) ?? null;
+    }
+    refreshCapabilities() {
+        const inSession = this.session() !== null;
+        const desktop = !inSession && this.options.scene.onPointerObservable !== undefined;
+        // Babylon reports no native grab observation, so grabs are always
+        // poseOnly: the core drives the transform through the port.
+        const next = {
+            ...NO_CAPABILITIES,
+            headPose: true,
+            gaze: true,
+            pointer2d: desktop,
+            // The pointer fallback synthesises a grip on the ray, so hand-driven
+            // behaviours negotiate on desktop too. Without this every one of them
+            // switches itself off off-headset and only press remains usable.
+            grabs: desktop ? "poseOnly" : NO_CAPABILITIES.grabs,
+        };
+        if (inSession) {
+            for (const controller of this.controllers()) {
+                if (controller.pointer)
+                    next.rays = true;
+                if (controller.grip ?? controller.pointer)
+                    next.grabs = "poseOnly";
+                if (controller.inputSource.hand) {
+                    next.handJoints = true;
+                    next.pokes = true;
+                }
+                // Pinch strength needs the tracked hand itself, not just the flag on
+                // the input source, so it is gated on the feature reporting a hand.
+                if (this.handFor(controller))
+                    next.pinch = true;
+                if (controller.motionController)
+                    next.buttonsAxes = true;
+                if ((controller.inputSource.gamepad?.hapticActuators?.length ?? 0) > 0) {
+                    next.haptics = true;
+                }
+            }
+        }
+        const changed = JSON.stringify(next) !== JSON.stringify(this.capabilities);
+        this.capabilities = next;
+        if (changed) {
+            for (const listener of [...this.capsListeners])
+                listener(next);
+        }
+    }
+    getCapabilities() {
+        return this.capabilities;
+    }
+    onCapabilitiesChanged(listener) {
+        this.capsListeners.add(listener);
+        return () => this.capsListeners.delete(listener);
+    }
+    onSourcesChanged(listener) {
+        this.sourceListeners.add(listener);
+        return () => this.sourceListeners.delete(listener);
+    }
+    // -- sampling -----------------------------------------------------------------
+    sample() {
+        this.sampled.clear();
+        if (this.session() === null) {
+            // A session that ended between frames leaves stale capabilities behind.
+            if (this.capabilities.rays)
+                this.refreshCapabilities();
+            return this.samplePointer();
+        }
+        const snapshots = [];
+        for (const controller of this.controllers()) {
+            const handedness = normalizeHandedness(controller.inputSource.handedness);
+            const hand = this.handFor(controller);
+            const pointerNode = controller.pointer;
+            const snapshot = {
+                id: controller.uniqueId,
+                kind: controller.inputSource.hand ? "hand" : "controller",
+                handedness,
+                select: componentValue(controller.motionController?.getComponentOfType?.(TRIGGER_COMPONENT) ??
+                    controller.motionController?.getMainComponent?.() ??
+                    null),
+                squeeze: componentValue(controller.motionController?.getComponentOfType?.(SQUEEZE_COMPONENT) ?? null),
+            };
+            if (pointerNode) {
+                snapshot.ray = {
+                    origin: toVec3(pointerNode.getAbsolutePosition()) ?? [0, 0, 0],
+                    direction: nodeForward(pointerNode, this.rightHanded),
+                };
+            }
+            // Babylon exposes the grip node only for a controller with one; a hand,
+            // and a controller without a grip space, carry on the pointer node.
+            const gripNode = controller.grip ?? pointerNode;
+            if (gripNode)
+                snapshot.gripPose = nodeWorldPose(gripNode);
+            const tip = jointPosition(hand, INDEX_TIP_JOINT);
+            if (tip)
+                snapshot.indexTip = tip;
+            if ((controller.inputSource.gamepad?.hapticActuators?.length ?? 0) > 0) {
+                snapshot.hapticsAvailable = true;
+            }
+            // Babylon reports no per-pose velocity, so nothing is set here and the
+            // core's VelocityTracker derives it from consecutive grip poses.
+            snapshots.push(snapshot);
+            this.sampled.set(snapshot.id, { handedness, controller });
+        }
+        return snapshots;
+    }
+    /**
+     * The desktop pointer, shaped like the three.js adapter's mouse fallback:
+     * one source, `handedness: "none"`, `kind: "pointer2d"`.
+     */
+    samplePointer() {
+        if (this.options.scene.onPointerObservable === undefined)
+            return [];
+        const ray = this.pointer.ray ?? this.pickRay();
+        if (!ray)
+            return [];
+        const grip = [
+            ray.origin[0] + ray.direction[0] * this.gripDistance,
+            ray.origin[1] + ray.direction[1] * this.gripDistance,
+            ray.origin[2] + ray.direction[2] * this.gripDistance,
+        ];
+        return [
+            {
+                id: DESKTOP_SOURCE_ID,
+                kind: "pointer2d",
+                handedness: "none",
+                ray: { origin: ray.origin, direction: ray.direction },
+                gripPose: { position: grip, quaternion: toQuat(this.camera()?.absoluteRotation) },
+                select: this.pointer.down ? 1 : 0,
+                // A mouse has one button that means select. Squeeze stays 0 rather
+                // than doubling the left button up as both, which would fire a press
+                // and a grab together on an interactable that carries both.
+                squeeze: 0,
+            },
+        ];
+    }
+    /** Pick the scene at the last known cursor position for a ray. */
+    pickRay() {
+        const picked = this.options.scene.pick?.(this.pointer.x, this.pointer.y);
+        const ray = picked?.ray;
+        if (!ray)
+            return null;
+        return {
+            origin: toVec3(ray.origin) ?? [0, 0, 0],
+            direction: toVec3(ray.direction) ?? defaultForward(this.rightHanded),
+        };
+    }
+    camera() {
+        return this.options.camera ?? this.options.scene.activeCamera ?? null;
+    }
+    getHeadPose() {
+        const camera = this.camera();
+        return {
+            position: toVec3(camera?.globalPosition ?? camera?.position) ?? [0, 0, 0],
+            quaternion: toQuat(camera?.absoluteRotation),
+        };
+    }
+    // -- haptics ------------------------------------------------------------------
+    /**
+     * Babylon routes haptics through the motion controller rather than the
+     * gamepad actuator, so a source with no motion controller cannot pulse
+     * even when the gamepad reports an actuator.
+     */
+    pulse(sourceId, intensity, durationMs) {
+        const controller = this.sampled.get(sourceId)?.controller ??
+            this.controllers().find((c) => c.uniqueId === sourceId);
+        const motionController = controller?.motionController;
+        if (!motionController?.pulse)
+            return false;
+        void motionController.pulse(Math.min(1, Math.max(0, intensity)), durationMs);
+        return true;
+    }
+    // -- presence -----------------------------------------------------------------
+    /**
+     * True when Babylon has built at least one visual this provider can hide:
+     * a motion controller root mesh, or a hand mesh from the hand-tracking
+     * feature. Becomes `capabilities.presence` at
+     * `@realitycollective/webxr-input` 0.1.1.
+     */
+    get supportsPresence() {
+        for (const controller of this.controllers()) {
+            if (this.visualsFor(controller).length > 0)
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Show or hide the visuals Babylon built for the targeted sides. Returns
+     * false when the target has nothing to show or hide. `"none"` targets no
+     * side, so it reports whether presence is usable at all without changing
+     * anything.
+     */
+    setPresenceVisible(target, visible) {
+        if (target === "none")
+            return this.supportsPresence;
+        let applied = false;
+        for (const controller of this.controllers()) {
+            const side = normalizeHandedness(controller.inputSource.handedness);
+            if (target !== "all" && target !== side)
+                continue;
+            for (const node of this.visualsFor(controller)) {
+                node.setEnabled?.(visible);
+                applied = true;
+            }
+        }
+        return applied;
+    }
+    /**
+     * Always false. Babylon picks the visual per input source - a controller
+     * gets its motion-controller model, a tracked hand gets the hand mesh -
+     * and exposes no switch between the two. IWSDK builds both families, so
+     * its adapter implements this.
+     */
+    setPresenceModality(_mode) {
+        return false;
+    }
+    /** Every node that represents this controller on screen. */
+    visualsFor(controller) {
+        const nodes = [];
+        const root = controller.motionController?.rootMesh;
+        if (root)
+            nodes.push(root);
+        const handMesh = this.handFor(controller)?.handMesh;
+        if (handMesh)
+            nodes.push(handMesh);
+        return nodes;
+    }
+    dispose() {
+        for (const off of this.detach.splice(0))
+            off();
+        this.sampled.clear();
+        this.capsListeners.clear();
+        this.sourceListeners.clear();
+    }
+}
+/** Analog value where the component reports one, else the pressed flag. */
+function componentValue(component) {
+    if (!component)
+        return 0;
+    if (typeof component.value === "number" && component.value > 0)
+        return component.value;
+    return component.pressed ? 1 : 0;
+}
+function jointPosition(hand, joint) {
+    const mesh = hand?.getJointMesh?.(joint);
+    return mesh ? toVec3(mesh.getAbsolutePosition()) : null;
+}
+function normalizeHandedness(value) {
+    return value === "left" || value === "right" ? value : "none";
+}
+//# sourceMappingURL=provider.js.map