@realitycollective/webxr-interactions 0.1.1-preview.3 → 0.1.1

package/dist/near-pointer.d.ts

@@ -21,9 +21,16 @@
  * - **Priority.** Per source, the first of touch, grab, ray with a candidate
  *   is the active pointer (`PRIORITY_ORDER`), and once it is pressing or
  *   grabbing it stays active until the release (IWSDK's selection lock).
+ *   Since 29 September 2026 that decision is made ONCE per source across
+ *   interactables and UI panels by the `PointerArbiter` in
+ *   `@realitycollective/webxr-input` (`pointer-arbiter.ts`), which this
+ *   runtime feeds and reads; `POINTER_PRIORITY`, `pickActivePointer`,
+ *   `PointerCandidate` and `PointerVisuals` live there and are re-exported
+ *   here unchanged.
  * - **Visuals.** The ray and its cursor show only while the ray is the active
  *   pointer or nothing is (`shouldHideRay`); a near pointer owning the hand
- *   hides them, and the shared cursor sits at the active pointer's hit point.
+ *   hides them, and the shared cursor sits at the active pointer's hit. What
+ *   the app then shows of them is its `PointerDisplay` configuration.
  *
  * One rule is deliberately stricter than the template, as the Pale Signal
  * work order of 28 September 2026 required: a touch never presses from inside
@@ -33,10 +40,7 @@
  * press on that first frame; `touch-reference.test.ts` records the one frame
  * on which the two differ, and that they agree everywhere else.
  */
-/** The pointer that owns a source this frame. `"gaze"` is the eye-gaze source's own pointer. */
-export type ActivePointerKind = "touch" | "grab" | "ray" | "gaze";
-/** IWSDK's order: the first with a candidate wins. `multi-pointer.js` `PRIORITY_ORDER`. */
-export declare const POINTER_PRIORITY: readonly ActivePointerKind[];
+export { POINTER_PRIORITY, pickActivePointer, pointerVisualsFor, type ActivePointerKind, type PointerCandidate, type PointerVisuals, } from "@realitycollective/webxr-input";
 export interface NearPointerOptions {
     /** Surface distance, metres, within which a fingertip starts hovering a target. IWSDK `enterHoverDistance` 0.15. */
     touchHoverEnter: number;
@@ -82,50 +86,3 @@ export declare class TouchPointerState {
     /** Drop everything without reporting (the source went away). */
     reset(): void;
 }
-/** A candidate one pointer found: the target and the point the cursor sits at. */
-export interface PointerCandidate {
-    targetId: string;
-    /** World-space point: the ray's hit, or the closest point of a near target. */
-    point: readonly [number, number, number];
-    /** Metres: the ray parameter for a ray, the surface distance for a near pointer. */
-    distance: number;
-}
-/**
- * IWSDK's `pickActiveByPriority` with its selection lock: while the current
- * active pointer is selecting it stays; otherwise the first pointer in
- * `POINTER_PRIORITY` with a candidate wins, or none.
- */
-export declare function pickActivePointer(candidates: {
-    touch: boolean;
-    grab: boolean;
-    ray: boolean;
-}, current: ActivePointerKind | null, selecting: boolean): ActivePointerKind | null;
-/**
- * What a binding shows for one source: IWSDK's `shouldHideRay` and the shared
- * cursor from `MultiPointer.update`. A host draws exactly this and decides
- * nothing.
- */
-export interface PointerVisuals {
-    /** The source these visuals belong to. */
-    sourceId: string;
-    /** The pointer owning the source, or null when none has a candidate. */
-    activePointer: ActivePointerKind | null;
-    /**
-     * Draw this source's ray. True while the source has a ray and no near
-     * pointer owns it: the ray is active, or nothing is. False while touch or
-     * grab owns the hand, while eye gaze has taken the far ray, and for a
-     * source with no ray at all.
-     */
-    ray: boolean;
-    /**
-     * Draw the cursor disc at `cursorPoint`. True exactly while the active
-     * pointer has a candidate: at the ray's hit, or on the surface the
-     * fingertip or grip reaches. Never drawn "at every ray hit" regardless of
-     * ownership, which is what the September 2026 native contract said.
-     */
-    cursor: boolean;
-    /** World-space cursor position while `cursor` is true, else null. */
-    cursorPoint: readonly [number, number, number] | null;
-}
-/** Build the visuals for one source from its active pointer and that pointer's candidate. */
-export declare function pointerVisualsFor(sourceId: string, hasRay: boolean, active: ActivePointerKind | null, candidate: PointerCandidate | null): PointerVisuals;

package/dist/near-pointer.js

@@ -21,9 +21,16 @@
  * - **Priority.** Per source, the first of touch, grab, ray with a candidate
  *   is the active pointer (`PRIORITY_ORDER`), and once it is pressing or
  *   grabbing it stays active until the release (IWSDK's selection lock).
+ *   Since 29 September 2026 that decision is made ONCE per source across
+ *   interactables and UI panels by the `PointerArbiter` in
+ *   `@realitycollective/webxr-input` (`pointer-arbiter.ts`), which this
+ *   runtime feeds and reads; `POINTER_PRIORITY`, `pickActivePointer`,
+ *   `PointerCandidate` and `PointerVisuals` live there and are re-exported
+ *   here unchanged.
  * - **Visuals.** The ray and its cursor show only while the ray is the active
  *   pointer or nothing is (`shouldHideRay`); a near pointer owning the hand
- *   hides them, and the shared cursor sits at the active pointer's hit point.
+ *   hides them, and the shared cursor sits at the active pointer's hit. What
+ *   the app then shows of them is its `PointerDisplay` configuration.
  *
  * One rule is deliberately stricter than the template, as the Pale Signal
  * work order of 28 September 2026 required: a touch never presses from inside
@@ -33,8 +40,7 @@
  * press on that first frame; `touch-reference.test.ts` records the one frame
  * on which the two differ, and that they agree everywhere else.
  */
-/** IWSDK's order: the first with a candidate wins. `multi-pointer.js` `PRIORITY_ORDER`. */
-export const POINTER_PRIORITY = Object.freeze(["touch", "grab", "ray"]);
+export { POINTER_PRIORITY, pickActivePointer, pointerVisualsFor, } from "@realitycollective/webxr-input";
 /** IWSDK 1.0.0's constants: `TOUCH_HYSTERESIS`, `TOUCH_DEFAULTS.downRadius`, `createGrabPointer`'s radius. */
 export const NEAR_POINTER_DEFAULTS = Object.freeze({
     touchHoverEnter: 0.15,
@@ -105,24 +111,4 @@ export class TouchPointerState {
         this.armed = false;
     }
 }
-/**
- * IWSDK's `pickActiveByPriority` with its selection lock: while the current
- * active pointer is selecting it stays; otherwise the first pointer in
- * `POINTER_PRIORITY` with a candidate wins, or none.
- */
-export function pickActivePointer(candidates, current, selecting) {
-    if (selecting && current !== null)
-        return current;
-    for (const kind of POINTER_PRIORITY) {
-        if (candidates[kind])
-            return kind;
-    }
-    return null;
-}
-/** Build the visuals for one source from its active pointer and that pointer's candidate. */
-export function pointerVisualsFor(sourceId, hasRay, active, candidate) {
-    const ray = hasRay && (active === null || active === "ray");
-    const cursor = active !== null && candidate !== null;
-    return { sourceId, activePointer: active, ray, cursor, cursorPoint: cursor ? candidate.point : null };
-}
 //# sourceMappingURL=near-pointer.js.map

package/dist/near-pointer.js.map

@@ -1 +1 @@
-{"version":3,"file":"near-pointer.js","sourceRoot":"","sources":["../src/near-pointer.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Near pointers - the touch press, the grip grab, which pointer owns a hand\n * and what that means for the ray and cursor. Pure logic, no engine.\n *\n * The template is IWSDK 1.0.0's pointer stack (`@iwsdk/xr-input`\n * `multi-pointer.js`, `touch-pointer.js`, `grab-pointer.js`, over\n * `@pmndrs/pointer-events`), restated here so every binding runs the same\n * rule from the facts it already reports (`indexTip`, `gripPose`, `ray`):\n *\n * - **Touch.** A fingertip (a controller's ray origin stands in for one)\n *   hovers a target once its distance to the target's SURFACE is within\n *   `touchHoverEnter` (0.15 m) and keeps hovering until it is beyond\n *   `touchHoverExit` (0.2 m): `TOUCH_HYSTERESIS`. It presses while that\n *   distance is at or under `touchDown` (0.02 m): `TOUCH_DEFAULTS.downRadius`,\n *   which `@pmndrs/pointer-events` compares every frame, so the release is\n *   the way out past the same distance.\n * - **Grab.** The grip is a sphere of `grabRadius` (0.07 m,\n *   `createGrabPointer`'s default) and a target whose surface it reaches is\n *   the grab candidate. The squeeze (or a hand's pinch on a grab-only\n *   target) then grabs it.\n * - **Priority.** Per source, the first of touch, grab, ray with a candidate\n *   is the active pointer (`PRIORITY_ORDER`), and once it is pressing or\n *   grabbing it stays active until the release (IWSDK's selection lock).\n * - **Visuals.** The ray and its cursor show only while the ray is the active\n *   pointer or nothing is (`shouldHideRay`); a near pointer owning the hand\n *   hides them, and the shared cursor sits at the active pointer's hit point.\n *\n * One rule is deliberately stricter than the template, as the Pale Signal\n * work order of 28 September 2026 required: a touch never presses from inside\n * or from behind. A fingertip first seen already within the press band, a\n * hand that pops into tracking inside the target, does not press until it has\n * been seen outside the band and comes back in. IWSDK's touch pointer would\n * press on that first frame; `touch-reference.test.ts` records the one frame\n * on which the two differ, and that they agree everywhere else.\n */\n\n/** The pointer that owns a source this frame. `\"gaze\"` is the eye-gaze source's own pointer. */\nexport type ActivePointerKind = \"touch\" | \"grab\" | \"ray\" | \"gaze\";\n\n/** IWSDK's order: the first with a candidate wins. `multi-pointer.js` `PRIORITY_ORDER`. */\nexport const POINTER_PRIORITY: readonly ActivePointerKind[] = Object.freeze([\"touch\", \"grab\", \"ray\"]);\n\nexport interface NearPointerOptions {\n  /** Surface distance, metres, within which a fingertip starts hovering a target. IWSDK `enterHoverDistance` 0.15. */\n  touchHoverEnter: number;\n  /** Surface distance, metres, beyond which a hovering fingertip stops hovering. IWSDK `exitHoverDistance` 0.2. Never less than `touchHoverEnter`. */\n  touchHoverExit: number;\n  /** Surface distance, metres, at or under which a hovering fingertip presses, and above which it releases. IWSDK `downRadius` 0.02. */\n  touchDown: number;\n  /** Radius, metres, of the grip sphere that finds a grab candidate. `createGrabPointer` default 0.07. */\n  grabRadius: number;\n}\n\n/** IWSDK 1.0.0's constants: `TOUCH_HYSTERESIS`, `TOUCH_DEFAULTS.downRadius`, `createGrabPointer`'s radius. */\nexport const NEAR_POINTER_DEFAULTS: Readonly<NearPointerOptions> = Object.freeze({\n  touchHoverEnter: 0.15,\n  touchHoverExit: 0.2,\n  touchDown: 0.02,\n  grabRadius: 0.07,\n});\n\nexport function resolveNearPointerOptions(options: Partial<NearPointerOptions> = {}): NearPointerOptions {\n  const resolved = { ...NEAR_POINTER_DEFAULTS, ...options };\n  if (resolved.touchDown < 0 || resolved.touchHoverEnter < 0 || resolved.grabRadius < 0) {\n    throw new Error(\"[webxr-interactions] near pointer distances must be >= 0\");\n  }\n  if (resolved.touchHoverExit < resolved.touchHoverEnter) {\n    throw new Error(\n      `[webxr-interactions] touchHoverExit (${resolved.touchHoverExit}) must be >= touchHoverEnter (${resolved.touchHoverEnter})`,\n    );\n  }\n  return resolved;\n}\n\n/** What the touch machine reports after one frame. */\nexport interface TouchPointerUpdate {\n  /** The fingertip is hovering a target this frame (the touch pointer has a candidate). */\n  hovering: boolean;\n  /** The touch is pressing this frame. */\n  pressed: boolean;\n  /** True on the exact frame a press started. */\n  pressStarted: boolean;\n  /** True on the exact frame a press ended. */\n  pressEnded: boolean;\n}\n\n/**\n * One source's touch pointer: hover with hysteresis, press at `touchDown`\n * armed only from outside the band. Feed it the fingertip's surface distance\n * to the nearest target each frame, or `null` when no target is in reach.\n */\nexport class TouchPointerState {\n  private hovering = false;\n  private pressed = false;\n  /** The fingertip has been seen outside the press band since it last lost contact. */\n  private armed = false;\n\n  get isHovering(): boolean {\n    return this.hovering;\n  }\n\n  get isPressed(): boolean {\n    return this.pressed;\n  }\n\n  /**\n   * Advance one frame. `enter`/`exit` are the hover band for the target in\n   * question (an interactable may widen the default), `down` the press\n   * distance.\n   */\n  update(distance: number | null, enter: number, exit: number, down: number): TouchPointerUpdate {\n    const wasPressed = this.pressed;\n    const threshold = this.hovering ? exit : enter;\n    if (distance === null || distance > threshold) {\n      this.hovering = false;\n      this.pressed = false;\n      this.armed = false;\n      return { hovering: false, pressed: false, pressStarted: false, pressEnded: wasPressed };\n    }\n    this.hovering = true;\n    if (distance > down) {\n      // Outside the press band: released if it was pressing, and armed for the next press.\n      this.armed = true;\n      this.pressed = false;\n      return { hovering: true, pressed: false, pressStarted: false, pressEnded: wasPressed };\n    }\n    // Within the press band. IWSDK presses here unconditionally; the core\n    // requires the fingertip to have arrived from outside (see the file comment).\n    if (!this.pressed && this.armed) {\n      this.pressed = true;\n      this.armed = false;\n      return { hovering: true, pressed: true, pressStarted: true, pressEnded: false };\n    }\n    return { hovering: true, pressed: this.pressed, pressStarted: false, pressEnded: false };\n  }\n\n  /** Drop everything without reporting (the source went away). */\n  reset(): void {\n    this.hovering = false;\n    this.pressed = false;\n    this.armed = false;\n  }\n}\n\n/** A candidate one pointer found: the target and the point the cursor sits at. */\nexport interface PointerCandidate {\n  targetId: string;\n  /** World-space point: the ray's hit, or the closest point of a near target. */\n  point: readonly [number, number, number];\n  /** Metres: the ray parameter for a ray, the surface distance for a near pointer. */\n  distance: number;\n}\n\n/**\n * IWSDK's `pickActiveByPriority` with its selection lock: while the current\n * active pointer is selecting it stays; otherwise the first pointer in\n * `POINTER_PRIORITY` with a candidate wins, or none.\n */\nexport function pickActivePointer(\n  candidates: { touch: boolean; grab: boolean; ray: boolean },\n  current: ActivePointerKind | null,\n  selecting: boolean,\n): ActivePointerKind | null {\n  if (selecting && current !== null) return current;\n  for (const kind of POINTER_PRIORITY) {\n    if (candidates[kind as \"touch\" | \"grab\" | \"ray\"]) return kind;\n  }\n  return null;\n}\n\n/**\n * What a binding shows for one source: IWSDK's `shouldHideRay` and the shared\n * cursor from `MultiPointer.update`. A host draws exactly this and decides\n * nothing.\n */\nexport interface PointerVisuals {\n  /** The source these visuals belong to. */\n  sourceId: string;\n  /** The pointer owning the source, or null when none has a candidate. */\n  activePointer: ActivePointerKind | null;\n  /**\n   * Draw this source's ray. True while the source has a ray and no near\n   * pointer owns it: the ray is active, or nothing is. False while touch or\n   * grab owns the hand, while eye gaze has taken the far ray, and for a\n   * source with no ray at all.\n   */\n  ray: boolean;\n  /**\n   * Draw the cursor disc at `cursorPoint`. True exactly while the active\n   * pointer has a candidate: at the ray's hit, or on the surface the\n   * fingertip or grip reaches. Never drawn \"at every ray hit\" regardless of\n   * ownership, which is what the September 2026 native contract said.\n   */\n  cursor: boolean;\n  /** World-space cursor position while `cursor` is true, else null. */\n  cursorPoint: readonly [number, number, number] | null;\n}\n\n/** Build the visuals for one source from its active pointer and that pointer's candidate. */\nexport function pointerVisualsFor(\n  sourceId: string,\n  hasRay: boolean,\n  active: ActivePointerKind | null,\n  candidate: PointerCandidate | null,\n): PointerVisuals {\n  const ray = hasRay && (active === null || active === \"ray\");\n  const cursor = active !== null && candidate !== null;\n  return { sourceId, activePointer: active, ray, cursor, cursorPoint: cursor ? candidate!.point : null };\n}\n"]}
+{"version":3,"file":"near-pointer.js","sourceRoot":"","sources":["../src/near-pointer.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Near pointers - the touch press, the grip grab, which pointer owns a hand\n * and what that means for the ray and cursor. Pure logic, no engine.\n *\n * The template is IWSDK 1.0.0's pointer stack (`@iwsdk/xr-input`\n * `multi-pointer.js`, `touch-pointer.js`, `grab-pointer.js`, over\n * `@pmndrs/pointer-events`), restated here so every binding runs the same\n * rule from the facts it already reports (`indexTip`, `gripPose`, `ray`):\n *\n * - **Touch.** A fingertip (a controller's ray origin stands in for one)\n *   hovers a target once its distance to the target's SURFACE is within\n *   `touchHoverEnter` (0.15 m) and keeps hovering until it is beyond\n *   `touchHoverExit` (0.2 m): `TOUCH_HYSTERESIS`. It presses while that\n *   distance is at or under `touchDown` (0.02 m): `TOUCH_DEFAULTS.downRadius`,\n *   which `@pmndrs/pointer-events` compares every frame, so the release is\n *   the way out past the same distance.\n * - **Grab.** The grip is a sphere of `grabRadius` (0.07 m,\n *   `createGrabPointer`'s default) and a target whose surface it reaches is\n *   the grab candidate. The squeeze (or a hand's pinch on a grab-only\n *   target) then grabs it.\n * - **Priority.** Per source, the first of touch, grab, ray with a candidate\n *   is the active pointer (`PRIORITY_ORDER`), and once it is pressing or\n *   grabbing it stays active until the release (IWSDK's selection lock).\n *   Since 29 September 2026 that decision is made ONCE per source across\n *   interactables and UI panels by the `PointerArbiter` in\n *   `@realitycollective/webxr-input` (`pointer-arbiter.ts`), which this\n *   runtime feeds and reads; `POINTER_PRIORITY`, `pickActivePointer`,\n *   `PointerCandidate` and `PointerVisuals` live there and are re-exported\n *   here unchanged.\n * - **Visuals.** The ray and its cursor show only while the ray is the active\n *   pointer or nothing is (`shouldHideRay`); a near pointer owning the hand\n *   hides them, and the shared cursor sits at the active pointer's hit. What\n *   the app then shows of them is its `PointerDisplay` configuration.\n *\n * One rule is deliberately stricter than the template, as the Pale Signal\n * work order of 28 September 2026 required: a touch never presses from inside\n * or from behind. A fingertip first seen already within the press band, a\n * hand that pops into tracking inside the target, does not press until it has\n * been seen outside the band and comes back in. IWSDK's touch pointer would\n * press on that first frame; `touch-reference.test.ts` records the one frame\n * on which the two differ, and that they agree everywhere else.\n */\nexport {\n  POINTER_PRIORITY,\n  pickActivePointer,\n  pointerVisualsFor,\n  type ActivePointerKind,\n  type PointerCandidate,\n  type PointerVisuals,\n} from \"@realitycollective/webxr-input\";\n\nexport interface NearPointerOptions {\n  /** Surface distance, metres, within which a fingertip starts hovering a target. IWSDK `enterHoverDistance` 0.15. */\n  touchHoverEnter: number;\n  /** Surface distance, metres, beyond which a hovering fingertip stops hovering. IWSDK `exitHoverDistance` 0.2. Never less than `touchHoverEnter`. */\n  touchHoverExit: number;\n  /** Surface distance, metres, at or under which a hovering fingertip presses, and above which it releases. IWSDK `downRadius` 0.02. */\n  touchDown: number;\n  /** Radius, metres, of the grip sphere that finds a grab candidate. `createGrabPointer` default 0.07. */\n  grabRadius: number;\n}\n\n/** IWSDK 1.0.0's constants: `TOUCH_HYSTERESIS`, `TOUCH_DEFAULTS.downRadius`, `createGrabPointer`'s radius. */\nexport const NEAR_POINTER_DEFAULTS: Readonly<NearPointerOptions> = Object.freeze({\n  touchHoverEnter: 0.15,\n  touchHoverExit: 0.2,\n  touchDown: 0.02,\n  grabRadius: 0.07,\n});\n\nexport function resolveNearPointerOptions(options: Partial<NearPointerOptions> = {}): NearPointerOptions {\n  const resolved = { ...NEAR_POINTER_DEFAULTS, ...options };\n  if (resolved.touchDown < 0 || resolved.touchHoverEnter < 0 || resolved.grabRadius < 0) {\n    throw new Error(\"[webxr-interactions] near pointer distances must be >= 0\");\n  }\n  if (resolved.touchHoverExit < resolved.touchHoverEnter) {\n    throw new Error(\n      `[webxr-interactions] touchHoverExit (${resolved.touchHoverExit}) must be >= touchHoverEnter (${resolved.touchHoverEnter})`,\n    );\n  }\n  return resolved;\n}\n\n/** What the touch machine reports after one frame. */\nexport interface TouchPointerUpdate {\n  /** The fingertip is hovering a target this frame (the touch pointer has a candidate). */\n  hovering: boolean;\n  /** The touch is pressing this frame. */\n  pressed: boolean;\n  /** True on the exact frame a press started. */\n  pressStarted: boolean;\n  /** True on the exact frame a press ended. */\n  pressEnded: boolean;\n}\n\n/**\n * One source's touch pointer: hover with hysteresis, press at `touchDown`\n * armed only from outside the band. Feed it the fingertip's surface distance\n * to the nearest target each frame, or `null` when no target is in reach.\n */\nexport class TouchPointerState {\n  private hovering = false;\n  private pressed = false;\n  /** The fingertip has been seen outside the press band since it last lost contact. */\n  private armed = false;\n\n  get isHovering(): boolean {\n    return this.hovering;\n  }\n\n  get isPressed(): boolean {\n    return this.pressed;\n  }\n\n  /**\n   * Advance one frame. `enter`/`exit` are the hover band for the target in\n   * question (an interactable may widen the default), `down` the press\n   * distance.\n   */\n  update(distance: number | null, enter: number, exit: number, down: number): TouchPointerUpdate {\n    const wasPressed = this.pressed;\n    const threshold = this.hovering ? exit : enter;\n    if (distance === null || distance > threshold) {\n      this.hovering = false;\n      this.pressed = false;\n      this.armed = false;\n      return { hovering: false, pressed: false, pressStarted: false, pressEnded: wasPressed };\n    }\n    this.hovering = true;\n    if (distance > down) {\n      // Outside the press band: released if it was pressing, and armed for the next press.\n      this.armed = true;\n      this.pressed = false;\n      return { hovering: true, pressed: false, pressStarted: false, pressEnded: wasPressed };\n    }\n    // Within the press band. IWSDK presses here unconditionally; the core\n    // requires the fingertip to have arrived from outside (see the file comment).\n    if (!this.pressed && this.armed) {\n      this.pressed = true;\n      this.armed = false;\n      return { hovering: true, pressed: true, pressStarted: true, pressEnded: false };\n    }\n    return { hovering: true, pressed: this.pressed, pressStarted: false, pressEnded: false };\n  }\n\n  /** Drop everything without reporting (the source went away). */\n  reset(): void {\n    this.hovering = false;\n    this.pressed = false;\n    this.armed = false;\n  }\n}\n"]}

package/dist/release-velocity.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The release velocity of a throw - the core rule, restated from what Meta
+ * IWSDK 1.0.0 does with a held object so every platform's throw carries the
+ * same speed on the same input.
+ *
+ * On the web a thrown object is carried by IWSDK's grab system and Havok.
+ * While the object is `Grabbed`, `physics-system.js` sends the body a
+ * `SetTargetTransform` command every frame with the object's pose (the pose
+ * the grab pointer moved it to), so Havok drives the body kinematically to
+ * that target at each 1/60 s step (`PHYSICS_DEFAULTS.stepsPerSecond`). When
+ * the grab ends the tag is removed and nothing resets the body: it keeps the
+ * velocity the engine gave it to reach the last target, the displacement of
+ * the OBJECT over the last physics step divided by the step. So IWSDK's
+ * throw is:
+ *
+ * - the velocity of the held OBJECT, not of the grip: for a rigid carry the
+ *   two agree, but the rule is stated on the object, which every platform
+ *   has, rather than on a runtime-reported hand velocity, which most do not;
+ * - measured over the last physics step, `RELEASE_WINDOW_SECONDS` (1/60 s):
+ *   at 72 Hz that is one frame, at 90 Hz two, at 120 Hz two;
+ * - angular velocity from the orientation delta over the same window.
+ *
+ * `ReleaseVelocityTracker` keeps the poses the carry wrote and their frame
+ * times; `release()` differentiates over the most recent frames that cover
+ * the window, or over the last frame when only one has been seen. A hold
+ * that never moved (or was released the frame it started) throws nothing:
+ * zeros, so the object rests where it was let go. A synthesised release
+ * (source lost, target unregistered, runtime disposed) never reads this: the
+ * grab behaviour hands the port zeros, as `grab.ts` says.
+ */
+import { type PoseTuple } from "@realitycollective/webxr-input";
+import type { HoldRelease } from "./ports.js";
+/** IWSDK's physics step, 1/60 s: the window a throw's velocity is measured over. */
+export declare const RELEASE_WINDOW_SECONDS: number;
+export interface ReleaseVelocityTrackerOptions {
+    /** Seconds the release velocity is measured over. Default `RELEASE_WINDOW_SECONDS`. */
+    windowSeconds?: number;
+}
+export declare class ReleaseVelocityTracker {
+    private readonly window;
+    private readonly samples;
+    constructor(options?: ReleaseVelocityTrackerOptions);
+    /** Forget every pose: the hold starts afresh. */
+    reset(): void;
+    /**
+     * Record the pose the carry wrote this frame, `dt` seconds after the last
+     * one. The tuples are copied, so the caller may reuse them.
+     */
+    record(pose: PoseTuple, dt: number): void;
+    /** How many poses are recorded. */
+    get size(): number;
+    /**
+     * The velocity the object carries at release: linear m/s and angular
+     * rad/s (axis scaled), world space, over the most recent frames that span
+     * at least the window. Zeros with fewer than two poses, or no elapsed time.
+     */
+    release(): HoldRelease;
+}

package/dist/release-velocity.js

@@ -0,0 +1,89 @@
+/**
+ * The release velocity of a throw - the core rule, restated from what Meta
+ * IWSDK 1.0.0 does with a held object so every platform's throw carries the
+ * same speed on the same input.
+ *
+ * On the web a thrown object is carried by IWSDK's grab system and Havok.
+ * While the object is `Grabbed`, `physics-system.js` sends the body a
+ * `SetTargetTransform` command every frame with the object's pose (the pose
+ * the grab pointer moved it to), so Havok drives the body kinematically to
+ * that target at each 1/60 s step (`PHYSICS_DEFAULTS.stepsPerSecond`). When
+ * the grab ends the tag is removed and nothing resets the body: it keeps the
+ * velocity the engine gave it to reach the last target, the displacement of
+ * the OBJECT over the last physics step divided by the step. So IWSDK's
+ * throw is:
+ *
+ * - the velocity of the held OBJECT, not of the grip: for a rigid carry the
+ *   two agree, but the rule is stated on the object, which every platform
+ *   has, rather than on a runtime-reported hand velocity, which most do not;
+ * - measured over the last physics step, `RELEASE_WINDOW_SECONDS` (1/60 s):
+ *   at 72 Hz that is one frame, at 90 Hz two, at 120 Hz two;
+ * - angular velocity from the orientation delta over the same window.
+ *
+ * `ReleaseVelocityTracker` keeps the poses the carry wrote and their frame
+ * times; `release()` differentiates over the most recent frames that cover
+ * the window, or over the last frame when only one has been seen. A hold
+ * that never moved (or was released the frame it started) throws nothing:
+ * zeros, so the object rests where it was let go. A synthesised release
+ * (source lost, target unregistered, runtime disposed) never reads this: the
+ * grab behaviour hands the port zeros, as `grab.ts` says.
+ */
+import { velocityBetween } from "@realitycollective/webxr-input";
+/** IWSDK's physics step, 1/60 s: the window a throw's velocity is measured over. */
+export const RELEASE_WINDOW_SECONDS = 1 / 60;
+/** How many past frames the tracker keeps: enough to cover the window at any refresh rate down to 30 Hz. */
+const MAX_SAMPLES = 8;
+export class ReleaseVelocityTracker {
+    window;
+    samples = [];
+    constructor(options = {}) {
+        const window = options.windowSeconds ?? RELEASE_WINDOW_SECONDS;
+        if (!Number.isFinite(window) || window <= 0) {
+            throw new Error(`[webxr-interactions] release window must be a positive number of seconds, got ${String(window)}`);
+        }
+        this.window = window;
+    }
+    /** Forget every pose: the hold starts afresh. */
+    reset() {
+        this.samples.length = 0;
+    }
+    /**
+     * Record the pose the carry wrote this frame, `dt` seconds after the last
+     * one. The tuples are copied, so the caller may reuse them.
+     */
+    record(pose, dt) {
+        const copy = {
+            position: [pose.position[0], pose.position[1], pose.position[2]],
+            quaternion: [pose.quaternion[0], pose.quaternion[1], pose.quaternion[2], pose.quaternion[3]],
+        };
+        const step = this.samples.length === 0 || !Number.isFinite(dt) || dt < 0 ? 0 : dt;
+        this.samples.push({ pose: copy, dt: step });
+        if (this.samples.length > MAX_SAMPLES)
+            this.samples.shift();
+    }
+    /** How many poses are recorded. */
+    get size() {
+        return this.samples.length;
+    }
+    /**
+     * The velocity the object carries at release: linear m/s and angular
+     * rad/s (axis scaled), world space, over the most recent frames that span
+     * at least the window. Zeros with fewer than two poses, or no elapsed time.
+     */
+    release() {
+        const n = this.samples.length;
+        if (n < 2)
+            return { linearVelocity: [0, 0, 0], angularVelocity: [0, 0, 0] };
+        let elapsed = 0;
+        let start = n - 1;
+        while (start > 0 && elapsed < this.window) {
+            elapsed += this.samples[start].dt;
+            start -= 1;
+        }
+        if (elapsed <= 0)
+            return { linearVelocity: [0, 0, 0], angularVelocity: [0, 0, 0] };
+        const velocity = velocityBetween(this.samples[start].pose, this.samples[n - 1].pose, elapsed);
+        return { linearVelocity: velocity.linear, angularVelocity: velocity.angular };
+    }
+}
+//# sourceMappingURL=release-velocity.js.map

package/dist/release-velocity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-velocity.js","sourceRoot":"","sources":["../src/release-velocity.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The release velocity of a throw - the core rule, restated from what Meta\n * IWSDK 1.0.0 does with a held object so every platform's throw carries the\n * same speed on the same input.\n *\n * On the web a thrown object is carried by IWSDK's grab system and Havok.\n * While the object is `Grabbed`, `physics-system.js` sends the body a\n * `SetTargetTransform` command every frame with the object's pose (the pose\n * the grab pointer moved it to), so Havok drives the body kinematically to\n * that target at each 1/60 s step (`PHYSICS_DEFAULTS.stepsPerSecond`). When\n * the grab ends the tag is removed and nothing resets the body: it keeps the\n * velocity the engine gave it to reach the last target, the displacement of\n * the OBJECT over the last physics step divided by the step. So IWSDK's\n * throw is:\n *\n * - the velocity of the held OBJECT, not of the grip: for a rigid carry the\n *   two agree, but the rule is stated on the object, which every platform\n *   has, rather than on a runtime-reported hand velocity, which most do not;\n * - measured over the last physics step, `RELEASE_WINDOW_SECONDS` (1/60 s):\n *   at 72 Hz that is one frame, at 90 Hz two, at 120 Hz two;\n * - angular velocity from the orientation delta over the same window.\n *\n * `ReleaseVelocityTracker` keeps the poses the carry wrote and their frame\n * times; `release()` differentiates over the most recent frames that cover\n * the window, or over the last frame when only one has been seen. A hold\n * that never moved (or was released the frame it started) throws nothing:\n * zeros, so the object rests where it was let go. A synthesised release\n * (source lost, target unregistered, runtime disposed) never reads this: the\n * grab behaviour hands the port zeros, as `grab.ts` says.\n */\nimport { velocityBetween, type PoseTuple } from \"@realitycollective/webxr-input\";\nimport type { HoldRelease } from \"./ports.js\";\n\n/** IWSDK's physics step, 1/60 s: the window a throw's velocity is measured over. */\nexport const RELEASE_WINDOW_SECONDS = 1 / 60;\n\n/** How many past frames the tracker keeps: enough to cover the window at any refresh rate down to 30 Hz. */\nconst MAX_SAMPLES = 8;\n\ninterface Sample {\n  pose: PoseTuple;\n  /** Seconds between this pose and the one before it (0 for the first). */\n  dt: number;\n}\n\nexport interface ReleaseVelocityTrackerOptions {\n  /** Seconds the release velocity is measured over. Default `RELEASE_WINDOW_SECONDS`. */\n  windowSeconds?: number;\n}\n\nexport class ReleaseVelocityTracker {\n  private readonly window: number;\n  private readonly samples: Sample[] = [];\n\n  constructor(options: ReleaseVelocityTrackerOptions = {}) {\n    const window = options.windowSeconds ?? RELEASE_WINDOW_SECONDS;\n    if (!Number.isFinite(window) || window <= 0) {\n      throw new Error(`[webxr-interactions] release window must be a positive number of seconds, got ${String(window)}`);\n    }\n    this.window = window;\n  }\n\n  /** Forget every pose: the hold starts afresh. */\n  reset(): void {\n    this.samples.length = 0;\n  }\n\n  /**\n   * Record the pose the carry wrote this frame, `dt` seconds after the last\n   * one. The tuples are copied, so the caller may reuse them.\n   */\n  record(pose: PoseTuple, dt: number): void {\n    const copy: PoseTuple = {\n      position: [pose.position[0], pose.position[1], pose.position[2]],\n      quaternion: [pose.quaternion[0], pose.quaternion[1], pose.quaternion[2], pose.quaternion[3]],\n    };\n    const step = this.samples.length === 0 || !Number.isFinite(dt) || dt < 0 ? 0 : dt;\n    this.samples.push({ pose: copy, dt: step });\n    if (this.samples.length > MAX_SAMPLES) this.samples.shift();\n  }\n\n  /** How many poses are recorded. */\n  get size(): number {\n    return this.samples.length;\n  }\n\n  /**\n   * The velocity the object carries at release: linear m/s and angular\n   * rad/s (axis scaled), world space, over the most recent frames that span\n   * at least the window. Zeros with fewer than two poses, or no elapsed time.\n   */\n  release(): HoldRelease {\n    const n = this.samples.length;\n    if (n < 2) return { linearVelocity: [0, 0, 0], angularVelocity: [0, 0, 0] };\n    let elapsed = 0;\n    let start = n - 1;\n    while (start > 0 && elapsed < this.window) {\n      elapsed += this.samples[start]!.dt;\n      start -= 1;\n    }\n    if (elapsed <= 0) return { linearVelocity: [0, 0, 0], angularVelocity: [0, 0, 0] };\n    const velocity = velocityBetween(this.samples[start]!.pose, this.samples[n - 1]!.pose, elapsed);\n    return { linearVelocity: velocity.linear, angularVelocity: velocity.angular };\n  }\n}\n"]}

package/dist/runtime.d.ts

@@ -13,14 +13,14 @@
  * unregister, enable and disable; behaviours disabled by capability
  * negotiation announce themselves with a `behaviourDisabled` event.
  */
-import { type EyeGazeOptions, type InputCapabilities, type InputProvider, type InputSourceSnapshot, type Unsubscribe } from "@realitycollective/webxr-input";
+import { PointerArbiter, PointerDisplay, type ActivePointerKind, type EyeGazeOptions, type InputCapabilities, type InputProvider, type InputSourceSnapshot, type PointerDisplayConfig, type PointerDrawing, type PointerVisuals, type Unsubscribe } from "@realitycollective/webxr-input";
 import type { Behaviour } from "./behaviours/behaviour.js";
 import type { InteractableDescriptor } from "./descriptor.js";
 import { type InteractionEventListener } from "./events.js";
 import type { FeedbackListener } from "./feedback.js";
 import { type DwellConfig } from "./gaze.js";
 import type { HitTester, TransformPort } from "./ports.js";
-import { type ActivePointerKind, type NearPointerOptions, type PointerVisuals } from "./near-pointer.js";
+import { type NearPointerOptions } from "./near-pointer.js";
 import { type VelocityTrackerOptions } from "./velocity-tracker.js";
 /** Interactor id used when gaze is synthesized from the head pose. */
 export declare const HEAD_GAZE_INTERACTOR_ID = "head-gaze";
@@ -60,7 +60,23 @@ export interface InteractionRuntimeOptions {
      * the touch hover enter distance for that target alone.
      */
     nearPointer?: Partial<NearPointerOptions>;
+    /**
+     * The pointer arbiter shared with everything else a pointer can reach (the
+     * UI Extensions window hosts), so one decision per source covers panels
+     * and interactables alike, as IWSDK's `MultiPointer` does. Omit for a
+     * runtime used on its own: it makes one, and decides over its own targets.
+     */
+    pointers?: PointerArbiter;
+    /**
+     * The app's pointer display settings (ray never, always or while hitting;
+     * cursors on objects and on panels; the ray and cursor look), or a
+     * `PointerDisplay` to share. Defaults are IWSDK 1.0.0's. Settable at run
+     * time through `getPointerDisplay().set(...)`.
+     */
+    pointerDisplay?: PointerDisplay | Partial<PointerDisplayConfig>;
 }
+/** The target set this runtime registers with its arbiter. */
+export declare const INTERACTIONS_POINTER_SET = "interactions";
 export interface RegisterPorts {
     transform?: TransformPort;
 }
@@ -74,8 +90,13 @@ export declare class InteractionRuntime {
     private readonly feedbackEmitter;
     private readonly afterSample;
     private readonly visualsEmitter;
+    private readonly drawingEmitter;
     private readonly nearPointer;
+    private readonly pointers;
+    private readonly targetSet;
+    private readonly pointerDisplay;
     private lastVisuals;
+    private lastDrawings;
     private readonly velocityTracker;
     private lastSources;
     private capabilities;
@@ -149,6 +170,21 @@ export declare class InteractionRuntime {
     onPointerVisuals(listener: (visuals: readonly PointerVisuals[]) => void): Unsubscribe;
     /** The visuals last published for a source, or undefined before its first frame. */
     getPointerVisuals(sourceId: string): PointerVisuals | undefined;
+    /**
+     * What to draw for every source this frame under the app's pointer display
+     * settings: the visuals above resolved through `pointerDrawing`. Published
+     * right after `onPointerVisuals`. A binding that draws its own ray and
+     * cursor applies exactly this; a native binding hands it to the host.
+     */
+    onPointerDrawing(listener: (drawings: readonly PointerDrawing[]) => void): Unsubscribe;
+    /** The drawing last published for a source, or undefined before its first frame. */
+    getPointerDrawing(sourceId: string): PointerDrawing | undefined;
+    /** The arbiter deciding which pointer owns each source, shared with the UI Extensions hosts when the app passed one. */
+    getPointerArbiter(): PointerArbiter;
+    /** The app's pointer display settings; `set` changes them at run time. */
+    getPointerDisplay(): PointerDisplay;
+    /** Whether a source is pressing or grabbing this frame (the selection that recolours its pointer). */
+    isSelecting(sourceId: string): boolean;
     update(dt: number): void;
     dispose(): void;
     /**

package/dist/runtime.js

@@ -13,16 +13,18 @@
  * unregister, enable and disable; behaviours disabled by capability
  * negotiation announce themselves with a `behaviourDisabled` event.
  */
-import { SELECT_PRESS_THRESHOLD, SELECT_RELEASE_THRESHOLD, rayPoseFromRay, resolveEyeGazeOptions, unmetRequirements, } from "@realitycollective/webxr-input";
+import { PointerArbiter, PointerDisplay, SELECT_PRESS_THRESHOLD, SELECT_RELEASE_THRESHOLD, pointerVisualsFor, rayPoseFromRay, resolveEyeGazeOptions, unmetRequirements, } from "@realitycollective/webxr-input";
 import { createBehaviour, } from "./behaviours/factory.js";
 import { GrabBehaviour } from "./behaviours/grab.js";
 import { Emitter } from "./events.js";
 import { DwellState, GazeConsensus, resolveDwellConfig, DWELL_DEFAULTS } from "./gaze.js";
 import { quatConjugate, quatMultiply, vApplyQuat, vLength, vNormalize, vSub } from "./math.js";
-import { pickActivePointer, pointerVisualsFor, resolveNearPointerOptions, TouchPointerState, } from "./near-pointer.js";
+import { resolveNearPointerOptions, TouchPointerState } from "./near-pointer.js";
 import { VelocityTracker } from "./velocity-tracker.js";
 /** Interactor id used when gaze is synthesized from the head pose. */
 export const HEAD_GAZE_INTERACTOR_ID = "head-gaze";
+/** The target set this runtime registers with its arbiter. */
+export const INTERACTIONS_POINTER_SET = "interactions";
 export class InteractionRuntime {
     provider;
     hitTester;
@@ -33,8 +35,13 @@ export class InteractionRuntime {
     feedbackEmitter = new Emitter();
     afterSample = new Emitter();
     visualsEmitter = new Emitter();
+    drawingEmitter = new Emitter();
     nearPointer;
+    pointers;
+    targetSet;
+    pointerDisplay;
     lastVisuals = [];
+    lastDrawings = [];
     velocityTracker;
     lastSources = new Map();
     capabilities;
@@ -51,6 +58,10 @@ export class InteractionRuntime {
         this.provider = options.provider;
         this.hitTester = options.hitTester ?? null;
         this.nearPointer = resolveNearPointerOptions(options.nearPointer);
+        this.pointers = options.pointers ?? new PointerArbiter();
+        this.targetSet = this.pointers.registerSet(INTERACTIONS_POINTER_SET, "object");
+        this.pointerDisplay =
+            options.pointerDisplay instanceof PointerDisplay ? options.pointerDisplay : new PointerDisplay(options.pointerDisplay);
         this.eyeGaze = resolveEyeGazeOptions(options.eyeGaze);
         this.gazeConsensus = new GazeConsensus(this.eyeGaze.dwellWindowSeconds);
         const d = options.dwellDefaults;
@@ -218,6 +229,32 @@ export class InteractionRuntime {
     getPointerVisuals(sourceId) {
         return this.lastVisuals.find((visuals) => visuals.sourceId === sourceId);
     }
+    /**
+     * What to draw for every source this frame under the app's pointer display
+     * settings: the visuals above resolved through `pointerDrawing`. Published
+     * right after `onPointerVisuals`. A binding that draws its own ray and
+     * cursor applies exactly this; a native binding hands it to the host.
+     */
+    onPointerDrawing(listener) {
+        return this.drawingEmitter.subscribe(listener);
+    }
+    /** The drawing last published for a source, or undefined before its first frame. */
+    getPointerDrawing(sourceId) {
+        return this.lastDrawings.find((drawing) => drawing.sourceId === sourceId);
+    }
+    /** The arbiter deciding which pointer owns each source, shared with the UI Extensions hosts when the app passed one. */
+    getPointerArbiter() {
+        return this.pointers;
+    }
+    /** The app's pointer display settings; `set` changes them at run time. */
+    getPointerDisplay() {
+        return this.pointerDisplay;
+    }
+    /** Whether a source is pressing or grabbing this frame (the selection that recolours its pointer). */
+    isSelecting(sourceId) {
+        const state = this.sourceStates.get(sourceId);
+        return state !== undefined && (state.pressTarget !== null || state.grabTarget !== null);
+    }
     // -- frame ------------------------------------------------------------------
     update(dt) {
         if (this.disposed)
@@ -267,14 +304,19 @@ export class InteractionRuntime {
             if (!seen.has(id)) {
                 this.forceRelease(id, state);
                 this.sourceStates.delete(id);
+                this.pointers.forget(id);
             }
         }
         this.updateGaze(sources, dt);
         this.tickBehaviours(sources, dt);
         this.lastVisuals = visuals;
         this.visualsEmitter.emit(visuals);
+        const drawings = visuals.map((entry) => this.pointerDisplay.drawing(entry, this.isSelecting(entry.sourceId)));
+        this.lastDrawings = drawings;
+        this.drawingEmitter.emit(drawings);
     }
     dispose() {
+        this.targetSet.dispose();
         if (this.disposed)
             return;
         this.disposed = true;
@@ -460,7 +502,9 @@ export class InteractionRuntime {
             state.touch.reset();
             const gazeTarget = this.eyeGazeTarget;
             const point = gazeTarget ? this.gazePoints.get(gazeTarget) : undefined;
-            state.candidate = gazeTarget && point ? { targetId: gazeTarget, point, distance: 0 } : null;
+            state.candidate =
+                gazeTarget && point ? { targetId: gazeTarget, point, distance: 0, set: this.targetSet.id, targetKind: "object" } : null;
+            this.pointers.setDecision({ sourceId: source.id, active: "gaze", candidate: state.candidate });
             if (hint && this.targetable(hint.targetId)) {
                 state.resolvedBy = "hint";
                 return hint.targetId;
@@ -469,21 +513,31 @@ export class InteractionRuntime {
                 state.resolvedBy = "gaze";
             return gazeTarget;
         }
-        const touch = this.touchCandidate(source, state);
-        const grab = this.grabCandidate(source);
-        const ray = this.rayCandidate(source);
-        const selecting = state.pressTarget !== null || state.grabTarget !== null;
-        const active = pickActivePointer({ touch: touch !== null, grab: grab !== null, ray: ray !== null }, state.active, selecting);
-        state.active = active;
-        state.candidate = active === "touch" ? touch : active === "grab" ? grab : active === "ray" ? ray : null;
+        // This runtime's own candidates go to the arbiter, which decides across
+        // every target set (a UI panel may be nearer than any interactable). A
+        // hand or controller is also reachable by its side, so a UI host that
+        // knows only the side offers to the same source.
+        if (source.handedness === "left" || source.handedness === "right")
+            this.pointers.alias(source.handedness, source.id);
+        this.targetSet.offer(source.id, "touch", this.touchCandidate(source, state));
+        this.targetSet.offer(source.id, "grab", this.grabCandidate(source));
+        this.targetSet.offer(source.id, "ray", this.rayCandidate(source));
+        const decision = this.pointers.resolve(source.id);
+        state.active = decision.active;
+        state.candidate = decision.candidate;
         if (hint && this.targetable(hint.targetId)) {
             state.resolvedBy = "hint";
             return hint.targetId;
         }
-        if (!state.candidate || !active)
+        const active = decision.active;
+        if (!decision.candidate || !active)
+            return null;
+        // Another set's target (a panel) owns the pointer: no interactable is
+        // targeted, and the visuals still say where the cursor sits.
+        if (decision.candidate.set !== this.targetSet.id)
             return null;
         state.resolvedBy = active === "touch" ? "poke" : active;
-        return state.candidate.targetId;
+        return decision.candidate.targetId;
     }
     /**
      * The touch pointer's candidate this frame, advancing the source's touch
@@ -628,6 +682,12 @@ export class InteractionRuntime {
                 state.grabTarget = null;
             }
         }
+        // The selection lock: the pointer that owns this source keeps it while
+        // it presses or grabs, whatever appears nearer meanwhile.
+        const selecting = state.pressTarget !== null || state.grabTarget !== null;
+        for (const kind of ["touch", "grab", "ray"]) {
+            this.targetSet.setSelecting(source.id, kind, selecting && state.active === kind);
+        }
         if (this.capabilities.eyeGaze && source.kind === "gaze")
             this.trackGazeHold(source, state, target);
     }
@@ -691,7 +751,7 @@ export class InteractionRuntime {
         }
     }
     forceRelease(sourceId, state) {
-        const info = { id: sourceId, kind: "other", select: 0, squeeze: 0 };
+        const info = { id: sourceId, kind: "other", select: 0, squeeze: 0, synthesized: true };
         if (state.pressTarget)
             this.routePressEnd(state.pressTarget, sourceId, info);
         if (state.grabTarget)
@@ -705,12 +765,12 @@ export class InteractionRuntime {
     releaseAllHolds(id) {
         for (const [sourceId, state] of this.sourceStates) {
             if (state.pressTarget === id) {
-                this.routePressEnd(id, sourceId, { id: sourceId, kind: "other", select: 0, squeeze: 0 });
+                this.routePressEnd(id, sourceId, { id: sourceId, kind: "other", select: 0, squeeze: 0, synthesized: true });
                 state.pressTarget = null;
                 state.pressed = false;
             }
             if (state.grabTarget === id) {
-                this.endGrab(id, sourceId, { id: sourceId, kind: "other", select: 0, squeeze: 0 });
+                this.endGrab(id, sourceId, { id: sourceId, kind: "other", select: 0, squeeze: 0, synthesized: true });
                 state.grabTarget = null;
                 state.grabbed = false;
             }