@needle-tools/engine 4.14.0 → 4.15.0-next.f391a30

package/src/engine/webcomponents/needle menu/needle-menu-spatial.ts

@@ -302,7 +302,7 @@ export class NeedleSpatialMenu {
             // logoObject.position.y = 1;
             // this._context.scene.add(logoObject);
             const textureLoader = new TextureLoader();
-            textureLoader.load("./include/needle/poweredbyneedle.webp", (texture) => {
+            textureLoader.load("https://cdn.needle.tools/static/branding/poweredbyneedle.webp", (texture) => {
                 if (texture) {
                     onClick.allowModifyUI = false;
                     firstLabel.removeFromParent();
@@ -343,7 +343,11 @@ export class NeedleSpatialMenu {
 
         if (!fontFamily) {
             fontFamily = ThreeMeshUI.FontLibrary.addFontFamily(this.familyName);
-            const normal = fontFamily.addVariant("normal", "normal", "./include/needle/arial-msdf.json", "./include/needle/arial.png") as any as ThreeMeshUI.FontVariant;
+            const normal = fontFamily.addVariant(
+                "normal", 
+                "normal", 
+                "https://cdn.needle.tools/static/fonts/msdf/arial/arial-msdf.json", 
+                "https://cdn.needle.tools/static/fonts/msdf/arial/arial.png") as any as ThreeMeshUI.FontVariant;
             /** @ts-ignore */
             normal?.addEventListener('ready', () => {
                 this.markDirty();

package/src/engine/webcomponents/needle menu/needle-menu.ts

@@ -129,6 +129,7 @@ export class NeedleMenu {
 
     constructor(context: Context) {
         this._menu = NeedleMenuElement.getOrCreate(context.domElement, context);
+        this._menu.ensureInitialized();
         this._context = context;
         this._spatialMenu = new NeedleSpatialMenu(context, this._menu);
         window.addEventListener("message", this.onPostMessage);
@@ -309,8 +310,7 @@ export class NeedleMenu {
 export class NeedleMenuElement extends HTMLElement {
 
     static create() {
-        // https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement#is
-        return document.createElement(elementName, { is: elementName });
+        return document.createElement(elementName);
     }
 
     static getOrCreate(domElement: HTMLElement, context: Context) {
@@ -337,9 +337,13 @@ export class NeedleMenuElement extends HTMLElement {
 
     private _domElement: HTMLElement | null = null;
     private _context: Context | null = null;
+    private _didInitialize = false;
 
     constructor() {
         super();
+    }
+
+    private initializeDom() {
 
         const template = document.createElement('template');
         // TODO: make host full size again and move the buttons to a wrapper so that we can later easily open e.g. foldouts/dropdowns / use the whole canvas space
@@ -795,7 +799,7 @@ export class NeedleMenuElement extends HTMLElement {
 
 
         let context = this._context;
-        // we need to assign it in the timeout because the reference is set *after* the constructor did run
+        // we need to assign it in the timeout because the reference is set *after* the element is initialized
         setTimeout(() => context = this._context);
 
         // watch changes
@@ -864,13 +868,21 @@ export class NeedleMenuElement extends HTMLElement {
         }
     }
 
+    ensureInitialized() {
+        if (!this._didInitialize) {
+            this._didInitialize = true;
+            this.initializeDom();
+        }
+    }
+
     private _sizeChangeInterval;
 
     connectedCallback() {
+        this.ensureInitialized();
         window.addEventListener("resize", this.handleSizeChange);
         this.handleMenuVisible();
         this._sizeChangeInterval = setInterval(() => this.handleSizeChange(undefined, false), 5000);
-        // the dom element is set after the constructor runs
+        // the dom element is set after initialization runs
         setTimeout(() => {
             this._domElement?.addEventListener("resize", this.handleSizeChange);
             this._domElement?.addEventListener("click", this.#onClick);
@@ -958,19 +970,19 @@ export class NeedleMenuElement extends HTMLElement {
 
     // private _root: ShadowRoot | null = null;
     /** @private root container element inside shadow DOM */
-    private readonly root: HTMLDivElement;
+    private root!: HTMLDivElement;
     /** @private wraps the whole content (internal layout) */
-    private readonly wrapper: HTMLDivElement;
+    private wrapper!: HTMLDivElement;
     /** @private contains the buttons and dynamic elements */
-    private readonly options: HTMLDivElement;
+    private options!: HTMLDivElement;
     /** @private contains options visible when in compact mode */
-    private readonly optionsCompactMode: HTMLDivElement;
+    private optionsCompactMode!: HTMLDivElement;
     /** @private contains the needle-logo html element */
-    private readonly logoContainer: HTMLDivElement;
+    private logoContainer!: HTMLDivElement;
     /** @private compact menu button element */
-    private readonly compactMenuButton: HTMLButtonElement;
+    private compactMenuButton!: HTMLButtonElement;
     /** @private foldout container used in compact mode */
-    private readonly foldout: HTMLDivElement;
+    private foldout!: HTMLDivElement;
 
 
     private readonly trackedElements: WeakSet<Node> = new WeakSet();

package/src/engine/webcomponents/needle-button.ts

@@ -13,32 +13,58 @@ const htmlTagName = "needle-button";
 const isDev = isDevEnvironment();
 
 /**
- * A <needle-button> can be used to simply add VR, AR or Quicklook buttons to your website without having to write any code.  
- * @example
+ * [&lt;needle-button&gt;](https://engine.needle.tools/docs/api/NeedleButtonElement) is a web component for easily adding AR, VR, Quicklook, or QR code buttons to your website without writing JavaScript code.
+ *
+ * The button automatically handles session management and displays appropriate UI based on device capabilities.
+ * It comes with default styling (glassmorphism design) but can be fully customized with CSS.
+ *
+ * **Supported button types:**
+ * - `ar` - WebXR AR session button
+ * - `vr` - WebXR VR session button
+ * - `quicklook` - Apple AR Quick Look button (iOS only)
+ * - `qrcode` - QR code sharing button
+ *
+ * @example Basic AR/VR buttons
  * ```html
+ * <needle-engine src="scene.glb"></needle-engine>
  * <needle-button ar></needle-button>
  * <needle-button vr></needle-button>
  * <needle-button quicklook></needle-button>
  * ```
- * 
- * @example custom label
+ *
+ * @example Custom button labels
  * ```html
- * <needle-button ar>Start AR</needle-button>
- * <needle-button vr>Start VR</needle-button>
+ * <needle-button ar>Start AR Experience</needle-button>
+ * <needle-button vr>Enter VR Mode</needle-button>
  * <needle-button quicklook>View in AR</needle-button>
  * ```
- * 
- * @example custom styling
+ *
+ * @example Custom styling
  * ```html
- * <!-- You can either style the element directly or use a CSS stylesheet -->
  * <style>
- * needle-button {
- *    background-color: red;
- *   color: white;
- * }
+ *   needle-button {
+ *     background-color: #ff6b6b;
+ *     color: white;
+ *     border-radius: 8px;
+ *     padding: 1rem 2rem;
+ *   }
+ *   needle-button:hover {
+ *     background-color: #ff5252;
+ *   }
  * </style>
  * <needle-button ar>Start AR</needle-button>
  * ```
+ *
+ * @example Unstyled button (for complete custom styling)
+ * ```html
+ * <needle-button ar unstyled>
+ *   <span class="my-icon">🥽</span>
+ *   Launch AR
+ * </needle-button>
+ * ```
+ *
+ * @see {@link NeedleEngineWebComponent} for the main &lt;needle-engine&gt; element
+ * @see {@link NeedleMenu} for the built-in menu component that can display similar buttons
  */
 export class NeedleButtonElement extends HTMLElement {
 
@@ -73,18 +99,22 @@ export class NeedleButtonElement extends HTMLElement {
         if (this.getAttribute("ar") != null) {
             this.#webxrfactory ??= new WebXRButtonFactory()
             this.#button = this.#webxrfactory.createARButton();
+            this.setAttribute("aria-label", "Enter augmented reality mode");
         }
         else if (this.getAttribute("vr") != null) {
             this.#webxrfactory ??= new WebXRButtonFactory()
             this.#button = this.#webxrfactory.createVRButton();
+            this.setAttribute("aria-label", "Enter virtual reality mode");
         }
         else if (this.getAttribute("quicklook") != null) {
             this.#webxrfactory ??= new WebXRButtonFactory()
             this.#button = this.#webxrfactory.createQuicklookButton();
+            this.setAttribute("aria-label", "View in AR with Apple Quick Look");
         }
         else if (this.getAttribute("qrcode") != null) {
             this.#buttonfactory ??= new ButtonsFactory();
             this.#button = this.#buttonfactory.createQRCode({ anchorElement: this });
+            this.setAttribute("aria-label", "Share application with QR code");
         }
         else {
             if (isDev) {
@@ -93,6 +123,7 @@ export class NeedleButtonElement extends HTMLElement {
             else {
                 console.debug("No button type specified for <needle-button>. Use either ar, vr or quicklook attribute.")
             }
+            this.setAttribute("aria-label", "Needle Button with no specified type");
             return;
         }
 

package/src/engine/webcomponents/needle-engine.ar-overlay.ts

@@ -121,7 +121,7 @@ export class AROverlayHandler {
 
         const quitARSlot = document.createElement("slot");
         quitARSlot.style.display = "contents";
-        quitARSlot.style.padding = "10px"; 
+        quitARSlot.style.padding = "10px";
         quitARSlot.setAttribute("name", "quit-ar");
         this.appendElement(quitARSlot, element);
         this._createdAROnlyElements.push(quitARSlot);
@@ -131,7 +131,16 @@ export class AROverlayHandler {
         // No default quit button in the top right corner in app clips
         // we provide one via the native UI
         if (DeviceUtilities.isNeedleAppClip()) {
-            quitARSlot.style.display = "none";
+
+            // quitARSlot.style.display = "none";
+            globalThis["NEEDLE_ENGINE_APPCLIP_DISABLE_MENU"] = true;
+
+            // respect the UI bar at the top of the screen and add some padding to the quit button container
+            // @TODO: this should be done in CSS in one place and not here and in debug overlay
+            const meta = document.querySelector('meta[name="viewport"]');
+            if (meta && !meta.getAttribute("content")?.includes("viewport-fit=")) {
+                meta.setAttribute("content", meta.getAttribute("content") + ",viewport-fit=cover");
+            }
         }
 
         // We want to search the document if there's a quit-ar button
@@ -155,6 +164,8 @@ export class AROverlayHandler {
             right: 0;
             z-index: 600;
             pointer-events: all;
+            padding-top: env(safe-area-inset-top, 0px);
+            padding-right: calc(env(safe-area-inset-right, 0px) + 10px);
         `;
         this.appendElement(fixedButtonContainer, quitARSlot);
 

package/src/engine/webcomponents/needle-engine.ts

@@ -87,17 +87,25 @@ const observedAttributes = [
 
 // https://developers.google.com/web/fundamentals/web-components/customelements
 
-/** 
- * The `<needle-engine>` web component. See {@link NeedleEngineAttributes} attributes for supported attributes    
- * The web component creates and manages a Needle Engine context, which is responsible for rendering a 3D scene using threejs.   
- * The context is created when the `src` attribute is set, and disposed when the element is removed from the DOM. You can prevent cleanup by setting the `keep-alive` attribute to `true`.  
+/**
+ * The `<needle-engine>` web component. See {@link NeedleEngineAttributes} attributes for supported attributes
+ * The web component creates and manages a Needle Engine context, which is responsible for rendering a 3D scene using threejs.
+ * The context is created when the `src` attribute is set, and disposed when the element is removed from the DOM. You can prevent cleanup by setting the `keep-alive` attribute to `true`.
  * The context is accessible from the `<needle-engine>` element: `document.querySelector("needle-engine").context`.
  * See {@link https://engine.needle.tools/docs/reference/needle-engine-attributes}
  *
- * @example
+ * @example Basic usage
+ * ```html
  * <needle-engine src="https://example.com/scene.glb"></needle-engine>
- * @example
+ * ```
+ *
+ * @example With camera controls disabled
+ * ```html
  * <needle-engine src="https://example.com/scene.glb" camera-controls="false"></needle-engine>
+ * ```
+ *
+ * @see {@link NeedleButtonElement} for adding AR/VR/Quicklook buttons via &lt;needle-button&gt;
+ * @see {@link NeedleMenu} for the built-in menu configuration component
  */
 export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngineComponent {
 
@@ -160,23 +168,36 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
      */
     public get context() { return this._context; }
 
-    private _context: Context;
+    private _context!: Context;
     private _overlay_ar: AROverlayHandler;
     private _loadingProgress01: number = 0;
     private _loadingView?: ILoadingViewHandler;
     private _previousSrc: string | null | string[] = null;
     /** @private set to true after <needle-engine> did load completely at least once. Set to false when < to false when <needle-engine> is removed from the document removed from the document */
     private _didFullyLoad: boolean = false;
+    private _didInitialize = false;
 
     constructor() {
         super();
         this._overlay_ar = new AROverlayHandler();
         // TODO: do we want to rename this event?
         this.addEventListener("ready", this.onReady);
+    }
+
+    private ensureInitialized() {
+        if (!this._didInitialize) {
+            this._didInitialize = true;
+            this.initializeDom();
+        }
+    }
+
+    private initializeDom() {
 
         ensureFonts();
 
-        this.attachShadow({ mode: 'open' });
+        this.attachShadow({ mode: 'open', delegatesFocus: true });
+        this.setAttribute("role", "application");
+        this.setAttribute("aria-label", "Needle Engine 3D scene");
         const template = document.createElement('template');
         // #region CSS
         template.innerHTML = `<style>
@@ -271,6 +292,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
      * @internal
      */
     async connectedCallback() {
+        this.ensureInitialized();
         if (debug) {
             console.log("<needle-engine> connected");
         }
@@ -282,6 +304,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
         if (this.getAttribute("tabindex") === null || this.getAttribute("tabindex") === undefined)
             this.setAttribute("tabindex", "0");
 
+
         this.addEventListener("xr-session-started", this.onXRSessionStarted);
         this.onSetupDesktop();
 

package/src/engine-components/Component.ts

@@ -10,7 +10,7 @@ import * as main from "../engine/engine_mainloop_utils.js";
 import { syncDestroy, syncInstantiate, SyncInstantiateOptions } from "../engine/engine_networking_instantiate.js";
 import { Context, FrameEvent } from "../engine/engine_setup.js";
 import * as threeutils from "../engine/engine_three_utils.js";
-import type { Collision, ComponentInit, Constructor, ConstructorConcrete, GuidsMap, ICollider, IComponent, IGameObject, SourceIdentifier } from "../engine/engine_types.js";
+import { $componentName, type Collision, type ComponentInit, type Constructor, type ConstructorConcrete, type GuidsMap, type ICollider, type IComponent, type IGameObject, type SourceIdentifier } from "../engine/engine_types.js";
 import { TypeStore } from "../engine/engine_typestore.js";
 import type { INeedleXRSessionEventReceiver, NeedleXRControllerEventArgs, NeedleXREventArgs } from "../engine/engine_xr.js";
 import { type IPointerEventHandler, PointerEventData } from "./ui/PointerEvents.js";
@@ -49,7 +49,7 @@ export abstract class GameObject extends Object3D implements Object3D, IGameObje
     abstract activeSelf: boolean;
 
     /** @deprecated Use {@link addComponent} instead */
-    // eslint-disable-next-line deprecation/deprecation
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     abstract addNewComponent<T extends IComponent>(type: ConstructorConcrete<T>, init?: ComponentInit<T>): T;
 
     /** 
@@ -364,7 +364,6 @@ export abstract class GameObject extends Object3D implements Object3D, IGameObje
     }
 
     /** @deprecated use `addComponent` */
-    // eslint-disable-next-line deprecation/deprecation
     public static addNewComponent<T extends IComponent>(go: IGameObject | Object3D, type: T | ConstructorConcrete<T>, init?: ComponentInit<T>, callAwake: boolean = true): T {
         return addComponent(go, type, init, { callAwake });
     }
@@ -542,8 +541,6 @@ export abstract class GameObject extends Object3D implements Object3D, IGameObje
     }
 }
 
-// DO NOT CHANGE THE SYMBOL NAME
-const $componentName = Symbol("component-name");
 
 /** 
  * Needle Engine component's are the main building blocks of the Needle Engine.    

package/src/engine-components/DragControls.ts

@@ -193,7 +193,7 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
             }
         }
     }
-    
+
     private _rigidbody: Rigidbody | null = null;
 
     // future:
@@ -235,12 +235,22 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
     /** @internal */
     onEnable(): void {
         DragControls._instances.push(this);
+        this.context.accessibility.updateElement(this, {
+            role: "button",
+            label: "Drag " + (this.gameObject.name || "object"),
+            hidden: false,
+        });
     }
     /** @internal */
     onDisable(): void {
+        this.context.accessibility.updateElement(this, { hidden: true });
         DragControls._instances = DragControls._instances.filter(i => i !== this);
     }
 
+    onDestroy(): void {
+        this.context.accessibility.removeElement(this);
+    }
+
     /**
      * Checks if editing is allowed for the current networking connection.
      * @param _obj Optional object to check edit permissions for
@@ -268,6 +278,8 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
         if (!dc || dc !== this) return;
         DragControls.lastHovered = evt.object;
         this.context.domElement.style.cursor = 'pointer';
+
+        this.context.accessibility.hover(this, `Draggable ${evt.object?.name}`);
     }
 
     /** 
@@ -339,6 +351,14 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
             }
 
             args.use();
+
+            this.context.accessibility.updateElement(this, {
+                role: "button",
+                label: "Dragging " + (this.gameObject.name || "object"),
+                hidden: false,
+                busy: true,
+            });
+            this.context.accessibility.focus(this);
         }
     }
 
@@ -375,6 +395,11 @@ export class DragControls extends Behaviour implements IPointerEventHandler {
             }
             args.use();
         }
+
+        this.context.accessibility.unfocus(this);
+        this.context.accessibility.updateElement(this, {
+            busy: false,
+        });
     }
 
     /**
@@ -779,12 +804,12 @@ class DragPointerHandler implements IDragHandler {
      * Used for determining if enough motion has occurred to start a drag.
      */
     getTotalMovement(): Vector3 { return this._totalMovement; }
-    
+
     /** 
      * Returns the object that follows the pointer during dragging operations.
      */
     get followObject(): GameObject { return this._followObject; }
-    
+
     /**
      * Returns the point where the pointer initially hit the object in local space.
      */
@@ -1377,7 +1402,7 @@ class LegacyDragVisualsHelper {
 
     /** Controls whether visual helpers like lines and markers are displayed */
     showGizmo: boolean = true;
-    
+
     /** When true, drag plane alignment changes based on view angle */
     useViewAngle: boolean = true;
 

package/src/engine-components/NeedleMenu.ts

@@ -9,8 +9,8 @@ import type { Voip } from './Voip.js';
 /**
  * [NeedleMenu](https://engine.needle.tools/docs/api/NeedleMenu) provides configuration for the built-in UI menu.
  * The menu renders as HTML overlay in browser mode and automatically
- * switches to a 3D spatial menu in VR/AR.    
- * 
+ * switches to a 3D spatial menu in VR/AR.
+ *
  * ![](https://cloud.needle.tools/-/media/YKleg1oPy_I8Hv8sg_k40Q.png)
  *
  * **Features:**
@@ -18,7 +18,7 @@ import type { Voip } from './Voip.js';
  * - Audio mute/unmute button
  * - QR code sharing (desktop only)
  * - Spatial menu in XR (appears when looking up)
- * - Custom positioning (top/bottom)  
+ * - Custom positioning (top/bottom)
  *
  * **Programmatic access:**
  * Access the menu API via `this.context.menu` to add custom buttons,
@@ -36,6 +36,8 @@ import type { Voip } from './Voip.js';
  * @category User Interface
  * @group Components
  * @see {@link Context.menu} for programmatic menu control
+ * @see {@link NeedleButtonElement} for standalone <needle-button> web component
+ * @see {@link NeedleEngineWebComponent} for the main <needle-engine> element
  * @see {@link Voip} adds a microphone button to the menu
  * @see {@link ScreenCapture} adds a screen sharing button
  **/

package/src/engine-components/Networking.ts

@@ -7,10 +7,34 @@ import { Behaviour } from "./Component.js";
 const debug = getParam("debugnet");
 
 /**
- * Provides configuration to the built-in networking system.
- * This component supplies websocket URLs for establishing connections.
- * It implements the {@link INetworkingWebsocketUrlProvider} interface.
- * 
+ * Provides websocket URL configuration for the built-in networking system.
+ * Add this component to override the default networking backend URL used by {@link NetworkConnection} (`this.context.connection`).
+ *
+ * The component registers itself as a URL provider on `awake()`. When the networking system connects,
+ * it queries this provider for the websocket URL to use instead of the default Needle networking backend.
+ *
+ * **URL resolution order:**
+ * 1. If `urlParameterName` is set and the corresponding URL parameter exists in the browser URL, that value is used
+ * 2. If running on a local network and `localhost` is set, the `localhost` URL is used
+ * 3. Otherwise, the `url` field is used
+ *
+ * Without this component, the default backend URL `wss://networking-2.needle.tools/socket` is used.
+ *
+ * **Note:** This component only configures the websocket URL. To actually join a networked room,
+ * use a `SyncedRoom` component or call `this.context.connection.joinRoom("room-name")` directly.
+ *
+ * @example Overriding the URL via browser parameter
+ * ```ts
+ * // With urlParameterName="server", visiting:
+ * // https://myapp.com/?server=wss://my-server.com/socket
+ * // will connect to that server instead
+ * ```
+ *
+ * @see {@link NetworkConnection} for the main networking API (`this.context.connection`)
+ * @see {@link SyncedRoom} for automatic room joining
+ * @see {@link OwnershipModel} for networked object ownership
+ * @see {@link RoomEvents} for room lifecycle events
+ * @link https://engine.needle.tools/docs/how-to-guides/networking/
  * @summary Networking configuration
  * @category Networking
  * @group Components
@@ -20,6 +44,7 @@ export class Networking extends Behaviour implements INetworkingWebsocketUrlProv
     /** 
      * The websocket URL to connect to for networking functionality.
      * Can be a complete URL or a relative path that will be resolved against the current origin.
+     * @default null
      */
     @serializable()
     url: string | null = null;