@realitycollective/webxr-interactions 0.1.0-preview.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+Change log for the Reality Collective WebXR Interaction Extensions packages. All four packages are versioned and released together; the version below is the one carried by the `v<version>` release tag.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Preview builds are not listed separately. The entry for a version accumulates while its previews are published, and is dated when that version is released.
+
+## [0.1.0]
+
+### Added
+
+- `@realitycollective/webxr-interactions` - engine-free core: interactables and interactors, the behaviour set (`press` including latching, `pulse`, `hinge`, `dial`, `slide`, `grab` in poseOnly and native modes, `tossScore`), gaze (`required` gating and dwell-to-press), the runtime/binder with hints > poke > ray targeting, hysteresis and lifecycle, capability negotiation with a visible `behaviourDisabled` outcome, events as the only outbound pathway, and feedback intents (haptics and audio remain the client's, with `routeHapticsToProvider` as an explicit opt-in).
+- `@realitycollective/threejs-interactions` - the default standalone adapter: raw WebXR (`XRSession` sources, hand joints, select/squeeze plus gamepad analog, haptic pulse), three.js hit-testing and transform ports, and a desktop mouse fallback. No framework required.
+- `@realitycollective/iwsdk-interactions` - Meta IWSDK adapter: player-rig poses and stateful gamepads as the provider, IWSDK's own targeting (`Pressed` / `Grabbed` tags) forwarded as pre-resolved hints, and native grab fulfilment when the app enables IWSDK grabbing/physics. One-call `registerInteractions(world)` setup.
+- `@realitycollective/xrblocks-interactions` - EXPERIMENTAL Google XR Blocks adapter, structurally typed against xrblocks v0.20.0 (`Input.getFrame()` ray sources and direct touches, pooled structs copied, no haptics upstream).
+- `demos/playground` - the standalone interaction playground: the full station set from one portable `InteractionDescriptor`, with client-side audio cues, opt-in controller haptics and client-side toss ballistics.
+
+### Notes
+
+- All four packages depend on `@realitycollective/webxr-input`, released independently from the [WebXR-Input](https://github.com/realitycollective/WebXR-Input) repository. That package must be published before this one.
+
+[0.1.0]: https://github.com/realitycollective/WebXR-Interactions/commits/main

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Reality Collective
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# @realitycollective/webxr-interactions
+
+The core of the Reality Collective Interaction Extensions. It holds all the interaction logic for WebXR and contains no 3D engine code at all.
+
+Two words are used throughout. An **interactable** is an object that can be interacted with, such as a button. An **interactor** is the thing doing the interacting: a hand, controller, ray or mouse.
+
+```sh
+npm install @realitycollective/webxr-interactions
+```
+
+> You usually do **not** install this directly. Install an adapter for your engine instead. Each adapter re-exports everything here, so your app depends on one package: [`threejs-interactions`](https://www.npmjs.com/package/@realitycollective/threejs-interactions) · [`iwsdk-interactions`](https://www.npmjs.com/package/@realitycollective/iwsdk-interactions) · [`xrblocks-interactions`](https://www.npmjs.com/package/@realitycollective/xrblocks-interactions)
+
+## What it provides
+
+| Area | Detail |
+| --- | --- |
+| **Behaviours** | Ready-made interaction types: `press` (with an optional latching mode that stays down until pressed again), `pulse`, `hinge`, `dial`, `slide`, `grab`, and `tossScore` for throw-and-catch scoring |
+| **Gaze** | Optional look-to-activate. Require the user to be looking before an object responds, or let a sustained look trigger the press by itself |
+| **Targeting** | Picks one target per hand, trying the platform's own answer first, then a close-range touch, then a pointing ray. A short delay stops the target flickering between two objects on a boundary |
+| **Capability checks** | If the headset cannot do what a behaviour needs, the behaviour switches itself off and reports `behaviourDisabled`, rather than silently doing nothing |
+| **Events** | The core never calls into your code. It emits events and you subscribe |
+| **Feedback** | The core asks for a haptic pulse or a sound. Playing it is your app's job. `routeHapticsToProvider` is an opt-in helper that sends those requests straight to the controller |
+
+All input arrives through the shared [`@realitycollective/webxr-input`](https://www.npmjs.com/package/@realitycollective/webxr-input) types, so the same core runs on any runtime that has an adapter.
+
+## Design rules
+
+- **No engine imports.** No `three`, no `@iwsdk/*`, no `xrblocks`. The adapter supplies the code that works out what a ray hits, and the code that moves an object.
+- **Events out, never callbacks in.** The core never reaches into your objects.
+- **Fail loudly, not silently.** A behaviour the hardware cannot support reports `behaviourDisabled` instead of quietly doing nothing.
+
+## Live demo
+
+The interaction playground - the full station set, mouse-capable on desktop, VR button for headsets: **[webxr-interactions.pages.dev](https://webxr-interactions.pages.dev)**
+
+## Documentation
+
+Full architecture notes, the behaviour catalogue and the playground demo live in the [repository README](https://github.com/realitycollective/WebXR-Interactions#readme).
+
+## License
+
+MIT - see [LICENSE](./LICENSE).

package/dist/behaviours/behaviour.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The behaviour contract - a mechanism attached to an interactable.
+ *
+ * Behaviours are pure state machines: they receive routed input moments
+ * (press/grab transitions), tick from `update(dt)`, and write their output
+ * through the interactable's {@link TransformPort}. They declare:
+ *
+ * - `ownership` - who owns the transform (the formalised pale-signal
+ *   driven / dragged / handDriven / native models), so a binder knows
+ *   without reading code;
+ * - `requires` / `requiresAnyOf` - the input capabilities they need;
+ *   capability negotiation disables unsatisfiable behaviours VISIBLY
+ *   (a `behaviourDisabled` event with the unmet list), never silently.
+ */
+import type { InputCapabilityRequirement, InputSourceKind, PoseTuple, RayTuple, Vec3Tuple } from "@realitycollective/webxr-input";
+import type { InteractionEvent } from "../events.js";
+import type { FeedbackIntent } from "../feedback.js";
+import type { TransformPort } from "../ports.js";
+/** Who owns the interactable's transform while this behaviour is active. */
+export type TransformOwnership = "driven" | "dragged" | "handDriven" | "native";
+/** The slice of a live interactor a behaviour may consume. */
+export interface InteractorInfo {
+    id: string;
+    kind: InputSourceKind;
+    ray?: RayTuple;
+    gripPose?: PoseTuple;
+    indexTip?: Vec3Tuple;
+    select: number;
+    squeeze: number;
+}
+/** Everything a behaviour can reach during a tick or a routed moment. */
+export interface BehaviourContext {
+    dt: number;
+    interactableId: string;
+    transform: TransformPort | undefined;
+    emit(event: Omit<InteractionEvent, "interactableId">): void;
+    feedback(intent: Omit<FeedbackIntent, "interactableId">): void;
+    /** REST world pose of another registered interactable (toss scoring). */
+    getWorldPose(interactableId: string): PoseTuple | undefined;
+}
+export interface Behaviour {
+    readonly kind: string;
+    readonly ownership: TransformOwnership;
+    /** ALL of these must be satisfied. */
+    readonly requires: readonly InputCapabilityRequirement[];
+    /** For each group, AT LEAST ONE must be satisfied. */
+    readonly requiresAnyOf?: readonly (readonly InputCapabilityRequirement[])[];
+    /** True when this behaviour makes the interactable a grab target. */
+    readonly grabbable: boolean;
+    onPressStart?(ctx: BehaviourContext, interactor: InteractorInfo): void;
+    onPressEnd?(ctx: BehaviourContext, interactor: InteractorInfo): void;
+    onGrabStart?(ctx: BehaviourContext, interactor: InteractorInfo): void;
+    onGrabEnd?(ctx: BehaviourContext, interactor: InteractorInfo): void;
+    /**
+     * Per-frame tick. `holder` is set while a grab interactor holds this
+     * interactable (grab-family behaviours consume it; others ignore it).
+     */
+    update(ctx: BehaviourContext, holder?: InteractorInfo): void;
+    /** Current logical 0..1 value (state snapshots, HUDs). */
+    getValue(): number;
+}
+/** Hand position a hand-driven behaviour should track, best available. */
+export declare function holderPoint(holder: InteractorInfo): Vec3Tuple | undefined;

package/dist/behaviours/behaviour.js

@@ -0,0 +1,5 @@
+/** Hand position a hand-driven behaviour should track, best available. */
+export function holderPoint(holder) {
+    return holder.indexTip ?? holder.gripPose?.position ?? holder.ray?.origin;
+}
+//# sourceMappingURL=behaviour.js.map

package/dist/behaviours/behaviour.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"behaviour.js","sourceRoot":"","sources":["../../src/behaviours/behaviour.ts"],"names":[],"mappings":"AA2EA,0EAA0E;AAC1E,MAAM,UAAU,WAAW,CAAC,MAAsB;IAChD,OAAO,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,EAAE,QAAQ,IAAI,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC;AAC5E,CAAC","sourcesContent":["/**\n * The behaviour contract - a mechanism attached to an interactable.\n *\n * Behaviours are pure state machines: they receive routed input moments\n * (press/grab transitions), tick from `update(dt)`, and write their output\n * through the interactable's {@link TransformPort}. They declare:\n *\n * - `ownership` - who owns the transform (the formalised pale-signal\n *   driven / dragged / handDriven / native models), so a binder knows\n *   without reading code;\n * - `requires` / `requiresAnyOf` - the input capabilities they need;\n *   capability negotiation disables unsatisfiable behaviours VISIBLY\n *   (a `behaviourDisabled` event with the unmet list), never silently.\n */\nimport type {\n  InputCapabilityRequirement,\n  InputSourceKind,\n  PoseTuple,\n  RayTuple,\n  Vec3Tuple,\n} from \"@realitycollective/webxr-input\";\nimport type { InteractionEvent } from \"../events.js\";\nimport type { FeedbackIntent } from \"../feedback.js\";\nimport type { TransformPort } from \"../ports.js\";\n\n/** Who owns the interactable's transform while this behaviour is active. */\nexport type TransformOwnership = \"driven\" | \"dragged\" | \"handDriven\" | \"native\";\n\n/** The slice of a live interactor a behaviour may consume. */\nexport interface InteractorInfo {\n  id: string;\n  kind: InputSourceKind;\n  ray?: RayTuple;\n  gripPose?: PoseTuple;\n  indexTip?: Vec3Tuple;\n  select: number;\n  squeeze: number;\n}\n\n/** Everything a behaviour can reach during a tick or a routed moment. */\nexport interface BehaviourContext {\n  dt: number;\n  interactableId: string;\n  transform: TransformPort | undefined;\n  emit(event: Omit<InteractionEvent, \"interactableId\">): void;\n  feedback(intent: Omit<FeedbackIntent, \"interactableId\">): void;\n  /** REST world pose of another registered interactable (toss scoring). */\n  getWorldPose(interactableId: string): PoseTuple | undefined;\n}\n\nexport interface Behaviour {\n  readonly kind: string;\n  readonly ownership: TransformOwnership;\n  /** ALL of these must be satisfied. */\n  readonly requires: readonly InputCapabilityRequirement[];\n  /** For each group, AT LEAST ONE must be satisfied. */\n  readonly requiresAnyOf?: readonly (readonly InputCapabilityRequirement[])[];\n  /** True when this behaviour makes the interactable a grab target. */\n  readonly grabbable: boolean;\n\n  onPressStart?(ctx: BehaviourContext, interactor: InteractorInfo): void;\n  onPressEnd?(ctx: BehaviourContext, interactor: InteractorInfo): void;\n  onGrabStart?(ctx: BehaviourContext, interactor: InteractorInfo): void;\n  onGrabEnd?(ctx: BehaviourContext, interactor: InteractorInfo): void;\n\n  /**\n   * Per-frame tick. `holder` is set while a grab interactor holds this\n   * interactable (grab-family behaviours consume it; others ignore it).\n   */\n  update(ctx: BehaviourContext, holder?: InteractorInfo): void;\n\n  /** Current logical 0..1 value (state snapshots, HUDs). */\n  getValue(): number;\n}\n\n/** Hand position a hand-driven behaviour should track, best available. */\nexport function holderPoint(holder: InteractorInfo): Vec3Tuple | undefined {\n  return holder.indexTip ?? holder.gripPose?.position ?? holder.ray?.origin;\n}\n"]}

package/dist/behaviours/dial.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Dial - a twistable knob. `handDriven`: while held, the hand's bearing
+ * around the dial axis accumulates a clamped rotation `[0, maxAngle]`;
+ * publishes `normalize01(angle, maxAngle)`. Works from any provider that
+ * can grab and report a hand/grip position (the research prototype's
+ * engine-dragged variant becomes an adapter option later).
+ */
+import type { Vec3Tuple } from "@realitycollective/webxr-input";
+import { type Behaviour, type BehaviourContext, type InteractorInfo } from "./behaviour.js";
+export interface DialConfig {
+    kind: "dial";
+    /** Local twist axis. */
+    axis?: Vec3Tuple;
+    /** Max rotation from rest (radians). */
+    maxAngle?: number;
+}
+export declare class DialBehaviour implements Behaviour {
+    readonly kind = "dial";
+    readonly ownership: "handDriven";
+    readonly requires: readonly ["grabs"];
+    readonly grabbable = true;
+    private readonly axis;
+    private maxAngle;
+    private angle;
+    private angleAtGrab;
+    private refBearing;
+    private lastEmitted;
+    constructor(config?: Omit<DialConfig, "kind">);
+    private bearingOf;
+    onGrabStart(ctx: BehaviourContext, interactor: InteractorInfo): void;
+    onGrabEnd(ctx: BehaviourContext, interactor: InteractorInfo): void;
+    update(ctx: BehaviourContext, holder?: InteractorInfo): void;
+    getValue(): number;
+    setMaxAngle(maxAngle: number): void;
+    getMaxAngle(): number;
+}

package/dist/behaviours/dial.js

@@ -0,0 +1,88 @@
+import { normalize01, quatFromAxisAngle, vCross, vDot, vNormalize, vSub, worldToLocal, } from "../math.js";
+import { holderPoint } from "./behaviour.js";
+const VALUE_EPSILON = 1e-3;
+export class DialBehaviour {
+    kind = "dial";
+    ownership = "handDriven";
+    requires = ["grabs"];
+    grabbable = true;
+    axis;
+    maxAngle;
+    angle = 0;
+    angleAtGrab = 0;
+    refBearing = null;
+    lastEmitted = -1;
+    constructor(config = {}) {
+        this.axis = config.axis ?? [0, 1, 0];
+        this.maxAngle = config.maxAngle ?? (3 * Math.PI) / 2;
+    }
+    bearingOf(ctx, holder) {
+        const hand = holderPoint(holder);
+        const transform = ctx.transform;
+        if (!hand || !transform)
+            return null;
+        const rest = transform.getWorldPose();
+        const local = worldToLocal(hand, rest.position, rest.quaternion);
+        // Project onto the plane perpendicular to the axis.
+        const along = vDot(local, this.axis);
+        const planar = vSub(local, [
+            this.axis[0] * along,
+            this.axis[1] * along,
+            this.axis[2] * along,
+        ]);
+        const n = vNormalize(planar);
+        return n[0] === 0 && n[1] === 0 && n[2] === 0 ? null : n;
+    }
+    onGrabStart(ctx, interactor) {
+        this.refBearing = this.bearingOf(ctx, interactor);
+        this.angleAtGrab = this.angle;
+        ctx.emit({ type: "grabStart", behaviourKind: this.kind, interactorId: interactor.id });
+        ctx.feedback({
+            cue: "grab",
+            behaviourKind: this.kind,
+            sourceId: interactor.id,
+            intensity: 0.4,
+            durationMs: 25,
+        });
+    }
+    onGrabEnd(ctx, interactor) {
+        this.refBearing = null;
+        ctx.emit({ type: "grabEnd", behaviourKind: this.kind, interactorId: interactor.id });
+        ctx.feedback({
+            cue: "drop",
+            behaviourKind: this.kind,
+            sourceId: interactor.id,
+            intensity: 0.2,
+            durationMs: 15,
+        });
+    }
+    update(ctx, holder) {
+        if (holder && this.refBearing && ctx.transform) {
+            const current = this.bearingOf(ctx, holder);
+            if (current) {
+                const cross = vCross(this.refBearing, current);
+                const delta = Math.atan2(vDot(cross, this.axis), vDot(this.refBearing, current));
+                const next = Math.min(this.maxAngle, Math.max(0, this.angleAtGrab + delta));
+                this.angle = next;
+                ctx.transform.setLocalRotation(quatFromAxisAngle(this.axis, this.angle));
+            }
+        }
+        const value = this.getValue();
+        if (Math.abs(value - this.lastEmitted) > VALUE_EPSILON) {
+            this.lastEmitted = value;
+            ctx.emit({ type: "valueChanged", behaviourKind: this.kind, value });
+        }
+    }
+    getValue() {
+        return normalize01(this.angle, this.maxAngle);
+    }
+    setMaxAngle(maxAngle) {
+        this.maxAngle = maxAngle;
+        if (this.angle > maxAngle)
+            this.angle = maxAngle;
+    }
+    getMaxAngle() {
+        return this.maxAngle;
+    }
+}
+//# sourceMappingURL=dial.js.map

package/dist/behaviours/dial.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dial.js","sourceRoot":"","sources":["../../src/behaviours/dial.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Dial - a twistable knob. `handDriven`: while held, the hand's bearing\n * around the dial axis accumulates a clamped rotation `[0, maxAngle]`;\n * publishes `normalize01(angle, maxAngle)`. Works from any provider that\n * can grab and report a hand/grip position (the research prototype's\n * engine-dragged variant becomes an adapter option later).\n */\nimport type { Vec3Tuple } from \"@realitycollective/webxr-input\";\nimport {\n  normalize01,\n  quatFromAxisAngle,\n  vCross,\n  vDot,\n  vNormalize,\n  vSub,\n  worldToLocal,\n} from \"../math.js\";\nimport { holderPoint, type Behaviour, type BehaviourContext, type InteractorInfo } from \"./behaviour.js\";\n\nexport interface DialConfig {\n  kind: \"dial\";\n  /** Local twist axis. */\n  axis?: Vec3Tuple;\n  /** Max rotation from rest (radians). */\n  maxAngle?: number;\n}\n\nconst VALUE_EPSILON = 1e-3;\n\nexport class DialBehaviour implements Behaviour {\n  readonly kind = \"dial\";\n  readonly ownership = \"handDriven\" as const;\n  readonly requires = [\"grabs\"] as const;\n  readonly grabbable = true;\n\n  private readonly axis: Vec3Tuple;\n  private maxAngle: number;\n  private angle = 0;\n  private angleAtGrab = 0;\n  private refBearing: Vec3Tuple | null = null;\n  private lastEmitted = -1;\n\n  constructor(config: Omit<DialConfig, \"kind\"> = {}) {\n    this.axis = config.axis ?? [0, 1, 0];\n    this.maxAngle = config.maxAngle ?? (3 * Math.PI) / 2;\n  }\n\n  private bearingOf(ctx: BehaviourContext, holder: InteractorInfo): Vec3Tuple | null {\n    const hand = holderPoint(holder);\n    const transform = ctx.transform;\n    if (!hand || !transform) return null;\n    const rest = transform.getWorldPose();\n    const local = worldToLocal(hand, rest.position, rest.quaternion);\n    // Project onto the plane perpendicular to the axis.\n    const along = vDot(local, this.axis);\n    const planar = vSub(local, [\n      this.axis[0] * along,\n      this.axis[1] * along,\n      this.axis[2] * along,\n    ]);\n    const n = vNormalize(planar);\n    return n[0] === 0 && n[1] === 0 && n[2] === 0 ? null : n;\n  }\n\n  onGrabStart(ctx: BehaviourContext, interactor: InteractorInfo): void {\n    this.refBearing = this.bearingOf(ctx, interactor);\n    this.angleAtGrab = this.angle;\n    ctx.emit({ type: \"grabStart\", behaviourKind: this.kind, interactorId: interactor.id });\n    ctx.feedback({\n      cue: \"grab\",\n      behaviourKind: this.kind,\n      sourceId: interactor.id,\n      intensity: 0.4,\n      durationMs: 25,\n    });\n  }\n\n  onGrabEnd(ctx: BehaviourContext, interactor: InteractorInfo): void {\n    this.refBearing = null;\n    ctx.emit({ type: \"grabEnd\", behaviourKind: this.kind, interactorId: interactor.id });\n    ctx.feedback({\n      cue: \"drop\",\n      behaviourKind: this.kind,\n      sourceId: interactor.id,\n      intensity: 0.2,\n      durationMs: 15,\n    });\n  }\n\n  update(ctx: BehaviourContext, holder?: InteractorInfo): void {\n    if (holder && this.refBearing && ctx.transform) {\n      const current = this.bearingOf(ctx, holder);\n      if (current) {\n        const cross = vCross(this.refBearing, current);\n        const delta = Math.atan2(vDot(cross, this.axis), vDot(this.refBearing, current));\n        const next = Math.min(this.maxAngle, Math.max(0, this.angleAtGrab + delta));\n        this.angle = next;\n        ctx.transform.setLocalRotation(quatFromAxisAngle(this.axis, this.angle));\n      }\n    }\n    const value = this.getValue();\n    if (Math.abs(value - this.lastEmitted) > VALUE_EPSILON) {\n      this.lastEmitted = value;\n      ctx.emit({ type: \"valueChanged\", behaviourKind: this.kind, value });\n    }\n  }\n\n  getValue(): number {\n    return normalize01(this.angle, this.maxAngle);\n  }\n\n  setMaxAngle(maxAngle: number): void {\n    this.maxAngle = maxAngle;\n    if (this.angle > maxAngle) this.angle = maxAngle;\n  }\n\n  getMaxAngle(): number {\n    return this.maxAngle;\n  }\n}\n"]}

package/dist/behaviours/factory.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Behaviour factory - turns portable config data into behaviour instances.
+ * Custom kinds register through {@link registerBehaviourKind}, so apps can
+ * add mechanisms without touching the core.
+ */
+import type { Behaviour } from "./behaviour.js";
+import { type DialConfig } from "./dial.js";
+import { type GrabConfig, type GrabFulfilment } from "./grab.js";
+import { type HingeConfig } from "./hinge.js";
+import { type PressConfig } from "./press.js";
+import { type PulseConfig } from "./pulse.js";
+import { type SlideConfig } from "./slide.js";
+import { type TossScoreConfig } from "./toss-score.js";
+export type BehaviourConfig = PressConfig | PulseConfig | HingeConfig | DialConfig | SlideConfig | GrabConfig | TossScoreConfig | (Record<string, unknown> & {
+    kind: string;
+});
+export interface BehaviourFactoryContext {
+    /** Grab fulfilment negotiated from the provider's capabilities. */
+    grabFulfilment: GrabFulfilment;
+}
+type BehaviourFactory = (config: Record<string, unknown>, context: BehaviourFactoryContext) => Behaviour;
+export declare function registerBehaviourKind(kind: string, factory: BehaviourFactory): void;
+export declare function createBehaviour(config: BehaviourConfig, context: BehaviourFactoryContext): Behaviour;
+export {};

package/dist/behaviours/factory.js

@@ -0,0 +1,29 @@
+import { DialBehaviour } from "./dial.js";
+import { GrabBehaviour } from "./grab.js";
+import { HingeBehaviour } from "./hinge.js";
+import { PressBehaviour } from "./press.js";
+import { PulseBehaviour } from "./pulse.js";
+import { SlideBehaviour } from "./slide.js";
+import { TossScoreBehaviour } from "./toss-score.js";
+const registry = new Map();
+export function registerBehaviourKind(kind, factory) {
+    registry.set(kind, factory);
+}
+export function createBehaviour(config, context) {
+    const factory = registry.get(config.kind);
+    if (!factory) {
+        throw new Error(`Unknown behaviour kind "${config.kind}"`);
+    }
+    return factory(config, context);
+}
+registerBehaviourKind("press", (c) => new PressBehaviour(c));
+registerBehaviourKind("pulse", (c) => new PulseBehaviour(c));
+registerBehaviourKind("hinge", (c) => new HingeBehaviour(c));
+registerBehaviourKind("dial", (c) => new DialBehaviour(c));
+registerBehaviourKind("slide", (c) => new SlideBehaviour(c));
+registerBehaviourKind("grab", (c, ctx) => new GrabBehaviour(c, ctx.grabFulfilment));
+registerBehaviourKind("tossScore", (c) => {
+    const config = c;
+    return new TossScoreBehaviour(config);
+});
+//# sourceMappingURL=factory.js.map

package/dist/behaviours/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/behaviours/factory.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,aAAa,EAAmB,MAAM,WAAW,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAwC,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,cAAc,EAAoB,MAAM,YAAY,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAoB,MAAM,YAAY,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAoB,MAAM,YAAY,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAoB,MAAM,YAAY,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAwB,MAAM,iBAAiB,CAAC;AAsB3E,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA4B,CAAC;AAErD,MAAM,UAAU,qBAAqB,CAAC,IAAY,EAAE,OAAyB;IAC3E,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,MAAuB,EACvB,OAAgC;IAEhC,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,2BAA2B,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,OAAO,CAAC,MAAiC,EAAE,OAAO,CAAC,CAAC;AAC7D,CAAC;AAED,qBAAqB,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,cAAc,CAAC,CAA8B,CAAC,CAAC,CAAC;AAC1F,qBAAqB,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,cAAc,CAAC,CAA8B,CAAC,CAAC,CAAC;AAC1F,qBAAqB,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,cAAc,CAAC,CAA8B,CAAC,CAAC,CAAC;AAC1F,qBAAqB,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,aAAa,CAAC,CAA6B,CAAC,CAAC,CAAC;AACvF,qBAAqB,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,cAAc,CAAC,CAA8B,CAAC,CAAC,CAAC;AAC1F,qBAAqB,CACnB,MAAM,EACN,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC,IAAI,aAAa,CAAC,CAA6B,EAAE,GAAG,CAAC,cAAc,CAAC,CACjF,CAAC;AACF,qBAAqB,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE;IACvC,MAAM,MAAM,GAAG,CAA+B,CAAC;IAC/C,OAAO,IAAI,kBAAkB,CAAC,MAAM,CAAC,CAAC;AACxC,CAAC,CAAC,CAAC","sourcesContent":["/**\n * Behaviour factory - turns portable config data into behaviour instances.\n * Custom kinds register through {@link registerBehaviourKind}, so apps can\n * add mechanisms without touching the core.\n */\nimport type { Behaviour } from \"./behaviour.js\";\nimport { DialBehaviour, type DialConfig } from \"./dial.js\";\nimport { GrabBehaviour, type GrabConfig, type GrabFulfilment } from \"./grab.js\";\nimport { HingeBehaviour, type HingeConfig } from \"./hinge.js\";\nimport { PressBehaviour, type PressConfig } from \"./press.js\";\nimport { PulseBehaviour, type PulseConfig } from \"./pulse.js\";\nimport { SlideBehaviour, type SlideConfig } from \"./slide.js\";\nimport { TossScoreBehaviour, type TossScoreConfig } from \"./toss-score.js\";\n\nexport type BehaviourConfig =\n  | PressConfig\n  | PulseConfig\n  | HingeConfig\n  | DialConfig\n  | SlideConfig\n  | GrabConfig\n  | TossScoreConfig\n  | (Record<string, unknown> & { kind: string });\n\nexport interface BehaviourFactoryContext {\n  /** Grab fulfilment negotiated from the provider's capabilities. */\n  grabFulfilment: GrabFulfilment;\n}\n\ntype BehaviourFactory = (\n  config: Record<string, unknown>,\n  context: BehaviourFactoryContext,\n) => Behaviour;\n\nconst registry = new Map<string, BehaviourFactory>();\n\nexport function registerBehaviourKind(kind: string, factory: BehaviourFactory): void {\n  registry.set(kind, factory);\n}\n\nexport function createBehaviour(\n  config: BehaviourConfig,\n  context: BehaviourFactoryContext,\n): Behaviour {\n  const factory = registry.get(config.kind);\n  if (!factory) {\n    throw new Error(`Unknown behaviour kind \"${config.kind}\"`);\n  }\n  return factory(config as Record<string, unknown>, context);\n}\n\nregisterBehaviourKind(\"press\", (c) => new PressBehaviour(c as Omit<PressConfig, \"kind\">));\nregisterBehaviourKind(\"pulse\", (c) => new PulseBehaviour(c as Omit<PulseConfig, \"kind\">));\nregisterBehaviourKind(\"hinge\", (c) => new HingeBehaviour(c as Omit<HingeConfig, \"kind\">));\nregisterBehaviourKind(\"dial\", (c) => new DialBehaviour(c as Omit<DialConfig, \"kind\">));\nregisterBehaviourKind(\"slide\", (c) => new SlideBehaviour(c as Omit<SlideConfig, \"kind\">));\nregisterBehaviourKind(\n  \"grab\",\n  (c, ctx) => new GrabBehaviour(c as Omit<GrabConfig, \"kind\">, ctx.grabFulfilment),\n);\nregisterBehaviourKind(\"tossScore\", (c) => {\n  const config = c as unknown as TossScoreConfig;\n  return new TossScoreBehaviour(config);\n});\n"]}

package/dist/behaviours/grab.d.ts

@@ -0,0 +1,21 @@
+import type { Behaviour, BehaviourContext, InteractorInfo } from "./behaviour.js";
+export interface GrabConfig {
+    kind: "grab";
+}
+export type GrabFulfilment = "poseOnly" | "native";
+export declare class GrabBehaviour implements Behaviour {
+    readonly kind = "grab";
+    readonly ownership: "handDriven" | "native";
+    readonly requires: readonly ["grabs"];
+    readonly grabbable = true;
+    private fulfilment;
+    private held;
+    private offsetPosition;
+    private offsetQuaternion;
+    constructor(_config?: Omit<GrabConfig, "kind">, fulfilment?: GrabFulfilment);
+    setFulfilment(fulfilment: GrabFulfilment): void;
+    onGrabStart(ctx: BehaviourContext, interactor: InteractorInfo): void;
+    onGrabEnd(ctx: BehaviourContext, interactor: InteractorInfo): void;
+    update(ctx: BehaviourContext, holder?: InteractorInfo): void;
+    getValue(): number;
+}

package/dist/behaviours/grab.js

@@ -0,0 +1,64 @@
+import { quatConjugate, quatMultiply, vAdd, vApplyQuat, vSub } from "../math.js";
+export class GrabBehaviour {
+    kind = "grab";
+    ownership;
+    requires = ["grabs"];
+    grabbable = true;
+    fulfilment;
+    held = false;
+    offsetPosition = [0, 0, 0];
+    offsetQuaternion = [0, 0, 0, 1];
+    constructor(_config = {}, fulfilment = "poseOnly") {
+        this.fulfilment = fulfilment;
+        this.ownership = fulfilment === "native" ? "native" : "handDriven";
+    }
+    setFulfilment(fulfilment) {
+        this.fulfilment = fulfilment;
+    }
+    onGrabStart(ctx, interactor) {
+        this.held = true;
+        if (this.fulfilment === "poseOnly" && interactor.gripPose && ctx.transform) {
+            const object = ctx.transform.getWorldPose();
+            const grip = interactor.gripPose;
+            const invGrip = quatConjugate(grip.quaternion);
+            this.offsetPosition = vApplyQuat(vSub(object.position, grip.position), invGrip);
+            this.offsetQuaternion = quatMultiply(invGrip, object.quaternion);
+        }
+        ctx.emit({ type: "grabStart", behaviourKind: this.kind, interactorId: interactor.id });
+        ctx.feedback({
+            cue: "grab",
+            behaviourKind: this.kind,
+            sourceId: interactor.id,
+            intensity: 0.5,
+            durationMs: 30,
+        });
+    }
+    onGrabEnd(ctx, interactor) {
+        this.held = false;
+        ctx.emit({ type: "grabEnd", behaviourKind: this.kind, interactorId: interactor.id });
+        ctx.feedback({
+            cue: "drop",
+            behaviourKind: this.kind,
+            sourceId: interactor.id,
+            intensity: 0.25,
+            durationMs: 20,
+        });
+    }
+    update(ctx, holder) {
+        if (this.fulfilment !== "poseOnly" || !this.held || !holder)
+            return;
+        const grip = holder.gripPose;
+        const transform = ctx.transform;
+        if (!grip || !transform?.setWorldPose)
+            return;
+        const pose = {
+            position: vAdd(grip.position, vApplyQuat(this.offsetPosition, grip.quaternion)),
+            quaternion: quatMultiply(grip.quaternion, this.offsetQuaternion),
+        };
+        transform.setWorldPose(pose);
+    }
+    getValue() {
+        return this.held ? 1 : 0;
+    }
+}
+//# sourceMappingURL=grab.js.map

package/dist/behaviours/grab.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grab.js","sourceRoot":"","sources":["../../src/behaviours/grab.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Grab - pick up and carry an object.\n *\n * Two fulfilments, chosen by capability negotiation at bind time:\n * - `\"poseOnly\"` - the behaviour owns the carry: on grab it captures the\n *   offset between the holder's grip and the object, then follows the grip\n *   each frame via `setWorldPose`. On release the object stays where\n *   dropped - ballistics/physics are deliberately the CLIENT's concern\n *   (physics is a property of the object in space, not of the interaction\n *   layer).\n * - `\"native\"` - the engine owns carry/throw (e.g. IWSDK grabbables +\n *   physics); the behaviour only mirrors transitions into core events.\n */\nimport type { PoseTuple } from \"@realitycollective/webxr-input\";\nimport { quatConjugate, quatMultiply, vAdd, vApplyQuat, vSub } from \"../math.js\";\nimport type { Behaviour, BehaviourContext, InteractorInfo } from \"./behaviour.js\";\n\nexport interface GrabConfig {\n  kind: \"grab\";\n}\n\nexport type GrabFulfilment = \"poseOnly\" | \"native\";\n\nexport class GrabBehaviour implements Behaviour {\n  readonly kind = \"grab\";\n  readonly ownership: \"handDriven\" | \"native\";\n  readonly requires = [\"grabs\"] as const;\n  readonly grabbable = true;\n\n  private fulfilment: GrabFulfilment;\n  private held = false;\n  private offsetPosition = [0, 0, 0] as [number, number, number];\n  private offsetQuaternion = [0, 0, 0, 1] as [number, number, number, number];\n\n  constructor(_config: Omit<GrabConfig, \"kind\"> = {}, fulfilment: GrabFulfilment = \"poseOnly\") {\n    this.fulfilment = fulfilment;\n    this.ownership = fulfilment === \"native\" ? \"native\" : \"handDriven\";\n  }\n\n  setFulfilment(fulfilment: GrabFulfilment): void {\n    this.fulfilment = fulfilment;\n  }\n\n  onGrabStart(ctx: BehaviourContext, interactor: InteractorInfo): void {\n    this.held = true;\n    if (this.fulfilment === \"poseOnly\" && interactor.gripPose && ctx.transform) {\n      const object = ctx.transform.getWorldPose();\n      const grip = interactor.gripPose;\n      const invGrip = quatConjugate(grip.quaternion);\n      this.offsetPosition = vApplyQuat(vSub(object.position, grip.position), invGrip);\n      this.offsetQuaternion = quatMultiply(invGrip, object.quaternion);\n    }\n    ctx.emit({ type: \"grabStart\", behaviourKind: this.kind, interactorId: interactor.id });\n    ctx.feedback({\n      cue: \"grab\",\n      behaviourKind: this.kind,\n      sourceId: interactor.id,\n      intensity: 0.5,\n      durationMs: 30,\n    });\n  }\n\n  onGrabEnd(ctx: BehaviourContext, interactor: InteractorInfo): void {\n    this.held = false;\n    ctx.emit({ type: \"grabEnd\", behaviourKind: this.kind, interactorId: interactor.id });\n    ctx.feedback({\n      cue: \"drop\",\n      behaviourKind: this.kind,\n      sourceId: interactor.id,\n      intensity: 0.25,\n      durationMs: 20,\n    });\n  }\n\n  update(ctx: BehaviourContext, holder?: InteractorInfo): void {\n    if (this.fulfilment !== \"poseOnly\" || !this.held || !holder) return;\n    const grip = holder.gripPose;\n    const transform = ctx.transform;\n    if (!grip || !transform?.setWorldPose) return;\n    const pose: PoseTuple = {\n      position: vAdd(grip.position, vApplyQuat(this.offsetPosition, grip.quaternion)),\n      quaternion: quatMultiply(grip.quaternion, this.offsetQuaternion),\n    };\n    transform.setWorldPose(pose);\n  }\n\n  getValue(): number {\n    return this.held ? 1 : 0;\n  }\n}\n"]}

package/dist/behaviours/hinge.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Hinge - a position-driven lever. `handDriven`: grabbing only marks the
+ * hold; the behaviour reads the holder's hand position each frame and
+ * swings the arm to point at it (movement, not wrist), bidirectional about
+ * rest, clamped to ±maxAngle. Stays where left on release. Publishes a
+ * centred 0..1 value (rest = 0.5).
+ *
+ * All math happens in the interactable's REST local frame, so the mount
+ * (table / wall vertical / wall horizontal / any) is simply the parent
+ * orientation of the object - no faceYaw plumbing needed.
+ */
+import type { Vec3Tuple } from "@realitycollective/webxr-input";
+import { type Behaviour, type BehaviourContext, type InteractorInfo } from "./behaviour.js";
+export interface HingeConfig {
+    kind: "hinge";
+    /** Local hinge axis. */
+    axis?: Vec3Tuple;
+    /** Local rest direction of the arm. */
+    restDir?: Vec3Tuple;
+    /** Max swing (radians) either side of rest. */
+    maxAngle?: number;
+}
+export declare class HingeBehaviour implements Behaviour {
+    readonly kind = "hinge";
+    readonly ownership: "handDriven";
+    readonly requires: readonly ["grabs"];
+    readonly grabbable = true;
+    private readonly axis;
+    private readonly restDir;
+    private readonly swingDir;
+    private maxAngle;
+    private angle;
+    private lastEmitted;
+    constructor(config?: Omit<HingeConfig, "kind">);
+    onGrabStart(ctx: BehaviourContext, interactor: InteractorInfo): void;
+    onGrabEnd(ctx: BehaviourContext, interactor: InteractorInfo): void;
+    update(ctx: BehaviourContext, holder?: InteractorInfo): void;
+    getValue(): number;
+    /** Live-tune the swing range (playground steppers). */
+    setMaxAngle(maxAngle: number): void;
+    getMaxAngle(): number;
+}

package/dist/behaviours/hinge.js

@@ -0,0 +1,70 @@
+import { centeredUnit, hingeAngleToHand, quatFromAxisAngle, vCross, vDot, worldToLocal, } from "../math.js";
+import { holderPoint } from "./behaviour.js";
+const VALUE_EPSILON = 1e-3;
+export class HingeBehaviour {
+    kind = "hinge";
+    ownership = "handDriven";
+    requires = ["grabs"];
+    grabbable = true;
+    axis;
+    restDir;
+    swingDir;
+    maxAngle;
+    angle = 0;
+    lastEmitted = -1;
+    constructor(config = {}) {
+        this.axis = config.axis ?? [1, 0, 0];
+        this.restDir = config.restDir ?? [0, 1, 0];
+        this.swingDir = vCross(this.axis, this.restDir);
+        this.maxAngle = config.maxAngle ?? Math.PI / 4;
+    }
+    onGrabStart(ctx, interactor) {
+        ctx.emit({ type: "grabStart", behaviourKind: this.kind, interactorId: interactor.id });
+        ctx.feedback({
+            cue: "grab",
+            behaviourKind: this.kind,
+            sourceId: interactor.id,
+            intensity: 0.4,
+            durationMs: 25,
+        });
+    }
+    onGrabEnd(ctx, interactor) {
+        ctx.emit({ type: "grabEnd", behaviourKind: this.kind, interactorId: interactor.id });
+        ctx.feedback({
+            cue: "drop",
+            behaviourKind: this.kind,
+            sourceId: interactor.id,
+            intensity: 0.2,
+            durationMs: 15,
+        });
+    }
+    update(ctx, holder) {
+        if (holder && ctx.transform) {
+            const hand = holderPoint(holder);
+            if (hand) {
+                const rest = ctx.transform.getWorldPose();
+                const local = worldToLocal(hand, rest.position, rest.quaternion);
+                const alongRest = vDot(local, this.restDir);
+                const alongSwing = vDot(local, this.swingDir);
+                this.angle = hingeAngleToHand(alongRest, alongSwing, this.maxAngle);
+                ctx.transform.setLocalRotation(quatFromAxisAngle(this.axis, this.angle));
+            }
+        }
+        const value = this.getValue();
+        if (Math.abs(value - this.lastEmitted) > VALUE_EPSILON) {
+            this.lastEmitted = value;
+            ctx.emit({ type: "valueChanged", behaviourKind: this.kind, value });
+        }
+    }
+    getValue() {
+        return centeredUnit(this.angle, this.maxAngle);
+    }
+    /** Live-tune the swing range (playground steppers). */
+    setMaxAngle(maxAngle) {
+        this.maxAngle = maxAngle;
+    }
+    getMaxAngle() {
+        return this.maxAngle;
+    }
+}
+//# sourceMappingURL=hinge.js.map

package/dist/behaviours/hinge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hinge.js","sourceRoot":"","sources":["../../src/behaviours/hinge.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Hinge - a position-driven lever. `handDriven`: grabbing only marks the\n * hold; the behaviour reads the holder's hand position each frame and\n * swings the arm to point at it (movement, not wrist), bidirectional about\n * rest, clamped to ±maxAngle. Stays where left on release. Publishes a\n * centred 0..1 value (rest = 0.5).\n *\n * All math happens in the interactable's REST local frame, so the mount\n * (table / wall vertical / wall horizontal / any) is simply the parent\n * orientation of the object - no faceYaw plumbing needed.\n */\nimport type { Vec3Tuple } from \"@realitycollective/webxr-input\";\nimport {\n  centeredUnit,\n  hingeAngleToHand,\n  quatFromAxisAngle,\n  vCross,\n  vDot,\n  worldToLocal,\n} from \"../math.js\";\nimport { holderPoint, type Behaviour, type BehaviourContext, type InteractorInfo } from \"./behaviour.js\";\n\nexport interface HingeConfig {\n  kind: \"hinge\";\n  /** Local hinge axis. */\n  axis?: Vec3Tuple;\n  /** Local rest direction of the arm. */\n  restDir?: Vec3Tuple;\n  /** Max swing (radians) either side of rest. */\n  maxAngle?: number;\n}\n\nconst VALUE_EPSILON = 1e-3;\n\nexport class HingeBehaviour implements Behaviour {\n  readonly kind = \"hinge\";\n  readonly ownership = \"handDriven\" as const;\n  readonly requires = [\"grabs\"] as const;\n  readonly grabbable = true;\n\n  private readonly axis: Vec3Tuple;\n  private readonly restDir: Vec3Tuple;\n  private readonly swingDir: Vec3Tuple;\n  private maxAngle: number;\n  private angle = 0;\n  private lastEmitted = -1;\n\n  constructor(config: Omit<HingeConfig, \"kind\"> = {}) {\n    this.axis = config.axis ?? [1, 0, 0];\n    this.restDir = config.restDir ?? [0, 1, 0];\n    this.swingDir = vCross(this.axis, this.restDir);\n    this.maxAngle = config.maxAngle ?? Math.PI / 4;\n  }\n\n  onGrabStart(ctx: BehaviourContext, interactor: InteractorInfo): void {\n    ctx.emit({ type: \"grabStart\", behaviourKind: this.kind, interactorId: interactor.id });\n    ctx.feedback({\n      cue: \"grab\",\n      behaviourKind: this.kind,\n      sourceId: interactor.id,\n      intensity: 0.4,\n      durationMs: 25,\n    });\n  }\n\n  onGrabEnd(ctx: BehaviourContext, interactor: InteractorInfo): void {\n    ctx.emit({ type: \"grabEnd\", behaviourKind: this.kind, interactorId: interactor.id });\n    ctx.feedback({\n      cue: \"drop\",\n      behaviourKind: this.kind,\n      sourceId: interactor.id,\n      intensity: 0.2,\n      durationMs: 15,\n    });\n  }\n\n  update(ctx: BehaviourContext, holder?: InteractorInfo): void {\n    if (holder && ctx.transform) {\n      const hand = holderPoint(holder);\n      if (hand) {\n        const rest = ctx.transform.getWorldPose();\n        const local = worldToLocal(hand, rest.position, rest.quaternion);\n        const alongRest = vDot(local, this.restDir);\n        const alongSwing = vDot(local, this.swingDir);\n        this.angle = hingeAngleToHand(alongRest, alongSwing, this.maxAngle);\n        ctx.transform.setLocalRotation(quatFromAxisAngle(this.axis, this.angle));\n      }\n    }\n    const value = this.getValue();\n    if (Math.abs(value - this.lastEmitted) > VALUE_EPSILON) {\n      this.lastEmitted = value;\n      ctx.emit({ type: \"valueChanged\", behaviourKind: this.kind, value });\n    }\n  }\n\n  getValue(): number {\n    return centeredUnit(this.angle, this.maxAngle);\n  }\n\n  /** Live-tune the swing range (playground steppers). */\n  setMaxAngle(maxAngle: number): void {\n    this.maxAngle = maxAngle;\n  }\n\n  getMaxAngle(): number {\n    return this.maxAngle;\n  }\n}\n"]}