@realitycollective/webxr-interactions 0.1.0-preview.0

package/dist/feedback.js

@@ -0,0 +1,15 @@
+/**
+ * Client opt-in: forward the haptic half of feedback intents to the input
+ * provider's `pulse` (which no-ops on sources without actuators - hands).
+ * Returns the unsubscribe. Audio remains entirely the client's concern.
+ */
+export function routeHapticsToProvider(onFeedback, provider, scale = 1) {
+    return onFeedback((intent) => {
+        if (!intent.sourceId)
+            return;
+        if (!provider.getCapabilities().haptics)
+            return;
+        provider.pulse?.(intent.sourceId, Math.min(1, intent.intensity * scale), intent.durationMs);
+    });
+}
+//# sourceMappingURL=feedback.js.map

package/dist/feedback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback.js","sourceRoot":"","sources":["../src/feedback.ts"],"names":[],"mappings":"AAsCA;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CACpC,UAAuD,EACvD,QAAuB,EACvB,KAAK,GAAG,CAAC;IAET,OAAO,UAAU,CAAC,CAAC,MAAM,EAAE,EAAE;QAC3B,IAAI,CAAC,MAAM,CAAC,QAAQ;YAAE,OAAO;QAC7B,IAAI,CAAC,QAAQ,CAAC,eAAe,EAAE,CAAC,OAAO;YAAE,OAAO;QAChD,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,SAAS,GAAG,KAAK,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAC9F,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["/**\n * Feedback hooks - haptics/audio stay OUT of the framework; the client\n * implements them. Behaviours emit *intents* describing the physical\n * moment (\"this press just actuated, a short strong pulse would fit\");\n * the client subscribes and realises them however it likes (haptic pulse\n * on controllers, an audio cue, both, neither).\n *\n * `routeHapticsToProvider` is the one convenience the framework offers -\n * an explicit opt-in the client calls, never an automatic behaviour.\n */\nimport type { InputProvider, Unsubscribe } from \"@realitycollective/webxr-input\";\n\n/** A named moment a client may want to sonify/hapticise. */\nexport type FeedbackCue =\n  | \"hover\"\n  | \"press\"\n  | \"actuate\"\n  | \"release\"\n  | \"grab\"\n  | \"drop\"\n  | \"score\"\n  | \"dwellComplete\"\n  | \"valueTick\"; // discrete steps on analog controls (dial detents etc.)\n\nexport interface FeedbackIntent {\n  cue: FeedbackCue;\n  interactableId: string;\n  behaviourKind?: string;\n  /** The input source that caused the moment - haptics target this. */\n  sourceId?: string;\n  /** Suggested haptic intensity 0..1 (clients may remap freely). */\n  intensity: number;\n  /** Suggested haptic duration in ms. */\n  durationMs: number;\n}\n\nexport type FeedbackListener = (intent: FeedbackIntent) => void;\n\n/**\n * Client opt-in: forward the haptic half of feedback intents to the input\n * provider's `pulse` (which no-ops on sources without actuators - hands).\n * Returns the unsubscribe. Audio remains entirely the client's concern.\n */\nexport function routeHapticsToProvider(\n  onFeedback: (listener: FeedbackListener) => Unsubscribe,\n  provider: InputProvider,\n  scale = 1,\n): Unsubscribe {\n  return onFeedback((intent) => {\n    if (!intent.sourceId) return;\n    if (!provider.getCapabilities().haptics) return;\n    provider.pulse?.(intent.sourceId, Math.min(1, intent.intensity * scale), intent.durationMs);\n  });\n}\n"]}

package/dist/gaze.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Gaze support - first-class, per the design decision that gaze serves two
+ * roles:
+ *
+ * 1. **Combination gating** (`gaze.required`): input on an interactable only
+ *    counts while the viewer is looking at it.
+ * 2. **Accessibility** (`gaze.dwell`): looking at an interactable fills a
+ *    dwell meter; a full meter fires a synthesized press - no hands needed.
+ *    Consumers render the meter from `dwellProgress` events.
+ *
+ * The dwell state machine is pure and headless-tested. The runtime feeds it
+ * hover booleans; it never sees the engine.
+ */
+export interface DwellConfig {
+    /** Seconds of sustained gaze to fire. */
+    holdSeconds?: number;
+    /** Drain speed multiplier when looking away. */
+    decayFactor?: number;
+    /** After firing, progress must fall below this before it can re-arm. */
+    rearmBelow?: number;
+}
+export interface GazeConfig {
+    /** Non-gaze input on this interactable only counts while gazed at. */
+    required?: boolean;
+    /** Enable dwell-to-press. `true` uses defaults. */
+    dwell?: boolean | DwellConfig;
+}
+export declare const DWELL_DEFAULTS: Required<DwellConfig>;
+export declare function resolveDwellConfig(config: boolean | DwellConfig | undefined, defaults?: Required<DwellConfig>): Required<DwellConfig> | null;
+export interface DwellTick {
+    /** Dwell meter 0..1. */
+    progress: number;
+    /** Progress moved enough to be worth re-rendering (≥ 1%). */
+    changed: boolean;
+    /** The meter just completed - fire the synthesized press. */
+    fired: boolean;
+}
+export declare class DwellState {
+    private progress;
+    private lastReported;
+    private armed;
+    update(hovered: boolean, dt: number, config: Required<DwellConfig>): DwellTick;
+    getProgress(): number;
+}

package/dist/gaze.js

@@ -0,0 +1,61 @@
+/**
+ * Gaze support - first-class, per the design decision that gaze serves two
+ * roles:
+ *
+ * 1. **Combination gating** (`gaze.required`): input on an interactable only
+ *    counts while the viewer is looking at it.
+ * 2. **Accessibility** (`gaze.dwell`): looking at an interactable fills a
+ *    dwell meter; a full meter fires a synthesized press - no hands needed.
+ *    Consumers render the meter from `dwellProgress` events.
+ *
+ * The dwell state machine is pure and headless-tested. The runtime feeds it
+ * hover booleans; it never sees the engine.
+ */
+export const DWELL_DEFAULTS = {
+    holdSeconds: 1.8,
+    decayFactor: 2.5,
+    rearmBelow: 0.1,
+};
+export function resolveDwellConfig(config, defaults = DWELL_DEFAULTS) {
+    if (!config)
+        return null;
+    if (config === true)
+        return defaults;
+    return {
+        holdSeconds: config.holdSeconds ?? defaults.holdSeconds,
+        decayFactor: config.decayFactor ?? defaults.decayFactor,
+        rearmBelow: config.rearmBelow ?? defaults.rearmBelow,
+    };
+}
+export class DwellState {
+    progress = 0;
+    lastReported = 0;
+    armed = true;
+    update(hovered, dt, config) {
+        const before = this.progress;
+        if (hovered) {
+            this.progress = Math.min(1, this.progress + dt / config.holdSeconds);
+        }
+        else {
+            this.progress = Math.max(0, this.progress - (dt * config.decayFactor) / config.holdSeconds);
+        }
+        let fired = false;
+        if (this.armed && this.progress >= 1) {
+            fired = true;
+            this.armed = false;
+            this.progress = 0;
+        }
+        else if (!this.armed && this.progress <= config.rearmBelow) {
+            this.armed = true;
+        }
+        const changed = Math.abs(this.progress - this.lastReported) >= 0.01 ||
+            (this.progress === 0 && before !== 0);
+        if (changed)
+            this.lastReported = this.progress;
+        return { progress: this.progress, changed, fired };
+    }
+    getProgress() {
+        return this.progress;
+    }
+}
+//# sourceMappingURL=gaze.js.map

package/dist/gaze.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gaze.js","sourceRoot":"","sources":["../src/gaze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAkBH,MAAM,CAAC,MAAM,cAAc,GAA0B;IACnD,WAAW,EAAE,GAAG;IAChB,WAAW,EAAE,GAAG;IAChB,UAAU,EAAE,GAAG;CAChB,CAAC;AAEF,MAAM,UAAU,kBAAkB,CAChC,MAAyC,EACzC,WAAkC,cAAc;IAEhD,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,QAAQ,CAAC;IACrC,OAAO;QACL,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,QAAQ,CAAC,WAAW;QACvD,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,QAAQ,CAAC,WAAW;QACvD,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,QAAQ,CAAC,UAAU;KACrD,CAAC;AACJ,CAAC;AAWD,MAAM,OAAO,UAAU;IACb,QAAQ,GAAG,CAAC,CAAC;IACb,YAAY,GAAG,CAAC,CAAC;IACjB,KAAK,GAAG,IAAI,CAAC;IAErB,MAAM,CAAC,OAAgB,EAAE,EAAU,EAAE,MAA6B;QAChE,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC7B,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,QAAQ,GAAG,EAAE,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;QACvE,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,CACtB,CAAC,EACD,IAAI,CAAC,QAAQ,GAAG,CAAC,EAAE,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,MAAM,CAAC,WAAW,CAC/D,CAAC;QACJ,CAAC;QAED,IAAI,KAAK,GAAG,KAAK,CAAC;QAClB,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,QAAQ,IAAI,CAAC,EAAE,CAAC;YACrC,KAAK,GAAG,IAAI,CAAC;YACb,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;YACnB,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;QACpB,CAAC;aAAM,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,QAAQ,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YAC7D,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;QAED,MAAM,OAAO,GACX,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,IAAI;YACnD,CAAC,IAAI,CAAC,QAAQ,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC,CAAC,CAAC;QACxC,IAAI,OAAO;YAAE,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC/C,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACrD,CAAC;IAED,WAAW;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;CACF","sourcesContent":["/**\n * Gaze support - first-class, per the design decision that gaze serves two\n * roles:\n *\n * 1. **Combination gating** (`gaze.required`): input on an interactable only\n *    counts while the viewer is looking at it.\n * 2. **Accessibility** (`gaze.dwell`): looking at an interactable fills a\n *    dwell meter; a full meter fires a synthesized press - no hands needed.\n *    Consumers render the meter from `dwellProgress` events.\n *\n * The dwell state machine is pure and headless-tested. The runtime feeds it\n * hover booleans; it never sees the engine.\n */\n\nexport interface DwellConfig {\n  /** Seconds of sustained gaze to fire. */\n  holdSeconds?: number;\n  /** Drain speed multiplier when looking away. */\n  decayFactor?: number;\n  /** After firing, progress must fall below this before it can re-arm. */\n  rearmBelow?: number;\n}\n\nexport interface GazeConfig {\n  /** Non-gaze input on this interactable only counts while gazed at. */\n  required?: boolean;\n  /** Enable dwell-to-press. `true` uses defaults. */\n  dwell?: boolean | DwellConfig;\n}\n\nexport const DWELL_DEFAULTS: Required<DwellConfig> = {\n  holdSeconds: 1.8,\n  decayFactor: 2.5,\n  rearmBelow: 0.1,\n};\n\nexport function resolveDwellConfig(\n  config: boolean | DwellConfig | undefined,\n  defaults: Required<DwellConfig> = DWELL_DEFAULTS,\n): Required<DwellConfig> | null {\n  if (!config) return null;\n  if (config === true) return defaults;\n  return {\n    holdSeconds: config.holdSeconds ?? defaults.holdSeconds,\n    decayFactor: config.decayFactor ?? defaults.decayFactor,\n    rearmBelow: config.rearmBelow ?? defaults.rearmBelow,\n  };\n}\n\nexport interface DwellTick {\n  /** Dwell meter 0..1. */\n  progress: number;\n  /** Progress moved enough to be worth re-rendering (≥ 1%). */\n  changed: boolean;\n  /** The meter just completed - fire the synthesized press. */\n  fired: boolean;\n}\n\nexport class DwellState {\n  private progress = 0;\n  private lastReported = 0;\n  private armed = true;\n\n  update(hovered: boolean, dt: number, config: Required<DwellConfig>): DwellTick {\n    const before = this.progress;\n    if (hovered) {\n      this.progress = Math.min(1, this.progress + dt / config.holdSeconds);\n    } else {\n      this.progress = Math.max(\n        0,\n        this.progress - (dt * config.decayFactor) / config.holdSeconds,\n      );\n    }\n\n    let fired = false;\n    if (this.armed && this.progress >= 1) {\n      fired = true;\n      this.armed = false;\n      this.progress = 0;\n    } else if (!this.armed && this.progress <= config.rearmBelow) {\n      this.armed = true;\n    }\n\n    const changed =\n      Math.abs(this.progress - this.lastReported) >= 0.01 ||\n      (this.progress === 0 && before !== 0);\n    if (changed) this.lastReported = this.progress;\n    return { progress: this.progress, changed, fired };\n  }\n\n  getProgress(): number {\n    return this.progress;\n  }\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @realitycollective/webxr-interactions - the engine-free interaction core.
+ *
+ * Layers (each strictly on the one below):
+ *  - behaviours (press, pulse, hinge, dial, slide, grab, tossScore) -
+ *    pure state machines driven by `update(dt)`;
+ *  - the runtime/binder - targeting, press/grab transitions, gaze gating
+ *    + dwell, capability negotiation, events, feedback intents;
+ *  - the shared input contracts, re-exported from
+ *    `@realitycollective/webxr-input`.
+ *
+ * Pair with an engine adapter: `@realitycollective/threejs-interactions`
+ * (standalone WebXR + three.js), `@realitycollective/iwsdk-interactions`
+ * (Meta IWSDK) or `@realitycollective/xrblocks-interactions` (Google XR
+ * Blocks, experimental).
+ */
+export * from "@realitycollective/webxr-input";
+export * from "./math.js";
+export * from "./events.js";
+export * from "./feedback.js";
+export * from "./ports.js";
+export * from "./gaze.js";
+export * from "./descriptor.js";
+export * from "./runtime.js";
+export * from "./pointer-bridge.js";
+export * from "./behaviours/behaviour.js";
+export * from "./behaviours/press.js";
+export * from "./behaviours/pulse.js";
+export * from "./behaviours/hinge.js";
+export * from "./behaviours/dial.js";
+export * from "./behaviours/slide.js";
+export * from "./behaviours/grab.js";
+export * from "./behaviours/toss-score.js";
+export * from "./behaviours/factory.js";

package/dist/index.js

@@ -0,0 +1,35 @@
+/**
+ * @realitycollective/webxr-interactions - the engine-free interaction core.
+ *
+ * Layers (each strictly on the one below):
+ *  - behaviours (press, pulse, hinge, dial, slide, grab, tossScore) -
+ *    pure state machines driven by `update(dt)`;
+ *  - the runtime/binder - targeting, press/grab transitions, gaze gating
+ *    + dwell, capability negotiation, events, feedback intents;
+ *  - the shared input contracts, re-exported from
+ *    `@realitycollective/webxr-input`.
+ *
+ * Pair with an engine adapter: `@realitycollective/threejs-interactions`
+ * (standalone WebXR + three.js), `@realitycollective/iwsdk-interactions`
+ * (Meta IWSDK) or `@realitycollective/xrblocks-interactions` (Google XR
+ * Blocks, experimental).
+ */
+export * from "@realitycollective/webxr-input";
+export * from "./math.js";
+export * from "./events.js";
+export * from "./feedback.js";
+export * from "./ports.js";
+export * from "./gaze.js";
+export * from "./descriptor.js";
+export * from "./runtime.js";
+export * from "./pointer-bridge.js";
+export * from "./behaviours/behaviour.js";
+export * from "./behaviours/press.js";
+export * from "./behaviours/pulse.js";
+export * from "./behaviours/hinge.js";
+export * from "./behaviours/dial.js";
+export * from "./behaviours/slide.js";
+export * from "./behaviours/grab.js";
+export * from "./behaviours/toss-score.js";
+export * from "./behaviours/factory.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;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,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 \"./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/math.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Pure interaction math - the proven motion functions extracted from the
+ * Pale Signal research (springs, hinge/dial normalisation, hoop scoring),
+ * plus the tuple vector/quaternion helpers the binder and behaviours need.
+ * No engine imports; everything is unit-tested headless.
+ */
+import type { QuatTuple, RayTuple, Vec3Tuple } from "@realitycollective/webxr-input";
+/** Clamp to the unit interval. */
+export declare function clamp01(t: number): number;
+/**
+ * Normalize a measured displacement/angle against a signed range to 0..1.
+ * Sign-agnostic: a range of `-π/2` maps `-π/2 → 1`.
+ */
+export declare function normalize01(value: number, range: number): number;
+/**
+ * Did a tossed object pass *through* a hoop this frame? True when it crossed
+ * the hoop plane in the scoring direction (downward - `prev` above, `curr`
+ * at/below) while inside the ring (`radial <= radius`).
+ */
+export declare function passedThroughHoop(prevAlong: number, currAlong: number, planeAlong: number, radial: number, radius: number): boolean;
+/**
+ * One step of a damped harmonic oscillator (semi-implicit Euler).
+ * `out[0]` = next value, `out[1]` = next velocity. An under-damped spring
+ * (damping ratio ≈ 0.3-0.5) is what gives a pressed button its bounce.
+ * `dt` is clamped to 1/30 s so a long frame can't blow the integrator up.
+ */
+export declare function springStep(value: number, velocity: number, target: number, stiffness: number, damping: number, dt: number, out?: Float32Array): Float32Array;
+/** Exponential decay of `value` toward 0 over `dt` at `ratePerSec`. */
+export declare function decay(value: number, ratePerSec: number, dt: number): number;
+/** Penner's ease-out-bounce on `t ∈ [0,1]`. */
+export declare function easeOutBounce(t: number): number;
+/** Clamp a value to the symmetric range `[-|mag|, +|mag|]`. */
+export declare function clampSym(x: number, mag: number): number;
+/**
+ * Hinge angle for a position-driven lever: given the hand's offset from the
+ * pivot resolved into the hinge plane - `alongRest` (toward the arm's rest
+ * direction) and `alongSwing` (the in-plane perpendicular) - the angle the
+ * arm should take to point at the hand, clamped to `±|maxMag|`.
+ */
+export declare function hingeAngleToHand(alongRest: number, alongSwing: number, maxMag: number): number;
+/**
+ * Map a centered hinge angle in `[-|mag|, +|mag|]` to a 0..1 analog value
+ * with the rest (0) at 0.5 - a bidirectional lever as one normalized value.
+ */
+export declare function centeredUnit(angle: number, mag: number): number;
+export declare function vSub(a: Vec3Tuple, b: Vec3Tuple): Vec3Tuple;
+export declare function vAdd(a: Vec3Tuple, b: Vec3Tuple): Vec3Tuple;
+export declare function vScale(a: Vec3Tuple, s: number): Vec3Tuple;
+export declare function vDot(a: Vec3Tuple, b: Vec3Tuple): number;
+export declare function vCross(a: Vec3Tuple, b: Vec3Tuple): Vec3Tuple;
+export declare function vLength(a: Vec3Tuple): number;
+export declare function vDistance(a: Vec3Tuple, b: Vec3Tuple): number;
+export declare function vNormalize(a: Vec3Tuple): Vec3Tuple;
+/** Quaternion from an axis (normalised) and an angle in radians. */
+export declare function quatFromAxisAngle(axis: Vec3Tuple, angle: number): QuatTuple;
+export declare function quatMultiply(a: QuatTuple, b: QuatTuple): QuatTuple;
+export declare function quatConjugate(q: QuatTuple): QuatTuple;
+/** Rotate a vector by a quaternion. */
+export declare function vApplyQuat(v: Vec3Tuple, q: QuatTuple): Vec3Tuple;
+/** Transform a world-space point into the local frame of `pose`. */
+export declare function worldToLocal(point: Vec3Tuple, posePosition: Vec3Tuple, poseQuaternion: QuatTuple): Vec3Tuple;
+/** Closest-approach distance from a ray to a point, and the along-ray t. */
+export declare function rayPointDistance(ray: RayTuple, point: Vec3Tuple): {
+    distance: number;
+    t: number;
+};
+/** Angular offset (radians) between a ray direction and the direction to a point. */
+export declare function rayAngleTo(ray: RayTuple, point: Vec3Tuple): number;

package/dist/math.js

@@ -0,0 +1,164 @@
+/** Clamp to the unit interval. */
+export function clamp01(t) {
+    return t < 0 ? 0 : t > 1 ? 1 : t;
+}
+/**
+ * Normalize a measured displacement/angle against a signed range to 0..1.
+ * Sign-agnostic: a range of `-π/2` maps `-π/2 → 1`.
+ */
+export function normalize01(value, range) {
+    if (range === 0)
+        return 0;
+    return clamp01(value / range);
+}
+/**
+ * Did a tossed object pass *through* a hoop this frame? True when it crossed
+ * the hoop plane in the scoring direction (downward - `prev` above, `curr`
+ * at/below) while inside the ring (`radial <= radius`).
+ */
+export function passedThroughHoop(prevAlong, currAlong, planeAlong, radial, radius) {
+    const crossedDown = prevAlong > planeAlong && currAlong <= planeAlong;
+    return crossedDown && radial <= radius;
+}
+/**
+ * One step of a damped harmonic oscillator (semi-implicit Euler).
+ * `out[0]` = next value, `out[1]` = next velocity. An under-damped spring
+ * (damping ratio ≈ 0.3-0.5) is what gives a pressed button its bounce.
+ * `dt` is clamped to 1/30 s so a long frame can't blow the integrator up.
+ */
+export function springStep(value, velocity, target, stiffness, damping, dt, out = new Float32Array(2)) {
+    const h = Math.min(dt, 1 / 30);
+    const accel = -stiffness * (value - target) - damping * velocity;
+    const nextVelocity = velocity + accel * h;
+    out[0] = value + nextVelocity * h;
+    out[1] = nextVelocity;
+    return out;
+}
+/** Exponential decay of `value` toward 0 over `dt` at `ratePerSec`. */
+export function decay(value, ratePerSec, dt) {
+    const next = value * Math.exp(-ratePerSec * Math.max(dt, 0));
+    return next < 1e-4 ? 0 : next;
+}
+/** Penner's ease-out-bounce on `t ∈ [0,1]`. */
+export function easeOutBounce(t) {
+    const n1 = 7.5625;
+    const d1 = 2.75;
+    let x = clamp01(t);
+    if (x < 1 / d1)
+        return n1 * x * x;
+    if (x < 2 / d1)
+        return n1 * (x -= 1.5 / d1) * x + 0.75;
+    if (x < 2.5 / d1)
+        return n1 * (x -= 2.25 / d1) * x + 0.9375;
+    return n1 * (x -= 2.625 / d1) * x + 0.984375;
+}
+/** Clamp a value to the symmetric range `[-|mag|, +|mag|]`. */
+export function clampSym(x, mag) {
+    const m = Math.abs(mag);
+    return x < -m ? -m : x > m ? m : x;
+}
+/**
+ * Hinge angle for a position-driven lever: given the hand's offset from the
+ * pivot resolved into the hinge plane - `alongRest` (toward the arm's rest
+ * direction) and `alongSwing` (the in-plane perpendicular) - the angle the
+ * arm should take to point at the hand, clamped to `±|maxMag|`.
+ */
+export function hingeAngleToHand(alongRest, alongSwing, maxMag) {
+    return clampSym(Math.atan2(alongSwing, alongRest), maxMag);
+}
+/**
+ * Map a centered hinge angle in `[-|mag|, +|mag|]` to a 0..1 analog value
+ * with the rest (0) at 0.5 - a bidirectional lever as one normalized value.
+ */
+export function centeredUnit(angle, mag) {
+    const m = Math.abs(mag);
+    if (m < 1e-6)
+        return 0.5;
+    return clamp01(0.5 + (0.5 * angle) / m);
+}
+// ---------------------------------------------------------------------------
+// Tuple vector / quaternion helpers (allocation-light, no engine types).
+// ---------------------------------------------------------------------------
+export function vSub(a, b) {
+    return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+}
+export function vAdd(a, b) {
+    return [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+}
+export function vScale(a, s) {
+    return [a[0] * s, a[1] * s, a[2] * s];
+}
+export function vDot(a, b) {
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+export function vCross(a, b) {
+    return [
+        a[1] * b[2] - a[2] * b[1],
+        a[2] * b[0] - a[0] * b[2],
+        a[0] * b[1] - a[1] * b[0],
+    ];
+}
+export function vLength(a) {
+    return Math.hypot(a[0], a[1], a[2]);
+}
+export function vDistance(a, b) {
+    return Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+}
+export function vNormalize(a) {
+    const l = vLength(a);
+    return l < 1e-9 ? [0, 0, 0] : [a[0] / l, a[1] / l, a[2] / l];
+}
+/** Quaternion from an axis (normalised) and an angle in radians. */
+export function quatFromAxisAngle(axis, angle) {
+    const half = angle / 2;
+    const s = Math.sin(half);
+    return [axis[0] * s, axis[1] * s, axis[2] * s, Math.cos(half)];
+}
+export function quatMultiply(a, b) {
+    const [ax, ay, az, aw] = a;
+    const [bx, by, bz, bw] = b;
+    return [
+        aw * bx + ax * bw + ay * bz - az * by,
+        aw * by - ax * bz + ay * bw + az * bx,
+        aw * bz + ax * by - ay * bx + az * bw,
+        aw * bw - ax * bx - ay * by - az * bz,
+    ];
+}
+export function quatConjugate(q) {
+    return [-q[0], -q[1], -q[2], q[3]];
+}
+/** Rotate a vector by a quaternion. */
+export function vApplyQuat(v, q) {
+    const [x, y, z] = v;
+    const [qx, qy, qz, qw] = q;
+    // t = 2 * cross(q.xyz, v)
+    const tx = 2 * (qy * z - qz * y);
+    const ty = 2 * (qz * x - qx * z);
+    const tz = 2 * (qx * y - qy * x);
+    // v + qw * t + cross(q.xyz, t)
+    return [
+        x + qw * tx + qy * tz - qz * ty,
+        y + qw * ty + qz * tx - qx * tz,
+        z + qw * tz + qx * ty - qy * tx,
+    ];
+}
+/** Transform a world-space point into the local frame of `pose`. */
+export function worldToLocal(point, posePosition, poseQuaternion) {
+    return vApplyQuat(vSub(point, posePosition), quatConjugate(poseQuaternion));
+}
+/** Closest-approach distance from a ray to a point, and the along-ray t. */
+export function rayPointDistance(ray, point) {
+    const toPoint = vSub(point, ray.origin);
+    const t = vDot(toPoint, ray.direction);
+    if (t <= 0)
+        return { distance: vLength(toPoint), t: 0 };
+    const closest = vAdd(ray.origin, vScale(ray.direction, t));
+    return { distance: vDistance(closest, point), t };
+}
+/** Angular offset (radians) between a ray direction and the direction to a point. */
+export function rayAngleTo(ray, point) {
+    const dir = vNormalize(vSub(point, ray.origin));
+    const d = vDot(vNormalize(ray.direction), dir);
+    return Math.acos(Math.min(1, Math.max(-1, d)));
+}
+//# sourceMappingURL=math.js.map

package/dist/math.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"math.js","sourceRoot":"","sources":["../src/math.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Pure interaction math - the proven motion functions extracted from the\n * Pale Signal research (springs, hinge/dial normalisation, hoop scoring),\n * plus the tuple vector/quaternion helpers the binder and behaviours need.\n * No engine imports; everything is unit-tested headless.\n */\nimport type { QuatTuple, RayTuple, Vec3Tuple } from \"@realitycollective/webxr-input\";\n\n/** Clamp to the unit interval. */\nexport function clamp01(t: number): number {\n  return t < 0 ? 0 : t > 1 ? 1 : t;\n}\n\n/**\n * Normalize a measured displacement/angle against a signed range to 0..1.\n * Sign-agnostic: a range of `-π/2` maps `-π/2 → 1`.\n */\nexport function normalize01(value: number, range: number): number {\n  if (range === 0) return 0;\n  return clamp01(value / range);\n}\n\n/**\n * Did a tossed object pass *through* a hoop this frame? True when it crossed\n * the hoop plane in the scoring direction (downward - `prev` above, `curr`\n * at/below) while inside the ring (`radial <= radius`).\n */\nexport function passedThroughHoop(\n  prevAlong: number,\n  currAlong: number,\n  planeAlong: number,\n  radial: number,\n  radius: number,\n): boolean {\n  const crossedDown = prevAlong > planeAlong && currAlong <= planeAlong;\n  return crossedDown && radial <= radius;\n}\n\n/**\n * One step of a damped harmonic oscillator (semi-implicit Euler).\n * `out[0]` = next value, `out[1]` = next velocity. An under-damped spring\n * (damping ratio ≈ 0.3-0.5) is what gives a pressed button its bounce.\n * `dt` is clamped to 1/30 s so a long frame can't blow the integrator up.\n */\nexport function springStep(\n  value: number,\n  velocity: number,\n  target: number,\n  stiffness: number,\n  damping: number,\n  dt: number,\n  out: Float32Array = new Float32Array(2),\n): Float32Array {\n  const h = Math.min(dt, 1 / 30);\n  const accel = -stiffness * (value - target) - damping * velocity;\n  const nextVelocity = velocity + accel * h;\n  out[0] = value + nextVelocity * h;\n  out[1] = nextVelocity;\n  return out;\n}\n\n/** Exponential decay of `value` toward 0 over `dt` at `ratePerSec`. */\nexport function decay(value: number, ratePerSec: number, dt: number): number {\n  const next = value * Math.exp(-ratePerSec * Math.max(dt, 0));\n  return next < 1e-4 ? 0 : next;\n}\n\n/** Penner's ease-out-bounce on `t ∈ [0,1]`. */\nexport function easeOutBounce(t: number): number {\n  const n1 = 7.5625;\n  const d1 = 2.75;\n  let x = clamp01(t);\n  if (x < 1 / d1) return n1 * x * x;\n  if (x < 2 / d1) return n1 * (x -= 1.5 / d1) * x + 0.75;\n  if (x < 2.5 / d1) return n1 * (x -= 2.25 / d1) * x + 0.9375;\n  return n1 * (x -= 2.625 / d1) * x + 0.984375;\n}\n\n/** Clamp a value to the symmetric range `[-|mag|, +|mag|]`. */\nexport function clampSym(x: number, mag: number): number {\n  const m = Math.abs(mag);\n  return x < -m ? -m : x > m ? m : x;\n}\n\n/**\n * Hinge angle for a position-driven lever: given the hand's offset from the\n * pivot resolved into the hinge plane - `alongRest` (toward the arm's rest\n * direction) and `alongSwing` (the in-plane perpendicular) - the angle the\n * arm should take to point at the hand, clamped to `±|maxMag|`.\n */\nexport function hingeAngleToHand(alongRest: number, alongSwing: number, maxMag: number): number {\n  return clampSym(Math.atan2(alongSwing, alongRest), maxMag);\n}\n\n/**\n * Map a centered hinge angle in `[-|mag|, +|mag|]` to a 0..1 analog value\n * with the rest (0) at 0.5 - a bidirectional lever as one normalized value.\n */\nexport function centeredUnit(angle: number, mag: number): number {\n  const m = Math.abs(mag);\n  if (m < 1e-6) return 0.5;\n  return clamp01(0.5 + (0.5 * angle) / m);\n}\n\n// ---------------------------------------------------------------------------\n// Tuple vector / quaternion helpers (allocation-light, no engine types).\n// ---------------------------------------------------------------------------\n\nexport function vSub(a: Vec3Tuple, b: Vec3Tuple): Vec3Tuple {\n  return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];\n}\n\nexport function vAdd(a: Vec3Tuple, b: Vec3Tuple): Vec3Tuple {\n  return [a[0] + b[0], a[1] + b[1], a[2] + b[2]];\n}\n\nexport function vScale(a: Vec3Tuple, s: number): Vec3Tuple {\n  return [a[0] * s, a[1] * s, a[2] * s];\n}\n\nexport function vDot(a: Vec3Tuple, b: Vec3Tuple): number {\n  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];\n}\n\nexport function vCross(a: Vec3Tuple, b: Vec3Tuple): Vec3Tuple {\n  return [\n    a[1] * b[2] - a[2] * b[1],\n    a[2] * b[0] - a[0] * b[2],\n    a[0] * b[1] - a[1] * b[0],\n  ];\n}\n\nexport function vLength(a: Vec3Tuple): number {\n  return Math.hypot(a[0], a[1], a[2]);\n}\n\nexport function vDistance(a: Vec3Tuple, b: Vec3Tuple): number {\n  return Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);\n}\n\nexport function vNormalize(a: Vec3Tuple): Vec3Tuple {\n  const l = vLength(a);\n  return l < 1e-9 ? [0, 0, 0] : [a[0] / l, a[1] / l, a[2] / l];\n}\n\n/** Quaternion from an axis (normalised) and an angle in radians. */\nexport function quatFromAxisAngle(axis: Vec3Tuple, angle: number): QuatTuple {\n  const half = angle / 2;\n  const s = Math.sin(half);\n  return [axis[0] * s, axis[1] * s, axis[2] * s, Math.cos(half)];\n}\n\nexport function quatMultiply(a: QuatTuple, b: QuatTuple): QuatTuple {\n  const [ax, ay, az, aw] = a;\n  const [bx, by, bz, bw] = b;\n  return [\n    aw * bx + ax * bw + ay * bz - az * by,\n    aw * by - ax * bz + ay * bw + az * bx,\n    aw * bz + ax * by - ay * bx + az * bw,\n    aw * bw - ax * bx - ay * by - az * bz,\n  ];\n}\n\nexport function quatConjugate(q: QuatTuple): QuatTuple {\n  return [-q[0], -q[1], -q[2], q[3]];\n}\n\n/** Rotate a vector by a quaternion. */\nexport function vApplyQuat(v: Vec3Tuple, q: QuatTuple): Vec3Tuple {\n  const [x, y, z] = v;\n  const [qx, qy, qz, qw] = q;\n  // t = 2 * cross(q.xyz, v)\n  const tx = 2 * (qy * z - qz * y);\n  const ty = 2 * (qz * x - qx * z);\n  const tz = 2 * (qx * y - qy * x);\n  // v + qw * t + cross(q.xyz, t)\n  return [\n    x + qw * tx + qy * tz - qz * ty,\n    y + qw * ty + qz * tx - qx * tz,\n    z + qw * tz + qx * ty - qy * tx,\n  ];\n}\n\n/** Transform a world-space point into the local frame of `pose`. */\nexport function worldToLocal(\n  point: Vec3Tuple,\n  posePosition: Vec3Tuple,\n  poseQuaternion: QuatTuple,\n): Vec3Tuple {\n  return vApplyQuat(vSub(point, posePosition), quatConjugate(poseQuaternion));\n}\n\n/** Closest-approach distance from a ray to a point, and the along-ray t. */\nexport function rayPointDistance(ray: RayTuple, point: Vec3Tuple): { distance: number; t: number } {\n  const toPoint = vSub(point, ray.origin);\n  const t = vDot(toPoint, ray.direction);\n  if (t <= 0) return { distance: vLength(toPoint), t: 0 };\n  const closest = vAdd(ray.origin, vScale(ray.direction, t));\n  return { distance: vDistance(closest, point), t };\n}\n\n/** Angular offset (radians) between a ray direction and the direction to a point. */\nexport function rayAngleTo(ray: RayTuple, point: Vec3Tuple): number {\n  const dir = vNormalize(vSub(point, ray.origin));\n  const d = vDot(vNormalize(ray.direction), dir);\n  return Math.acos(Math.min(1, Math.max(-1, d)));\n}\n"]}

package/dist/pointer-bridge.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Pointer bridge - drive the UI Extensions (or anything speaking the
+ * shared pointer contract) from the SAME input stack that drives the
+ * interactions. One provider, both families: this is the coexistence
+ * contract in code.
+ *
+ * The returned object implements `PointerInputSource` (structurally
+ * identical in `@realitycollective/webxr-input` and
+ * `@realitycollective/webxr-uiextensions`): press-move-release derived
+ * from a source's ray + select signal, fed by the runtime's per-frame
+ * sampling.
+ */
+import { type PointerInputSource } from "@realitycollective/webxr-input";
+import type { InteractionRuntime } from "./runtime.js";
+export interface PointerBridge {
+    source: PointerInputSource;
+    dispose(): void;
+}
+/**
+ * Create a pointer stream from the runtime's sampled sources.
+ * `match` picks which source drives it (default: any source with a ray -
+ * first pressed wins and holds until release).
+ */
+export declare function createPointerBridge(runtime: InteractionRuntime, match?: (sourceId: string) => boolean): PointerBridge;

package/dist/pointer-bridge.js

@@ -0,0 +1,60 @@
+/**
+ * Pointer bridge - drive the UI Extensions (or anything speaking the
+ * shared pointer contract) from the SAME input stack that drives the
+ * interactions. One provider, both families: this is the coexistence
+ * contract in code.
+ *
+ * The returned object implements `PointerInputSource` (structurally
+ * identical in `@realitycollective/webxr-input` and
+ * `@realitycollective/webxr-uiextensions`): press-move-release derived
+ * from a source's ray + select signal, fed by the runtime's per-frame
+ * sampling.
+ */
+import { SELECT_PRESS_THRESHOLD, SELECT_RELEASE_THRESHOLD, } from "@realitycollective/webxr-input";
+import { Emitter } from "./events.js";
+/**
+ * Create a pointer stream from the runtime's sampled sources.
+ * `match` picks which source drives it (default: any source with a ray -
+ * first pressed wins and holds until release).
+ */
+export function createPointerBridge(runtime, match = () => true) {
+    const press = new Emitter();
+    const move = new Emitter();
+    const release = new Emitter();
+    let activeSourceId = null;
+    const unsubscribe = runtime.onSourcesSampled((sources) => {
+        if (activeSourceId === null) {
+            for (const source of sources) {
+                if (!source.ray || !match(source.id))
+                    continue;
+                if (source.select >= SELECT_PRESS_THRESHOLD) {
+                    activeSourceId = source.id;
+                    press.emit({ origin: source.ray.origin, direction: source.ray.direction });
+                    break;
+                }
+            }
+            return;
+        }
+        const active = sources.find((s) => s.id === activeSourceId);
+        if (!active || !active.ray || active.select <= SELECT_RELEASE_THRESHOLD) {
+            if (active?.ray) {
+                release.emit({ origin: active.ray.origin, direction: active.ray.direction });
+            }
+            else if (activeSourceId !== null) {
+                release.emit({ origin: [0, 0, 0], direction: [0, 0, -1] });
+            }
+            activeSourceId = null;
+            return;
+        }
+        move.emit({ origin: active.ray.origin, direction: active.ray.direction });
+    });
+    return {
+        source: {
+            onPress: (l) => press.subscribe(l),
+            onMove: (l) => move.subscribe(l),
+            onRelease: (l) => release.subscribe(l),
+        },
+        dispose: unsubscribe,
+    };
+}
+//# sourceMappingURL=pointer-bridge.js.map

package/dist/pointer-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pointer-bridge.js","sourceRoot":"","sources":["../src/pointer-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EACL,sBAAsB,EACtB,wBAAwB,GAIzB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAQtC;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAA2B,EAC3B,QAAuC,GAAG,EAAE,CAAC,IAAI;IAEjD,MAAM,KAAK,GAAG,IAAI,OAAO,EAAiB,CAAC;IAC3C,MAAM,IAAI,GAAG,IAAI,OAAO,EAAiB,CAAC;IAC1C,MAAM,OAAO,GAAG,IAAI,OAAO,EAAiB,CAAC;IAE7C,IAAI,cAAc,GAAkB,IAAI,CAAC;IAEzC,MAAM,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,OAAO,EAAE,EAAE;QACvD,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;YAC5B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;oBAAE,SAAS;gBAC/C,IAAI,MAAM,CAAC,MAAM,IAAI,sBAAsB,EAAE,CAAC;oBAC5C,cAAc,GAAG,MAAM,CAAC,EAAE,CAAC;oBAC3B,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;oBAC3E,MAAM;gBACR,CAAC;YACH,CAAC;YACD,OAAO;QACT,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,cAAc,CAAC,CAAC;QAC5D,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC,MAAM,IAAI,wBAAwB,EAAE,CAAC;YACxE,IAAI,MAAM,EAAE,GAAG,EAAE,CAAC;gBAChB,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;YAC/E,CAAC;iBAAM,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;gBACnC,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAC7D,CAAC;YACD,cAAc,GAAG,IAAI,CAAC;YACtB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;IAC5E,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,MAAM,EAAE;YACN,OAAO,EAAE,CAAC,CAAC,EAAe,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;YAC/C,MAAM,EAAE,CAAC,CAAC,EAAe,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;YAC7C,SAAS,EAAE,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;SACpD;QACD,OAAO,EAAE,WAAW;KACrB,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Pointer bridge - drive the UI Extensions (or anything speaking the\n * shared pointer contract) from the SAME input stack that drives the\n * interactions. One provider, both families: this is the coexistence\n * contract in code.\n *\n * The returned object implements `PointerInputSource` (structurally\n * identical in `@realitycollective/webxr-input` and\n * `@realitycollective/webxr-uiextensions`): press-move-release derived\n * from a source's ray + select signal, fed by the runtime's per-frame\n * sampling.\n */\nimport {\n  SELECT_PRESS_THRESHOLD,\n  SELECT_RELEASE_THRESHOLD,\n  type PointerInputSource,\n  type PointerSample,\n  type Unsubscribe,\n} from \"@realitycollective/webxr-input\";\nimport { Emitter } from \"./events.js\";\nimport type { InteractionRuntime } from \"./runtime.js\";\n\nexport interface PointerBridge {\n  source: PointerInputSource;\n  dispose(): void;\n}\n\n/**\n * Create a pointer stream from the runtime's sampled sources.\n * `match` picks which source drives it (default: any source with a ray -\n * first pressed wins and holds until release).\n */\nexport function createPointerBridge(\n  runtime: InteractionRuntime,\n  match: (sourceId: string) => boolean = () => true,\n): PointerBridge {\n  const press = new Emitter<PointerSample>();\n  const move = new Emitter<PointerSample>();\n  const release = new Emitter<PointerSample>();\n\n  let activeSourceId: string | null = null;\n\n  const unsubscribe = runtime.onSourcesSampled((sources) => {\n    if (activeSourceId === null) {\n      for (const source of sources) {\n        if (!source.ray || !match(source.id)) continue;\n        if (source.select >= SELECT_PRESS_THRESHOLD) {\n          activeSourceId = source.id;\n          press.emit({ origin: source.ray.origin, direction: source.ray.direction });\n          break;\n        }\n      }\n      return;\n    }\n    const active = sources.find((s) => s.id === activeSourceId);\n    if (!active || !active.ray || active.select <= SELECT_RELEASE_THRESHOLD) {\n      if (active?.ray) {\n        release.emit({ origin: active.ray.origin, direction: active.ray.direction });\n      } else if (activeSourceId !== null) {\n        release.emit({ origin: [0, 0, 0], direction: [0, 0, -1] });\n      }\n      activeSourceId = null;\n      return;\n    }\n    move.emit({ origin: active.ray.origin, direction: active.ray.direction });\n  });\n\n  return {\n    source: {\n      onPress: (l): Unsubscribe => press.subscribe(l),\n      onMove: (l): Unsubscribe => move.subscribe(l),\n      onRelease: (l): Unsubscribe => release.subscribe(l),\n    },\n    dispose: unsubscribe,\n  };\n}\n"]}

package/dist/ports.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Engine-side ports - the space queries and transform writes the core
+ * cannot perform itself. Adapters implement these against their scene
+ * graph; the core only ever speaks tuples and interactable ids.
+ */
+import type { PoseTuple, QuatTuple, RayTuple, Vec3Tuple } from "@realitycollective/webxr-input";
+export interface InteractableHit {
+    interactableId: string;
+    /** Distance from the query origin (ray origin / probe point). */
+    distance: number;
+    /** World-space hit or closest point. */
+    point: Vec3Tuple;
+}
+/**
+ * Resolves which interactable a ray or a proximity probe touches.
+ * 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.
+ */
+export interface HitTester {
+    hitRay(ray: RayTuple): InteractableHit | null;
+    hitProximity(point: Vec3Tuple, radius: number): InteractableHit | null;
+}
+/**
+ * The transform/effect surface of ONE interactable's scene object.
+ * Behaviours write through this; the adapter owns how writes land
+ * (Object3D fields, ECS components, …).
+ *
+ * Offsets/rotations are FROM REST: the adapter captures the rest pose at
+ * registration and applies these relative to it, so behaviours compose
+ * with anything else animating the same object (the pale-signal
+ * non-destructive-offset rule).
+ */
+export interface TransformPort {
+    /** Current world pose. */
+    getWorldPose(): 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). */
+    setWorldPose?(pose: PoseTuple): void;
+    /** Additive presentation effect (pulse): scale multiplier & emissive boost. */
+    setEffect?(effect: {
+        scale?: number;
+        emissive?: number;
+    }): void;
+}

package/dist/ports.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ports.js.map

package/dist/ports.js.map

@@ -0,0 +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"]}