@realitycollective/webxr-interactions 0.1.0 → 0.1.1-preview.1

package/dist/contract-cases.js

@@ -0,0 +1,339 @@
+import { quatMultiply, vAdd, vApplyQuat } from "./math.js";
+/**
+ * The shared `HitTester` conformance suite. An adapter's test file is a loop:
+ *
+ * ```ts
+ * for (const contractCase of hitTesterContractCases()) {
+ *   it(contractCase.name, () => contractCase.run(makeSubject()));
+ * }
+ * ```
+ */
+export function hitTesterContractCases() {
+    return HIT_TESTER_CASES;
+}
+const DOWN_RAY = { origin: [0, 0, 0], direction: [0, 0, -1] };
+const AWAY_RAY = { origin: [0, 0, 0], direction: [0, 0, 1] };
+/**
+ * A ray-based query only has to land WITHIN the target's own radius:
+ * `ports.ts` documents `point` as "world-space hit or closest point", so a
+ * mesh-accurate ray tester (three.js) reporting the surface it actually hit
+ * is as conforming as a sphere tester (Babylon, IWSDK) reporting the target's
+ * centre. Placing the target exactly on the ray's line makes both answers
+ * the same point when a tester has no radius-shaped slack, and this is the
+ * tolerance for testers that do.
+ */
+function slack(radius) {
+    return radius + 0.05;
+}
+const HIT_TESTER_CASES = [
+    {
+        name: "an empty scene answers a ray with null",
+        run({ hitTester }) {
+            assert(hitTester.hitRay(DOWN_RAY) === null, "hitRay over an empty scene must return null");
+        },
+    },
+    {
+        name: "a ray through a placed target returns its id, a positive distance and a point near the ray",
+        run({ hitTester, driver }) {
+            const radius = 0.15;
+            driver.place("target", [0, 0, -2], radius);
+            const hit = hitTester.hitRay(DOWN_RAY);
+            assert(hit !== null, "a ray through a placed target must not miss");
+            assert(hit.interactableId === "target", `expected interactableId "target", got "${hit.interactableId}"`);
+            assert(hit.distance > 0, `distance must be positive, got ${hit.distance}`);
+            const eps = slack(radius);
+            assert(closeTo(hit.distance, 2, eps), `distance must be close to 2, got ${hit.distance}`);
+            assertVec3Close(hit.point, [0, 0, -2], eps, "point");
+        },
+    },
+    {
+        name: "a ray pointing away from the target returns null",
+        run({ hitTester, driver }) {
+            driver.place("target", [0, 0, -2], 0.15);
+            assert(hitTester.hitRay(AWAY_RAY) === null, "a ray pointing away from every target must return null");
+        },
+    },
+    {
+        name: "hitProximity finds a target inside its radius and misses outside it",
+        run({ hitTester, driver }) {
+            driver.place("target", [0, 0, -2], 0.1);
+            const inside = hitTester.hitProximity([0, 0, -2], 0.5);
+            assert(inside !== null, "hitProximity at the target's own position must find it");
+            assert(inside.interactableId === "target", `expected interactableId "target", got "${inside.interactableId}"`);
+            const outside = hitTester.hitProximity([5, 5, 5], 0.05);
+            assert(outside === null, "hitProximity far from every target must return null");
+        },
+    },
+    {
+        name: "with two targets on one ray, the nearer one wins",
+        run({ hitTester, driver }) {
+            const radius = 0.1;
+            driver.place("far", [0, 0, -3], radius);
+            driver.place("near", [0, 0, -1], radius);
+            const hit = hitTester.hitRay(DOWN_RAY);
+            assert(hit !== null, "a ray through two targets must not miss");
+            assert(hit.interactableId === "near", `the nearer target must win, got "${hit.interactableId}"`);
+            assert(closeTo(hit.distance, 1, slack(radius)), `distance must be close to 1, got ${hit.distance}`);
+        },
+    },
+    {
+        name: "each hit and its point are fresh values the caller owns",
+        run({ hitTester, driver }) {
+            driver.place("target", [0, 0, -2], 0.15);
+            for (const [label, query] of [
+                ["hitRay", () => hitTester.hitRay(DOWN_RAY)],
+                ["hitProximity", () => hitTester.hitProximity([0, 0, -2], 0.5)],
+            ]) {
+                const first = query();
+                const second = query();
+                assert(first !== null && second !== null, `${label} must find the placed target`);
+                assert(second !== first && second.point !== first.point, `${label} must return a new hit and point each call`);
+                const expected = first.point[2];
+                first.point[2] = 1e6;
+                const third = query();
+                assert(third !== null && closeTo(third.point[2], expected, POSE_EPS), `writing to a returned point must not change the next ${label} answer`);
+            }
+        },
+    },
+];
+/**
+ * The shared `TransformPort` conformance suite. An adapter's test file is a
+ * loop, the same shape as {@link hitTesterContractCases}.
+ */
+export function transformPortContractCases() {
+    return TRANSFORM_PORT_CASES;
+}
+const POSE_EPS = 1e-3;
+// A quarter turn about Y - a non-identity unit quaternion, so the case
+// cannot pass by accident on a port that ignores its argument.
+const QUARTER_TURN_Y = [0, Math.SQRT1_2, 0, Math.SQRT1_2];
+// ---------------------------------------------------------------------------
+// Held / released / reset - the "held pose" rule, checked only when the
+// subject carries a physics driver. One fixed step size and a looser
+// position tolerance than POSE_EPS: real engines differ slightly in their
+// integrator, and a held/reset case allows for up to one step of gravity
+// (see PHYSICS_POSE_EPS's own comment), where the plain pose cases above
+// never touch physics at all.
+// ---------------------------------------------------------------------------
+const PHYSICS_DT = 1 / 60;
+const HELD_STEPS = 5;
+/** metres/second - small enough that one step's drift is easy to read, large enough not to vanish into PHYSICS_POSE_EPS. */
+const RELEASE_SPEED = 2;
+/** metres/second - about 25x RELEASE_SPEED, so "kept the old velocity" and "one step of gravity" cannot be confused. */
+const LARGE_PRIOR_SPEED = 50;
+/**
+ * 2 cm. One step of gravity at PHYSICS_DT droops roughly
+ * `0.5 * 9.8 * PHYSICS_DT^2` ≈ 1.4 mm, well inside this; a full step of
+ * LARGE_PRIOR_SPEED (≈ 0.83 m) or RELEASE_SPEED (≈ 33 mm) is well outside it.
+ */
+const PHYSICS_POSE_EPS = 0.02;
+function assertPhysicsPoseClose(value, expected, label) {
+    assertVec3Close(value.position, expected.position, PHYSICS_POSE_EPS, `${label}.position`);
+    assertQuatClose(value.quaternion, expected.quaternion, `${label}.quaternion`);
+}
+const TRANSFORM_PORT_CASES = [
+    {
+        name: "setLocalOffset then getLocalOffset returns the same offset",
+        run({ port }) {
+            const offset = [0.3, -0.1, 0.05];
+            port.setLocalOffset(offset);
+            assertVec3Close(port.getLocalOffset(), offset, POSE_EPS, "getLocalOffset()");
+        },
+    },
+    {
+        name: "getWorldPose returns finite numbers and a unit quaternion",
+        run({ port }) {
+            const pose = port.getWorldPose();
+            for (const value of [...pose.position, ...pose.quaternion]) {
+                assert(Number.isFinite(value), `getWorldPose() must return finite numbers, got ${value}`);
+            }
+            const length = quatLength(pose.quaternion);
+            assert(closeTo(length, 1, POSE_EPS), `getWorldPose().quaternion must be a unit quaternion, length was ${length}`);
+        },
+    },
+    {
+        name: "setLocalRotation with a unit quaternion does not throw",
+        run({ port }) {
+            try {
+                port.setLocalRotation(QUARTER_TURN_Y);
+            }
+            catch (error) {
+                throw new Error(`setLocalRotation(unit quaternion) must not throw, it threw: ${String(error)}`);
+            }
+        },
+    },
+    {
+        name: "getRestWorldPose returns the pose captured at registration",
+        run({ port, rest }) {
+            assertPoseClose(port.getRestWorldPose(), rest, "getRestWorldPose()");
+        },
+    },
+    {
+        name: "before any write, the live pose is the rest pose",
+        run({ port, rest }) {
+            assertPoseClose(port.getWorldPose(), rest, "getWorldPose()");
+        },
+    },
+    {
+        name: "getWorldPose follows setLocalOffset while getRestWorldPose stays put",
+        run({ port, rest }) {
+            const offset = [0.3, -0.1, 0.05];
+            port.setLocalOffset(offset);
+            assertVec3Close(port.getWorldPose().position, vAdd(rest.position, vApplyQuat(offset, rest.quaternion)), POSE_EPS, "getWorldPose().position after setLocalOffset");
+            assertPoseClose(port.getRestWorldPose(), rest, "getRestWorldPose() after setLocalOffset");
+        },
+    },
+    {
+        name: "getWorldPose follows setLocalRotation while getRestWorldPose stays put",
+        run({ port, rest }) {
+            port.setLocalRotation(QUARTER_TURN_Y);
+            assertQuatClose(port.getWorldPose().quaternion, quatMultiply(rest.quaternion, QUARTER_TURN_Y), "getWorldPose().quaternion after setLocalRotation");
+            assertPoseClose(port.getRestWorldPose(), rest, "getRestWorldPose() after setLocalRotation");
+        },
+    },
+    {
+        name: "setWorldPose, when present, is what getWorldPose reads back",
+        run({ port, rest }) {
+            if (!port.setWorldPose)
+                return;
+            const target = { position: [0.5, 1.2, -0.4], quaternion: QUARTER_TURN_Y };
+            port.setWorldPose(target);
+            assertPoseClose(port.getWorldPose(), target, "getWorldPose() after setWorldPose");
+            assertPoseClose(port.getRestWorldPose(), rest, "getRestWorldPose() after setWorldPose");
+        },
+    },
+    {
+        name: "every returned tuple is a fresh value the caller owns",
+        run({ port }) {
+            const pose = port.getWorldPose();
+            const restPose = port.getRestWorldPose();
+            const offset = port.getLocalOffset();
+            pose.position[0] = 1e6;
+            pose.quaternion[3] = 1e6;
+            restPose.position[0] = 1e6;
+            offset[0] = 1e6;
+            assert(port.getWorldPose().position[0] !== 1e6, "writing to a returned getWorldPose() tuple must not change the port");
+            assert(port.getWorldPose().quaternion[3] !== 1e6, "writing to a returned getWorldPose() quaternion must not change the port");
+            assert(port.getRestWorldPose().position[0] !== 1e6, "writing to a returned getRestWorldPose() tuple must not change the port");
+            assert(port.getLocalOffset()[0] !== 1e6, "writing to a returned getLocalOffset() tuple must not change the port");
+        },
+    },
+    {
+        name: "a tuple passed in is not kept",
+        run({ port }) {
+            const offset = [0.3, -0.1, 0.05];
+            port.setLocalOffset(offset);
+            offset[0] = 9;
+            assertVec3Close(port.getLocalOffset(), [0.3, -0.1, 0.05], POSE_EPS, "getLocalOffset() after the caller reused its tuple");
+            if (!port.setWorldPose)
+                return;
+            const target = { position: [0.5, 1.2, -0.4], quaternion: [0, 0, 0, 1] };
+            port.setWorldPose(target);
+            target.position[0] = 9;
+            assertVec3Close(port.getWorldPose().position, [0.5, 1.2, -0.4], POSE_EPS, "getWorldPose() after the caller reused its tuple");
+        },
+    },
+    {
+        name: "setEffect, when present, accepts scale and emissive without throwing",
+        run({ port }) {
+            if (!port.setEffect)
+                return;
+            try {
+                port.setEffect({ scale: 1.2, emissive: 0.3 });
+            }
+            catch (error) {
+                throw new Error(`setEffect({ scale, emissive }) must not throw, it threw: ${String(error)}`);
+            }
+        },
+    },
+    {
+        name: "Held: beginHold holds a fixed setWorldPose without falling, when the subject has physics",
+        run({ port, rest, physics }) {
+            if (!physics || !port.setWorldPose || !port.beginHold)
+                return;
+            const held = {
+                position: [rest.position[0], rest.position[1] + 1, rest.position[2]],
+                quaternion: rest.quaternion,
+            };
+            port.beginHold();
+            for (let i = 0; i < HELD_STEPS; i++) {
+                port.setWorldPose(held);
+                physics.step(PHYSICS_DT);
+            }
+            // A tight tolerance, not PHYSICS_POSE_EPS: a genuinely held body sees
+            // no simulation at all, so it matches the written pose exactly bar
+            // floating point noise - the same POSE_EPS the non-physics cases
+            // above use. One step of unwanted gravity (~2.7 mm at PHYSICS_DT) is
+            // what this case exists to catch, and it must not hide inside the
+            // tolerance the way it deliberately may in the Reset case below.
+            assertPoseClose(port.getWorldPose(), held, `getWorldPose() after ${HELD_STEPS} held steps`);
+        },
+    },
+    {
+        name: "Released: endHold sends the body away with the release velocity, when the subject has physics",
+        run({ port, rest, physics }) {
+            if (!physics || !port.beginHold || !port.endHold)
+                return;
+            port.beginHold();
+            const release = { linearVelocity: [RELEASE_SPEED, 0, 0], angularVelocity: [0, 0, 0] };
+            port.endHold(release);
+            physics.step(PHYSICS_DT);
+            const moved = port.getWorldPose().position[0] - rest.position[0];
+            assert(moved > RELEASE_SPEED * PHYSICS_DT * 0.5, `endHold({ linearVelocity: [${RELEASE_SPEED}, 0, 0] }) must move the body that way within one step, moved ${moved}`);
+        },
+    },
+    {
+        name: "Reset: setWorldPose while not held teleports to the pose and clears velocity, when the subject has physics",
+        run({ port, rest, physics }) {
+            if (!physics || !port.setWorldPose || !port.beginHold || !port.endHold)
+                return;
+            // Give the body a large prior velocity and let it run for a step, so
+            // carrying that velocity through the reset below is unmistakable -
+            // one step of it (~0.83 m) dwarfs PHYSICS_POSE_EPS (2 cm).
+            port.beginHold();
+            const priorRelease = { linearVelocity: [LARGE_PRIOR_SPEED, 0, 0], angularVelocity: [0, 0, 0] };
+            port.endHold(priorRelease);
+            physics.step(PHYSICS_DT);
+            const target = {
+                position: [rest.position[0] - 1, rest.position[1] + 2, rest.position[2] + 0.5],
+                quaternion: rest.quaternion,
+            };
+            port.setWorldPose(target);
+            // One further step: it must be at `target`, not carrying the prior
+            // velocity forward - allowing for this one step's worth of gravity.
+            physics.step(PHYSICS_DT);
+            assertPhysicsPoseClose(port.getWorldPose(), target, "getWorldPose() one step after a reset setWorldPose");
+        },
+    },
+];
+// ---------------------------------------------------------------------------
+// Shared assertion helpers
+// ---------------------------------------------------------------------------
+function assert(condition, message) {
+    if (!condition)
+        throw new Error(message);
+}
+function closeTo(a, b, eps) {
+    return Math.abs(a - b) <= eps;
+}
+// Indexed one component at a time, rather than in a loop, so each index is a
+// literal: `noUncheckedIndexedAccess` cannot narrow a tuple read through a
+// variable index back to `number`.
+function assertVec3Close(value, expected, eps, label) {
+    assert(closeTo(value[0], expected[0], eps), `${label}[0] must be close to ${expected[0]}, got ${value[0]}`);
+    assert(closeTo(value[1], expected[1], eps), `${label}[1] must be close to ${expected[1]}, got ${value[1]}`);
+    assert(closeTo(value[2], expected[2], eps), `${label}[2] must be close to ${expected[2]}, got ${value[2]}`);
+}
+// q and -q are the same rotation, so compare by the size of the dot product.
+function assertQuatClose(value, expected, label) {
+    const dot = value[0] * expected[0] + value[1] * expected[1] + value[2] * expected[2] + value[3] * expected[3];
+    assert(closeTo(Math.abs(dot), 1, POSE_EPS), `${label} must be close to [${expected.join(", ")}], got [${value.join(", ")}]`);
+}
+function assertPoseClose(value, expected, label) {
+    assertVec3Close(value.position, expected.position, POSE_EPS, `${label}.position`);
+    assertQuatClose(value.quaternion, expected.quaternion, `${label}.quaternion`);
+}
+function quatLength(q) {
+    return Math.sqrt(q[0] * q[0] + q[1] * q[1] + q[2] * q[2] + q[3] * q[3]);
+}
+//# sourceMappingURL=contract-cases.js.map

package/dist/contract-cases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-cases.js","sourceRoot":"","sources":["../src/contract-cases.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared `HitTester` and `TransformPort` conformance suites, shipped as data\n * rather than as tests - the same idea as `windowHostContractCases()` in\n * WebXR-UIExtensions and `inputProviderContractCases()` in\n * `@realitycollective/webxr-input`. Five adapters implement these two ports\n * against five different scene graphs; running the same checks against every\n * one is what stops an adapter quietly dropping a documented rule.\n *\n * The suites are runner-free on purpose. Every adapter repository already has\n * its own test runner, and an adapter written outside this repository cannot\n * reach into this one's `test/` folder, so the checks ship as plain objects\n * that throw an `Error` on failure and the adapter iterates them.\n *\n * Both suites assert only what `ports.ts` documents, including two rules\n * every platform now shares:\n *  - `getWorldPose()` is the LIVE pose and `getRestWorldPose()` the rest pose\n *    offsets are measured from.\n *  - Every tuple a port returns is fresh and owned by the caller, and a tuple\n *    passed in is not kept.\n */\nimport type { PoseTuple, QuatTuple, RayTuple, Vec3Tuple } from \"@realitycollective/webxr-input\";\nimport { quatMultiply, vAdd, vApplyQuat } from \"./math.js\";\nimport type { HitTester, HoldRelease, TransformPort } from \"./ports.js\";\n\n// ---------------------------------------------------------------------------\n// HitTester\n// ---------------------------------------------------------------------------\n\n/**\n * Places (or replaces) one target for a case to query against. Build a FRESH\n * subject per case: cases place targets of their own and do not clean up.\n */\nexport interface HitTesterContractDriver {\n  /**\n   * Register a target at `position` with an interaction radius of `radius`,\n   * however the platform registers a target - a mesh, a node, an entity.\n   */\n  place(id: string, position: Vec3Tuple, radius: number): void;\n}\n\n/** The tester under test, plus the means of putting targets into its scene. */\nexport interface HitTesterContractSubject {\n  hitTester: HitTester;\n  driver: HitTesterContractDriver;\n}\n\n/** One check a {@link HitTester} implementation must pass. */\nexport interface HitTesterContractCase {\n  name: string;\n  run(subject: HitTesterContractSubject): void;\n}\n\n/**\n * The shared `HitTester` conformance suite. An adapter's test file is a loop:\n *\n * ```ts\n * for (const contractCase of hitTesterContractCases()) {\n *   it(contractCase.name, () => contractCase.run(makeSubject()));\n * }\n * ```\n */\nexport function hitTesterContractCases(): readonly HitTesterContractCase[] {\n  return HIT_TESTER_CASES;\n}\n\nconst DOWN_RAY: RayTuple = { origin: [0, 0, 0], direction: [0, 0, -1] };\nconst AWAY_RAY: RayTuple = { origin: [0, 0, 0], direction: [0, 0, 1] };\n\n/**\n * A ray-based query only has to land WITHIN the target's own radius:\n * `ports.ts` documents `point` as \"world-space hit or closest point\", so a\n * mesh-accurate ray tester (three.js) reporting the surface it actually hit\n * is as conforming as a sphere tester (Babylon, IWSDK) reporting the target's\n * centre. Placing the target exactly on the ray's line makes both answers\n * the same point when a tester has no radius-shaped slack, and this is the\n * tolerance for testers that do.\n */\nfunction slack(radius: number): number {\n  return radius + 0.05;\n}\n\nconst HIT_TESTER_CASES: readonly HitTesterContractCase[] = [\n  {\n    name: \"an empty scene answers a ray with null\",\n    run({ hitTester }) {\n      assert(hitTester.hitRay(DOWN_RAY) === null, \"hitRay over an empty scene must return null\");\n    },\n  },\n  {\n    name: \"a ray through a placed target returns its id, a positive distance and a point near the ray\",\n    run({ hitTester, driver }) {\n      const radius = 0.15;\n      driver.place(\"target\", [0, 0, -2], radius);\n      const hit = hitTester.hitRay(DOWN_RAY);\n      assert(hit !== null, \"a ray through a placed target must not miss\");\n      assert(hit.interactableId === \"target\", `expected interactableId \"target\", got \"${hit.interactableId}\"`);\n      assert(hit.distance > 0, `distance must be positive, got ${hit.distance}`);\n      const eps = slack(radius);\n      assert(closeTo(hit.distance, 2, eps), `distance must be close to 2, got ${hit.distance}`);\n      assertVec3Close(hit.point, [0, 0, -2], eps, \"point\");\n    },\n  },\n  {\n    name: \"a ray pointing away from the target returns null\",\n    run({ hitTester, driver }) {\n      driver.place(\"target\", [0, 0, -2], 0.15);\n      assert(hitTester.hitRay(AWAY_RAY) === null, \"a ray pointing away from every target must return null\");\n    },\n  },\n  {\n    name: \"hitProximity finds a target inside its radius and misses outside it\",\n    run({ hitTester, driver }) {\n      driver.place(\"target\", [0, 0, -2], 0.1);\n      const inside = hitTester.hitProximity([0, 0, -2], 0.5);\n      assert(inside !== null, \"hitProximity at the target's own position must find it\");\n      assert(\n        inside.interactableId === \"target\",\n        `expected interactableId \"target\", got \"${inside.interactableId}\"`,\n      );\n      const outside = hitTester.hitProximity([5, 5, 5], 0.05);\n      assert(outside === null, \"hitProximity far from every target must return null\");\n    },\n  },\n  {\n    name: \"with two targets on one ray, the nearer one wins\",\n    run({ hitTester, driver }) {\n      const radius = 0.1;\n      driver.place(\"far\", [0, 0, -3], radius);\n      driver.place(\"near\", [0, 0, -1], radius);\n      const hit = hitTester.hitRay(DOWN_RAY);\n      assert(hit !== null, \"a ray through two targets must not miss\");\n      assert(hit.interactableId === \"near\", `the nearer target must win, got \"${hit.interactableId}\"`);\n      assert(closeTo(hit.distance, 1, slack(radius)), `distance must be close to 1, got ${hit.distance}`);\n    },\n  },\n  {\n    name: \"each hit and its point are fresh values the caller owns\",\n    run({ hitTester, driver }) {\n      driver.place(\"target\", [0, 0, -2], 0.15);\n      for (const [label, query] of [\n        [\"hitRay\", () => hitTester.hitRay(DOWN_RAY)],\n        [\"hitProximity\", () => hitTester.hitProximity([0, 0, -2], 0.5)],\n      ] as const) {\n        const first = query();\n        const second = query();\n        assert(first !== null && second !== null, `${label} must find the placed target`);\n        assert(second !== first && second.point !== first.point, `${label} must return a new hit and point each call`);\n        const expected = first.point[2];\n        first.point[2] = 1e6;\n        const third = query();\n        assert(\n          third !== null && closeTo(third.point[2], expected, POSE_EPS),\n          `writing to a returned point must not change the next ${label} answer`,\n        );\n      }\n    },\n  },\n];\n\n// ---------------------------------------------------------------------------\n// TransformPort\n// ---------------------------------------------------------------------------\n\n/**\n * Advances a subject's physics simulation - a real engine step where a\n * platform's physics can run in a test, otherwise a fake that faithfully\n * reproduces the one behaviour these cases check: gravity moves the object\n * unless held, and a release velocity carries it.\n */\nexport interface TransformPortPhysicsDriver {\n  step(dtSeconds: number): void;\n}\n\n/** The port under test, over one object. Build a FRESH one per case. */\nexport interface TransformPortContractSubject {\n  port: TransformPort;\n  /**\n   * The world pose the object sat at when the port captured its rest. Place\n   * it away from the origin and turned, under no parent or an unscaled one,\n   * so a port that ignores its rest frame cannot pass by accident.\n   */\n  rest: PoseTuple;\n  /**\n   * Present only when the object has a physics body - the same condition\n   * that gives the port `beginHold`/`endHold`. The held/released/reset\n   * cases below skip without one, since there is nothing for them to check.\n   */\n  physics?: TransformPortPhysicsDriver;\n}\n\n/** One check a {@link TransformPort} implementation must pass. */\nexport interface TransformPortContractCase {\n  name: string;\n  run(subject: TransformPortContractSubject): void;\n}\n\n/**\n * The shared `TransformPort` conformance suite. An adapter's test file is a\n * loop, the same shape as {@link hitTesterContractCases}.\n */\nexport function transformPortContractCases(): readonly TransformPortContractCase[] {\n  return TRANSFORM_PORT_CASES;\n}\n\nconst POSE_EPS = 1e-3;\n// A quarter turn about Y - a non-identity unit quaternion, so the case\n// cannot pass by accident on a port that ignores its argument.\nconst QUARTER_TURN_Y: QuatTuple = [0, Math.SQRT1_2, 0, Math.SQRT1_2];\n\n// ---------------------------------------------------------------------------\n// Held / released / reset - the \"held pose\" rule, checked only when the\n// subject carries a physics driver. One fixed step size and a looser\n// position tolerance than POSE_EPS: real engines differ slightly in their\n// integrator, and a held/reset case allows for up to one step of gravity\n// (see PHYSICS_POSE_EPS's own comment), where the plain pose cases above\n// never touch physics at all.\n// ---------------------------------------------------------------------------\n\nconst PHYSICS_DT = 1 / 60;\nconst HELD_STEPS = 5;\n/** metres/second - small enough that one step's drift is easy to read, large enough not to vanish into PHYSICS_POSE_EPS. */\nconst RELEASE_SPEED = 2;\n/** metres/second - about 25x RELEASE_SPEED, so \"kept the old velocity\" and \"one step of gravity\" cannot be confused. */\nconst LARGE_PRIOR_SPEED = 50;\n/**\n * 2 cm. One step of gravity at PHYSICS_DT droops roughly\n * `0.5 * 9.8 * PHYSICS_DT^2` ≈ 1.4 mm, well inside this; a full step of\n * LARGE_PRIOR_SPEED (≈ 0.83 m) or RELEASE_SPEED (≈ 33 mm) is well outside it.\n */\nconst PHYSICS_POSE_EPS = 0.02;\n\nfunction assertPhysicsPoseClose(value: PoseTuple, expected: PoseTuple, label: string): void {\n  assertVec3Close(value.position, expected.position, PHYSICS_POSE_EPS, `${label}.position`);\n  assertQuatClose(value.quaternion, expected.quaternion, `${label}.quaternion`);\n}\n\nconst TRANSFORM_PORT_CASES: readonly TransformPortContractCase[] = [\n  {\n    name: \"setLocalOffset then getLocalOffset returns the same offset\",\n    run({ port }) {\n      const offset: Vec3Tuple = [0.3, -0.1, 0.05];\n      port.setLocalOffset(offset);\n      assertVec3Close(port.getLocalOffset(), offset, POSE_EPS, \"getLocalOffset()\");\n    },\n  },\n  {\n    name: \"getWorldPose returns finite numbers and a unit quaternion\",\n    run({ port }) {\n      const pose = port.getWorldPose();\n      for (const value of [...pose.position, ...pose.quaternion]) {\n        assert(Number.isFinite(value), `getWorldPose() must return finite numbers, got ${value}`);\n      }\n      const length = quatLength(pose.quaternion);\n      assert(\n        closeTo(length, 1, POSE_EPS),\n        `getWorldPose().quaternion must be a unit quaternion, length was ${length}`,\n      );\n    },\n  },\n  {\n    name: \"setLocalRotation with a unit quaternion does not throw\",\n    run({ port }) {\n      try {\n        port.setLocalRotation(QUARTER_TURN_Y);\n      } catch (error) {\n        throw new Error(`setLocalRotation(unit quaternion) must not throw, it threw: ${String(error)}`);\n      }\n    },\n  },\n  {\n    name: \"getRestWorldPose returns the pose captured at registration\",\n    run({ port, rest }) {\n      assertPoseClose(port.getRestWorldPose(), rest, \"getRestWorldPose()\");\n    },\n  },\n  {\n    name: \"before any write, the live pose is the rest pose\",\n    run({ port, rest }) {\n      assertPoseClose(port.getWorldPose(), rest, \"getWorldPose()\");\n    },\n  },\n  {\n    name: \"getWorldPose follows setLocalOffset while getRestWorldPose stays put\",\n    run({ port, rest }) {\n      const offset: Vec3Tuple = [0.3, -0.1, 0.05];\n      port.setLocalOffset(offset);\n      assertVec3Close(\n        port.getWorldPose().position,\n        vAdd(rest.position, vApplyQuat(offset, rest.quaternion)),\n        POSE_EPS,\n        \"getWorldPose().position after setLocalOffset\",\n      );\n      assertPoseClose(port.getRestWorldPose(), rest, \"getRestWorldPose() after setLocalOffset\");\n    },\n  },\n  {\n    name: \"getWorldPose follows setLocalRotation while getRestWorldPose stays put\",\n    run({ port, rest }) {\n      port.setLocalRotation(QUARTER_TURN_Y);\n      assertQuatClose(\n        port.getWorldPose().quaternion,\n        quatMultiply(rest.quaternion, QUARTER_TURN_Y),\n        \"getWorldPose().quaternion after setLocalRotation\",\n      );\n      assertPoseClose(port.getRestWorldPose(), rest, \"getRestWorldPose() after setLocalRotation\");\n    },\n  },\n  {\n    name: \"setWorldPose, when present, is what getWorldPose reads back\",\n    run({ port, rest }) {\n      if (!port.setWorldPose) return;\n      const target: PoseTuple = { position: [0.5, 1.2, -0.4], quaternion: QUARTER_TURN_Y };\n      port.setWorldPose(target);\n      assertPoseClose(port.getWorldPose(), target, \"getWorldPose() after setWorldPose\");\n      assertPoseClose(port.getRestWorldPose(), rest, \"getRestWorldPose() after setWorldPose\");\n    },\n  },\n  {\n    name: \"every returned tuple is a fresh value the caller owns\",\n    run({ port }) {\n      const pose = port.getWorldPose();\n      const restPose = port.getRestWorldPose();\n      const offset = port.getLocalOffset();\n      pose.position[0] = 1e6;\n      pose.quaternion[3] = 1e6;\n      restPose.position[0] = 1e6;\n      offset[0] = 1e6;\n      assert(port.getWorldPose().position[0] !== 1e6, \"writing to a returned getWorldPose() tuple must not change the port\");\n      assert(port.getWorldPose().quaternion[3] !== 1e6, \"writing to a returned getWorldPose() quaternion must not change the port\");\n      assert(port.getRestWorldPose().position[0] !== 1e6, \"writing to a returned getRestWorldPose() tuple must not change the port\");\n      assert(port.getLocalOffset()[0] !== 1e6, \"writing to a returned getLocalOffset() tuple must not change the port\");\n    },\n  },\n  {\n    name: \"a tuple passed in is not kept\",\n    run({ port }) {\n      const offset: Vec3Tuple = [0.3, -0.1, 0.05];\n      port.setLocalOffset(offset);\n      offset[0] = 9;\n      assertVec3Close(port.getLocalOffset(), [0.3, -0.1, 0.05], POSE_EPS, \"getLocalOffset() after the caller reused its tuple\");\n      if (!port.setWorldPose) return;\n      const target: PoseTuple = { position: [0.5, 1.2, -0.4], quaternion: [0, 0, 0, 1] };\n      port.setWorldPose(target);\n      target.position[0] = 9;\n      assertVec3Close(port.getWorldPose().position, [0.5, 1.2, -0.4], POSE_EPS, \"getWorldPose() after the caller reused its tuple\");\n    },\n  },\n  {\n    name: \"setEffect, when present, accepts scale and emissive without throwing\",\n    run({ port }) {\n      if (!port.setEffect) return;\n      try {\n        port.setEffect({ scale: 1.2, emissive: 0.3 });\n      } catch (error) {\n        throw new Error(`setEffect({ scale, emissive }) must not throw, it threw: ${String(error)}`);\n      }\n    },\n  },\n  {\n    name: \"Held: beginHold holds a fixed setWorldPose without falling, when the subject has physics\",\n    run({ port, rest, physics }) {\n      if (!physics || !port.setWorldPose || !port.beginHold) return;\n      const held: PoseTuple = {\n        position: [rest.position[0], rest.position[1] + 1, rest.position[2]],\n        quaternion: rest.quaternion,\n      };\n      port.beginHold();\n      for (let i = 0; i < HELD_STEPS; i++) {\n        port.setWorldPose(held);\n        physics.step(PHYSICS_DT);\n      }\n      // A tight tolerance, not PHYSICS_POSE_EPS: a genuinely held body sees\n      // no simulation at all, so it matches the written pose exactly bar\n      // floating point noise - the same POSE_EPS the non-physics cases\n      // above use. One step of unwanted gravity (~2.7 mm at PHYSICS_DT) is\n      // what this case exists to catch, and it must not hide inside the\n      // tolerance the way it deliberately may in the Reset case below.\n      assertPoseClose(port.getWorldPose(), held, `getWorldPose() after ${HELD_STEPS} held steps`);\n    },\n  },\n  {\n    name: \"Released: endHold sends the body away with the release velocity, when the subject has physics\",\n    run({ port, rest, physics }) {\n      if (!physics || !port.beginHold || !port.endHold) return;\n      port.beginHold();\n      const release: HoldRelease = { linearVelocity: [RELEASE_SPEED, 0, 0], angularVelocity: [0, 0, 0] };\n      port.endHold(release);\n      physics.step(PHYSICS_DT);\n      const moved = port.getWorldPose().position[0] - rest.position[0];\n      assert(\n        moved > RELEASE_SPEED * PHYSICS_DT * 0.5,\n        `endHold({ linearVelocity: [${RELEASE_SPEED}, 0, 0] }) must move the body that way within one step, moved ${moved}`,\n      );\n    },\n  },\n  {\n    name: \"Reset: setWorldPose while not held teleports to the pose and clears velocity, when the subject has physics\",\n    run({ port, rest, physics }) {\n      if (!physics || !port.setWorldPose || !port.beginHold || !port.endHold) return;\n      // Give the body a large prior velocity and let it run for a step, so\n      // carrying that velocity through the reset below is unmistakable -\n      // one step of it (~0.83 m) dwarfs PHYSICS_POSE_EPS (2 cm).\n      port.beginHold();\n      const priorRelease: HoldRelease = { linearVelocity: [LARGE_PRIOR_SPEED, 0, 0], angularVelocity: [0, 0, 0] };\n      port.endHold(priorRelease);\n      physics.step(PHYSICS_DT);\n      const target: PoseTuple = {\n        position: [rest.position[0] - 1, rest.position[1] + 2, rest.position[2] + 0.5],\n        quaternion: rest.quaternion,\n      };\n      port.setWorldPose(target);\n      // One further step: it must be at `target`, not carrying the prior\n      // velocity forward - allowing for this one step's worth of gravity.\n      physics.step(PHYSICS_DT);\n      assertPhysicsPoseClose(port.getWorldPose(), target, \"getWorldPose() one step after a reset setWorldPose\");\n    },\n  },\n];\n\n// ---------------------------------------------------------------------------\n// Shared assertion helpers\n// ---------------------------------------------------------------------------\n\nfunction assert(condition: boolean, message: string): asserts condition {\n  if (!condition) throw new Error(message);\n}\n\nfunction closeTo(a: number, b: number, eps: number): boolean {\n  return Math.abs(a - b) <= eps;\n}\n\n// Indexed one component at a time, rather than in a loop, so each index is a\n// literal: `noUncheckedIndexedAccess` cannot narrow a tuple read through a\n// variable index back to `number`.\nfunction assertVec3Close(value: Vec3Tuple, expected: Vec3Tuple, eps: number, label: string): void {\n  assert(closeTo(value[0], expected[0], eps), `${label}[0] must be close to ${expected[0]}, got ${value[0]}`);\n  assert(closeTo(value[1], expected[1], eps), `${label}[1] must be close to ${expected[1]}, got ${value[1]}`);\n  assert(closeTo(value[2], expected[2], eps), `${label}[2] must be close to ${expected[2]}, got ${value[2]}`);\n}\n\n// q and -q are the same rotation, so compare by the size of the dot product.\nfunction assertQuatClose(value: QuatTuple, expected: QuatTuple, label: string): void {\n  const dot = value[0] * expected[0] + value[1] * expected[1] + value[2] * expected[2] + value[3] * expected[3];\n  assert(\n    closeTo(Math.abs(dot), 1, POSE_EPS),\n    `${label} must be close to [${expected.join(\", \")}], got [${value.join(\", \")}]`,\n  );\n}\n\nfunction assertPoseClose(value: PoseTuple, expected: PoseTuple, label: string): void {\n  assertVec3Close(value.position, expected.position, POSE_EPS, `${label}.position`);\n  assertQuatClose(value.quaternion, expected.quaternion, `${label}.quaternion`);\n}\n\nfunction quatLength(q: QuatTuple): number {\n  return Math.sqrt(q[0] * q[0] + q[1] * q[1] + q[2] * q[2] + q[3] * q[3]);\n}\n"]}

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export * from "./math.js";
 export * from "./events.js";
 export * from "./feedback.js";
 export * from "./ports.js";
+export * from "./contract-cases.js";
 export * from "./gaze.js";
 export * from "./descriptor.js";
 export * from "./velocity-tracker.js";

package/dist/index.js

@@ -19,6 +19,7 @@ export * from "./math.js";
 export * from "./events.js";
 export * from "./feedback.js";
 export * from "./ports.js";
+export * from "./contract-cases.js";
 export * from "./gaze.js";
 export * from "./descriptor.js";
 export * from "./velocity-tracker.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,cAAc,gCAAgC,CAAC;AAE/C,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AAEpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,yBAAyB,CAAC","sourcesContent":["/**\n * @realitycollective/webxr-interactions - the engine-free interaction core.\n *\n * Layers (each strictly on the one below):\n *  - behaviours (press, pulse, hinge, dial, slide, grab, tossScore) -\n *    pure state machines driven by `update(dt)`;\n *  - the runtime/binder - targeting, press/grab transitions, gaze gating\n *    + dwell, capability negotiation, events, feedback intents;\n *  - the shared input contracts, re-exported from\n *    `@realitycollective/webxr-input`.\n *\n * Pair with an engine adapter: `@realitycollective/threejs-interactions`\n * (standalone WebXR + three.js), `@realitycollective/iwsdk-interactions`\n * (Meta IWSDK) or `@realitycollective/xrblocks-interactions` (Google XR\n * Blocks, experimental).\n */\nexport * from \"@realitycollective/webxr-input\";\n\nexport * from \"./math.js\";\nexport * from \"./events.js\";\nexport * from \"./feedback.js\";\nexport * from \"./ports.js\";\nexport * from \"./gaze.js\";\nexport * from \"./descriptor.js\";\nexport * from \"./velocity-tracker.js\";\nexport * from \"./runtime.js\";\nexport * from \"./pointer-bridge.js\";\n\nexport * from \"./behaviours/behaviour.js\";\nexport * from \"./behaviours/press.js\";\nexport * from \"./behaviours/pulse.js\";\nexport * from \"./behaviours/hinge.js\";\nexport * from \"./behaviours/dial.js\";\nexport * from \"./behaviours/slide.js\";\nexport * from \"./behaviours/grab.js\";\nexport * from \"./behaviours/toss-score.js\";\nexport * from \"./behaviours/factory.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,cAAc,gCAAgC,CAAC;AAE/C,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AACpC,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AAEpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,yBAAyB,CAAC","sourcesContent":["/**\n * @realitycollective/webxr-interactions - the engine-free interaction core.\n *\n * Layers (each strictly on the one below):\n *  - behaviours (press, pulse, hinge, dial, slide, grab, tossScore) -\n *    pure state machines driven by `update(dt)`;\n *  - the runtime/binder - targeting, press/grab transitions, gaze gating\n *    + dwell, capability negotiation, events, feedback intents;\n *  - the shared input contracts, re-exported from\n *    `@realitycollective/webxr-input`.\n *\n * Pair with an engine adapter: `@realitycollective/threejs-interactions`\n * (standalone WebXR + three.js), `@realitycollective/iwsdk-interactions`\n * (Meta IWSDK) or `@realitycollective/xrblocks-interactions` (Google XR\n * Blocks, experimental).\n */\nexport * from \"@realitycollective/webxr-input\";\n\nexport * from \"./math.js\";\nexport * from \"./events.js\";\nexport * from \"./feedback.js\";\nexport * from \"./ports.js\";\nexport * from \"./contract-cases.js\";\nexport * from \"./gaze.js\";\nexport * from \"./descriptor.js\";\nexport * from \"./velocity-tracker.js\";\nexport * from \"./runtime.js\";\nexport * from \"./pointer-bridge.js\";\n\nexport * from \"./behaviours/behaviour.js\";\nexport * from \"./behaviours/press.js\";\nexport * from \"./behaviours/pulse.js\";\nexport * from \"./behaviours/hinge.js\";\nexport * from \"./behaviours/dial.js\";\nexport * from \"./behaviours/slide.js\";\nexport * from \"./behaviours/grab.js\";\nexport * from \"./behaviours/toss-score.js\";\nexport * from \"./behaviours/factory.js\";\n"]}

package/dist/ports.d.ts

@@ -16,11 +16,25 @@ export interface InteractableHit {
  * Implemented by the adapter (three.js Raycaster, engine BVH, …). A
  * provider that pre-resolves targeting (IWSDK) may make this redundant -
  * provider hints always take precedence over hit-tester results.
+ *
+ * Each hit, and the `point` tuple in it, is a fresh value the caller owns.
+ * A ray or point passed in is read during the call and not kept.
  */
 export interface HitTester {
     hitRay(ray: RayTuple): InteractableHit | null;
     hitProximity(point: Vec3Tuple, radius: number): InteractableHit | null;
 }
+/**
+ * The release velocities handed to {@link TransformPort.endHold} - the
+ * grabbing source's velocity at the moment of release, so a throw carries
+ * through. Linear is metres per second, angular is radians per second,
+ * both in world space, both plain tuples: this crosses the same boundary
+ * `PoseTuple`/`Vec3Tuple` do, so it carries no engine object either.
+ */
+export interface HoldRelease {
+    linearVelocity: Vec3Tuple;
+    angularVelocity: Vec3Tuple;
+}
 /**
  * The transform/effect surface of ONE interactable's scene object.
  * Behaviours write through this; the adapter owns how writes land
@@ -30,21 +44,66 @@ export interface HitTester {
  * registration and applies these relative to it, so behaviours compose
  * with anything else animating the same object (the pale-signal
  * non-destructive-offset rule).
+ *
+ * Every tuple a port returns is a fresh value the caller owns. The port
+ * keeps no reference to it and never writes to it again. A tuple passed in
+ * is read during the call and not kept, so the caller may reuse it.
  */
 export interface TransformPort {
-    /** Current world pose. */
+    /**
+     * The LIVE world pose: where the object is now, after every offset,
+     * rotation and world-pose write, including a write made by anything else.
+     */
     getWorldPose(): PoseTuple;
+    /**
+     * The rest pose captured at registration, in world space. Offsets and
+     * rotations are measured from it, so it stays put while the port writes.
+     * It follows a parent that moves.
+     */
+    getRestWorldPose(): PoseTuple;
     /** Local-space pose relative to the captured rest (dragged observation). */
     getLocalOffset(): Vec3Tuple;
     /** Additive local-space offset from rest (driven press / slide). */
     setLocalOffset(offset: Vec3Tuple): void;
     /** Local rotation about the rest orientation (hinge / dial output). */
     setLocalRotation(quaternion: QuatTuple): void;
-    /** Follow a world pose while grabbed (poseOnly grab fulfilment). */
+    /**
+     * Follow a world pose while grabbed (poseOnly grab fulfilment), or place
+     * the object directly the rest of the time (reset / teleport).
+     *
+     * On a host whose object has physics, the two situations mean different
+     * things and a conforming port tells them apart with {@link beginHold}/
+     * {@link endHold}: WHILE HELD - between a `beginHold` and its matching
+     * `endHold` - the object follows every write exactly and its velocities
+     * are left untouched, because physics is suspended for the hold. NOT
+     * HELD, a write teleports the object there and clears its velocities, so
+     * it comes to rest at the pose ("back to the tee") rather than carrying
+     * whatever it was doing a moment before. A host with no physics has only
+     * the one meaning: the object is simply placed there.
+     */
     setWorldPose?(pose: PoseTuple): void;
     /** Additive presentation effect (pulse): scale multiplier & emissive boost. */
     setEffect?(effect: {
         scale?: number;
         emissive?: number;
     }): void;
+    /**
+     * Suspend physics for this object: from here until the matching
+     * `endHold`, it follows `setWorldPose` writes exactly and gravity /
+     * collisions stop moving it - see {@link setWorldPose}.
+     *
+     * Present only on a port whose object carries a physics body; a port
+     * with no physics never grows this member, so it behaves exactly as
+     * before. A platform that fulfils grabs natively through its own engine
+     * (`grabsNative`) must show the same three behaviours (held / released /
+     * reset) through that engine - the runtime never calls `beginHold` for
+     * one, because the engine, not `webxr-interactions`, already owns the
+     * hold.
+     */
+    beginHold?(): void;
+    /**
+     * Resume physics, applying `release` as the body's new velocity so a
+     * throw carries through. Present on the same terms as {@link beginHold}.
+     */
+    endHold?(release: HoldRelease): void;
 }

package/dist/ports.js.map

@@ -1 +1 @@
-{"version":3,"file":"ports.js","sourceRoot":"","sources":["../src/ports.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Engine-side ports - the space queries and transform writes the core\n * cannot perform itself. Adapters implement these against their scene\n * graph; the core only ever speaks tuples and interactable ids.\n */\nimport type { PoseTuple, QuatTuple, RayTuple, Vec3Tuple } from \"@realitycollective/webxr-input\";\n\nexport interface InteractableHit {\n  interactableId: 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 * Resolves which interactable a ray or a proximity probe touches.\n * Implemented by the adapter (three.js Raycaster, engine BVH, …). A\n * provider that pre-resolves targeting (IWSDK) may make this redundant -\n * provider hints always take precedence over hit-tester results.\n */\nexport interface HitTester {\n  hitRay(ray: RayTuple): InteractableHit | null;\n  hitProximity(point: Vec3Tuple, radius: number): InteractableHit | null;\n}\n\n/**\n * The transform/effect surface of ONE interactable's scene object.\n * Behaviours write through this; the adapter owns how writes land\n * (Object3D fields, ECS components, …).\n *\n * Offsets/rotations are FROM REST: the adapter captures the rest pose at\n * registration and applies these relative to it, so behaviours compose\n * with anything else animating the same object (the pale-signal\n * non-destructive-offset rule).\n */\nexport interface TransformPort {\n  /** Current world pose. */\n  getWorldPose(): PoseTuple;\n  /** Local-space pose relative to the captured rest (dragged observation). */\n  getLocalOffset(): Vec3Tuple;\n  /** Additive local-space offset from rest (driven press / slide). */\n  setLocalOffset(offset: Vec3Tuple): void;\n  /** Local rotation about the rest orientation (hinge / dial output). */\n  setLocalRotation(quaternion: QuatTuple): void;\n  /** Follow a world pose while grabbed (poseOnly grab fulfilment). */\n  setWorldPose?(pose: PoseTuple): void;\n  /** Additive presentation effect (pulse): scale multiplier & emissive boost. */\n  setEffect?(effect: { scale?: number; emissive?: number }): void;\n}\n"]}
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../src/ports.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Engine-side ports - the space queries and transform writes the core\n * cannot perform itself. Adapters implement these against their scene\n * graph; the core only ever speaks tuples and interactable ids.\n */\nimport type { PoseTuple, QuatTuple, RayTuple, Vec3Tuple } from \"@realitycollective/webxr-input\";\n\nexport interface InteractableHit {\n  interactableId: 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 * Resolves which interactable a ray or a proximity probe touches.\n * Implemented by the adapter (three.js Raycaster, engine BVH, …). A\n * provider that pre-resolves targeting (IWSDK) may make this redundant -\n * provider hints always take precedence over hit-tester results.\n *\n * Each hit, and the `point` tuple in it, is a fresh value the caller owns.\n * A ray or point passed in is read during the call and not kept.\n */\nexport interface HitTester {\n  hitRay(ray: RayTuple): InteractableHit | null;\n  hitProximity(point: Vec3Tuple, radius: number): InteractableHit | null;\n}\n\n/**\n * The release velocities handed to {@link TransformPort.endHold} - the\n * grabbing source's velocity at the moment of release, so a throw carries\n * through. Linear is metres per second, angular is radians per second,\n * both in world space, both plain tuples: this crosses the same boundary\n * `PoseTuple`/`Vec3Tuple` do, so it carries no engine object either.\n */\nexport interface HoldRelease {\n  linearVelocity: Vec3Tuple;\n  angularVelocity: Vec3Tuple;\n}\n\n/**\n * The transform/effect surface of ONE interactable's scene object.\n * Behaviours write through this; the adapter owns how writes land\n * (Object3D fields, ECS components, …).\n *\n * Offsets/rotations are FROM REST: the adapter captures the rest pose at\n * registration and applies these relative to it, so behaviours compose\n * with anything else animating the same object (the pale-signal\n * non-destructive-offset rule).\n *\n * Every tuple a port returns is a fresh value the caller owns. The port\n * keeps no reference to it and never writes to it again. A tuple passed in\n * is read during the call and not kept, so the caller may reuse it.\n */\nexport interface TransformPort {\n  /**\n   * The LIVE world pose: where the object is now, after every offset,\n   * rotation and world-pose write, including a write made by anything else.\n   */\n  getWorldPose(): PoseTuple;\n  /**\n   * The rest pose captured at registration, in world space. Offsets and\n   * rotations are measured from it, so it stays put while the port writes.\n   * It follows a parent that moves.\n   */\n  getRestWorldPose(): PoseTuple;\n  /** Local-space pose relative to the captured rest (dragged observation). */\n  getLocalOffset(): Vec3Tuple;\n  /** Additive local-space offset from rest (driven press / slide). */\n  setLocalOffset(offset: Vec3Tuple): void;\n  /** Local rotation about the rest orientation (hinge / dial output). */\n  setLocalRotation(quaternion: QuatTuple): void;\n  /**\n   * Follow a world pose while grabbed (poseOnly grab fulfilment), or place\n   * the object directly the rest of the time (reset / teleport).\n   *\n   * On a host whose object has physics, the two situations mean different\n   * things and a conforming port tells them apart with {@link beginHold}/\n   * {@link endHold}: WHILE HELD - between a `beginHold` and its matching\n   * `endHold` - the object follows every write exactly and its velocities\n   * are left untouched, because physics is suspended for the hold. NOT\n   * HELD, a write teleports the object there and clears its velocities, so\n   * it comes to rest at the pose (\"back to the tee\") rather than carrying\n   * whatever it was doing a moment before. A host with no physics has only\n   * the one meaning: the object is simply placed there.\n   */\n  setWorldPose?(pose: PoseTuple): void;\n  /** Additive presentation effect (pulse): scale multiplier & emissive boost. */\n  setEffect?(effect: { scale?: number; emissive?: number }): void;\n  /**\n   * Suspend physics for this object: from here until the matching\n   * `endHold`, it follows `setWorldPose` writes exactly and gravity /\n   * collisions stop moving it - see {@link setWorldPose}.\n   *\n   * Present only on a port whose object carries a physics body; a port\n   * with no physics never grows this member, so it behaves exactly as\n   * before. A platform that fulfils grabs natively through its own engine\n   * (`grabsNative`) must show the same three behaviours (held / released /\n   * reset) through that engine - the runtime never calls `beginHold` for\n   * one, because the engine, not `webxr-interactions`, already owns the\n   * hold.\n   */\n  beginHold?(): void;\n  /**\n   * Resume physics, applying `release` as the body's new velocity so a\n   * throw carries through. Present on the same terms as {@link beginHold}.\n   */\n  endHold?(release: HoldRelease): void;\n}\n"]}

package/dist/runtime.d.ts

@@ -111,6 +111,8 @@ export declare class InteractionRuntime {
     /** Resolve this source's target: hints beat poke beats ray. */
     private resolveTarget;
     private targetable;
+    /** The largest poke radius among enabled interactables; the default when none is registered. */
+    private maxPokeRadius;
     private flags;
     private updateSource;
     private gazeAllows;

package/dist/runtime.js

@@ -210,7 +210,22 @@ export class InteractionRuntime {
         this.tickBehaviours(sources, dt);
     }
     dispose() {
+        if (this.disposed)
+            return;
         this.disposed = true;
+        // A disposed runtime still owes every held grab exactly one `endHold`
+        // (zero velocity - nothing threw it away, the scene just went down),
+        // so physics never stays suspended once nothing is left to resume it.
+        for (const [id, registered] of this.interactables) {
+            if (registered.grabbedBy) {
+                this.endGrab(id, registered.grabbedBy, {
+                    id: registered.grabbedBy,
+                    kind: "other",
+                    select: 0,
+                    squeeze: 0,
+                });
+            }
+        }
         this.unsubscribeCaps();
         this.interactables.clear();
         this.sourceStates.clear();
@@ -239,6 +254,10 @@ export class InteractionRuntime {
             info.gripPose = source.gripPose;
         if (source.indexTip)
             info.indexTip = source.indexTip;
+        if (source.linearVelocity)
+            info.linearVelocity = source.linearVelocity;
+        if (source.angularVelocity)
+            info.angularVelocity = source.angularVelocity;
         return info;
     }
     /** Resolve this source's target: hints beat poke beats ray. */
@@ -249,9 +268,18 @@ export class InteractionRuntime {
         if (hint && this.targetable(hint.targetId))
             return hint.targetId;
         if (source.indexTip && this.hitTester) {
-            const poke = this.hitTester.hitProximity(source.indexTip, DEFAULT_POKE_RADIUS);
-            if (poke && this.targetable(poke.interactableId))
-                return poke.interactableId;
+            // One proximity query at the largest radius any interactable asked for,
+            // then the nearest hit must be inside ITS OWN radius. A per-interactable
+            // query would be a hit test per registration per source per frame; this
+            // keeps it to one. The trade: a farther interactable with a bigger radius
+            // is not found behind a nearer one with a smaller radius, because the
+            // tester returns only the nearest.
+            const poke = this.hitTester.hitProximity(source.indexTip, this.maxPokeRadius());
+            if (poke && this.targetable(poke.interactableId)) {
+                const registered = this.interactables.get(poke.interactableId);
+                if (poke.distance <= registered.pokeRadius)
+                    return poke.interactableId;
+            }
         }
         if (source.ray && this.hitTester) {
             const hit = this.hitTester.hitRay(source.ray);
@@ -264,6 +292,15 @@ export class InteractionRuntime {
         const registered = this.interactables.get(id);
         return registered !== undefined && registered.enabled;
     }
+    /** The largest poke radius among enabled interactables; the default when none is registered. */
+    maxPokeRadius() {
+        let radius = 0;
+        for (const registered of this.interactables.values()) {
+            if (registered.enabled && registered.pokeRadius > radius)
+                radius = registered.pokeRadius;
+        }
+        return radius > 0 ? radius : DEFAULT_POKE_RADIUS;
+    }
     flags(registered) {
         let pressable = false;
         let grabbable = false;