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

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,13 +13,14 @@
  * unregister, enable and disable; behaviours disabled by capability
  * negotiation announce themselves with a `behaviourDisabled` event.
  */
-import { 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 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";
@@ -39,13 +40,43 @@ export interface InteractionRuntimeOptions {
     provider: InputProvider;
     hitTester?: HitTester;
     dwellDefaults?: DwellConfig;
+    /**
+     * Eye-gaze targeting, when the provider reports `capabilities.eyeGaze`:
+     * the selection cone, dwell window, near-pointer suppression and whether a
+     * gaze-started drag follows the pinching hand. Defaults are IWSDK 1.0.0's
+     * (`EYE_GAZE_DEFAULTS`).
+     */
+    eyeGaze?: EyeGazeOptions;
     /**
      * Per-source velocity tracking. On by default with no smoothing; pass
      * `false` to skip it, or options to smooth. The tracker only fills in
      * what the provider did not supply.
      */
     velocity?: VelocityTrackerOptions | false;
+    /**
+     * The near-pointer rule's distances: touch hover enter and exit, touch
+     * press, grip grab radius. Defaults are IWSDK 1.0.0's
+     * (`NEAR_POINTER_DEFAULTS`). An interactable's own `pokeRadius` overrides
+     * 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;
 }
@@ -58,11 +89,26 @@ export declare class InteractionRuntime {
     private readonly events;
     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;
     private readonly unsubscribeCaps;
     private disposed;
+    private readonly eyeGaze;
+    private readonly gazeConsensus;
+    /** The eye-gaze source's target this frame: cone, consensus and suppression applied. */
+    private eyeGazeTarget;
+    /** Where the eye-gaze ray last aimed at each target, for the pinching hand to aim at. */
+    private readonly gazePoints;
+    private gazeHold;
     constructor(options: InteractionRuntimeOptions);
     registerInteractable(def: InteractableDescriptor, ports?: RegisterPorts): void;
     unregisterInteractable(id: string): void;
@@ -104,15 +150,94 @@ export declare class InteractionRuntime {
     getSource(id: string): InputSourceSnapshot | undefined;
     getCapabilities(): InputCapabilities;
     getProvider(): InputProvider;
+    /** The near-pointer distances in force (the defaults, or the options given). */
+    getNearPointerOptions(): Readonly<NearPointerOptions>;
+    /**
+     * The pointer that owns a source this frame: `"touch"`, `"grab"`, `"ray"`
+     * or `"gaze"`, or null when no pointer has a candidate (or the source is
+     * unknown). Decided by the core rule in `near-pointer.ts`, on every
+     * platform; a provider hint names the target but never the pointer.
+     */
+    getActivePointer(sourceId: string): ActivePointerKind | null;
+    /**
+     * What to draw for every source this frame: the ray only while the ray is
+     * the active pointer or nothing is, the cursor at the active pointer's
+     * candidate. Published once per `update`, after the sources; a binding
+     * applies it to its ray and cursor visuals, and a native binding hands it
+     * to the host as `applyPointerVisuals`. The list and its entries are fresh
+     * each frame and never written to again.
+     */
+    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;
+    /**
+     * The targeting half of the eye-gaze rule (`@realitycollective/webxr-input`
+     * `eye-gaze.ts` states the whole of it): the cone's best candidate this
+     * frame, then the dwell consensus over the window, and nothing at all while
+     * a hand's near pointer is hovering or selecting (IWSDK
+     * `suppressWhenDirectPointerActive`). A frame with no valid gaze ray clears
+     * the record, as IWSDK resets its conecaster, unless a selection is held.
+     */
+    private resolveEyeGaze;
+    /** A hand's near pointer is hovering or selecting: touch or grab owns the hand, or a grab is held. */
+    private directPointerActive;
+    /**
+     * Once a gaze selection is held, the pinching hand drives the pointer
+     * (IWSDK `pointerTransformFollowsHand`): the frame the hold starts, a ray
+     * from the hand's ray space is aimed at the gaze hit and its orientation
+     * relative to the hand recorded; every later frame the gaze snapshot's ray
+     * is that hand's ray space turned by the same amount. When the hand could
+     * not reach the hit, or the option is off, the ray stays where the
+     * selection was made. Consumers of `onSample` and `getSource`, and every
+     * behaviour, see the followed ray.
+     */
+    private followHand;
+    /** Start, keep or end the gaze hold from the gaze source's press and grab state this frame. */
+    private trackGazeHold;
     private sourceState;
     private interactorInfo;
-    /** Resolve this source's target: hints beat poke beats ray. */
+    /**
+     * Resolve this source's target and its active pointer. The pointer is the
+     * core rule (`near-pointer.ts`): touch, then grab, then ray, the first with
+     * a candidate, locked while it presses or grabs. The target is a provider
+     * hint when there is one (provider power: IWSDK's mesh-accurate tags), else
+     * the active pointer's candidate. An eye-gaze source targets through the
+     * cone and consensus instead.
+     */
     private resolveTarget;
+    /**
+     * The touch pointer's candidate this frame, advancing the source's touch
+     * machine: the nearest target within the widest touch band, hovering by
+     * that target's own enter and exit distances. One proximity query at the
+     * largest radius any interactable asked for, then the nearest hit must be
+     * inside ITS OWN band; the trade is that a farther target with a wider
+     * band is not found behind a nearer one with a narrower band.
+     */
+    private touchCandidate;
+    /** The grab pointer's candidate: the nearest target whose surface the grip sphere reaches. */
+    private grabCandidate;
+    /** The ray pointer's candidate: the nearest target along the ray. */
+    private rayCandidate;
     private targetable;
-    /** The largest poke radius among enabled interactables; the default when none is registered. */
-    private maxPokeRadius;
+    /** The widest touch exit band among enabled interactables; the default exit distance when none is registered. */
+    private touchQueryRadius;
     private flags;
     private updateSource;
     private gazeAllows;