npm - @realitycollective/xrblocks-interactions - Versions diffs - 0.1.0-preview.0 - Mend

@realitycollective/xrblocks-interactions 0.1.0-preview.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,21 @@
+# Changelog
+Change log for the Reality Collective WebXR Interaction Extensions packages. All four 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.
+### Notes
+- All four 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.
+[0.1.0]: https://github.com/realitycollective/WebXR-Interactions/commits/main

package/LICENSE ADDED Viewed

@@ -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 ADDED Viewed

@@ -0,0 +1,42 @@
+# @realitycollective/xrblocks-interactions
+> **EXPERIMENTAL.** The XR Blocks pipeline is young and its API still moves. Treat this adapter as a preview and pin your versions.
+The Google XR Blocks adapter for the Reality Collective Interaction Extensions. It feeds XR Blocks' input into the [`@realitycollective/webxr-interactions`](https://www.npmjs.com/package/@realitycollective/webxr-interactions) core, reusing the three.js adapter's hit-testing and object movement.
+```sh
+npm install @realitycollective/xrblocks-interactions three
+```
+It re-exports everything from the core, so this is the only interaction package your app needs.
+## What it binds
+| Layer | Detail |
+| --- | --- |
+| **Input** | `Input.getFrame()` ray sources and direct touches; XR Blocks `Script` select events |
+| **Hit-testing** | Shared with the three.js adapter |
+| **No xrblocks dependency** | It matches the shape of the XR Blocks API in TypeScript rather than importing `xrblocks`, so an upstream release cannot break your install |
+| **Haptics** | XR Blocks has none, so haptic requests are reported but never played |
+Structurally typed against xrblocks **v0.20.0**.
+## Known constraint
+xrblocks declares a peer of `three@^0.184` while Meta's IWSDK mandates the `super-three@0.181` fork. A bundler resolves a single `three` per bundle, so the pairing works in practice, but npm's peer check cannot express it - the Reality Collective workspaces set `legacy-peer-deps=true` for this reason.
+## Peer dependency
+`three >= 0.170.0`.
+## 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)**
+## Documentation
+See the [repository README](https://github.com/realitycollective/WebXR-Interactions#readme).
+## License
+MIT - see [LICENSE](./LICENSE).

package/dist/host.d.ts ADDED Viewed

@@ -0,0 +1,37 @@
+/**
+ * connectXRBlocksInteractions - EXPERIMENTAL one-call setup.
+ *
+ * XR Blocks Scripts are ordinary three.js Object3Ds, so the shim reuses
+ * the three.js adapter's hit-tester and transform ports; only the input
+ * provider is XR Blocks-specific.
+ *
+ * ```ts
+ * import * as xb from 'xrblocks';
+ * class MyScript extends xb.Script {
+ *   init() {
+ *     this.ix = connectXRBlocksInteractions({ input: xb.input, camera: xb.camera });
+ *     this.ix.register({ id: "button", behaviours: [{ kind: "press" }] }, buttonMesh);
+ *   }
+ *   update() { this.ix.update(xb.getDeltaTime()); }
+ * }
+ * ```
+ */
+import type { Object3D } from "three";
+import { InteractionRuntime, ThreeHitTester, ThreeTransformPort, type DwellConfig, type InteractableDescriptor } from "@realitycollective/threejs-interactions";
+import { XRBlocksInputProvider, type XRBlocksContext } from "./provider.js";
+export interface XRBlocksInteractionsOptions extends XRBlocksContext {
+    dwellDefaults?: DwellConfig;
+}
+export declare class XRBlocksInteractions {
+    readonly runtime: InteractionRuntime;
+    readonly provider: XRBlocksInputProvider;
+    readonly hitTester: ThreeHitTester;
+    private readonly ports;
+    constructor(options: XRBlocksInteractionsOptions);
+    register(descriptor: InteractableDescriptor, object: Object3D): ThreeTransformPort;
+    unregister(id: string): void;
+    getPort(id: string): ThreeTransformPort | undefined;
+    update(dt: number): void;
+    dispose(): void;
+}
+export declare function connectXRBlocksInteractions(options: XRBlocksInteractionsOptions): XRBlocksInteractions;

package/dist/host.js ADDED Viewed

@@ -0,0 +1,42 @@
+import { InteractionRuntime, ThreeHitTester, ThreeTransformPort, } from "@realitycollective/threejs-interactions";
+import { XRBlocksInputProvider } from "./provider.js";
+export class XRBlocksInteractions {
+    runtime;
+    provider;
+    hitTester;
+    ports = new Map();
+    constructor(options) {
+        this.provider = new XRBlocksInputProvider(options);
+        this.hitTester = new ThreeHitTester();
+        this.runtime = new InteractionRuntime({
+            provider: this.provider,
+            hitTester: this.hitTester,
+            ...(options.dwellDefaults ? { dwellDefaults: options.dwellDefaults } : {}),
+        });
+    }
+    register(descriptor, object) {
+        const port = new ThreeTransformPort(object);
+        this.ports.set(descriptor.id, port);
+        this.hitTester.register(descriptor.id, object);
+        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.runtime.dispose();
+    }
+}
+export function connectXRBlocksInteractions(options) {
+    return new XRBlocksInteractions(options);
+}
+//# sourceMappingURL=host.js.map

package/dist/host.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"host.js","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAmBA,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,kBAAkB,GAGnB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,qBAAqB,EAAwB,MAAM,eAAe,CAAC;AAM5E,MAAM,OAAO,oBAAoB;IACtB,OAAO,CAAqB;IAC5B,QAAQ,CAAwB;IAChC,SAAS,CAAiB;IAClB,KAAK,GAAG,IAAI,GAAG,EAA8B,CAAC;IAE/D,YAAY,OAAoC;QAC9C,IAAI,CAAC,QAAQ,GAAG,IAAI,qBAAqB,CAAC,OAAO,CAAC,CAAC;QACnD,IAAI,CAAC,SAAS,GAAG,IAAI,cAAc,EAAE,CAAC;QACtC,IAAI,CAAC,OAAO,GAAG,IAAI,kBAAkB,CAAC;YACpC,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC3E,CAAC,CAAC;IACL,CAAC;IAED,QAAQ,CAAC,UAAkC,EAAE,MAAgB;QAC3D,MAAM,IAAI,GAAG,IAAI,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAC5C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QAC/C,IAAI,CAAC,OAAO,CAAC,oBAAoB,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACnE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,UAAU,CAAC,EAAU;QACnB,IAAI,CAAC,OAAO,CAAC,sBAAsB,CAAC,EAAE,CAAC,CAAC;QACxC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QAC9B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC;IAED,OAAO,CAAC,EAAU;QAChB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED,MAAM,CAAC,EAAU;QACf,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC1B,CAAC;IAED,OAAO;QACL,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IACzB,CAAC;CACF;AAED,MAAM,UAAU,2BAA2B,CACzC,OAAoC;IAEpC,OAAO,IAAI,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC3C,CAAC","sourcesContent":["/**\n * connectXRBlocksInteractions - EXPERIMENTAL one-call setup.\n *\n * XR Blocks Scripts are ordinary three.js Object3Ds, so the shim reuses\n * the three.js adapter's hit-tester and transform ports; only the input\n * provider is XR Blocks-specific.\n *\n * ```ts\n * import * as xb from 'xrblocks';\n * class MyScript extends xb.Script {\n * init() {\n * this.ix = connectXRBlocksInteractions({ input: xb.input, camera: xb.camera });\n * this.ix.register({ id: \"button\", behaviours: [{ kind: \"press\" }] }, buttonMesh);\n * }\n * update() { this.ix.update(xb.getDeltaTime()); }\n * }\n * ```\n */\nimport type { Object3D } from \"three\";\nimport {\n InteractionRuntime,\n ThreeHitTester,\n ThreeTransformPort,\n type DwellConfig,\n type InteractableDescriptor,\n} from \"@realitycollective/threejs-interactions\";\nimport { XRBlocksInputProvider, type XRBlocksContext } from \"./provider.js\";\n\nexport interface XRBlocksInteractionsOptions extends XRBlocksContext {\n dwellDefaults?: DwellConfig;\n}\n\nexport class XRBlocksInteractions {\n readonly runtime: InteractionRuntime;\n readonly provider: XRBlocksInputProvider;\n readonly hitTester: ThreeHitTester;\n private readonly ports = new Map<string, ThreeTransformPort>();\n\n constructor(options: XRBlocksInteractionsOptions) {\n this.provider = new XRBlocksInputProvider(options);\n this.hitTester = new ThreeHitTester();\n this.runtime = new InteractionRuntime({\n provider: this.provider,\n hitTester: this.hitTester,\n ...(options.dwellDefaults ? { dwellDefaults: options.dwellDefaults } : {}),\n });\n }\n\n register(descriptor: InteractableDescriptor, object: Object3D): ThreeTransformPort {\n const port = new ThreeTransformPort(object);\n this.ports.set(descriptor.id, port);\n this.hitTester.register(descriptor.id, object);\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): ThreeTransformPort | 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.runtime.dispose();\n }\n}\n\nexport function connectXRBlocksInteractions(\n options: XRBlocksInteractionsOptions,\n): XRBlocksInteractions {\n return new XRBlocksInteractions(options);\n}\n"]}

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,8 @@
+/**
+ * @realitycollective/xrblocks-interactions - EXPERIMENTAL Google XR Blocks
+ * adapter. Structurally typed against xrblocks v0.20.0 (no xrblocks
+ * import); re-exports the core (via the three.js adapter machinery).
+ */
+export * from "@realitycollective/threejs-interactions";
+export * from "./provider.js";
+export * from "./host.js";

package/dist/index.js ADDED Viewed

@@ -0,0 +1,9 @@
+/**
+ * @realitycollective/xrblocks-interactions - EXPERIMENTAL Google XR Blocks
+ * adapter. Structurally typed against xrblocks v0.20.0 (no xrblocks
+ * import); re-exports the core (via the three.js adapter machinery).
+ */
+export * from "@realitycollective/threejs-interactions";
+export * from "./provider.js";
+export * from "./host.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,cAAc,yCAAyC,CAAC;AAExD,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC","sourcesContent":["/**\n * @realitycollective/xrblocks-interactions - EXPERIMENTAL Google XR Blocks\n * adapter. Structurally typed against xrblocks v0.20.0 (no xrblocks\n * import); re-exports the core (via the three.js adapter machinery).\n */\nexport * from \"@realitycollective/threejs-interactions\";\n\nexport * from \"./provider.js\";\nexport * from \"./host.js\";\n"]}

package/dist/provider.d.ts ADDED Viewed

@@ -0,0 +1,96 @@
+/**
+ * XRBlocksInputProvider - EXPERIMENTAL.
+ *
+ * Binds to the SHAPE of Google XR Blocks (verified against xrblocks
+ * v0.20.0 source, 2026-08) without importing `xrblocks`, per the
+ * UI Extensions structural-typing convention:
+ *
+ *  - `xb.input.getFrame()` → `{ raySources, directTouches }`. Those slot
+ *    objects are POOLED AND MUTATED per frame upstream - everything is
+ *    copied here, never retained.
+ *  - `RaySourceInput`: `{ controller, sourceType: 'mouse'|'controller-ray'
+ *    |'hand-ray'|'gaze'|'simulator', ray, selected }` - handedness from
+ *    `controller.inputSource?.handedness`; analog select only via
+ *    `controller.gamepad?.buttons[0].value`; squeeze only as the boolean
+ *    `controller.userData.squeezing`.
+ *  - `DirectTouchInput`: `{ handIndex (0=left,1=right), point }` - the
+ *    index-fingertip world position, merged into the matching hand source.
+ *  - Grip poses are not exposed by the frame struct; the ray pose doubles
+ *    as the carry pose (XR Blocks keeps grip transforms behind
+ *    `options.controllers.visualization`).
+ *  - Gaze rides `sourceType: 'gaze'` and never raw-selects (XR Blocks
+ *    selects gaze via its own dwell; ours is the core's dwell).
+ *  - Haptics: none in XR Blocks (verified) - capability stays false.
+ */
+import { type HeadPose, type InputCapabilities, type InputProvider, type InputSourceSnapshot, type Unsubscribe } from "@realitycollective/webxr-input";
+/** Structural slice of THREE.Vector3 / Quaternion. */
+interface Vec3Like {
+    x: number;
+    y: number;
+    z: number;
+}
+interface QuatLike extends Vec3Like {
+    w: number;
+}
+interface RayLike {
+    origin: Vec3Like;
+    direction: Vec3Like;
+}
+interface ControllerLike {
+    inputSource?: {
+        handedness?: string;
+    };
+    gamepad?: {
+        buttons?: ReadonlyArray<{
+            value: number;
+        }>;
+    };
+    userData?: {
+        squeezing?: boolean;
+        selected?: boolean;
+        id?: number;
+    };
+}
+/** Structural `RaySourceInput` (xrblocks src/interaction/InteractionTypes.ts). */
+export interface XBRaySourceLike {
+    controller: ControllerLike;
+    sourceType: string;
+    ray: RayLike;
+    selected: boolean;
+}
+/** Structural `DirectTouchInput`. */
+export interface XBDirectTouchLike {
+    controller: ControllerLike;
+    handIndex: number;
+    point: Vec3Like;
+    selected: boolean;
+}
+export interface XBFrameLike {
+    raySources: readonly XBRaySourceLike[];
+    directTouches: readonly XBDirectTouchLike[];
+}
+/** The slice of the XR Blocks singletons the provider binds to. */
+export interface XRBlocksContext {
+    /** `xb.input` - must expose `getFrame()`. */
+    input: {
+        getFrame(): XBFrameLike;
+    };
+    /** `xb.camera` / `xb.core.camera` - the head pose. */
+    camera: {
+        getWorldPosition(target: Vec3Like): Vec3Like;
+        getWorldQuaternion(target: QuatLike): QuatLike;
+    };
+}
+export declare class XRBlocksInputProvider implements InputProvider {
+    private readonly context;
+    private capabilities;
+    private readonly capsListeners;
+    constructor(context: XRBlocksContext);
+    getCapabilities(): InputCapabilities;
+    onCapabilitiesChanged(listener: (c: InputCapabilities) => void): Unsubscribe;
+    onSourcesChanged(): Unsubscribe;
+    sample(): readonly InputSourceSnapshot[];
+    private refreshCapabilities;
+    getHeadPose(): HeadPose;
+}
+export {};

package/dist/provider.js ADDED Viewed

@@ -0,0 +1,150 @@
+/**
+ * XRBlocksInputProvider - EXPERIMENTAL.
+ *
+ * Binds to the SHAPE of Google XR Blocks (verified against xrblocks
+ * v0.20.0 source, 2026-08) without importing `xrblocks`, per the
+ * UI Extensions structural-typing convention:
+ *
+ *  - `xb.input.getFrame()` → `{ raySources, directTouches }`. Those slot
+ *    objects are POOLED AND MUTATED per frame upstream - everything is
+ *    copied here, never retained.
+ *  - `RaySourceInput`: `{ controller, sourceType: 'mouse'|'controller-ray'
+ *    |'hand-ray'|'gaze'|'simulator', ray, selected }` - handedness from
+ *    `controller.inputSource?.handedness`; analog select only via
+ *    `controller.gamepad?.buttons[0].value`; squeeze only as the boolean
+ *    `controller.userData.squeezing`.
+ *  - `DirectTouchInput`: `{ handIndex (0=left,1=right), point }` - the
+ *    index-fingertip world position, merged into the matching hand source.
+ *  - Grip poses are not exposed by the frame struct; the ray pose doubles
+ *    as the carry pose (XR Blocks keeps grip transforms behind
+ *    `options.controllers.visualization`).
+ *  - Gaze rides `sourceType: 'gaze'` and never raw-selects (XR Blocks
+ *    selects gaze via its own dwell; ours is the core's dwell).
+ *  - Haptics: none in XR Blocks (verified) - capability stays false.
+ */
+import { NO_CAPABILITIES, } from "@realitycollective/webxr-input";
+const SCRATCH_V = { x: 0, y: 0, z: 0 };
+const SCRATCH_Q = { x: 0, y: 0, z: 0, w: 1 };
+export class XRBlocksInputProvider {
+    context;
+    capabilities = { ...NO_CAPABILITIES, headPose: true, gaze: true };
+    capsListeners = new Set();
+    constructor(context) {
+        this.context = context;
+    }
+    getCapabilities() {
+        return this.capabilities;
+    }
+    onCapabilitiesChanged(listener) {
+        this.capsListeners.add(listener);
+        return () => this.capsListeners.delete(listener);
+    }
+    onSourcesChanged() {
+        return () => undefined;
+    }
+    sample() {
+        const frame = this.context.input.getFrame();
+        const snapshots = [];
+        const byHandedness = new Map();
+        let sawRay = false;
+        let sawTouch = false;
+        let sawMouse = false;
+        for (const source of frame.raySources) {
+            if (source.sourceType === "gaze") {
+                snapshots.push({
+                    id: "xb-gaze",
+                    kind: "gaze",
+                    handedness: "none",
+                    ray: copyRay(source.ray),
+                    select: 0, // gaze never raw-selects in XR Blocks
+                    squeeze: 0,
+                });
+                continue;
+            }
+            const handedness = normalizeHandedness(source.controller.inputSource?.handedness);
+            const isMouse = source.sourceType === "mouse";
+            if (isMouse)
+                sawMouse = true;
+            else
+                sawRay = true;
+            const analog = source.controller.gamepad?.buttons?.[0]?.value;
+            const select = analog !== undefined && analog > 0 ? analog : source.selected ? 1 : 0;
+            const ray = copyRay(source.ray);
+            const snapshot = {
+                id: isMouse ? "xb-mouse" : `xb-${handedness}-${source.sourceType}`,
+                kind: isMouse ? "pointer2d" : source.sourceType === "hand-ray" ? "hand" : "controller",
+                handedness,
+                ray,
+                // XR Blocks does not expose grip transforms in the frame struct;
+                // the ray pose doubles as the carry pose.
+                gripPose: { position: ray.origin, quaternion: [0, 0, 0, 1] },
+                select,
+                squeeze: source.controller.userData?.squeezing ? 1 : 0,
+            };
+            snapshots.push(snapshot);
+            if (handedness !== "none")
+                byHandedness.set(handedness, snapshot);
+        }
+        for (const touch of frame.directTouches) {
+            sawTouch = true;
+            const handedness = touch.handIndex === 0 ? "left" : "right";
+            const existing = byHandedness.get(handedness);
+            const tip = [touch.point.x, touch.point.y, touch.point.z];
+            if (existing) {
+                existing.indexTip = tip;
+                existing.kind = "hand";
+            }
+            else {
+                snapshots.push({
+                    id: `xb-${handedness}-touch`,
+                    kind: "hand",
+                    handedness,
+                    indexTip: tip,
+                    gripPose: { position: tip, quaternion: [0, 0, 0, 1] },
+                    select: touch.selected ? 1 : 0,
+                    squeeze: 0,
+                });
+            }
+        }
+        this.refreshCapabilities(sawRay, sawTouch, sawMouse);
+        return snapshots;
+    }
+    refreshCapabilities(rays, touches, mouse) {
+        const next = {
+            ...NO_CAPABILITIES,
+            rays,
+            pokes: touches,
+            grabs: rays || touches ? "poseOnly" : "none",
+            handJoints: touches,
+            pinch: touches,
+            gaze: true,
+            pointer2d: mouse,
+            headPose: true,
+            haptics: false, // xrblocks v0.20.0 has no haptics API
+        };
+        if (JSON.stringify(next) !== JSON.stringify(this.capabilities)) {
+            this.capabilities = next;
+            for (const listener of [...this.capsListeners])
+                listener(next);
+        }
+    }
+    getHeadPose() {
+        const position = this.context.camera.getWorldPosition(SCRATCH_V);
+        const quaternion = this.context.camera.getWorldQuaternion(SCRATCH_Q);
+        return {
+            position: [position.x, position.y, position.z],
+            quaternion: [quaternion.x, quaternion.y, quaternion.z, quaternion.w ?? 1],
+        };
+    }
+}
+function normalizeHandedness(value) {
+    return value === "left" || value === "right" ? value : "none";
+}
+function copyRay(ray) {
+    // Upstream slot objects are pooled - copy, never retain.
+    return {
+        origin: [ray.origin.x, ray.origin.y, ray.origin.z],
+        direction: [ray.direction.x, ray.direction.y, ray.direction.z],
+    };
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EACL,eAAe,GAMhB,MAAM,gCAAgC,CAAC;AAuDxC,MAAM,SAAS,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;AACvC,MAAM,SAAS,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;AAE7C,MAAM,OAAO,qBAAqB;IACf,OAAO,CAAkB;IAClC,YAAY,GAAsB,EAAE,GAAG,eAAe,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC5E,aAAa,GAAG,IAAI,GAAG,EAAkC,CAAC;IAE3E,YAAY,OAAwB;QAClC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,eAAe;QACb,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,qBAAqB,CAAC,QAAwC;QAC5D,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACjC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACnD,CAAC;IAED,gBAAgB;QACd,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC;IACzB,CAAC;IAED,MAAM;QACJ,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC5C,MAAM,SAAS,GAA0B,EAAE,CAAC;QAC5C,MAAM,YAAY,GAAG,IAAI,GAAG,EAA+B,CAAC;QAE5D,IAAI,MAAM,GAAG,KAAK,CAAC;QACnB,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,IAAI,QAAQ,GAAG,KAAK,CAAC;QAErB,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;YACtC,IAAI,MAAM,CAAC,UAAU,KAAK,MAAM,EAAE,CAAC;gBACjC,SAAS,CAAC,IAAI,CAAC;oBACb,EAAE,EAAE,SAAS;oBACb,IAAI,EAAE,MAAM;oBACZ,UAAU,EAAE,MAAM;oBAClB,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC;oBACxB,MAAM,EAAE,CAAC,EAAE,sCAAsC;oBACjD,OAAO,EAAE,CAAC;iBACX,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YACD,MAAM,UAAU,GAAG,mBAAmB,CAAC,MAAM,CAAC,UAAU,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;YAClF,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,KAAK,OAAO,CAAC;YAC9C,IAAI,OAAO;gBAAE,QAAQ,GAAG,IAAI,CAAC;;gBACxB,MAAM,GAAG,IAAI,CAAC;YACnB,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC;YAC9D,MAAM,MAAM,GAAG,MAAM,KAAK,SAAS,IAAI,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACrF,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAChC,MAAM,QAAQ,GAAwB;gBACpC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,UAAU,IAAI,MAAM,CAAC,UAAU,EAAE;gBAClE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY;gBACtF,UAAU;gBACV,GAAG;gBACH,iEAAiE;gBACjE,0CAA0C;gBAC1C,QAAQ,EAAE,EAAE,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE;gBAC5D,MAAM;gBACN,OAAO,EAAE,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;aACvD,CAAC;YACF,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACzB,IAAI,UAAU,KAAK,MAAM;gBAAE,YAAY,CAAC,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;QACpE,CAAC;QAED,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;YACxC,QAAQ,GAAG,IAAI,CAAC;YAChB,MAAM,UAAU,GAAG,KAAK,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;YAC5D,MAAM,QAAQ,GAAG,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YAC9C,MAAM,GAAG,GAA6B,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACpF,IAAI,QAAQ,EAAE,CAAC;gBACb,QAAQ,CAAC,QAAQ,GAAG,GAAG,CAAC;gBACxB,QAAQ,CAAC,IAAI,GAAG,MAAM,CAAC;YACzB,CAAC;iBAAM,CAAC;gBACN,SAAS,CAAC,IAAI,CAAC;oBACb,EAAE,EAAE,MAAM,UAAU,QAAQ;oBAC5B,IAAI,EAAE,MAAM;oBACZ,UAAU;oBACV,QAAQ,EAAE,GAAG;oBACb,QAAQ,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE;oBACrD,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;oBAC9B,OAAO,EAAE,CAAC;iBACX,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,IAAI,CAAC,mBAAmB,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;QACrD,OAAO,SAAS,CAAC;IACnB,CAAC;IAEO,mBAAmB,CAAC,IAAa,EAAE,OAAgB,EAAE,KAAc;QACzE,MAAM,IAAI,GAAsB;YAC9B,GAAG,eAAe;YAClB,IAAI;YACJ,KAAK,EAAE,OAAO;YACd,KAAK,EAAE,IAAI,IAAI,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM;YAC5C,UAAU,EAAE,OAAO;YACnB,KAAK,EAAE,OAAO;YACd,IAAI,EAAE,IAAI;YACV,SAAS,EAAE,KAAK;YAChB,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,KAAK,EAAE,sCAAsC;SACvD,CAAC;QACF,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;YAC/D,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;YACzB,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC;gBAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;QACjE,CAAC;IACH,CAAC;IAED,WAAW;QACT,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC;QACjE,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC;QACrE,OAAO;YACL,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;YAC9C,UAAU,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC;SAC1E,CAAC;IACJ,CAAC;CACF;AAED,SAAS,mBAAmB,CAAC,KAAyB;IACpD,OAAO,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;AAChE,CAAC;AAED,SAAS,OAAO,CAAC,GAAY;IAI3B,yDAAyD;IACzD,OAAO;QACL,MAAM,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;QAClD,SAAS,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;KAC/D,CAAC;AACJ,CAAC","sourcesContent":["/**\n * XRBlocksInputProvider - EXPERIMENTAL.\n *\n * Binds to the SHAPE of Google XR Blocks (verified against xrblocks\n * v0.20.0 source, 2026-08) without importing `xrblocks`, per the\n * UI Extensions structural-typing convention:\n *\n * - `xb.input.getFrame()` → `{ raySources, directTouches }`. Those slot\n * objects are POOLED AND MUTATED per frame upstream - everything is\n * copied here, never retained.\n * - `RaySourceInput`: `{ controller, sourceType: 'mouse'|'controller-ray'\n * |'hand-ray'|'gaze'|'simulator', ray, selected }` - handedness from\n * `controller.inputSource?.handedness`; analog select only via\n * `controller.gamepad?.buttons[0].value`; squeeze only as the boolean\n * `controller.userData.squeezing`.\n * - `DirectTouchInput`: `{ handIndex (0=left,1=right), point }` - the\n * index-fingertip world position, merged into the matching hand source.\n * - Grip poses are not exposed by the frame struct; the ray pose doubles\n * as the carry pose (XR Blocks keeps grip transforms behind\n * `options.controllers.visualization`).\n * - Gaze rides `sourceType: 'gaze'` and never raw-selects (XR Blocks\n * selects gaze via its own dwell; ours is the core's dwell).\n * - Haptics: none in XR Blocks (verified) - capability stays false.\n */\nimport {\n NO_CAPABILITIES,\n type HeadPose,\n type InputCapabilities,\n type InputProvider,\n type InputSourceSnapshot,\n type Unsubscribe,\n} from \"@realitycollective/webxr-input\";\n\n/** Structural slice of THREE.Vector3 / Quaternion. */\ninterface Vec3Like {\n x: number;\n y: number;\n z: number;\n}\ninterface QuatLike extends Vec3Like {\n w: number;\n}\n\ninterface RayLike {\n origin: Vec3Like;\n direction: Vec3Like;\n}\n\ninterface ControllerLike {\n inputSource?: { handedness?: string };\n gamepad?: { buttons?: ReadonlyArray<{ value: number }> };\n userData?: { squeezing?: boolean; selected?: boolean; id?: number };\n}\n\n/** Structural `RaySourceInput` (xrblocks src/interaction/InteractionTypes.ts). */\nexport interface XBRaySourceLike {\n controller: ControllerLike;\n sourceType: string; // 'mouse' | 'controller-ray' | 'hand-ray' | 'gaze' | 'simulator'\n ray: RayLike;\n selected: boolean;\n}\n\n/** Structural `DirectTouchInput`. */\nexport interface XBDirectTouchLike {\n controller: ControllerLike;\n handIndex: number; // 0 = LEFT, 1 = RIGHT (xrblocks Handedness enum)\n point: Vec3Like;\n selected: boolean;\n}\n\nexport interface XBFrameLike {\n raySources: readonly XBRaySourceLike[];\n directTouches: readonly XBDirectTouchLike[];\n}\n\n/** The slice of the XR Blocks singletons the provider binds to. */\nexport interface XRBlocksContext {\n /** `xb.input` - must expose `getFrame()`. */\n input: { getFrame(): XBFrameLike };\n /** `xb.camera` / `xb.core.camera` - the head pose. */\n camera: {\n getWorldPosition(target: Vec3Like): Vec3Like;\n getWorldQuaternion(target: QuatLike): QuatLike;\n };\n}\n\nconst SCRATCH_V = { x: 0, y: 0, z: 0 };\nconst SCRATCH_Q = { x: 0, y: 0, z: 0, w: 1 };\n\nexport class XRBlocksInputProvider implements InputProvider {\n private readonly context: XRBlocksContext;\n private capabilities: InputCapabilities = { ...NO_CAPABILITIES, headPose: true, gaze: true };\n private readonly capsListeners = new Set<(c: InputCapabilities) => void>();\n\n constructor(context: XRBlocksContext) {\n this.context = context;\n }\n\n getCapabilities(): InputCapabilities {\n return this.capabilities;\n }\n\n onCapabilitiesChanged(listener: (c: InputCapabilities) => void): Unsubscribe {\n this.capsListeners.add(listener);\n return () => this.capsListeners.delete(listener);\n }\n\n onSourcesChanged(): Unsubscribe {\n return () => undefined;\n }\n\n sample(): readonly InputSourceSnapshot[] {\n const frame = this.context.input.getFrame();\n const snapshots: InputSourceSnapshot[] = [];\n const byHandedness = new Map<string, InputSourceSnapshot>();\n\n let sawRay = false;\n let sawTouch = false;\n let sawMouse = false;\n\n for (const source of frame.raySources) {\n if (source.sourceType === \"gaze\") {\n snapshots.push({\n id: \"xb-gaze\",\n kind: \"gaze\",\n handedness: \"none\",\n ray: copyRay(source.ray),\n select: 0, // gaze never raw-selects in XR Blocks\n squeeze: 0,\n });\n continue;\n }\n const handedness = normalizeHandedness(source.controller.inputSource?.handedness);\n const isMouse = source.sourceType === \"mouse\";\n if (isMouse) sawMouse = true;\n else sawRay = true;\n const analog = source.controller.gamepad?.buttons?.[0]?.value;\n const select = analog !== undefined && analog > 0 ? analog : source.selected ? 1 : 0;\n const ray = copyRay(source.ray);\n const snapshot: InputSourceSnapshot = {\n id: isMouse ? \"xb-mouse\" : `xb-${handedness}-${source.sourceType}`,\n kind: isMouse ? \"pointer2d\" : source.sourceType === \"hand-ray\" ? \"hand\" : \"controller\",\n handedness,\n ray,\n // XR Blocks does not expose grip transforms in the frame struct;\n // the ray pose doubles as the carry pose.\n gripPose: { position: ray.origin, quaternion: [0, 0, 0, 1] },\n select,\n squeeze: source.controller.userData?.squeezing ? 1 : 0,\n };\n snapshots.push(snapshot);\n if (handedness !== \"none\") byHandedness.set(handedness, snapshot);\n }\n\n for (const touch of frame.directTouches) {\n sawTouch = true;\n const handedness = touch.handIndex === 0 ? \"left\" : \"right\";\n const existing = byHandedness.get(handedness);\n const tip: [number, number, number] = [touch.point.x, touch.point.y, touch.point.z];\n if (existing) {\n existing.indexTip = tip;\n existing.kind = \"hand\";\n } else {\n snapshots.push({\n id: `xb-${handedness}-touch`,\n kind: \"hand\",\n handedness,\n indexTip: tip,\n gripPose: { position: tip, quaternion: [0, 0, 0, 1] },\n select: touch.selected ? 1 : 0,\n squeeze: 0,\n });\n }\n }\n\n this.refreshCapabilities(sawRay, sawTouch, sawMouse);\n return snapshots;\n }\n\n private refreshCapabilities(rays: boolean, touches: boolean, mouse: boolean): void {\n const next: InputCapabilities = {\n ...NO_CAPABILITIES,\n rays,\n pokes: touches,\n grabs: rays || touches ? \"poseOnly\" : \"none\",\n handJoints: touches,\n pinch: touches,\n gaze: true,\n pointer2d: mouse,\n headPose: true,\n haptics: false, // xrblocks v0.20.0 has no haptics API\n };\n if (JSON.stringify(next) !== JSON.stringify(this.capabilities)) {\n this.capabilities = next;\n for (const listener of [...this.capsListeners]) listener(next);\n }\n }\n\n getHeadPose(): HeadPose {\n const position = this.context.camera.getWorldPosition(SCRATCH_V);\n const quaternion = this.context.camera.getWorldQuaternion(SCRATCH_Q);\n return {\n position: [position.x, position.y, position.z],\n quaternion: [quaternion.x, quaternion.y, quaternion.z, quaternion.w ?? 1],\n };\n }\n}\n\nfunction normalizeHandedness(value: string | undefined): \"left\" | \"right\" | \"none\" {\n return value === \"left\" || value === \"right\" ? value : \"none\";\n}\n\nfunction copyRay(ray: RayLike): {\n origin: [number, number, number];\n direction: [number, number, number];\n} {\n // Upstream slot objects are pooled - copy, never retain.\n return {\n origin: [ray.origin.x, ray.origin.y, ray.origin.z],\n direction: [ray.direction.x, ray.direction.y, ray.direction.z],\n };\n}\n"]}

package/package.json ADDED Viewed

@@ -0,0 +1,62 @@
+{
+  "name": "@realitycollective/xrblocks-interactions",
+  "version": "0.1.0-preview.0",
+  "description": "EXPERIMENTAL Google XR Blocks adapter for the Reality Collective Interaction Extensions - maps XR Blocks' input pipeline (Input.getFrame() ray sources + direct touches, Script select events) into the engine-free @realitycollective/webxr-interactions core, reusing the three.js hit-testing/transform machinery. Structurally typed: no xrblocks import. Re-exports the core.",
+  "keywords": [
+    "realitycollective",
+    "xrblocks",
+    "androidxr",
+    "webxr",
+    "threejs",
+    "interaction",
+    "input",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "Reality Collective",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@realitycollective/webxr-input": "^0.1.0",
+    "@realitycollective/webxr-interactions": "^0.1.0-preview.0",
+    "@realitycollective/threejs-interactions": "^0.1.0-preview.0"
+  },
+  "peerDependencies": {
+    "three": ">=0.170.0"
+  },
+  "devDependencies": {
+    "three": "npm:super-three@0.181.0",
+    "@types/three": "*"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/realitycollective/WebXR-Interactions.git",
+    "directory": "packages/xrblocks-interactions"
+  },
+  "homepage": "https://github.com/realitycollective/WebXR-Interactions#readme",
+  "bugs": {
+    "url": "https://github.com/realitycollective/WebXR-Interactions/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.19.0 <21.0.0-0 || >=22.12.0 <23.0.0-0 || >=24.0.0"
+  }
+}