@realitycollective/native-interactions 0.1.1-preview.0

package/CHANGELOG.md

@@ -0,0 +1,79 @@
+# 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.1]
+
+### Added
+
+- `@realitycollective/webxr-interactions` - shared conformance suites for `HitTester` and `TransformPort`, `hitTesterContractCases()` and `transformPortContractCases()`, alongside the existing `inputProviderContractCases()` from `@realitycollective/webxr-input`. Runner-free data, the same pattern as WebXR-UIExtensions' `windowHostContractCases()`: each case throws a plain `Error` naming what a platform's ray/proximity query or transform read/write broke, and asserts only what `ports.ts` documents - a ray or proximity query answers null or an id with a positive distance and a point near the query, the nearer of two targets wins, an offset round-trips, `getWorldPose()` is finite with a unit quaternion, `getRestWorldPose()` is the registration pose and stays put, `getWorldPose()` follows `setLocalOffset`, `setLocalRotation` and `setWorldPose` from that rest frame, every returned tuple is a fresh value the caller owns and no tuple passed in is kept, and the optional `setEffect` accepts its shape without throwing. Each platform's subject starts away from the origin and turned, so a port that ignores its rest frame fails. Run against all five platforms in `packages/iwsdk-interactions/test/port-parity.test.ts`, next to the provider parity suite; every platform passes every case.
+- `@realitycollective/native-interactions` - a native host adapter, the fifth platform. It reads the `input` and `interactions` slices a native app (OpenXR on Quest, CompositorServices on visionOS) installs on `globalThis.__rcHost`, or hands in directly, and maps them onto `InputProvider`, `HitTester` and `TransformPort` with no engine dependency at all - assets and rendering stay in the native app, and only tuples and target ids cross the boundary. Every snapshot, hit and pose read across that boundary is copied, so a host that reuses its own buffers cannot reach an object the app is still holding, and optional members (`getHeadPose`, `sampleHints`, `pulse`, `setPresenceVisible`, `setPresenceModality`, `setWorldPose`, `setEffect`) are present only when the host slice itself carries them. `createNativeInteractions()` is the one-call setup, with the same shape as the other adapters' setups; `attachToHost` drives updates from the app's frame callback. The public surface matches the other adapters, and slice reading and tuple copying stay internal. Covered headlessly by an in-memory fake of both slices, including the shared `InputProvider` contract suite.
+
+### Changed
+
+- `@realitycollective/webxr-interactions` - `TransformPort.getWorldPose()` is the LIVE world pose on every platform, and the new required `getRestWorldPose()` returns the rest pose captured at registration, in world space. The core only said "current world pose", and the platforms disagreed: the three.js, IWSDK and XR Blocks ports returned the rest pose, while the Babylon.js port returned the live one. The same behaviour therefore acted differently by platform. The hinge, slide and dial behaviours measure the hand against the rest pose, so they now call `getRestWorldPose()`. Grab and toss scoring keep `getWorldPose()` and now see where the object really is. `ports.ts` also states tuple ownership for `TransformPort` and `HitTester`: every returned tuple is fresh and owned by the caller, and a tuple passed in is read during the call and not kept. Every platform already met the ownership rule; the suites now hold them to it. The native `interactions` slice gains `getRestWorldPose(targetId)`, which the native app must implement. This adds a required member to `TransformPort`, so a port written outside this repository must implement it.
+- `@realitycollective/xrblocks-interactions` - the structural slices `XBVec3Like`, `XBQuatLike`, `XBRayLike` and `XBControllerLike` are exported, under the same `XB` prefix as `XBRaySourceLike`, `XBDirectTouchLike` and `XBFrameLike` whose fields they type. They were module-private, so a consumer building a fake frame for a test had nothing to name, and TypeDoc reported each as referenced but undocumented.
+
+### Fixed
+
+- `@realitycollective/threejs-interactions`, `@realitycollective/iwsdk-interactions` and `@realitycollective/xrblocks-interactions` - `getWorldPose()` returned the pose captured at registration, not where the object was. Toss scoring therefore read a thrown ball at its registered position until the app called `recaptureRest()`, and a second grab of an object moved without a recapture took its hold offset from the old position. `getWorldPose()` now returns the live pose, as the Babylon.js port already did.
+- `@realitycollective/webxr-interactions` - `InteractableDescriptor.pokeRadius` had no effect. The value was stored on the registration and documented as the poke trigger radius, but the proximity query always used the 5 cm default, so an interactable asking for a wider or narrower poke got the default. The runtime now queries once per source at the largest radius any enabled interactable registered, and accepts the nearest hit only when it lies inside that interactable's own radius. One query per source is kept deliberately; the trade is that a farther interactable with a larger radius is not found behind a nearer one with a smaller radius, because the hit tester returns only the nearest. Covered by a runtime test that failed before the change.
+- CI - the staging deploy published under `--branch=pr-<number>` while the `-test` Pages project's production branch is `staging`, so only `pr-<n>.webxr-interactions-test.pages.dev` aliases were ever created and the project's root URL was a 404. It now deploys as `staging` on every pull request and on every push to `development`, so `webxr-interactions-test.pages.dev` serves the newest preview build, the same arrangement WebXR-UIExtensions already had.
+
+## [0.1.0] - 2026-09-17
+
+### Added
+
+- `verify:pack` now lints the shape of what ships: publint over every package directory, with warnings counted as errors, and attw (Are The Types Wrong) over every packed tarball, resolving the published types under node10, node16 and bundler resolution. `cjs-resolves-to-esm` is ignored by design, because every package is ESM-only and a require() caller is expected to use a dynamic import. Both run offline on the tarballs the script already builds; `publint` and `@arethetypeswrong/cli` are dev dependencies. The script stays identical across the Reality Collective repositories.
+- `verify:pack` now also type-checks the published declarations themselves, with library checking on, through `scripts/declaration-check.mjs`, runnable on its own as `node scripts/declaration-check.mjs`. Each package's declaration entry is compiled as a strict consumer would compile it, with `skipLibCheck: false`, under nodenext and then bundler resolution; a diagnostic inside the package fails the run, and diagnostics inside upstream declaration files are counted and ignored, because they are not ours to fix and would drown the signal. attw proves the published types resolve; this proves they compile, which is what a consumer with library checking on, or a package emitting declarations on top of ours, needs. The check is opt-in per repository, through `declarationCheck` in `scripts/release.config.json`, because only a foreign declaration can put a name into our emitted types that the build did not already check. This repository reaches around 950 of them, from the IWSDK and three.js typings the adapter is built against, and every run prints that count so the opt-in stays measured rather than habitual. It is the check that would have caught the bare `World` under Fixed.
+- `@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)`. The differentiation itself is `velocityBetween` from `@realitycollective/webxr-input`, re-exported here; `clampDeadzone` joins 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)`. Every provider reports whether it can do this through `capabilities.presence`; 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 four providers and runs the shared contract suite against each one. The package's coverage ratchet moves off zero, and the other three ratchets rise to the floor they now measure.
+
+### Changed
+
+- `@types/three` is pinned to `0.181.0` across the workspace (root `overrides`), the typings for the super-three 0.181 the workspace runs. `@iwsdk/core` carries its own `@types/three` dependency, and without the pin the tree held two copies, whose structurally identical classes are mutually unassignable in TypeScript. One copy, matching the runtime, is the rule in every Reality Collective repository that hosts IWSDK.
+- Every provider reports presence through `capabilities.presence`, the required key `@realitycollective/webxr-input` 0.1.1 adds to `InputCapabilities`. The class-level `supportsPresence` field the four adapters carried while that key was unpublished is gone. This fixes a client-visible defect on the IWSDK adapter, which built its capabilities without a `presence` key at all: an app that read `capabilities.presence` saw false and hid a feature that worked. The value each provider reports is the one its own field computed - always true on IWSDK, true once Babylon has built a visual to hide, true on three.js once a model is registered, and always false on XR Blocks.
+- `@realitycollective/threejs-interactions` - `registerVisual` and the new `unregisterVisual` now re-derive capabilities and notify `onCapabilitiesChanged`. Presence on this adapter is genuinely conditional: your app builds its own hand and controller models, so `capabilities.presence` is false until you hand the first one over and false again once you take the last one back.
+- The Input 0.1.1 types replace the local stand-ins that were waiting on them. `InputSourceSnapshot` now carries `linearVelocity` and `angularVelocity` itself, so the `InputSourceSnapshotWithVelocity` alias is gone; the local `poseVelocity` is gone in favour of the shipped `velocityBetween`; and the per-adapter `PresenceTarget` and `PresenceModality` declarations are gone. `PresenceModality` now comes from the contracts, and a presence target is written as the contract writes it, `Handedness | "all"`. All three names were re-exported from these packages and are removed from that surface.
+- Every package now requires `@realitycollective/webxr-input` at `^0.1.1` rather than `^0.1.0`, because the code above uses members that only exist from 0.1.1. A fresh install resolved to 0.1.1 either way; the range says so now, so a consumer holding an older lockfile fails at install rather than at run time.
+- The provider parity suite is now three lines over `inputProviderContractCases()` from `@realitycollective/webxr-input`, run against all four adapters, instead of a hand-written copy of the same checks. The shared cases are stricter: they assert the capability record has exactly the contract's keys and that every snapshot is well formed. Two adapter-specific checks stay on top of them.
+- `@realitycollective/iwsdk-interactions` - `setPresenceVisible` and `setPresenceModality` write nothing when nothing changed. The provider holds what it last applied per side - visibility, modality and the hand-tracking capability presence is derived from - and skips a side whose three inputs are unchanged. An app pushing presence from a state subscription, which is the documented pattern, no longer walks every descendant of both visual families on every unrelated state change. The per-frame re-apply during `sample()` stays unconditional, because IWSDK re-asserts its own visuals from its update loop and a capability refresh can change the modality underneath the adapter.
+
+- `@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.
+- `@realitycollective/iwsdk-interactions` - the approximate hit tester the bridge keeps for gaze and poke targeting resolves each registered entity's world position once per frame instead of on every query. The core asks it five questions a frame (a poke and a ray test per side, plus the gaze ray) and each one walked every entity's parent chain again through `getWorldPosition`; the bridge now calls `beginFrame()` before the runtime ticks and the five answers come from one resolution. Measured 3.6x to 4x faster on the tester in the gate-1 benchmarks, 32 us to 9 us a frame at 50 entities on desktop, with the same answers. Its ray test also no longer allocates a tuple per entity per query.
+- `@realitycollective/threejs-interactions` - `ThreeHitTester` uses three-mesh-bvh when the app has installed its prototype hooks, which IWSDK does by default: geometries are given a bounds tree as they are registered and the raycaster asks for the first hit only, so a ray against a detailed mesh costs microseconds instead of the near-millisecond a plain triangle walk takes. `three-mesh-bvh` is declared as an optional peer; without it the plain raycast is used and the README explains collider proxies. The roots list handed to the raycaster and the intersections array are now reused between calls rather than built per call, and `hitProximity` reads each object's position and scale straight off its world matrix after one matrix update instead of two updates and a decompose, measured 4x faster at 50 registered objects.
+- `@realitycollective/webxr-interactions` - `onSample`, `getSource` and the pointer bridge document the snapshot ownership rule `@realitycollective/webxr-input` 0.1.3 states: a snapshot handed over is the receiver's to keep and is never written to again. The velocity tracker and the pointer bridge already relied on it.
+
+### Deprecated
+
+- `@realitycollective/webxr-interactions` - `InteractionRuntime.onSourcesSampled` is deprecated in favour of `onSample`. They are the same stream, and since `InputSourceSnapshot` carries the velocity fields itself the two signatures are now identical, so only one name is needed. Nothing is removed: existing callers keep working and the method will go in a later major release.
+
+### Fixed
+
+- `@realitycollective/iwsdk-interactions` emitted the same bare `World` in `InteractionBridgeSystem`'s base type that broke a consumer of the UI Extensions adapter on 9 September 2026. The cause is upstream: `@iwsdk/core` 0.5.3's `dist/ecs/system.d.ts` imports `World` from `'./world'` with no extension, the only such import in the package, and under the NodeNext resolution this repository builds with that import does not resolve (TS2835), so `World` was an unresolved name inside the host's own declaration and TypeScript's declaration emitter preserved it verbatim. `skipLibCheck` hid the error on both sides. It compiled for consumers only because `register.d.ts` happened to import `World` for another signature. The adapter now takes `createSystem` from its own `src/create-system.ts`, a wrapper whose return type names `World` through `@iwsdk/core`'s barrel, so the emitted base type no longer depends on that accident. The wrapper goes the day IWSDK ships `./world.js` there.
+- `@realitycollective/iwsdk-interactions` imported three.js's `Vector3`, `Quaternion` and `Matrix4`, and IWSDK's `InputComponent`, through `@iwsdk/core`, which only provides them by `export * from 'three'` and `export * from '@iwsdk/xr-input'`. That resolves in node and in every demo, and fails a consumer whose Vite config excludes `three` from dependency optimization, which any app that transforms three's source does: esbuild cannot enumerate a star re-export it is not bundling, and the dev server stops with `No matching export in "@iwsdk/core" for import "Vector3"`, a message that names neither the package nor the cause. The provider, the transform port and `registerInteractions` now import from `three` and `@iwsdk/xr-input`, both declared as peer dependencies (`three >=0.170.0`, the range the three.js adapter carries; `@iwsdk/xr-input >=0.5.0 <0.6.0`, the range of `@iwsdk/core`, which installs it). The Anatomy Atlas XR client reported the failure against the UI Extensions adapter; the estate sweep found the same import here.
+- `@realitycollective/xrblocks-interactions` imported `InteractionRuntime` from `@realitycollective/threejs-interactions`, which only re-exports it from `@realitycollective/webxr-interactions`. It now imports from the package that defines it, which it already depended on. Found by the new import-surface gate.
+- Two gates, shared with every Reality Collective repository. `packages/webxr-interactions/test/import-surface.test.ts` runs `scripts/import-surface.mjs` over every published package and fails an import of a name that a dependency only re-exports from another package, and any bare import of a package the manifest does not declare. `packages/iwsdk-interactions/test/prebundle.test.ts` runs the dependency optimizer of every bundler `scripts/release.config.json` names (`scripts/prebundle-check.mjs`) over the adapter next to `@iwsdk/core`, once with defaults and once with every package `@iwsdk/core` re-exports wholesale excluded, so the consumer path is exercised on every `npm test`. It runs on **Vite 7 and Vite 8**, because this fault belongs to a bundler rather than to bundling: Vite 7 optimizes with esbuild, which requires every named import to be statically enumerable and so rejects a name behind an external `export *`, while Vite 8 optimizes with rolldown, which resolves the same import lazily through a namespace object and accepts it. Testing only one of them would say nothing about consumers on the other. The versions under test are ordinary devDependencies installed under npm aliases, `vite-7` and `vite-8`, the same mechanism the workspace already uses for `three`; add an entry to `prebundle.bundlers` to support another. Each run also feeds the optimizer a **deliberately broken copy** of the adapter, carrying one extra module that imports a name the host only re-exports wholesale, and asserts the bundler's verdict matches that bundler's `detectsStarHops` flag. The probed name is discovered from the host's own surface rather than hard-coded, so it stays valid as that surface changes. This is what stops the check becoming decoration: on a permissive bundler a gate that can only pass reports safety it never verified, and the suite now fails if a bundler's strictness moves in either direction, or if no supported bundler can detect the fault at all. Transpiling uses the TypeScript compiler the repository already builds with, so no bundler is a hidden requirement of the harness itself. Both were red before this fix.
+- `@realitycollective/threejs-interactions` - `ThreeHitTester.hitProximity` reported the object's world scale as the hit `point`. The bounding-radius lookup reused the scratch vector holding the world position, so a box at (2, 1, -3) came back with `point: [1, 1, 1]`. The core only reads the id, so targeting was unaffected; anything reading `point` from a proximity hit on three.js or XR Blocks got the wrong answer.
+
+### Notes
+
+- All five packages depend on `@realitycollective/webxr-input`, released independently from the [WebXR-Input](https://github.com/realitycollective/WebXR-Input) repository. That package must be published before this one.
+- 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.1]: https://github.com/realitycollective/WebXR-Interactions/compare/v0.1.0...development
+[0.1.0]: https://github.com/realitycollective/WebXR-Interactions/releases/tag/v0.1.0

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,66 @@
+# @realitycollective/native-interactions
+
+The native host adapter for the Reality Collective Interaction Extensions. A native app (OpenXR on Quest, CompositorServices on visionOS, or any other shell embedding a JavaScript engine such as Hermes) installs `globalThis.__rcHost`, and this package reads its `input` and `interactions` slices into the [`@realitycollective/webxr-interactions`](https://www.npmjs.com/package/@realitycollective/webxr-interactions) core.
+
+```sh
+npm install @realitycollective/native-interactions
+```
+
+It re-exports everything from the core, so this is the only interaction package your app needs.
+
+## What it binds
+
+| Layer | Detail |
+| --- | --- |
+| **Input** | `__rcHost.input` - the same members as `InputProvider`: capabilities, source sampling, optional head pose, hints, haptics and presence |
+| **Hit-testing** | `__rcHost.interactions.hitRay` / `hitProximity` - the native app owns the scene and physics, so targeting is entirely its answer |
+| **Movement** | `__rcHost.interactions`, keyed by the target id you chose when you registered the object with the native scene |
+| **No engine dependency** | Assets and rendering stay in the native app; only numbers, strings, booleans and tuples cross the boundary |
+
+## Usage
+
+One call, the same shape as `createBabylonInteractions` and `createThreeInteractions`:
+
+```ts
+import { createNativeInteractions } from "@realitycollective/native-interactions";
+
+// Reads globalThis.__rcHost.input / .interactions when no slice is passed in,
+// and drives update(dt) from the app's own frame callback, __rcHost.onFrame.
+const interactions = createNativeInteractions({ attachToHost: true });
+
+interactions.register({ id: "button", behaviours: [{ kind: "press" }] });
+interactions.runtime.onEvent((event) => console.log(event.type));
+```
+
+The native app owns the scene, so an interactable is registered by id alone. The app answers hit queries and pose reads for that id through the `interactions` slice. Without `attachToHost`, call `interactions.update(dtSeconds)` from your own loop. `dispose()` detaches from the frame callback and disposes the runtime.
+
+The provider, hit tester and transform port are exported too, as on every adapter, for an app that composes the runtime itself.
+
+Pass the slices directly, typically in a test or when your host object is not on `globalThis`:
+
+```ts
+const provider = new NativeInputProvider({ input: myInputSlice });
+const hitTester = new NativeHitTester({ interactions: myInteractionSlice });
+const port = new NativeTransformPort("button", { interactions: myInteractionSlice });
+```
+
+A missing slice - neither passed in nor found on `globalThis.__rcHost` - throws one clear error naming it, at construction, rather than failing on the first call that needed it.
+
+## Things to know
+
+- **Copies, not references.** Every snapshot `sample()` returns, and every tuple inside it, is copied before it leaves `NativeInputProvider`, so a host that reuses its own sample buffers cannot change a snapshot your app is still holding. The same applies to hit results and to poses read through `NativeTransformPort`.
+- **Optional members are honest.** `getHeadPose`, `sampleHints`, `pulse`, `setPresenceVisible` and `setPresenceModality` on `NativeInputProvider`, and `setWorldPose`/`setEffect` on `NativeTransformPort`, are only ever present when the host slice itself carries the matching member - never a method that silently no-ops.
+- **One port per interactable.** `TransformPort` is per object; the native host is one object serving every registered interactable, so `NativeTransformPort` binds one `targetId` onto it, the same idea as an engine adapter's port binding to one scene node.
+- **`NativeHit.targetId`** is renamed to the core's `interactableId` on the way through `NativeHitTester` - the native host names the thing it hit, the core names the thing it manages.
+
+## Peer dependency
+
+None. No engine object crosses the boundary in either direction.
+
+## Documentation
+
+See the [repository README](https://github.com/realitycollective/WebXR-Interactions#readme).
+
+## License
+
+MIT - see [LICENSE](./LICENSE).

package/dist/hit-tester.d.ts

@@ -0,0 +1,20 @@
+/**
+ * NativeHitTester - resolves the core's ray and proximity queries against
+ * the native host's `interactions` slice. The native app owns the scene and
+ * physics, so targeting is entirely the host's answer; this class only
+ * copies the result across and renames its `targetId` to the core's
+ * `interactableId`.
+ */
+import type { RayTuple, Vec3Tuple } from "@realitycollective/webxr-input";
+import type { HitTester, InteractableHit } from "@realitycollective/webxr-interactions";
+import { type NativeInteractionHost } from "./native-types.js";
+export interface NativeHitTesterOptions {
+    /** The `interactions` slice. Omit to read `globalThis.__rcHost.interactions`. */
+    interactions?: NativeInteractionHost;
+}
+export declare class NativeHitTester implements HitTester {
+    private readonly host;
+    constructor(options?: NativeHitTesterOptions);
+    hitRay(ray: RayTuple): InteractableHit | null;
+    hitProximity(point: Vec3Tuple, radius: number): InteractableHit | null;
+}

package/dist/hit-tester.js

@@ -0,0 +1,19 @@
+import { copyRay, copyVec3, resolveHostSlice, } from "./native-types.js";
+export class NativeHitTester {
+    host;
+    constructor(options = {}) {
+        this.host = resolveHostSlice("interactions", options.interactions);
+    }
+    hitRay(ray) {
+        const hit = this.host.hitRay(copyRay(ray));
+        return hit ? toInteractableHit(hit) : null;
+    }
+    hitProximity(point, radius) {
+        const hit = this.host.hitProximity(copyVec3(point), radius);
+        return hit ? toInteractableHit(hit) : null;
+    }
+}
+function toInteractableHit(hit) {
+    return { interactableId: hit.targetId, distance: hit.distance, point: copyVec3(hit.point) };
+}
+//# 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":"AASA,OAAO,EACL,OAAO,EACP,QAAQ,EACR,gBAAgB,GAGjB,MAAM,mBAAmB,CAAC;AAO3B,MAAM,OAAO,eAAe;IACT,IAAI,CAAwB;IAE7C,YAAY,UAAkC,EAAE;QAC9C,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC,cAAc,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IACrE,CAAC;IAED,MAAM,CAAC,GAAa;QAClB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;QAC3C,OAAO,GAAG,CAAC,CAAC,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7C,CAAC;IAED,YAAY,CAAC,KAAgB,EAAE,MAAc;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;QAC5D,OAAO,GAAG,CAAC,CAAC,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7C,CAAC;CACF;AAED,SAAS,iBAAiB,CAAC,GAAc;IACvC,OAAO,EAAE,cAAc,EAAE,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;AAC9F,CAAC","sourcesContent":["/**\n * NativeHitTester - resolves the core's ray and proximity queries against\n * the native host's `interactions` slice. The native app owns the scene and\n * physics, so targeting is entirely the host's answer; this class only\n * copies the result across and renames its `targetId` to the core's\n * `interactableId`.\n */\nimport type { RayTuple, Vec3Tuple } from \"@realitycollective/webxr-input\";\nimport type { HitTester, InteractableHit } from \"@realitycollective/webxr-interactions\";\nimport {\n  copyRay,\n  copyVec3,\n  resolveHostSlice,\n  type NativeHit,\n  type NativeInteractionHost,\n} from \"./native-types.js\";\n\nexport interface NativeHitTesterOptions {\n  /** The `interactions` slice. Omit to read `globalThis.__rcHost.interactions`. */\n  interactions?: NativeInteractionHost;\n}\n\nexport class NativeHitTester implements HitTester {\n  private readonly host: NativeInteractionHost;\n\n  constructor(options: NativeHitTesterOptions = {}) {\n    this.host = resolveHostSlice(\"interactions\", options.interactions);\n  }\n\n  hitRay(ray: RayTuple): InteractableHit | null {\n    const hit = this.host.hitRay(copyRay(ray));\n    return hit ? toInteractableHit(hit) : null;\n  }\n\n  hitProximity(point: Vec3Tuple, radius: number): InteractableHit | null {\n    const hit = this.host.hitProximity(copyVec3(point), radius);\n    return hit ? toInteractableHit(hit) : null;\n  }\n}\n\nfunction toInteractableHit(hit: NativeHit): InteractableHit {\n  return { interactableId: hit.targetId, distance: hit.distance, point: copyVec3(hit.point) };\n}\n"]}

package/dist/host.d.ts

@@ -0,0 +1,48 @@
+/**
+ * createNativeInteractions - one-call setup for the native adapter, with the
+ * same shape as the Babylon, three.js, IWSDK and XR Blocks setups.
+ *
+ * ```ts
+ * const interactions = createNativeInteractions({ attachToHost: true });
+ * interactions.register({ id: "button", behaviours: [{ kind: "press" }] });
+ * interactions.runtime.onEvent((event) => console.log(event.type));
+ * ```
+ *
+ * The native app owns the scene, so an interactable is registered by id
+ * alone: the app answers hit queries and pose reads for that id through the
+ * `interactions` slice. With `attachToHost` the loop drives itself from the
+ * app's own frame callback. Without it, call `update(dt)` yourself with
+ * seconds.
+ */
+import { InteractionRuntime, type DwellConfig, type InteractableDescriptor } from "@realitycollective/webxr-interactions";
+import { NativeHitTester, type NativeHitTesterOptions } from "./hit-tester.js";
+import { NativeInputProvider, type NativeInputProviderOptions } from "./provider.js";
+import { NativeTransformPort } from "./transform-port.js";
+import { type NativeFrameSource } from "./native-types.js";
+export interface NativeInteractionsOptions extends NativeInputProviderOptions, NativeHitTesterOptions {
+    dwellDefaults?: DwellConfig;
+    /**
+     * Drive `update(dt)` from the native app's frame callback. Default false -
+     * the app calls `update` from its own loop.
+     */
+    attachToHost?: boolean;
+    /** Where frames come from for `attachToHost`. Omit to use `globalThis.__rcHost`. */
+    frames?: NativeFrameSource;
+}
+export declare class NativeInteractions {
+    readonly runtime: InteractionRuntime;
+    readonly provider: NativeInputProvider;
+    readonly hitTester: NativeHitTester;
+    private readonly ports;
+    private readonly options;
+    private detachHost;
+    constructor(options?: NativeInteractionsOptions);
+    /** Register an interactable. The native app knows it by `descriptor.id`. */
+    register(descriptor: InteractableDescriptor): NativeTransformPort;
+    unregister(id: string): void;
+    getPort(id: string): NativeTransformPort | undefined;
+    update(dt: number): void;
+    dispose(): void;
+    private attachToHost;
+}
+export declare function createNativeInteractions(options?: NativeInteractionsOptions): NativeInteractions;

package/dist/host.js

@@ -0,0 +1,80 @@
+/**
+ * createNativeInteractions - one-call setup for the native adapter, with the
+ * same shape as the Babylon, three.js, IWSDK and XR Blocks setups.
+ *
+ * ```ts
+ * const interactions = createNativeInteractions({ attachToHost: true });
+ * interactions.register({ id: "button", behaviours: [{ kind: "press" }] });
+ * interactions.runtime.onEvent((event) => console.log(event.type));
+ * ```
+ *
+ * The native app owns the scene, so an interactable is registered by id
+ * alone: the app answers hit queries and pose reads for that id through the
+ * `interactions` slice. With `attachToHost` the loop drives itself from the
+ * app's own frame callback. Without it, call `update(dt)` yourself with
+ * seconds.
+ */
+import { InteractionRuntime, } from "@realitycollective/webxr-interactions";
+import { NativeHitTester } from "./hit-tester.js";
+import { NativeInputProvider } from "./provider.js";
+import { NativeTransformPort } from "./transform-port.js";
+import { installedHost } from "./native-types.js";
+/** Longest frame the host-attached loop will report, in seconds. */
+const MAX_FRAME_SECONDS = 0.1;
+export class NativeInteractions {
+    runtime;
+    provider;
+    hitTester;
+    ports = new Map();
+    options;
+    detachHost = null;
+    constructor(options = {}) {
+        this.options = options;
+        this.provider = new NativeInputProvider(options);
+        this.hitTester = new NativeHitTester(options);
+        this.runtime = new InteractionRuntime({
+            provider: this.provider,
+            hitTester: this.hitTester,
+            ...(options.dwellDefaults ? { dwellDefaults: options.dwellDefaults } : {}),
+        });
+        if (options.attachToHost)
+            this.attachToHost(options);
+    }
+    /** Register an interactable. The native app knows it by `descriptor.id`. */
+    register(descriptor) {
+        const port = new NativeTransformPort(descriptor.id, this.options.interactions ? { interactions: this.options.interactions } : {});
+        this.ports.set(descriptor.id, port);
+        this.runtime.registerInteractable(descriptor, { transform: port });
+        return port;
+    }
+    unregister(id) {
+        this.runtime.unregisterInteractable(id);
+        this.ports.delete(id);
+    }
+    getPort(id) {
+        return this.ports.get(id);
+    }
+    update(dt) {
+        this.runtime.update(dt);
+    }
+    dispose() {
+        this.detachHost?.();
+        this.detachHost = null;
+        this.runtime.dispose();
+    }
+    attachToHost(options) {
+        const frames = options.frames ?? installedHost();
+        if (!frames?.onFrame) {
+            throw new Error("@realitycollective/native-interactions: attachToHost needs a frame source, and globalThis.__rcHost.onFrame is not installed. Pass `frames`, or call update(dt) yourself.");
+        }
+        // The app reports the frame delta in seconds. A long frame is clamped so
+        // behaviours integrate over a sane step rather than jumping.
+        this.detachHost = frames.onFrame((_timestampMs, deltaS) => {
+            this.update(Math.min(MAX_FRAME_SECONDS, Math.max(0, deltaS)));
+        });
+    }
+}
+export function createNativeInteractions(options = {}) {
+    return new NativeInteractions(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":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EACL,kBAAkB,GAGnB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,eAAe,EAA+B,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,mBAAmB,EAAmC,MAAM,eAAe,CAAC;AACrF,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAA0B,MAAM,mBAAmB,CAAC;AAe1E,oEAAoE;AACpE,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAE9B,MAAM,OAAO,kBAAkB;IACpB,OAAO,CAAqB;IAC5B,QAAQ,CAAsB;IAC9B,SAAS,CAAkB;IACnB,KAAK,GAAG,IAAI,GAAG,EAA+B,CAAC;IAC/C,OAAO,CAA4B;IAC5C,UAAU,GAAwB,IAAI,CAAC;IAE/C,YAAY,UAAqC,EAAE;QACjD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,IAAI,mBAAmB,CAAC,OAAO,CAAC,CAAC;QACjD,IAAI,CAAC,SAAS,GAAG,IAAI,eAAe,CAAC,OAAO,CAAC,CAAC;QAC9C,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;QACH,IAAI,OAAO,CAAC,YAAY;YAAE,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IACvD,CAAC;IAED,4EAA4E;IAC5E,QAAQ,CAAC,UAAkC;QACzC,MAAM,IAAI,GAAG,IAAI,mBAAmB,CAClC,UAAU,CAAC,EAAE,EACb,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAC7E,CAAC;QACF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QACpC,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,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,UAAU,EAAE,EAAE,CAAC;QACpB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IACzB,CAAC;IAEO,YAAY,CAAC,OAAkC;QACrD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,aAAa,EAAE,CAAC;QACjD,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CACb,0KAA0K,CAC3K,CAAC;QACJ,CAAC;QACD,yEAAyE;QACzE,6DAA6D;QAC7D,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,EAAE,MAAM,EAAE,EAAE;YACxD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;QAChE,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AAED,MAAM,UAAU,wBAAwB,CACtC,UAAqC,EAAE;IAEvC,OAAO,IAAI,kBAAkB,CAAC,OAAO,CAAC,CAAC;AACzC,CAAC","sourcesContent":["/**\n * createNativeInteractions - one-call setup for the native adapter, with the\n * same shape as the Babylon, three.js, IWSDK and XR Blocks setups.\n *\n * ```ts\n * const interactions = createNativeInteractions({ attachToHost: true });\n * interactions.register({ id: \"button\", behaviours: [{ kind: \"press\" }] });\n * interactions.runtime.onEvent((event) => console.log(event.type));\n * ```\n *\n * The native app owns the scene, so an interactable is registered by id\n * alone: the app answers hit queries and pose reads for that id through the\n * `interactions` slice. With `attachToHost` the loop drives itself from the\n * app's own frame callback. Without it, call `update(dt)` yourself with\n * seconds.\n */\nimport {\n  InteractionRuntime,\n  type DwellConfig,\n  type InteractableDescriptor,\n} from \"@realitycollective/webxr-interactions\";\nimport { NativeHitTester, type NativeHitTesterOptions } from \"./hit-tester.js\";\nimport { NativeInputProvider, type NativeInputProviderOptions } from \"./provider.js\";\nimport { NativeTransformPort } from \"./transform-port.js\";\nimport { installedHost, type NativeFrameSource } from \"./native-types.js\";\n\nexport interface NativeInteractionsOptions\n  extends NativeInputProviderOptions,\n    NativeHitTesterOptions {\n  dwellDefaults?: DwellConfig;\n  /**\n   * Drive `update(dt)` from the native app's frame callback. Default false -\n   * the app calls `update` from its own loop.\n   */\n  attachToHost?: boolean;\n  /** Where frames come from for `attachToHost`. Omit to use `globalThis.__rcHost`. */\n  frames?: NativeFrameSource;\n}\n\n/** Longest frame the host-attached loop will report, in seconds. */\nconst MAX_FRAME_SECONDS = 0.1;\n\nexport class NativeInteractions {\n  readonly runtime: InteractionRuntime;\n  readonly provider: NativeInputProvider;\n  readonly hitTester: NativeHitTester;\n  private readonly ports = new Map<string, NativeTransformPort>();\n  private readonly options: NativeInteractionsOptions;\n  private detachHost: (() => void) | null = null;\n\n  constructor(options: NativeInteractionsOptions = {}) {\n    this.options = options;\n    this.provider = new NativeInputProvider(options);\n    this.hitTester = new NativeHitTester(options);\n    this.runtime = new InteractionRuntime({\n      provider: this.provider,\n      hitTester: this.hitTester,\n      ...(options.dwellDefaults ? { dwellDefaults: options.dwellDefaults } : {}),\n    });\n    if (options.attachToHost) this.attachToHost(options);\n  }\n\n  /** Register an interactable. The native app knows it by `descriptor.id`. */\n  register(descriptor: InteractableDescriptor): NativeTransformPort {\n    const port = new NativeTransformPort(\n      descriptor.id,\n      this.options.interactions ? { interactions: this.options.interactions } : {},\n    );\n    this.ports.set(descriptor.id, port);\n    this.runtime.registerInteractable(descriptor, { transform: port });\n    return port;\n  }\n\n  unregister(id: string): void {\n    this.runtime.unregisterInteractable(id);\n    this.ports.delete(id);\n  }\n\n  getPort(id: string): NativeTransformPort | 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.detachHost?.();\n    this.detachHost = null;\n    this.runtime.dispose();\n  }\n\n  private attachToHost(options: NativeInteractionsOptions): void {\n    const frames = options.frames ?? installedHost();\n    if (!frames?.onFrame) {\n      throw new Error(\n        \"@realitycollective/native-interactions: attachToHost needs a frame source, and globalThis.__rcHost.onFrame is not installed. Pass `frames`, or call update(dt) yourself.\",\n      );\n    }\n    // The app reports the frame delta in seconds. A long frame is clamped so\n    // behaviours integrate over a sane step rather than jumping.\n    this.detachHost = frames.onFrame((_timestampMs, deltaS) => {\n      this.update(Math.min(MAX_FRAME_SECONDS, Math.max(0, deltaS)));\n    });\n  }\n}\n\nexport function createNativeInteractions(\n  options: NativeInteractionsOptions = {},\n): NativeInteractions {\n  return new NativeInteractions(options);\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Public entry point of the native adapter: the same kinds of export as the
+ * Babylon, three.js, IWSDK and XR Blocks adapters. The core is re-exported;
+ * the provider, hit tester and transform port implement its contracts; the
+ * setup entry point wires them together; and the slice types describe what
+ * the native app installs on `globalThis.__rcHost`. Slice reading and tuple
+ * copying stay internal.
+ */
+export * from "@realitycollective/webxr-interactions";
+export type { NativeFrameSource, NativeHit, NativeHostSlices, NativeInputHost, NativeInteractionHost, } from "./native-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,14 @@
+/**
+ * Public entry point of the native adapter: the same kinds of export as the
+ * Babylon, three.js, IWSDK and XR Blocks adapters. The core is re-exported;
+ * the provider, hit tester and transform port implement its contracts; the
+ * setup entry point wires them together; and the slice types describe what
+ * the native app installs on `globalThis.__rcHost`. Slice reading and tuple
+ * copying stay internal.
+ */
+export * from "@realitycollective/webxr-interactions";
+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;;;;;;;GAOG;AACH,cAAc,uCAAuC,CAAC;AAQtD,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,WAAW,CAAC","sourcesContent":["/**\n * Public entry point of the native adapter: the same kinds of export as the\n * Babylon, three.js, IWSDK and XR Blocks adapters. The core is re-exported;\n * the provider, hit tester and transform port implement its contracts; the\n * setup entry point wires them together; and the slice types describe what\n * the native app installs on `globalThis.__rcHost`. Slice reading and tuple\n * copying stay internal.\n */\nexport * from \"@realitycollective/webxr-interactions\";\nexport type {\n  NativeFrameSource,\n  NativeHit,\n  NativeHostSlices,\n  NativeInputHost,\n  NativeInteractionHost,\n} from \"./native-types.js\";\nexport * from \"./provider.js\";\nexport * from \"./hit-tester.js\";\nexport * from \"./transform-port.js\";\nexport * from \"./host.js\";\n"]}

package/dist/native-types.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The `input` and `interactions` slices a native host (OpenXR on Quest,
+ * CompositorServices on visionOS, or any other shell embedding a JavaScript
+ * engine such as Hermes) installs on `globalThis.__rcHost`.
+ *
+ * These are NOT new contracts: `NativeInputHost` is the exact shape of
+ * `InputProvider` from `@realitycollective/webxr-input`, and
+ * `NativeInteractionHost` is `HitTester` plus `TransformPort` from
+ * `@realitycollective/webxr-interactions/ports`, with a `targetId` added to
+ * every `TransformPort` member because that port is per object and the host
+ * is one object serving every registered interactable. Declaring them again
+ * here, rather than reusing the originals by reference, is deliberate: this
+ * file is the one place that states what crosses the native boundary, kept
+ * in the same structural-typing style as `babylon-types.ts` and the XR
+ * Blocks `XB*Like` types, so it reads correctly even without the other two
+ * packages open.
+ *
+ * Values that cross are plain: numbers, strings, booleans and tuples. No
+ * engine objects in either direction, and assets stay entirely on the
+ * native side.
+ */
+import type { Handedness, HeadPose, InputCapabilities, InputHitHint, InputSourceSnapshot, PoseTuple, PresenceModality, QuatTuple, RayTuple, Unsubscribe, Vec3Tuple } from "@realitycollective/webxr-input";
+/** The native host's `input` slice. Mirrors `InputProvider` member for member. */
+export interface NativeInputHost {
+    getCapabilities(): InputCapabilities;
+    onCapabilitiesChanged(listener: (capabilities: InputCapabilities) => void): Unsubscribe;
+    onSourcesChanged(listener: () => void): Unsubscribe;
+    sample(): readonly InputSourceSnapshot[];
+    getHeadPose?(): HeadPose;
+    sampleHints?(): readonly InputHitHint[];
+    pulse?(sourceId: string, intensity: number, durationMs: number): boolean;
+    setPresenceVisible?(target: Handedness | "all", visible: boolean): boolean;
+    setPresenceModality?(mode: PresenceModality): boolean;
+}
+/** What the host's ray/proximity query reports: the target it reached, if any. */
+export interface NativeHit {
+    /** The target id the app registered with `NativeTransformPort`/its own scene. */
+    targetId: string;
+    /** Distance from the query origin (ray origin / probe point). */
+    distance: number;
+    /** World-space hit or closest point. */
+    point: Vec3Tuple;
+}
+/**
+ * The native host's `interactions` slice: `HitTester` unchanged, and
+ * `TransformPort` with every member keyed by the target id the app chose
+ * when it registered the object with the native scene, because one host
+ * object serves every interactable rather than one port per object.
+ */
+export interface NativeInteractionHost {
+    hitRay(ray: RayTuple): NativeHit | null;
+    hitProximity(point: Vec3Tuple, radius: number): NativeHit | null;
+    /** Where the object is now. */
+    getWorldPose(targetId: string): PoseTuple;
+    /** The rest pose captured at registration, in world space. */
+    getRestWorldPose(targetId: string): PoseTuple;
+    getLocalOffset(targetId: string): Vec3Tuple;
+    setLocalOffset(targetId: string, offset: Vec3Tuple): void;
+    setLocalRotation(targetId: string, quaternion: QuatTuple): void;
+    setWorldPose?(targetId: string, pose: PoseTuple): void;
+    setEffect?(targetId: string, effect: {
+        scale?: number;
+        emissive?: number;
+    }): void;
+}
+/**
+ * The native app's frame callback, the root member of `__rcHost` that
+ * `NativeInteractions` attaches to when `attachToHost` is set.
+ */
+export interface NativeFrameSource {
+    onFrame(callback: (timestampMs: number, deltaS: number) => void): () => void;
+}
+/** The two slices this package reads off `globalThis.__rcHost`. */
+export interface NativeHostSlices {
+    input: NativeInputHost;
+    interactions: NativeInteractionHost;
+}
+/**
+ * `globalThis.__rcHost`, read defensively: the root `NativeHost` interface
+ * belongs to `service-framework-native`, which this package does not depend
+ * on, so the global is read as an unknown bag of optional slices rather than
+ * imported.
+ */
+export declare function installedHost(): (Partial<NativeHostSlices> & Partial<NativeFrameSource>) | undefined;
+/**
+ * Resolve one slice: the value passed in, or `globalThis.__rcHost`'s slice
+ * of the same name. Throws one clear error naming the missing slice, so a
+ * native-interactions class fails at construction rather than the first
+ * time something calls a method that is not there.
+ */
+export declare function resolveHostSlice<K extends keyof NativeHostSlices>(name: K, injected: NativeHostSlices[K] | undefined): NativeHostSlices[K];
+/** Copy a position tuple. */
+export declare function copyVec3(v: Vec3Tuple): Vec3Tuple;
+/** Copy an orientation tuple. */
+export declare function copyQuat(q: QuatTuple): QuatTuple;
+/** Copy a pose (position + orientation). */
+export declare function copyPose(pose: PoseTuple): PoseTuple;
+/** Copy a ray (origin + direction). */
+export declare function copyRay(ray: RayTuple): RayTuple;
+/**
+ * Copy one `InputSourceSnapshot` field by field, including every tuple it
+ * carries, so a host that pools and refills its own snapshot objects still
+ * meets the ownership rule: a snapshot handed to `sample()`'s caller is
+ * never written to again.
+ */
+export declare function copySnapshot(source: InputSourceSnapshot): InputSourceSnapshot;

package/dist/native-types.js

@@ -0,0 +1,73 @@
+/**
+ * `globalThis.__rcHost`, read defensively: the root `NativeHost` interface
+ * belongs to `service-framework-native`, which this package does not depend
+ * on, so the global is read as an unknown bag of optional slices rather than
+ * imported.
+ */
+export function installedHost() {
+    return globalThis.__rcHost;
+}
+/**
+ * Resolve one slice: the value passed in, or `globalThis.__rcHost`'s slice
+ * of the same name. Throws one clear error naming the missing slice, so a
+ * native-interactions class fails at construction rather than the first
+ * time something calls a method that is not there.
+ */
+export function resolveHostSlice(name, injected) {
+    const slice = injected ?? installedHost()?.[name];
+    if (!slice) {
+        throw new Error(`@realitycollective/native-interactions: no "${name}" slice was supplied and globalThis.__rcHost.${name} is not installed. Pass one directly, or have the native app install it before this package is constructed.`);
+    }
+    return slice;
+}
+// ---------------------------------------------------------------------------
+// Copies. A host may reuse its own buffers across calls, so every tuple that
+// crosses back into this package is copied on the way in, never referenced.
+// ---------------------------------------------------------------------------
+/** Copy a position tuple. */
+export function copyVec3(v) {
+    return [v[0], v[1], v[2]];
+}
+/** Copy an orientation tuple. */
+export function copyQuat(q) {
+    return [q[0], q[1], q[2], q[3]];
+}
+/** Copy a pose (position + orientation). */
+export function copyPose(pose) {
+    return { position: copyVec3(pose.position), quaternion: copyQuat(pose.quaternion) };
+}
+/** Copy a ray (origin + direction). */
+export function copyRay(ray) {
+    return { origin: copyVec3(ray.origin), direction: copyVec3(ray.direction) };
+}
+/**
+ * Copy one `InputSourceSnapshot` field by field, including every tuple it
+ * carries, so a host that pools and refills its own snapshot objects still
+ * meets the ownership rule: a snapshot handed to `sample()`'s caller is
+ * never written to again.
+ */
+export function copySnapshot(source) {
+    const copy = {
+        id: source.id,
+        kind: source.kind,
+        handedness: source.handedness,
+        select: source.select,
+        squeeze: source.squeeze,
+    };
+    if (source.ray)
+        copy.ray = copyRay(source.ray);
+    if (source.gripPose)
+        copy.gripPose = copyPose(source.gripPose);
+    if (source.indexTip)
+        copy.indexTip = copyVec3(source.indexTip);
+    if (source.linearVelocity)
+        copy.linearVelocity = copyVec3(source.linearVelocity);
+    if (source.angularVelocity)
+        copy.angularVelocity = copyVec3(source.angularVelocity);
+    if (source.nativeGrabbing !== undefined)
+        copy.nativeGrabbing = source.nativeGrabbing;
+    if (source.hapticsAvailable !== undefined)
+        copy.hapticsAvailable = source.hapticsAvailable;
+    return copy;
+}
+//# sourceMappingURL=native-types.js.map

package/dist/native-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-types.js","sourceRoot":"","sources":["../src/native-types.ts"],"names":[],"mappings":"AA4FA;;;;;GAKG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAQ,UAAoF,CAAC,QAAQ,CAAC;AACxG,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAO,EACP,QAAyC;IAEzC,MAAM,KAAK,GAAG,QAAQ,IAAK,aAAa,EAA4C,EAAE,CAAC,IAAI,CAAC,CAAC;IAC7F,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,+CAA+C,IAAI,gDAAgD,IAAI,6GAA6G,CACrN,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,8EAA8E;AAC9E,6EAA6E;AAC7E,4EAA4E;AAC5E,8EAA8E;AAE9E,6BAA6B;AAC7B,MAAM,UAAU,QAAQ,CAAC,CAAY;IACnC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5B,CAAC;AAED,iCAAiC;AACjC,MAAM,UAAU,QAAQ,CAAC,CAAY;IACnC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAClC,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,QAAQ,CAAC,IAAe;IACtC,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;AACtF,CAAC;AAED,uCAAuC;AACvC,MAAM,UAAU,OAAO,CAAC,GAAa;IACnC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;AAC9E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,MAA2B;IACtD,MAAM,IAAI,GAAwB;QAChC,EAAE,EAAE,MAAM,CAAC,EAAE;QACb,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,OAAO,EAAE,MAAM,CAAC,OAAO;KACxB,CAAC;IACF,IAAI,MAAM,CAAC,GAAG;QAAE,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC/C,IAAI,MAAM,CAAC,QAAQ;QAAE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/D,IAAI,MAAM,CAAC,QAAQ;QAAE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/D,IAAI,MAAM,CAAC,cAAc;QAAE,IAAI,CAAC,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IACjF,IAAI,MAAM,CAAC,eAAe;QAAE,IAAI,CAAC,eAAe,GAAG,QAAQ,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;IACpF,IAAI,MAAM,CAAC,cAAc,KAAK,SAAS;QAAE,IAAI,CAAC,cAAc,GAAG,MAAM,CAAC,cAAc,CAAC;IACrF,IAAI,MAAM,CAAC,gBAAgB,KAAK,SAAS;QAAE,IAAI,CAAC,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,CAAC;IAC3F,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["/**\n * The `input` and `interactions` slices a native host (OpenXR on Quest,\n * CompositorServices on visionOS, or any other shell embedding a JavaScript\n * engine such as Hermes) installs on `globalThis.__rcHost`.\n *\n * These are NOT new contracts: `NativeInputHost` is the exact shape of\n * `InputProvider` from `@realitycollective/webxr-input`, and\n * `NativeInteractionHost` is `HitTester` plus `TransformPort` from\n * `@realitycollective/webxr-interactions/ports`, with a `targetId` added to\n * every `TransformPort` member because that port is per object and the host\n * is one object serving every registered interactable. Declaring them again\n * here, rather than reusing the originals by reference, is deliberate: this\n * file is the one place that states what crosses the native boundary, kept\n * in the same structural-typing style as `babylon-types.ts` and the XR\n * Blocks `XB*Like` types, so it reads correctly even without the other two\n * packages open.\n *\n * Values that cross are plain: numbers, strings, booleans and tuples. No\n * engine objects in either direction, and assets stay entirely on the\n * native side.\n */\nimport type {\n  Handedness,\n  HeadPose,\n  InputCapabilities,\n  InputHitHint,\n  InputSourceSnapshot,\n  PoseTuple,\n  PresenceModality,\n  QuatTuple,\n  RayTuple,\n  Unsubscribe,\n  Vec3Tuple,\n} from \"@realitycollective/webxr-input\";\n\n/** The native host's `input` slice. Mirrors `InputProvider` member for member. */\nexport interface NativeInputHost {\n  getCapabilities(): InputCapabilities;\n  onCapabilitiesChanged(listener: (capabilities: InputCapabilities) => void): Unsubscribe;\n  onSourcesChanged(listener: () => void): Unsubscribe;\n  sample(): readonly InputSourceSnapshot[];\n  getHeadPose?(): HeadPose;\n  sampleHints?(): readonly InputHitHint[];\n  pulse?(sourceId: string, intensity: number, durationMs: number): boolean;\n  setPresenceVisible?(target: Handedness | \"all\", visible: boolean): boolean;\n  setPresenceModality?(mode: PresenceModality): boolean;\n}\n\n/** What the host's ray/proximity query reports: the target it reached, if any. */\nexport interface NativeHit {\n  /** The target id the app registered with `NativeTransformPort`/its own scene. */\n  targetId: string;\n  /** Distance from the query origin (ray origin / probe point). */\n  distance: number;\n  /** World-space hit or closest point. */\n  point: Vec3Tuple;\n}\n\n/**\n * The native host's `interactions` slice: `HitTester` unchanged, and\n * `TransformPort` with every member keyed by the target id the app chose\n * when it registered the object with the native scene, because one host\n * object serves every interactable rather than one port per object.\n */\nexport interface NativeInteractionHost {\n  hitRay(ray: RayTuple): NativeHit | null;\n  hitProximity(point: Vec3Tuple, radius: number): NativeHit | null;\n  /** Where the object is now. */\n  getWorldPose(targetId: string): PoseTuple;\n  /** The rest pose captured at registration, in world space. */\n  getRestWorldPose(targetId: string): PoseTuple;\n  getLocalOffset(targetId: string): Vec3Tuple;\n  setLocalOffset(targetId: string, offset: Vec3Tuple): void;\n  setLocalRotation(targetId: string, quaternion: QuatTuple): void;\n  setWorldPose?(targetId: string, pose: PoseTuple): void;\n  setEffect?(targetId: string, effect: { scale?: number; emissive?: number }): void;\n}\n\n/**\n * The native app's frame callback, the root member of `__rcHost` that\n * `NativeInteractions` attaches to when `attachToHost` is set.\n */\nexport interface NativeFrameSource {\n  onFrame(callback: (timestampMs: number, deltaS: number) => void): () => void;\n}\n\n/** The two slices this package reads off `globalThis.__rcHost`. */\nexport interface NativeHostSlices {\n  input: NativeInputHost;\n  interactions: NativeInteractionHost;\n}\n\n/**\n * `globalThis.__rcHost`, read defensively: the root `NativeHost` interface\n * belongs to `service-framework-native`, which this package does not depend\n * on, so the global is read as an unknown bag of optional slices rather than\n * imported.\n */\nexport function installedHost(): (Partial<NativeHostSlices> & Partial<NativeFrameSource>) | undefined {\n  return (globalThis as { __rcHost?: Partial<NativeHostSlices> & Partial<NativeFrameSource> }).__rcHost;\n}\n\n/**\n * Resolve one slice: the value passed in, or `globalThis.__rcHost`'s slice\n * of the same name. Throws one clear error naming the missing slice, so a\n * native-interactions class fails at construction rather than the first\n * time something calls a method that is not there.\n */\nexport function resolveHostSlice<K extends keyof NativeHostSlices>(\n  name: K,\n  injected: NativeHostSlices[K] | undefined,\n): NativeHostSlices[K] {\n  const slice = injected ?? (installedHost() as Partial<NativeHostSlices> | undefined)?.[name];\n  if (!slice) {\n    throw new Error(\n      `@realitycollective/native-interactions: no \"${name}\" slice was supplied and globalThis.__rcHost.${name} is not installed. Pass one directly, or have the native app install it before this package is constructed.`,\n    );\n  }\n  return slice;\n}\n\n// ---------------------------------------------------------------------------\n// Copies. A host may reuse its own buffers across calls, so every tuple that\n// crosses back into this package is copied on the way in, never referenced.\n// ---------------------------------------------------------------------------\n\n/** Copy a position tuple. */\nexport function copyVec3(v: Vec3Tuple): Vec3Tuple {\n  return [v[0], v[1], v[2]];\n}\n\n/** Copy an orientation tuple. */\nexport function copyQuat(q: QuatTuple): QuatTuple {\n  return [q[0], q[1], q[2], q[3]];\n}\n\n/** Copy a pose (position + orientation). */\nexport function copyPose(pose: PoseTuple): PoseTuple {\n  return { position: copyVec3(pose.position), quaternion: copyQuat(pose.quaternion) };\n}\n\n/** Copy a ray (origin + direction). */\nexport function copyRay(ray: RayTuple): RayTuple {\n  return { origin: copyVec3(ray.origin), direction: copyVec3(ray.direction) };\n}\n\n/**\n * Copy one `InputSourceSnapshot` field by field, including every tuple it\n * carries, so a host that pools and refills its own snapshot objects still\n * meets the ownership rule: a snapshot handed to `sample()`'s caller is\n * never written to again.\n */\nexport function copySnapshot(source: InputSourceSnapshot): InputSourceSnapshot {\n  const copy: InputSourceSnapshot = {\n    id: source.id,\n    kind: source.kind,\n    handedness: source.handedness,\n    select: source.select,\n    squeeze: source.squeeze,\n  };\n  if (source.ray) copy.ray = copyRay(source.ray);\n  if (source.gripPose) copy.gripPose = copyPose(source.gripPose);\n  if (source.indexTip) copy.indexTip = copyVec3(source.indexTip);\n  if (source.linearVelocity) copy.linearVelocity = copyVec3(source.linearVelocity);\n  if (source.angularVelocity) copy.angularVelocity = copyVec3(source.angularVelocity);\n  if (source.nativeGrabbing !== undefined) copy.nativeGrabbing = source.nativeGrabbing;\n  if (source.hapticsAvailable !== undefined) copy.hapticsAvailable = source.hapticsAvailable;\n  return copy;\n}\n"]}

package/dist/provider.d.ts

@@ -0,0 +1,34 @@
+/**
+ * NativeInputProvider - the native host's input provider.
+ *
+ * A thin, copying pass-through over the `input` slice a native app (OpenXR,
+ * visionOS) installs on `globalThis.__rcHost`, or hands in directly for
+ * tests. Every snapshot, and every tuple inside it, is copied before it
+ * leaves this class, so a host that reuses its own sample buffers still
+ * meets the ownership rule the shared contract suite checks.
+ *
+ * Optional members - `getHeadPose`, `sampleHints`, `pulse`,
+ * `setPresenceVisible`, `setPresenceModality` - are only ever assigned when
+ * the host itself carries them, so `typeof provider.pulse` answers honestly
+ * for a host that cannot pulse rather than a method that is present but
+ * always returns false.
+ */
+import { type Handedness, type HeadPose, type InputCapabilities, type InputHitHint, type InputProvider, type InputSourceSnapshot, type PresenceModality, type Unsubscribe } from "@realitycollective/webxr-input";
+import { type NativeInputHost } from "./native-types.js";
+export interface NativeInputProviderOptions {
+    /** The `input` slice. Omit to read `globalThis.__rcHost.input`. */
+    input?: NativeInputHost;
+}
+export declare class NativeInputProvider implements InputProvider {
+    private readonly host;
+    readonly getHeadPose?: () => HeadPose;
+    readonly sampleHints?: () => readonly InputHitHint[];
+    readonly pulse?: (sourceId: string, intensity: number, durationMs: number) => boolean;
+    readonly setPresenceVisible?: (target: Handedness | "all", visible: boolean) => boolean;
+    readonly setPresenceModality?: (mode: PresenceModality) => boolean;
+    constructor(options?: NativeInputProviderOptions);
+    getCapabilities(): InputCapabilities;
+    onCapabilitiesChanged(listener: (capabilities: InputCapabilities) => void): Unsubscribe;
+    onSourcesChanged(listener: () => void): Unsubscribe;
+    sample(): readonly InputSourceSnapshot[];
+}

package/dist/provider.js

@@ -0,0 +1,61 @@
+/**
+ * NativeInputProvider - the native host's input provider.
+ *
+ * A thin, copying pass-through over the `input` slice a native app (OpenXR,
+ * visionOS) installs on `globalThis.__rcHost`, or hands in directly for
+ * tests. Every snapshot, and every tuple inside it, is copied before it
+ * leaves this class, so a host that reuses its own sample buffers still
+ * meets the ownership rule the shared contract suite checks.
+ *
+ * Optional members - `getHeadPose`, `sampleHints`, `pulse`,
+ * `setPresenceVisible`, `setPresenceModality` - are only ever assigned when
+ * the host itself carries them, so `typeof provider.pulse` answers honestly
+ * for a host that cannot pulse rather than a method that is present but
+ * always returns false.
+ */
+import {} from "@realitycollective/webxr-input";
+import { copyPose, copySnapshot, resolveHostSlice } from "./native-types.js";
+export class NativeInputProvider {
+    host;
+    getHeadPose;
+    sampleHints;
+    pulse;
+    setPresenceVisible;
+    setPresenceModality;
+    constructor(options = {}) {
+        this.host = resolveHostSlice("input", options.input);
+        if (this.host.getHeadPose) {
+            const host = this.host;
+            this.getHeadPose = () => copyPose(host.getHeadPose());
+        }
+        if (this.host.sampleHints) {
+            const host = this.host;
+            this.sampleHints = () => host.sampleHints().map((hint) => ({ ...hint }));
+        }
+        if (this.host.pulse) {
+            const host = this.host;
+            this.pulse = (sourceId, intensity, durationMs) => host.pulse(sourceId, intensity, durationMs);
+        }
+        if (this.host.setPresenceVisible) {
+            const host = this.host;
+            this.setPresenceVisible = (target, visible) => host.setPresenceVisible(target, visible);
+        }
+        if (this.host.setPresenceModality) {
+            const host = this.host;
+            this.setPresenceModality = (mode) => host.setPresenceModality(mode);
+        }
+    }
+    getCapabilities() {
+        return this.host.getCapabilities();
+    }
+    onCapabilitiesChanged(listener) {
+        return this.host.onCapabilitiesChanged(listener);
+    }
+    onSourcesChanged(listener) {
+        return this.host.onSourcesChanged(listener);
+    }
+    sample() {
+        return this.host.sample().map(copySnapshot);
+    }
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EASN,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,gBAAgB,EAAwB,MAAM,mBAAmB,CAAC;AAOnG,MAAM,OAAO,mBAAmB;IACb,IAAI,CAAkB;IAE9B,WAAW,CAAkB;IAC7B,WAAW,CAAiC;IAC5C,KAAK,CAAwE;IAC7E,kBAAkB,CAA6D;IAC/E,mBAAmB,CAAuC;IAEnE,YAAY,UAAsC,EAAE;QAClD,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QAErD,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YAC1B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;YACvB,IAAI,CAAC,WAAW,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAY,EAAE,CAAC,CAAC;QACzD,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YAC1B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;YACvB,IAAI,CAAC,WAAW,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,WAAY,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC;QAC5E,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YACpB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;YACvB,IAAI,CAAC,KAAK,GAAG,CAAC,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,EAAE,CAAC,IAAI,CAAC,KAAM,CAAC,QAAQ,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;QACjG,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC;YACjC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;YACvB,IAAI,CAAC,kBAAkB,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,kBAAmB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC3F,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,CAAC;YAClC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;YACvB,IAAI,CAAC,mBAAmB,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,mBAAoB,CAAC,IAAI,CAAC,CAAC;QACvE,CAAC;IACH,CAAC;IAED,eAAe;QACb,OAAO,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;IACrC,CAAC;IAED,qBAAqB,CAAC,QAAmD;QACvE,OAAO,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IACnD,CAAC;IAED,gBAAgB,CAAC,QAAoB;QACnC,OAAO,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAC9C,CAAC;IAED,MAAM;QACJ,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC9C,CAAC;CACF","sourcesContent":["/**\n * NativeInputProvider - the native host's input provider.\n *\n * A thin, copying pass-through over the `input` slice a native app (OpenXR,\n * visionOS) installs on `globalThis.__rcHost`, or hands in directly for\n * tests. Every snapshot, and every tuple inside it, is copied before it\n * leaves this class, so a host that reuses its own sample buffers still\n * meets the ownership rule the shared contract suite checks.\n *\n * Optional members - `getHeadPose`, `sampleHints`, `pulse`,\n * `setPresenceVisible`, `setPresenceModality` - are only ever assigned when\n * the host itself carries them, so `typeof provider.pulse` answers honestly\n * for a host that cannot pulse rather than a method that is present but\n * always returns false.\n */\nimport {\n  type Handedness,\n  type HeadPose,\n  type InputCapabilities,\n  type InputHitHint,\n  type InputProvider,\n  type InputSourceSnapshot,\n  type PresenceModality,\n  type Unsubscribe,\n} from \"@realitycollective/webxr-input\";\nimport { copyPose, copySnapshot, resolveHostSlice, type NativeInputHost } from \"./native-types.js\";\n\nexport interface NativeInputProviderOptions {\n  /** The `input` slice. Omit to read `globalThis.__rcHost.input`. */\n  input?: NativeInputHost;\n}\n\nexport class NativeInputProvider implements InputProvider {\n  private readonly host: NativeInputHost;\n\n  readonly getHeadPose?: () => HeadPose;\n  readonly sampleHints?: () => readonly InputHitHint[];\n  readonly pulse?: (sourceId: string, intensity: number, durationMs: number) => boolean;\n  readonly setPresenceVisible?: (target: Handedness | \"all\", visible: boolean) => boolean;\n  readonly setPresenceModality?: (mode: PresenceModality) => boolean;\n\n  constructor(options: NativeInputProviderOptions = {}) {\n    this.host = resolveHostSlice(\"input\", options.input);\n\n    if (this.host.getHeadPose) {\n      const host = this.host;\n      this.getHeadPose = () => copyPose(host.getHeadPose!());\n    }\n    if (this.host.sampleHints) {\n      const host = this.host;\n      this.sampleHints = () => host.sampleHints!().map((hint) => ({ ...hint }));\n    }\n    if (this.host.pulse) {\n      const host = this.host;\n      this.pulse = (sourceId, intensity, durationMs) => host.pulse!(sourceId, intensity, durationMs);\n    }\n    if (this.host.setPresenceVisible) {\n      const host = this.host;\n      this.setPresenceVisible = (target, visible) => host.setPresenceVisible!(target, visible);\n    }\n    if (this.host.setPresenceModality) {\n      const host = this.host;\n      this.setPresenceModality = (mode) => host.setPresenceModality!(mode);\n    }\n  }\n\n  getCapabilities(): InputCapabilities {\n    return this.host.getCapabilities();\n  }\n\n  onCapabilitiesChanged(listener: (capabilities: InputCapabilities) => void): Unsubscribe {\n    return this.host.onCapabilitiesChanged(listener);\n  }\n\n  onSourcesChanged(listener: () => void): Unsubscribe {\n    return this.host.onSourcesChanged(listener);\n  }\n\n  sample(): readonly InputSourceSnapshot[] {\n    return this.host.sample().map(copySnapshot);\n  }\n}\n"]}

package/dist/transform-port.d.ts

@@ -0,0 +1,34 @@
+/**
+ * NativeTransformPort - the read/write surface of ONE interactable, over the
+ * native host's `interactions` slice. The host serves every registered
+ * object through one set of methods, so this port is a thin binding of one
+ * `targetId` onto them - the same idea as `BabylonTransformPort` binding to
+ * one node, but the object itself lives on the native side.
+ *
+ * `setWorldPose` and `setEffect` are optional on `TransformPort`, and are
+ * only ever assigned here when the host itself carries the matching member,
+ * so an app whose native host cannot follow a world pose, or has no effect
+ * hook, sees a port without one rather than a method that silently no-ops.
+ */
+import type { PoseTuple, QuatTuple, Vec3Tuple } from "@realitycollective/webxr-input";
+import type { TransformPort } from "@realitycollective/webxr-interactions";
+import { type NativeInteractionHost } from "./native-types.js";
+export interface NativeTransformPortOptions {
+    /** The `interactions` slice. Omit to read `globalThis.__rcHost.interactions`. */
+    interactions?: NativeInteractionHost;
+}
+export declare class NativeTransformPort implements TransformPort {
+    private readonly host;
+    private readonly targetId;
+    readonly setWorldPose?: (pose: PoseTuple) => void;
+    readonly setEffect?: (effect: {
+        scale?: number;
+        emissive?: number;
+    }) => void;
+    constructor(targetId: string, options?: NativeTransformPortOptions);
+    getWorldPose(): PoseTuple;
+    getRestWorldPose(): PoseTuple;
+    getLocalOffset(): Vec3Tuple;
+    setLocalOffset(offset: Vec3Tuple): void;
+    setLocalRotation(quaternion: QuatTuple): void;
+}

package/dist/transform-port.js

@@ -0,0 +1,35 @@
+import { copyPose, copyQuat, copyVec3, resolveHostSlice, } from "./native-types.js";
+export class NativeTransformPort {
+    host;
+    targetId;
+    setWorldPose;
+    setEffect;
+    constructor(targetId, options = {}) {
+        this.targetId = targetId;
+        this.host = resolveHostSlice("interactions", options.interactions);
+        if (this.host.setWorldPose) {
+            const host = this.host;
+            this.setWorldPose = (pose) => host.setWorldPose(targetId, copyPose(pose));
+        }
+        if (this.host.setEffect) {
+            const host = this.host;
+            this.setEffect = (effect) => host.setEffect(targetId, effect);
+        }
+    }
+    getWorldPose() {
+        return copyPose(this.host.getWorldPose(this.targetId));
+    }
+    getRestWorldPose() {
+        return copyPose(this.host.getRestWorldPose(this.targetId));
+    }
+    getLocalOffset() {
+        return copyVec3(this.host.getLocalOffset(this.targetId));
+    }
+    setLocalOffset(offset) {
+        this.host.setLocalOffset(this.targetId, copyVec3(offset));
+    }
+    setLocalRotation(quaternion) {
+        this.host.setLocalRotation(this.targetId, copyQuat(quaternion));
+    }
+}
+//# sourceMappingURL=transform-port.js.map

package/dist/transform-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform-port.js","sourceRoot":"","sources":["../src/transform-port.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,gBAAgB,GAEjB,MAAM,mBAAmB,CAAC;AAO3B,MAAM,OAAO,mBAAmB;IACb,IAAI,CAAwB;IAC5B,QAAQ,CAAS;IAEzB,YAAY,CAA6B;IACzC,SAAS,CAA2D;IAE7E,YAAY,QAAgB,EAAE,UAAsC,EAAE;QACpE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC,cAAc,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;QAEnE,IAAI,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;YACvB,IAAI,CAAC,YAAY,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,YAAa,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;QAC7E,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;YACvB,IAAI,CAAC,SAAS,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,SAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACjE,CAAC;IACH,CAAC;IAED,YAAY;QACV,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IACzD,CAAC;IAED,gBAAgB;QACd,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED,cAAc;QACZ,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED,cAAc,CAAC,MAAiB;QAC9B,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5D,CAAC;IAED,gBAAgB,CAAC,UAAqB;QACpC,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC;IAClE,CAAC;CACF","sourcesContent":["/**\n * NativeTransformPort - the read/write surface of ONE interactable, over the\n * native host's `interactions` slice. The host serves every registered\n * object through one set of methods, so this port is a thin binding of one\n * `targetId` onto them - the same idea as `BabylonTransformPort` binding to\n * one node, but the object itself lives on the native side.\n *\n * `setWorldPose` and `setEffect` are optional on `TransformPort`, and are\n * only ever assigned here when the host itself carries the matching member,\n * so an app whose native host cannot follow a world pose, or has no effect\n * hook, sees a port without one rather than a method that silently no-ops.\n */\nimport type { PoseTuple, QuatTuple, Vec3Tuple } from \"@realitycollective/webxr-input\";\nimport type { TransformPort } from \"@realitycollective/webxr-interactions\";\nimport {\n  copyPose,\n  copyQuat,\n  copyVec3,\n  resolveHostSlice,\n  type NativeInteractionHost,\n} from \"./native-types.js\";\n\nexport interface NativeTransformPortOptions {\n  /** The `interactions` slice. Omit to read `globalThis.__rcHost.interactions`. */\n  interactions?: NativeInteractionHost;\n}\n\nexport class NativeTransformPort implements TransformPort {\n  private readonly host: NativeInteractionHost;\n  private readonly targetId: string;\n\n  readonly setWorldPose?: (pose: PoseTuple) => void;\n  readonly setEffect?: (effect: { scale?: number; emissive?: number }) => void;\n\n  constructor(targetId: string, options: NativeTransformPortOptions = {}) {\n    this.targetId = targetId;\n    this.host = resolveHostSlice(\"interactions\", options.interactions);\n\n    if (this.host.setWorldPose) {\n      const host = this.host;\n      this.setWorldPose = (pose) => host.setWorldPose!(targetId, copyPose(pose));\n    }\n    if (this.host.setEffect) {\n      const host = this.host;\n      this.setEffect = (effect) => host.setEffect!(targetId, effect);\n    }\n  }\n\n  getWorldPose(): PoseTuple {\n    return copyPose(this.host.getWorldPose(this.targetId));\n  }\n\n  getRestWorldPose(): PoseTuple {\n    return copyPose(this.host.getRestWorldPose(this.targetId));\n  }\n\n  getLocalOffset(): Vec3Tuple {\n    return copyVec3(this.host.getLocalOffset(this.targetId));\n  }\n\n  setLocalOffset(offset: Vec3Tuple): void {\n    this.host.setLocalOffset(this.targetId, copyVec3(offset));\n  }\n\n  setLocalRotation(quaternion: QuatTuple): void {\n    this.host.setLocalRotation(this.targetId, copyQuat(quaternion));\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@realitycollective/native-interactions",
+  "version": "0.1.1-preview.0",
+  "description": "Native host adapter for the Reality Collective Interaction Extensions - reads the `input` and `interactions` slices a native app (OpenXR, visionOS) installs on `globalThis.__rcHost`, or an injected fake, and maps them into the engine-free @realitycollective/webxr-interactions core. No engine dependency: assets and rendering stay in the native app. Re-exports the core.",
+  "keywords": [
+    "realitycollective",
+    "native",
+    "openxr",
+    "visionos",
+    "webxr",
+    "xr",
+    "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.4",
+    "@realitycollective/webxr-interactions": "^0.1.1-preview.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/realitycollective/WebXR-Interactions.git",
+    "directory": "packages/native-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"
+  }
+}