@realitycollective/xrblocks-uiextensions 0.1.0-preview.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+Change log for the Reality Collective WebXR UI 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-uiextensions` - engine-free core: window manager, dock state and regions, drag maths, hold-to-drag, control models (stepper/toggle/expandable/log), the `SceneDescriptor` scene format, window chrome conventions and the platform-adapter contract.
+- `@realitycollective/iwsdk-uiextensions` - Meta IWSDK adapter binding the core onto IWSDK's ECS, UIKitML and interaction systems, with shipped examples.
+- `@realitycollective/xrblocks-uiextensions` - EXPERIMENTAL Google XR Blocks / plain three.js adapter: panel document, window host, follow and scale maths, desktop controls and locomotion, pointer forwarding.
+- `@realitycollective/uix-devtools` - dev-only tooling: edit-session launch gate, runtime UIKitML compilation, and the `uix-dev` CLI (Cloudflare quick tunnel, QR onboarding, environment doctor).
+- Demo clients: the IWSDK showcase, the devtools playground, and the multiplatform lab that picks its pipeline from the hardware.
+
+[0.1.0]: https://github.com/realitycollective/WebXR-UIExtensions/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,96 @@
+# @realitycollective/xrblocks-uiextensions
+
+**EXPERIMENTAL** adapter for [Google XR Blocks](https://github.com/google/xrblocks) and plain three.js. It hosts the same [`@realitycollective/webxr-uiextensions`](../webxr-uiextensions/README.md) core as the IWSDK adapter, with the same UIKitML panels, window chrome and window manager, inside any three.js WebXR scene. An XR Blocks Script gives you exactly that kind of scene.
+
+> **Maturity:** the IWSDK adapter is the most complete one, and this adapter is built to match it. It now has nearly all the same windowing features, and its desktop path is verified in a real browser (panels render, mouse clicks reach uikit controls, WASD/jump/ crouch move the camera). It has still had NO on-device pass on Android XR hardware - treat the XR Blocks path specifically as unverified.
+
+## Feature matrix vs the IWSDK adapter
+
+| Feature | IWSDK | XR Blocks / three.js (this package) |
+| --- | --- | --- |
+| UIKitML panel hosting (runtime interpret, scale-to-fit) | ✅ | ✅ `UixPanelDocument` |
+| Window lifecycle + chrome (focus/PIN/MIN/X, pin labels) | ✅ | ✅ `UixWindowHost` |
+| Portable scene descriptors (`applyScene`) | ✅ | ✅ implements `SceneTarget` |
+| Panel-ready wiring (`onPanelReady`) | ✅ | ✅ implements `WindowHost` |
+| Follow mode (body-follow, yaw-only, eased) | ✅ | ✅ pure `follow-math` |
+| Dock regions (wall/belt, slots, follow) | ✅ | ✅ `createRegion` / `dock` |
+| Desktop mouse input (hover, click, drag-to-look) | ✅ | ✅ via `@pmndrs/pointer-events` |
+| Desktop locomotion (WASD, jump, crouch, sprint) | n/a | ✅ `DesktopControls` |
+| XR select-ray click forwarding | ✅ | ✅ minimal (`forwardClick`) |
+| Title-bar ray drag (`@pmndrs/handle`) | ✅ | ⬜ roadmap |
+| Drop-to-dock by dragging | ✅ | ⬜ roadmap (needs drag) |
+| System keyboard text input | ✅ | ⬜ untested on Android XR |
+
+## Required renderer setup (read this first)
+
+uikit draws panel backgrounds, borders and **text glyphs** all as transparent meshes, stacked by `renderOrder`. three.js sorts transparent objects by camera distance by default, which is meaningless for coplanar UI layers - at grazing angles or close range a panel background can sort in front of its own text and labels silently vanish. uikit also clips panel content with local clipping planes, which three.js ignores unless enabled.
+
+Apply both settings to any renderer you create:
+
+```ts
+import { configureRendererForUikit } from '@realitycollective/xrblocks-uiextensions';
+
+const renderer = new WebGLRenderer({ antialias: true });
+configureRendererForUikit(renderer);   // transparent sort + local clipping
+```
+
+IWSDK does this internally, which is why panels look right there with no setup. **A hand-rolled three.js host must do it explicitly**, and under XR Blocks you should apply it to the renderer `xb.init()` creates.
+
+## Usage in an XR Blocks Script
+
+```ts
+import * as xb from 'xrblocks';
+import {
+  DockMode,
+  connectUIExtensions,
+  forwardClick,
+} from '@realitycollective/xrblocks-uiextensions';
+
+class MyScript extends xb.Script {
+  async init() {
+    this.uix = connectUIExtensions({ scene: this, camera: xb.camera });
+    const config = await fetch('./ui/my-window.json').then((r) => r.json());
+    this.uix.createWindow({
+      id: 'status',
+      title: 'Status',
+      config,
+      dockMode: DockMode.BodyFollow,
+    });
+  }
+  update() {
+    this.uix.update(xb.getDeltaTime());
+  }
+  onSelectStart(event) {
+    /* raycast from event.target, then forwardClick(intersections) -
+       see demos/webxr-multiplatform for the complete wiring */
+  }
+}
+
+xb.add(new MyScript());
+await xb.init();
+```
+
+Nothing here imports `xrblocks` - the glue binds to plain three.js shapes (`scene: Object3D`, `camera`), so the same host works in a hand-rolled three.js WebXR app.
+
+## Known constraint: three versions
+
+`xrblocks@0.19` declares a peer of `three@^0.184`, while IWSDK mandates the `super-three@0.181` fork used workspace-wide. Vite resolves a single `three` per bundle so the pairing works in practice, but npm's peer check cannot express it - this workspace uses `legacy-peer-deps` (see the root `.npmrc`). Revisit when IWSDK's three catches up.
+
+## Testing
+
+```bash
+npm test   # scale/follow/pointer math + a headless host lifecycle suite
+```
+
+## Demo
+
+[`demos/webxr-multiplatform`](../../demos/webxr-multiplatform/README.md) - detects the platform and boots this adapter on Android XR (or via `?uix-engine=xrblocks` anywhere, including XR Blocks' desktop simulator).
+
+## Live demos
+
+- Showcase: **[webxr-uiextensions.pages.dev](https://webxr-uiextensions.pages.dev)**
+- Multiplatform lab: **[webxr-uix-lab.pages.dev](https://webxr-uix-lab.pages.dev)**
+
+## License
+
+MIT © Reality Collective

package/dist/desktop-controls.d.ts

@@ -0,0 +1,60 @@
+/**
+ * DesktopControls - first-person camera control for mouse + keyboard, the
+ * stand-in for a headset's head tracking when running on a desktop.
+ *
+ * - WASD / arrows walk, Shift sprints, Space jumps, C (or Left Ctrl) crouches
+ * - Right-mouse drag looks around (left mouse stays free for clicking UI)
+ * - All motion runs through the pure model in `desktop-locomotion.ts`
+ *
+ * Deliberately NOT pointer-lock: the whole point of the desktop pipeline is
+ * clicking spatial UI, and pointer lock would swallow those clicks.
+ */
+import type { PerspectiveCamera } from 'three';
+import { type LocomotionOptions, type LocomotionState } from './desktop-locomotion.js';
+export interface DesktopControlsOptions {
+    /** Element that receives the input listeners (usually the canvas). */
+    domElement: HTMLElement;
+    /** Radians of rotation per pixel of mouse drag. Default 0.0025. */
+    lookSensitivity?: number;
+    /** Locomotion tuning; see {@link DEFAULT_LOCOMOTION}. */
+    locomotion?: Partial<LocomotionOptions>;
+    /** Starting ground position [x, z]. */
+    start?: [number, number];
+    /** Starting heading in radians (0 = facing -Z). */
+    startYaw?: number;
+}
+/**
+ * True when a key event is being typed into a DOM text field - `<input>`,
+ * `<textarea>`, `<select>` or anything contenteditable.
+ *
+ * Overlays share the page with the scene (the devtools playground puts a
+ * source editor over it), and their keystrokes are theirs alone: WASD must
+ * not walk the camera mid-word, and Space must reach the field instead of
+ * being swallowed as a jump.
+ *
+ * A structural check rather than `instanceof HTMLElement`, so it stays
+ * unit-testable with no DOM.
+ */
+export declare function isTextEntryTarget(target: unknown): boolean;
+export declare class DesktopControls {
+    readonly state: LocomotionState;
+    readonly options: LocomotionOptions;
+    /** Heading in radians, about +Y. */
+    yaw: number;
+    /** Look-up/down in radians, clamped to just under ±90°. */
+    pitch: number;
+    private readonly camera;
+    private readonly domElement;
+    private readonly lookSensitivity;
+    private readonly input;
+    private looking;
+    private lastX;
+    private lastY;
+    private readonly disposers;
+    constructor(camera: PerspectiveCamera, options: DesktopControlsOptions);
+    private bind;
+    /** Advance movement and write the pose onto the camera. */
+    update(delta: number): void;
+    private applyToCamera;
+    dispose(): void;
+}

package/dist/desktop-controls.js

@@ -0,0 +1,129 @@
+import { DEFAULT_LOCOMOTION, createLocomotionState, intentForKey, stepLocomotion, } from './desktop-locomotion.js';
+const MAX_PITCH = Math.PI / 2 - 0.05;
+/**
+ * True when a key event is being typed into a DOM text field - `<input>`,
+ * `<textarea>`, `<select>` or anything contenteditable.
+ *
+ * Overlays share the page with the scene (the devtools playground puts a
+ * source editor over it), and their keystrokes are theirs alone: WASD must
+ * not walk the camera mid-word, and Space must reach the field instead of
+ * being swallowed as a jump.
+ *
+ * A structural check rather than `instanceof HTMLElement`, so it stays
+ * unit-testable with no DOM.
+ */
+export function isTextEntryTarget(target) {
+    if (target === null || typeof target !== 'object') {
+        return false;
+    }
+    const element = target;
+    if (element.isContentEditable === true) {
+        return true;
+    }
+    const tag = typeof element.tagName === 'string' ? element.tagName.toUpperCase() : '';
+    return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT';
+}
+export class DesktopControls {
+    state;
+    options;
+    /** Heading in radians, about +Y. */
+    yaw;
+    /** Look-up/down in radians, clamped to just under ±90°. */
+    pitch = 0;
+    camera;
+    domElement;
+    lookSensitivity;
+    input = {
+        forward: false,
+        back: false,
+        left: false,
+        right: false,
+        jump: false,
+        crouch: false,
+        sprint: false,
+    };
+    looking = false;
+    lastX = 0;
+    lastY = 0;
+    disposers = [];
+    constructor(camera, options) {
+        this.camera = camera;
+        this.domElement = options.domElement;
+        this.lookSensitivity = options.lookSensitivity ?? 0.0025;
+        this.options = { ...DEFAULT_LOCOMOTION, ...options.locomotion };
+        this.state = createLocomotionState(this.options);
+        if (options.start) {
+            [this.state.x, this.state.z] = options.start;
+        }
+        this.yaw = options.startYaw ?? 0;
+        this.bind();
+        this.applyToCamera();
+    }
+    bind() {
+        const onKey = (down) => (event) => {
+            const intent = intentForKey(event.code);
+            if (intent === undefined) {
+                return;
+            }
+            // Only keydown is filtered: a keyup always releases, so a key held
+            // before focus moved into a field can never stick on.
+            if (down && isTextEntryTarget(event.target)) {
+                return;
+            }
+            // Space would otherwise scroll the page.
+            if (event.code === 'Space') {
+                event.preventDefault();
+            }
+            this.input[intent] = down;
+        };
+        const keydown = onKey(true);
+        const keyup = onKey(false);
+        window.addEventListener('keydown', keydown);
+        window.addEventListener('keyup', keyup);
+        this.disposers.push(() => window.removeEventListener('keydown', keydown));
+        this.disposers.push(() => window.removeEventListener('keyup', keyup));
+        // Right-drag to look; left button is reserved for UI interaction.
+        const pointerdown = (event) => {
+            if (event.button !== 2) {
+                return;
+            }
+            this.looking = true;
+            this.lastX = event.clientX;
+            this.lastY = event.clientY;
+        };
+        const pointermove = (event) => {
+            if (!this.looking) {
+                return;
+            }
+            const dx = event.clientX - this.lastX;
+            const dy = event.clientY - this.lastY;
+            this.lastX = event.clientX;
+            this.lastY = event.clientY;
+            this.yaw -= dx * this.lookSensitivity;
+            this.pitch = Math.max(-MAX_PITCH, Math.min(MAX_PITCH, this.pitch - dy * this.lookSensitivity));
+        };
+        const stopLooking = () => void (this.looking = false);
+        const contextmenu = (event) => event.preventDefault();
+        this.domElement.addEventListener('pointerdown', pointerdown);
+        window.addEventListener('pointermove', pointermove);
+        window.addEventListener('pointerup', stopLooking);
+        this.domElement.addEventListener('contextmenu', contextmenu);
+        this.disposers.push(() => this.domElement.removeEventListener('pointerdown', pointerdown), () => window.removeEventListener('pointermove', pointermove), () => window.removeEventListener('pointerup', stopLooking), () => this.domElement.removeEventListener('contextmenu', contextmenu));
+    }
+    /** Advance movement and write the pose onto the camera. */
+    update(delta) {
+        stepLocomotion(this.state, this.input, delta, this.options, this.yaw);
+        this.applyToCamera();
+    }
+    applyToCamera() {
+        this.camera.position.set(this.state.x, this.state.y, this.state.z);
+        this.camera.rotation.set(this.pitch, this.yaw, 0, 'YXZ');
+    }
+    dispose() {
+        for (const dispose of this.disposers) {
+            dispose();
+        }
+        this.disposers.length = 0;
+    }
+}
+//# sourceMappingURL=desktop-controls.js.map

package/dist/desktop-controls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop-controls.js","sourceRoot":"","sources":["../src/desktop-controls.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * DesktopControls - first-person camera control for mouse + keyboard, the\n * stand-in for a headset's head tracking when running on a desktop.\n *\n * - WASD / arrows walk, Shift sprints, Space jumps, C (or Left Ctrl) crouches\n * - Right-mouse drag looks around (left mouse stays free for clicking UI)\n * - All motion runs through the pure model in `desktop-locomotion.ts`\n *\n * Deliberately NOT pointer-lock: the whole point of the desktop pipeline is\n * clicking spatial UI, and pointer lock would swallow those clicks.\n */\nimport type { PerspectiveCamera } from 'three';\nimport {\n  DEFAULT_LOCOMOTION,\n  createLocomotionState,\n  intentForKey,\n  stepLocomotion,\n  type LocomotionOptions,\n  type LocomotionState,\n  type MoveInput,\n} from './desktop-locomotion.js';\n\nexport interface DesktopControlsOptions {\n  /** Element that receives the input listeners (usually the canvas). */\n  domElement: HTMLElement;\n  /** Radians of rotation per pixel of mouse drag. Default 0.0025. */\n  lookSensitivity?: number;\n  /** Locomotion tuning; see {@link DEFAULT_LOCOMOTION}. */\n  locomotion?: Partial<LocomotionOptions>;\n  /** Starting ground position [x, z]. */\n  start?: [number, number];\n  /** Starting heading in radians (0 = facing -Z). */\n  startYaw?: number;\n}\n\nconst MAX_PITCH = Math.PI / 2 - 0.05;\n\n/**\n * True when a key event is being typed into a DOM text field - `<input>`,\n * `<textarea>`, `<select>` or anything contenteditable.\n *\n * Overlays share the page with the scene (the devtools playground puts a\n * source editor over it), and their keystrokes are theirs alone: WASD must\n * not walk the camera mid-word, and Space must reach the field instead of\n * being swallowed as a jump.\n *\n * A structural check rather than `instanceof HTMLElement`, so it stays\n * unit-testable with no DOM.\n */\nexport function isTextEntryTarget(target: unknown): boolean {\n  if (target === null || typeof target !== 'object') {\n    return false;\n  }\n  const element = target as { tagName?: unknown; isContentEditable?: unknown };\n  if (element.isContentEditable === true) {\n    return true;\n  }\n  const tag =\n    typeof element.tagName === 'string' ? element.tagName.toUpperCase() : '';\n  return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT';\n}\n\nexport class DesktopControls {\n  readonly state: LocomotionState;\n  readonly options: LocomotionOptions;\n  /** Heading in radians, about +Y. */\n  yaw: number;\n  /** Look-up/down in radians, clamped to just under ±90°. */\n  pitch = 0;\n\n  private readonly camera: PerspectiveCamera;\n  private readonly domElement: HTMLElement;\n  private readonly lookSensitivity: number;\n  private readonly input: MoveInput = {\n    forward: false,\n    back: false,\n    left: false,\n    right: false,\n    jump: false,\n    crouch: false,\n    sprint: false,\n  };\n  private looking = false;\n  private lastX = 0;\n  private lastY = 0;\n  private readonly disposers: Array<() => void> = [];\n\n  constructor(camera: PerspectiveCamera, options: DesktopControlsOptions) {\n    this.camera = camera;\n    this.domElement = options.domElement;\n    this.lookSensitivity = options.lookSensitivity ?? 0.0025;\n    this.options = { ...DEFAULT_LOCOMOTION, ...options.locomotion };\n    this.state = createLocomotionState(this.options);\n    if (options.start) {\n      [this.state.x, this.state.z] = options.start;\n    }\n    this.yaw = options.startYaw ?? 0;\n\n    this.bind();\n    this.applyToCamera();\n  }\n\n  private bind(): void {\n    const onKey = (down: boolean) => (event: KeyboardEvent) => {\n      const intent = intentForKey(event.code);\n      if (intent === undefined) {\n        return;\n      }\n      // Only keydown is filtered: a keyup always releases, so a key held\n      // before focus moved into a field can never stick on.\n      if (down && isTextEntryTarget(event.target)) {\n        return;\n      }\n      // Space would otherwise scroll the page.\n      if (event.code === 'Space') {\n        event.preventDefault();\n      }\n      this.input[intent] = down;\n    };\n    const keydown = onKey(true);\n    const keyup = onKey(false);\n    window.addEventListener('keydown', keydown);\n    window.addEventListener('keyup', keyup);\n    this.disposers.push(() => window.removeEventListener('keydown', keydown));\n    this.disposers.push(() => window.removeEventListener('keyup', keyup));\n\n    // Right-drag to look; left button is reserved for UI interaction.\n    const pointerdown = (event: PointerEvent) => {\n      if (event.button !== 2) {\n        return;\n      }\n      this.looking = true;\n      this.lastX = event.clientX;\n      this.lastY = event.clientY;\n    };\n    const pointermove = (event: PointerEvent) => {\n      if (!this.looking) {\n        return;\n      }\n      const dx = event.clientX - this.lastX;\n      const dy = event.clientY - this.lastY;\n      this.lastX = event.clientX;\n      this.lastY = event.clientY;\n      this.yaw -= dx * this.lookSensitivity;\n      this.pitch = Math.max(\n        -MAX_PITCH,\n        Math.min(MAX_PITCH, this.pitch - dy * this.lookSensitivity),\n      );\n    };\n    const stopLooking = () => void (this.looking = false);\n    const contextmenu = (event: Event) => event.preventDefault();\n\n    this.domElement.addEventListener('pointerdown', pointerdown);\n    window.addEventListener('pointermove', pointermove);\n    window.addEventListener('pointerup', stopLooking);\n    this.domElement.addEventListener('contextmenu', contextmenu);\n    this.disposers.push(\n      () => this.domElement.removeEventListener('pointerdown', pointerdown),\n      () => window.removeEventListener('pointermove', pointermove),\n      () => window.removeEventListener('pointerup', stopLooking),\n      () => this.domElement.removeEventListener('contextmenu', contextmenu),\n    );\n  }\n\n  /** Advance movement and write the pose onto the camera. */\n  update(delta: number): void {\n    stepLocomotion(this.state, this.input, delta, this.options, this.yaw);\n    this.applyToCamera();\n  }\n\n  private applyToCamera(): void {\n    this.camera.position.set(this.state.x, this.state.y, this.state.z);\n    this.camera.rotation.set(this.pitch, this.yaw, 0, 'YXZ');\n  }\n\n  dispose(): void {\n    for (const dispose of this.disposers) {\n      dispose();\n    }\n    this.disposers.length = 0;\n  }\n}\n"]}

package/dist/desktop-locomotion.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Desktop locomotion - WASD walking, jump and crouch for a first-person
+ * camera, so a mouse-and-keyboard user can move around a scene that would
+ * otherwise rely on a headset's room-scale tracking.
+ *
+ * The MOTION MODEL here is pure and frame-rate independent (no three.js, no
+ * DOM), so it is fully unit-testable; `DesktopLocomotion` in
+ * `desktop-controls.ts` is the thin adapter that feeds it key state and
+ * writes the result onto a camera.
+ */
+/** Which movement intents are active this frame. */
+export interface MoveInput {
+    forward: boolean;
+    back: boolean;
+    left: boolean;
+    right: boolean;
+    jump: boolean;
+    crouch: boolean;
+    /** Shift - move faster. */
+    sprint: boolean;
+}
+export declare const NO_INPUT: MoveInput;
+export interface LocomotionOptions {
+    /** Walking speed, m/s. */
+    speed: number;
+    /** Multiplier applied while sprinting. */
+    sprintMultiplier: number;
+    /** Eye height when standing, meters. */
+    standHeight: number;
+    /** Eye height when crouching, meters. */
+    crouchHeight: number;
+    /** How fast the eye height eases between stand and crouch (1/s). */
+    crouchSpeed: number;
+    /** Upward velocity imparted by a jump, m/s. */
+    jumpVelocity: number;
+    /** Gravity, m/s² (positive magnitude). */
+    gravity: number;
+}
+export declare const DEFAULT_LOCOMOTION: LocomotionOptions;
+/** Mutable locomotion state. `x`/`z` are ground position; `y` is eye height. */
+export interface LocomotionState {
+    x: number;
+    z: number;
+    /** Current eye height (includes any jump arc). */
+    y: number;
+    /** Vertical velocity, m/s. Zero while grounded. */
+    verticalVelocity: number;
+    /** True when standing on the ground (jump allowed). */
+    grounded: boolean;
+}
+export declare function createLocomotionState(options?: LocomotionOptions): LocomotionState;
+/**
+ * Ground-plane movement direction in WORLD space for a given yaw.
+ *
+ * Yaw is the camera's heading (0 = looking down -Z, matching three.js).
+ * Returns a normalised [x, z] so diagonal movement isn't faster, or
+ * [0, 0] when no direction is held.
+ */
+export declare function moveDirection(input: MoveInput, yaw: number): [number, number];
+/** The eye height being eased toward, ignoring any jump arc. */
+export declare function targetStanceHeight(input: MoveInput, options: LocomotionOptions): number;
+/**
+ * Advance the locomotion state by `delta` seconds.
+ *
+ * Horizontal movement is direct (no inertia - precise for UI testing);
+ * vertical motion is a simple ballistic arc over the stance height, so
+ * jumping while crouched jumps from the lower stance as expected.
+ * Mutates and returns `state`.
+ */
+export declare function stepLocomotion(state: LocomotionState, input: MoveInput, delta: number, options?: LocomotionOptions, yaw?: number): LocomotionState;
+/** Map a `KeyboardEvent.code` to the movement intent it drives. */
+export declare function intentForKey(code: string): keyof MoveInput | undefined;

package/dist/desktop-locomotion.js

@@ -0,0 +1,131 @@
+/**
+ * Desktop locomotion - WASD walking, jump and crouch for a first-person
+ * camera, so a mouse-and-keyboard user can move around a scene that would
+ * otherwise rely on a headset's room-scale tracking.
+ *
+ * The MOTION MODEL here is pure and frame-rate independent (no three.js, no
+ * DOM), so it is fully unit-testable; `DesktopLocomotion` in
+ * `desktop-controls.ts` is the thin adapter that feeds it key state and
+ * writes the result onto a camera.
+ */
+export const NO_INPUT = {
+    forward: false,
+    back: false,
+    left: false,
+    right: false,
+    jump: false,
+    crouch: false,
+    sprint: false,
+};
+export const DEFAULT_LOCOMOTION = {
+    speed: 2.2,
+    sprintMultiplier: 2,
+    standHeight: 1.6,
+    crouchHeight: 0.9,
+    crouchSpeed: 8,
+    jumpVelocity: 3.6,
+    gravity: 9.81,
+};
+export function createLocomotionState(options = DEFAULT_LOCOMOTION) {
+    return {
+        x: 0,
+        z: 0,
+        y: options.standHeight,
+        verticalVelocity: 0,
+        grounded: true,
+    };
+}
+/**
+ * Ground-plane movement direction in WORLD space for a given yaw.
+ *
+ * Yaw is the camera's heading (0 = looking down -Z, matching three.js).
+ * Returns a normalised [x, z] so diagonal movement isn't faster, or
+ * [0, 0] when no direction is held.
+ */
+export function moveDirection(input, yaw) {
+    // Local axes: forward is -Z, right is +X.
+    const localZ = (input.back ? 1 : 0) - (input.forward ? 1 : 0);
+    const localX = (input.right ? 1 : 0) - (input.left ? 1 : 0);
+    if (localX === 0 && localZ === 0) {
+        return [0, 0];
+    }
+    const length = Math.hypot(localX, localZ);
+    const nx = localX / length;
+    const nz = localZ / length;
+    // Rotate the local direction by the camera yaw about +Y.
+    const sin = Math.sin(yaw);
+    const cos = Math.cos(yaw);
+    return [nx * cos + nz * sin, -nx * sin + nz * cos];
+}
+/** The eye height being eased toward, ignoring any jump arc. */
+export function targetStanceHeight(input, options) {
+    return input.crouch ? options.crouchHeight : options.standHeight;
+}
+/**
+ * Advance the locomotion state by `delta` seconds.
+ *
+ * Horizontal movement is direct (no inertia - precise for UI testing);
+ * vertical motion is a simple ballistic arc over the stance height, so
+ * jumping while crouched jumps from the lower stance as expected.
+ * Mutates and returns `state`.
+ */
+export function stepLocomotion(state, input, delta, options = DEFAULT_LOCOMOTION, yaw = 0) {
+    if (!(delta > 0)) {
+        return state;
+    }
+    const [dx, dz] = moveDirection(input, yaw);
+    const speed = options.speed * (input.sprint ? options.sprintMultiplier : 1);
+    state.x += dx * speed * delta;
+    state.z += dz * speed * delta;
+    const stance = targetStanceHeight(input, options);
+    if (state.grounded) {
+        if (input.jump) {
+            state.verticalVelocity = options.jumpVelocity;
+            state.grounded = false;
+        }
+        else {
+            // Ease the eye height toward the stance (crouch/stand transition).
+            const alpha = Math.min(1, options.crouchSpeed * delta);
+            state.y += (stance - state.y) * alpha;
+            state.verticalVelocity = 0;
+        }
+    }
+    if (!state.grounded) {
+        state.verticalVelocity -= options.gravity * delta;
+        state.y += state.verticalVelocity * delta;
+        if (state.y <= stance) {
+            state.y = stance;
+            state.verticalVelocity = 0;
+            state.grounded = true;
+        }
+    }
+    return state;
+}
+/** Map a `KeyboardEvent.code` to the movement intent it drives. */
+export function intentForKey(code) {
+    switch (code) {
+        case 'KeyW':
+        case 'ArrowUp':
+            return 'forward';
+        case 'KeyS':
+        case 'ArrowDown':
+            return 'back';
+        case 'KeyA':
+        case 'ArrowLeft':
+            return 'left';
+        case 'KeyD':
+        case 'ArrowRight':
+            return 'right';
+        case 'Space':
+            return 'jump';
+        case 'KeyC':
+        case 'ControlLeft':
+            return 'crouch';
+        case 'ShiftLeft':
+        case 'ShiftRight':
+            return 'sprint';
+        default:
+            return undefined;
+    }
+}
+//# sourceMappingURL=desktop-locomotion.js.map

package/dist/desktop-locomotion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop-locomotion.js","sourceRoot":"","sources":["../src/desktop-locomotion.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Desktop locomotion - WASD walking, jump and crouch for a first-person\n * camera, so a mouse-and-keyboard user can move around a scene that would\n * otherwise rely on a headset's room-scale tracking.\n *\n * The MOTION MODEL here is pure and frame-rate independent (no three.js, no\n * DOM), so it is fully unit-testable; `DesktopLocomotion` in\n * `desktop-controls.ts` is the thin adapter that feeds it key state and\n * writes the result onto a camera.\n */\n\n/** Which movement intents are active this frame. */\nexport interface MoveInput {\n  forward: boolean;\n  back: boolean;\n  left: boolean;\n  right: boolean;\n  jump: boolean;\n  crouch: boolean;\n  /** Shift - move faster. */\n  sprint: boolean;\n}\n\nexport const NO_INPUT: MoveInput = {\n  forward: false,\n  back: false,\n  left: false,\n  right: false,\n  jump: false,\n  crouch: false,\n  sprint: false,\n};\n\nexport interface LocomotionOptions {\n  /** Walking speed, m/s. */\n  speed: number;\n  /** Multiplier applied while sprinting. */\n  sprintMultiplier: number;\n  /** Eye height when standing, meters. */\n  standHeight: number;\n  /** Eye height when crouching, meters. */\n  crouchHeight: number;\n  /** How fast the eye height eases between stand and crouch (1/s). */\n  crouchSpeed: number;\n  /** Upward velocity imparted by a jump, m/s. */\n  jumpVelocity: number;\n  /** Gravity, m/s² (positive magnitude). */\n  gravity: number;\n}\n\nexport const DEFAULT_LOCOMOTION: LocomotionOptions = {\n  speed: 2.2,\n  sprintMultiplier: 2,\n  standHeight: 1.6,\n  crouchHeight: 0.9,\n  crouchSpeed: 8,\n  jumpVelocity: 3.6,\n  gravity: 9.81,\n};\n\n/** Mutable locomotion state. `x`/`z` are ground position; `y` is eye height. */\nexport interface LocomotionState {\n  x: number;\n  z: number;\n  /** Current eye height (includes any jump arc). */\n  y: number;\n  /** Vertical velocity, m/s. Zero while grounded. */\n  verticalVelocity: number;\n  /** True when standing on the ground (jump allowed). */\n  grounded: boolean;\n}\n\nexport function createLocomotionState(\n  options: LocomotionOptions = DEFAULT_LOCOMOTION,\n): LocomotionState {\n  return {\n    x: 0,\n    z: 0,\n    y: options.standHeight,\n    verticalVelocity: 0,\n    grounded: true,\n  };\n}\n\n/**\n * Ground-plane movement direction in WORLD space for a given yaw.\n *\n * Yaw is the camera's heading (0 = looking down -Z, matching three.js).\n * Returns a normalised [x, z] so diagonal movement isn't faster, or\n * [0, 0] when no direction is held.\n */\nexport function moveDirection(input: MoveInput, yaw: number): [number, number] {\n  // Local axes: forward is -Z, right is +X.\n  const localZ = (input.back ? 1 : 0) - (input.forward ? 1 : 0);\n  const localX = (input.right ? 1 : 0) - (input.left ? 1 : 0);\n  if (localX === 0 && localZ === 0) {\n    return [0, 0];\n  }\n  const length = Math.hypot(localX, localZ);\n  const nx = localX / length;\n  const nz = localZ / length;\n  // Rotate the local direction by the camera yaw about +Y.\n  const sin = Math.sin(yaw);\n  const cos = Math.cos(yaw);\n  return [nx * cos + nz * sin, -nx * sin + nz * cos];\n}\n\n/** The eye height being eased toward, ignoring any jump arc. */\nexport function targetStanceHeight(\n  input: MoveInput,\n  options: LocomotionOptions,\n): number {\n  return input.crouch ? options.crouchHeight : options.standHeight;\n}\n\n/**\n * Advance the locomotion state by `delta` seconds.\n *\n * Horizontal movement is direct (no inertia - precise for UI testing);\n * vertical motion is a simple ballistic arc over the stance height, so\n * jumping while crouched jumps from the lower stance as expected.\n * Mutates and returns `state`.\n */\nexport function stepLocomotion(\n  state: LocomotionState,\n  input: MoveInput,\n  delta: number,\n  options: LocomotionOptions = DEFAULT_LOCOMOTION,\n  yaw = 0,\n): LocomotionState {\n  if (!(delta > 0)) {\n    return state;\n  }\n\n  const [dx, dz] = moveDirection(input, yaw);\n  const speed = options.speed * (input.sprint ? options.sprintMultiplier : 1);\n  state.x += dx * speed * delta;\n  state.z += dz * speed * delta;\n\n  const stance = targetStanceHeight(input, options);\n\n  if (state.grounded) {\n    if (input.jump) {\n      state.verticalVelocity = options.jumpVelocity;\n      state.grounded = false;\n    } else {\n      // Ease the eye height toward the stance (crouch/stand transition).\n      const alpha = Math.min(1, options.crouchSpeed * delta);\n      state.y += (stance - state.y) * alpha;\n      state.verticalVelocity = 0;\n    }\n  }\n\n  if (!state.grounded) {\n    state.verticalVelocity -= options.gravity * delta;\n    state.y += state.verticalVelocity * delta;\n    if (state.y <= stance) {\n      state.y = stance;\n      state.verticalVelocity = 0;\n      state.grounded = true;\n    }\n  }\n\n  return state;\n}\n\n/** Map a `KeyboardEvent.code` to the movement intent it drives. */\nexport function intentForKey(code: string): keyof MoveInput | undefined {\n  switch (code) {\n    case 'KeyW':\n    case 'ArrowUp':\n      return 'forward';\n    case 'KeyS':\n    case 'ArrowDown':\n      return 'back';\n    case 'KeyA':\n    case 'ArrowLeft':\n      return 'left';\n    case 'KeyD':\n    case 'ArrowRight':\n      return 'right';\n    case 'Space':\n      return 'jump';\n    case 'KeyC':\n    case 'ControlLeft':\n      return 'crouch';\n    case 'ShiftLeft':\n    case 'ShiftRight':\n      return 'sprint';\n    default:\n      return undefined;\n  }\n}\n"]}

package/dist/follow-math.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Follow-mode math - pure tuple arithmetic (no three.js) so it is fully
+ * unit-testable. Windows in `body-follow` mode chase a target point that is
+ * the viewer's head position plus a yaw-rotated offset (pitch/roll are
+ * deliberately ignored so panels never tilt with the viewer's head).
+ */
+import type { HeadPose, Vec3Tuple } from '@realitycollective/webxr-uiextensions';
+/** Extract the yaw (rotation about +Y) from a quaternion [x, y, z, w]. */
+export declare function yawFromQuaternion(q: readonly [number, number, number, number]): number;
+/** Rotate an offset by a yaw angle (about +Y). */
+export declare function rotateOffsetByYaw(offset: Vec3Tuple, yaw: number): Vec3Tuple;
+/** World-space target position for a following window. */
+export declare function followTarget(pose: HeadPose, offset: Vec3Tuple): Vec3Tuple;
+/**
+ * Frame-rate-independent exponential approach: fraction of the remaining
+ * distance to cover this frame, for smoothing speed `speed` (1/s) over
+ * `delta` seconds. 0 when delta/speed are non-positive, approaches 1 for
+ * large steps.
+ */
+export declare function approachAlpha(speed: number, delta: number): number;
+/** Move `current` toward `target` by `alpha`, returning the new position. */
+export declare function approach(current: Vec3Tuple, target: Vec3Tuple, alpha: number): Vec3Tuple;
+/** Squared distance between two points (cheap tolerance checks). */
+export declare function distanceSquared(a: Vec3Tuple, b: Vec3Tuple): number;

package/dist/follow-math.js

@@ -0,0 +1,52 @@
+/** Extract the yaw (rotation about +Y) from a quaternion [x, y, z, w]. */
+export function yawFromQuaternion(q) {
+    const [x, y, z, w] = q;
+    // Yaw of the quaternion's forward vector, projected onto the XZ plane.
+    const forwardX = 2 * (x * z + w * y);
+    const forwardZ = 1 - 2 * (x * x + y * y);
+    return Math.atan2(forwardX, forwardZ);
+}
+/** Rotate an offset by a yaw angle (about +Y). */
+export function rotateOffsetByYaw(offset, yaw) {
+    const sin = Math.sin(yaw);
+    const cos = Math.cos(yaw);
+    const [x, y, z] = offset;
+    return [x * cos + z * sin, y, -x * sin + z * cos];
+}
+/** World-space target position for a following window. */
+export function followTarget(pose, offset) {
+    const rotated = rotateOffsetByYaw(offset, yawFromQuaternion(pose.quaternion));
+    return [
+        pose.position[0] + rotated[0],
+        pose.position[1] + rotated[1],
+        pose.position[2] + rotated[2],
+    ];
+}
+/**
+ * Frame-rate-independent exponential approach: fraction of the remaining
+ * distance to cover this frame, for smoothing speed `speed` (1/s) over
+ * `delta` seconds. 0 when delta/speed are non-positive, approaches 1 for
+ * large steps.
+ */
+export function approachAlpha(speed, delta) {
+    if (!(speed > 0) || !(delta > 0)) {
+        return 0;
+    }
+    return 1 - Math.exp(-speed * delta);
+}
+/** Move `current` toward `target` by `alpha`, returning the new position. */
+export function approach(current, target, alpha) {
+    return [
+        current[0] + (target[0] - current[0]) * alpha,
+        current[1] + (target[1] - current[1]) * alpha,
+        current[2] + (target[2] - current[2]) * alpha,
+    ];
+}
+/** Squared distance between two points (cheap tolerance checks). */
+export function distanceSquared(a, b) {
+    const dx = a[0] - b[0];
+    const dy = a[1] - b[1];
+    const dz = a[2] - b[2];
+    return dx * dx + dy * dy + dz * dz;
+}
+//# sourceMappingURL=follow-math.js.map