@needle-tools/engine 4.14.0-next.b2e3b1a → 4.15.0-next.cecd8e7

package/lib/engine/api.js

@@ -1,86 +1,339 @@
 /**
- * Contains core functionality for Needle Engine.
- * This includes
- * - Context Management
- * - Asset Loading
- * - Component Lifecycle
- * - Time Handling
- * - XR support
- * - Unified Input Handling
- * - Needle Menu
- * - Networking
- * - Physics, Collisions, Raycasting
- * - Math and Filtering Helpers
- * - Rendering Utilities
- * - Debugging Utilities, Gizmos
- * - User agent detection
- * - and more.
+ * The Engine Core API is the main entry point for Needle Engine functionality.
+ * It provides a unified interface for building interactive 3D web experiences
+ * with features spanning rendering, physics, networking, XR, and more.
+ *
+ * ## Quick Start
+ * ```typescript
+ * import { Context, Behaviour, serializable } from "@needle-tools/engine";
+ *
+ * class MyComponent extends Behaviour {
+ *     @serializable()
+ *     speed: number = 1;
+ *
+ *     update() {
+ *         this.gameObject.rotateY(this.context.time.deltaTime * this.speed);
+ *     }
+ * }
+ * ```
+ *
+ * ## Module Categories
+ *
+ * ### Context & Application
+ * The {@link Context} class is the central hub that manages the scene, renderer, camera,
+ * and all engine systems. Access it via `this.context` in any component.
+ * - {@link Context} - Main engine context managing scene, renderer, and systems
+ * - {@link ContextRegistry} - Registry for multiple engine contexts
+ * - {@link Application} - Application-level utilities and state
+ *
+ * ### Components & GameObjects
+ * Needle Engine uses a component-based architecture similar to Unity.
+ * Components are attached to three.js Object3D instances (GameObjects).
+ * - {@link addComponent}, {@link getComponent}, {@link removeComponent} - Component management
+ * - {@link findObjectOfType}, {@link findObjectsOfType} - Scene queries
+ * - {@link instantiate}, {@link destroy} - Object lifecycle
+ * @see {@link https://engine.needle.tools/docs/scripting.html | Scripting Documentation}
+ *
+ * ### Asset Loading
+ * Load glTF/GLB files, textures, and other assets at runtime.
+ * - {@link loadSync}, {@link parseSync} - Load glTF/GLB assets
+ * - {@link AssetDatabase} - Asset reference management
+ * - {@link Addressables} - Addressable asset system
+ * @see {@link https://engine.needle.tools/docs/addressables.html | Addressables Documentation}
+ *
+ * ### Input System
+ * Unified input handling for mouse, touch, keyboard, and XR controllers.
+ * Access via `this.context.input` in components.
+ * - {@link Input} - Unified input manager
+ * - {@link NEPointerEvent} - Cross-platform pointer events
+ * - {@link InputEvents} - Event types for input listeners
+ * @see {@link https://engine.needle.tools/docs/input.html | Input Documentation}
+ *
+ * ### Physics & Raycasting
+ * Rapier-based physics engine with collision detection and raycasting.
+ * - {@link Physics} - Physics world access and raycasting
+ * - {@link RaycastOptions} - Configure raycast behavior
+ * - {@link Collision}, {@link ContactPoint} - Collision data types
+ * @see {@link https://engine.needle.tools/docs/physics.html | Physics Documentation}
+ *
+ * ### Networking
+ * Real-time multiplayer networking with automatic state synchronization.
+ * - {@link NetworkConnection} - WebSocket connection management
+ * - {@link RoomEvents} - Room join/leave events
+ * - {@link syncField} - Decorator for automatic field synchronization
+ * - {@link PeerNetworking} - WebRTC peer-to-peer connections
+ * @see {@link https://engine.needle.tools/docs/networking.html | Networking Documentation}
+ *
+ * ### XR (AR/VR)
+ * WebXR support for augmented and virtual reality experiences.
+ * - {@link NeedleXRSession} - XR session management
+ * - {@link NeedleXRController} - XR controller input and tracking
+ * - {@link XRRig} - XR camera rig configuration
+ * @see {@link https://engine.needle.tools/docs/xr.html | XR Documentation}
+ *
+ * ### Time & Animation
+ * Frame timing and animation utilities.
+ * - {@link Time} - Delta time, frame count, time scale
+ * - {@link AnimationUtils} - Animation playback helpers
+ * - Coroutines via {@link startCoroutine} for async sequences
+ *
+ * ### Debugging & Gizmos
+ * Visual debugging tools for development.
+ * - {@link Gizmos} - Draw debug shapes (lines, spheres, boxes)
+ * - {@link showBalloonMessage}, {@link showBalloonWarning} - On-screen messages
+ * - {@link isDevEnvironment} - Check if running in development mode
+ *
+ * ### Utilities
+ * Helper functions for common operations.
+ * - {@link getParam} - URL parameter parsing
+ * - {@link delay} - Promise-based delay
+ * - {@link generateQRCode} - QR code generation
+ * - Math utilities: {@link Mathf}, vector operations
  *
  * @module Engine Core
+ * @see {@link https://engine.needle.tools/docs/ | Needle Engine Documentation}
  */
+// ============================================================================
+// DEBUGGING & DEVELOPMENT
+// Debugging utilities, gizmos, and development tools.
+// ============================================================================
 export * from "./debug/index.js";
+// ============================================================================
+// ASSET LOADING & MANAGEMENT
+// Systems for loading, managing, and referencing assets at runtime.
+// ============================================================================
+/** Addressable asset system for loading assets by address/label */
 export * from "./engine_addressables.js";
+/** Animation playback and control utilities */
 export { AnimationUtils } from "./engine_animation.js";
+/** Application-level state and utilities */
 export { Application } from "./engine_application.js";
+/** Asset database for managing asset references */
 export * from "./engine_assetdatabase.js";
+// ============================================================================
+// CAMERA & RENDERING
+// Camera control, rendering utilities, and visual effects.
+// ============================================================================
+/** Camera fitting utilities for framing objects */
 export * from "./engine_camera.fit.js";
+/** Camera controller management and auto-fit configuration */
 export { getCameraController, setAutoFitEnabled, setCameraController, useForAutoFit } from "./engine_camera.js";
+// ============================================================================
+// COMPONENTS & GAMEOBJECTS
+// Component-based architecture for building interactive 3D content.
+// Functions for adding, removing, and querying components on objects.
+// ============================================================================
+/**
+ * Component management functions: addComponent, getComponent, removeComponent, etc.
+ * @see {@link https://engine.needle.tools/docs/scripting.html | Scripting Documentation}
+ */
 export * from "./engine_components.js";
+/** Internal component lifecycle events and management */
 export * from "./engine_components_internal.js";
-export * from "./engine_components_internal.js";
+/** Engine constants and configuration values */
 export * from "./engine_constants.js";
+// ============================================================================
+// CONTEXT & LIFECYCLE
+// Core engine context and application lifecycle management.
+// ============================================================================
+/**
+ * Main engine context class - the central hub for all engine systems.
+ * Provides access to scene, renderer, camera, input, physics, networking, and more.
+ * @see {@link https://engine.needle.tools/docs/scripting.html#context | Context Documentation}
+ */
 export * from "./engine_context.js";
+/** Registry for managing multiple engine contexts */
 export * from "./engine_context_registry.js";
+/**
+ * Coroutine system for async sequences in components.
+ * Use startCoroutine() for frame-based async operations.
+ */
 export * from "./engine_coroutine.js";
+/** Factory functions for creating primitives and objects */
 export * from "./engine_create_objects.js";
+/** Feature flags for enabling/disabling engine features */
 export * from "./engine_feature_flags.js";
+/**
+ * GameObject utilities: instantiate, destroy, find, traverse.
+ * @see {@link https://engine.needle.tools/docs/scripting.html#finding-objects | Finding Objects}
+ */
 export * from "./engine_gameobject.js";
+/**
+ * Visual debugging with Gizmos - draw lines, spheres, boxes for debugging.
+ * @see {@link https://engine.needle.tools/docs/debugging.html | Debugging Documentation}
+ */
 export { Gizmos } from "./engine_gizmos.js";
+/** glTF/GLB loader registration and management */
 export * from "./engine_gltf.js";
+/** Hot reload support for development */
 export * from "./engine_hot_reload.js";
+// ============================================================================
+// INPUT SYSTEM
+// Unified input handling for mouse, touch, keyboard, and XR controllers.
+// ============================================================================
+/**
+ * Unified input system supporting mouse, touch, keyboard, and XR controllers.
+ * Access via this.context.input in components.
+ * @see {@link https://engine.needle.tools/docs/input.html | Input Documentation}
+ */
 export * from "./engine_input.js";
+// ============================================================================
+// INSTANCING & PERFORMANCE
+// GPU instancing and performance optimization utilities.
+// ============================================================================
+/** GPU instancing utilities for rendering many similar objects efficiently */
 export { InstancingUtil } from "./engine_instancing.js";
+/** License checking utilities */
 export { hasCommercialLicense, hasIndieLicense, hasProLicense } from "./engine_license.js";
+// ============================================================================
+// LIFECYCLE & LOADING
+// Component lifecycle hooks and asset loading systems.
+// ============================================================================
+/** Lifecycle API for registering global callbacks */
 export * from "./engine_lifecycle_api.js";
+/** Model loader callbacks for customizing load behavior */
 export { NeedleEngineModelLoader } from "./engine_loaders.callbacks.js";
+/**
+ * Asset loading functions: loadSync, parseSync for glTF/GLB files.
+ * @see {@link https://engine.needle.tools/docs/addressables.html | Loading Assets}
+ */
 export { loadAsset, loadSync, parseSync } from "./engine_loaders.js";
+// ============================================================================
+// MATERIALS & RENDERING
+// Material utilities and rendering helpers.
+// ============================================================================
+/** MaterialPropertyBlock for efficient material property overrides per-instance */
 export { MaterialPropertyBlock } from "./engine_materialpropertyblock.js";
+/** Math utilities: Mathf, interpolation, easing functions */
 export * from "./engine_math.js";
+/** Engine modules registry */
 export { MODULES as NEEDLE_ENGINE_MODULES } from "./engine_modules.js";
+// ============================================================================
+// NETWORKING
+// Real-time multiplayer networking with WebSocket and WebRTC support.
+// ============================================================================
+/**
+ * Core networking: NetworkConnection, RoomEvents, OwnershipEvent.
+ * @see {@link https://engine.needle.tools/docs/networking.html | Networking Documentation}
+ */
 export * from "./engine_networking.js";
+/**
+ * @syncField decorator for automatic field synchronization across clients.
+ * @see {@link https://engine.needle.tools/docs/networking.html#synced-variables | Synced Variables}
+ */
 export { syncField } from "./engine_networking_auto.js";
+/** Blob/binary data transfer over network */
 export * from "./engine_networking_blob.js";
+/** File transfer utilities for networking */
 export * from "./engine_networking_files.js";
+/**
+ * Network instantiation for spawning synced objects.
+ * @see {@link https://engine.needle.tools/docs/networking.html#spawning-objects | Spawning Objects}
+ */
 export * from "./engine_networking_instantiate.js";
+/** WebRTC peer-to-peer networking for direct client connections */
 export * from "./engine_networking_peer.js";
+/** Media streaming utilities (audio/video) */
 export * from "./engine_networking_streams.js";
+/** Networking type definitions and interfaces */
 export * from "./engine_networking_types.js";
+/** Networking utility functions */
 export * from "./engine_networking_utils.js";
+// ============================================================================
+// PHYSICS & RAYCASTING
+// Rapier-based physics simulation and raycasting.
+// ============================================================================
+/** Object patching utilities */
 export * from "./engine_patcher.js";
+/**
+ * Physics system: raycasting, collision queries, physics world access.
+ * @see {@link https://engine.needle.tools/docs/physics.html | Physics Documentation}
+ */
 export * from "./engine_physics.js";
+/** Physics type definitions: RaycastOptions, Collision, ContactPoint */
 export * from "./engine_physics.types.js";
+/** Rapier physics engine integration */
 export * from "./engine_physics_rapier.js";
+// ============================================================================
+// PLAYER & VIEW MANAGEMENT
+// Multi-player view management and scene lighting.
+// ============================================================================
+/** Player view management for multi-user scenarios */
 export * from "./engine_playerview.js";
+/** PMREM (Prefiltered Mipmapped Radiance Environment Map) loading */
 export { loadPMREM } from "./engine_pmrem.js";
+/** Scene lighting data and environment configuration */
 export * from "./engine_scenelighting.js";
+// ============================================================================
+// SERIALIZATION
+// Component serialization for saving/loading and networking.
+// ============================================================================
+/**
+ * Serialization utilities for components and objects.
+ * @see {@link https://engine.needle.tools/docs/scripting.html#serialization | Serialization Documentation}
+ */
 export * from "./engine_serialization.js";
+// ============================================================================
+// UTILITIES & HELPERS
+// General-purpose utility functions and helpers.
+// ============================================================================
+/** Testing utilities for automated tests */
 export * from "./engine_test_utils.js";
+/** Texture utilities and processing */
 export * from "./engine_texture.js";
+/** Three.js helper utilities: getWorldPosition, getTempVector, etc. */
 export * from "./engine_three_utils.js";
+/**
+ * Time class: deltaTime, time, frameCount, timeScale.
+ * Access via this.context.time in components.
+ */
 export * from "./engine_time.js";
+/** Time-related utility functions */
 export * from "./engine_time_utils.js";
+/** Core type definitions and interfaces */
 export * from "./engine_types.js";
+/** Type registration for component discovery */
 export { registerType, TypeStore } from "./engine_typestore.js";
+/** Decorator utilities: @prefix, @validate */
 export { prefix, validate } from "./engine_util_decorator.js";
+/** General utilities: getParam, delay, DeviceUtilities, etc. */
 export * from "./engine_utils.js";
+/** Formatting utilities for strings and numbers */
 export * from "./engine_utils_format.js";
+/** QR code generation utility */
 export { generateQRCode } from "./engine_utils_qrcode.js";
+/** Screenshot capture utilities */
 export * from "./engine_utils_screenshot.js";
+// ============================================================================
+// EXTENSIONS & INTEGRATIONS
+// glTF extensions and JavaScript object extensions.
+// ============================================================================
+/** Export utilities and formats */
 export * from "./export/index.js";
+/** glTF extension implementations (NEEDLE_components, etc.) */
 export * from "./extensions/index.js";
+/** JavaScript object extensions for three.js objects */
 export * from "./js-extensions/index.js";
+// ============================================================================
+// WEB COMPONENTS
+// Custom HTML elements for embedding Needle Engine.
+// ============================================================================
+/** Web component API utilities */
 export * from "./webcomponents/api.js";
+/**
+ * <needle-engine> web component for embedding 3D scenes.
+ * @see {@link https://engine.needle.tools/docs/html.html | HTML Integration}
+ */
 export * from "./webcomponents/needle-engine.js";
+/** Loading screen and progress indicators */
 export * from "./webcomponents/needle-engine.loading.js";
+// ============================================================================
+// XR (AR/VR)
+// WebXR support for augmented and virtual reality experiences.
+// ============================================================================
+/**
+ * XR API: NeedleXRSession, NeedleXRController, XRRig.
+ * @see {@link https://engine.needle.tools/docs/xr.html | XR Documentation}
+ */
 export * from "./xr/api.js";
 //# sourceMappingURL=api.js.map

package/lib/engine/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/engine/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAChH,cAAc,wBAAwB,CAAC;AACvC,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC;AAChD,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uBAAuB,CAAA;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAA;AACzC,cAAc,wBAAwB,CAAC;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAC3C,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC3F,cAAc,2BAA2B,CAAC;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AACxE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAA;AACzE,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,OAAO,IAAI,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACvE,cAAc,wBAAwB,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACxD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oCAAoC,CAAC;AACnD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAE1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC9D,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAA;AACtC,cAAc,kCAAkC,CAAC;AACjD,cAAc,0CAA0C,CAAC;AACzD,cAAc,aAAa,CAAA"}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/engine/api.ts"],"names":[],"mappings":"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"}

package/lib/engine/engine_accessibility.d.ts

@@ -0,0 +1,77 @@
+import { Object3D } from "three";
+import type { Context } from "./engine_setup";
+import { IComponent } from "./engine_types.js";
+/** Data describing the accessible semantics for a 3D object or component. */
+type AccessibilityData = {
+    /** ARIA role (e.g. `"button"`, `"img"`, `"region"`). */
+    role: string;
+    /** Human-readable label announced by screen readers. */
+    label: string;
+    /** When `true`, the element is hidden from the accessibility tree. */
+    hidden?: boolean;
+    /** When `true`, indicates the element's content is being updated. */
+    busy?: boolean;
+};
+/**
+ * Manages an accessible, screen-reader-friendly overlay for a Needle Engine {@link Context}.
+ *
+ * The manager maintains a visually-hidden DOM tree that mirrors relevant 3D scene objects
+ * with appropriate ARIA roles and labels. It also provides a live region so that hover
+ * events in the 3D scene can be announced to assistive technology without stealing focus.
+ *
+ * ## Automatic integration
+ * Several built-in components register accessible elements automatically:
+ * - {@link DragControls} — announces draggable objects and drag state
+ * - {@link Button} — exposes UI buttons to the accessibility tree
+ * - {@link Text} — exposes UI text content to screen readers
+ * - {@link ChangeTransformOnClick} — announces clickable transform actions
+ * - {@link ChangeMaterialOnClick} — announces clickable material changes
+ * - {@link EmphasizeOnClick} — announces clickable emphasis effects
+ * - {@link PlayAudioOnClick} — announces clickable audio playback
+ * - {@link PlayAnimationOnClick} — announces clickable animation triggers
+ *
+ * ## What this unlocks
+ * - Hovering over buttons and interactive objects with the cursor announces them to screen readers via an ARIA live region — no focus steal required
+ * - Screen readers can discover and navigate interactive 3D objects in the scene
+ * - Drag operations update the accessibility state (busy, label changes) in real time
+ * - Custom components can participate by calling {@link updateElement}, {@link focus}, and {@link hover}
+ *
+ * Access the manager via `this.context.accessibility` from any component.
+ */
+export declare class AccessibilityManager {
+    private readonly context;
+    private static readonly _managers;
+    /** Returns the {@link AccessibilityManager} associated with the given context or component. */
+    static get(obj: Context | IComponent): AccessibilityManager | undefined;
+    constructor(context: Context);
+    private _enabled;
+    /** Enables or disables the accessibility overlay. When disabled, the overlay DOM is removed. */
+    set enabled(value: boolean);
+    /** Removes all tracked accessibility elements, keeping only the live region. */
+    clear(): void;
+    /** Removes the overlay from the DOM and unregisters this manager from the context. */
+    dispose(): void;
+    private readonly root;
+    private readonly liveRegion;
+    private readonly treeElements;
+    /**
+     * Creates or updates the accessible DOM element for a 3D object or component.
+     * @param obj - The scene object or component to represent.
+     * @param data - Partial accessibility data (role, label, hidden, busy) to apply.
+     */
+    updateElement<T extends Object3D | IComponent>(obj: T, data: Partial<AccessibilityData>): void;
+    /** Moves keyboard focus to the accessible element representing the given object. */
+    focus<T extends Object3D | IComponent>(obj: T): void;
+    /** Removes keyboard focus from the accessible element representing the given object. */
+    unfocus<T extends Object3D | IComponent>(obj: T): void;
+    /**
+     * Announces a hover event to screen readers via the ARIA live region.
+     * @param obj - The hovered object (used to look up its label if `text` is not provided).
+     * @param text - Optional text to announce. Falls back to the element's `aria-label`.
+     */
+    hover<T extends Object3D | IComponent>(obj: T, text?: string): void;
+    /** Removes the accessible DOM element for the given object and stops tracking it. */
+    removeElement(obj: Object3D | IComponent): void;
+    private set liveRegionMode(value);
+}
+export {};

package/lib/engine/engine_accessibility.js

@@ -0,0 +1,162 @@
+import { isComponent } from "./engine_types.js";
+/**
+ * Manages an accessible, screen-reader-friendly overlay for a Needle Engine {@link Context}.
+ *
+ * The manager maintains a visually-hidden DOM tree that mirrors relevant 3D scene objects
+ * with appropriate ARIA roles and labels. It also provides a live region so that hover
+ * events in the 3D scene can be announced to assistive technology without stealing focus.
+ *
+ * ## Automatic integration
+ * Several built-in components register accessible elements automatically:
+ * - {@link DragControls} — announces draggable objects and drag state
+ * - {@link Button} — exposes UI buttons to the accessibility tree
+ * - {@link Text} — exposes UI text content to screen readers
+ * - {@link ChangeTransformOnClick} — announces clickable transform actions
+ * - {@link ChangeMaterialOnClick} — announces clickable material changes
+ * - {@link EmphasizeOnClick} — announces clickable emphasis effects
+ * - {@link PlayAudioOnClick} — announces clickable audio playback
+ * - {@link PlayAnimationOnClick} — announces clickable animation triggers
+ *
+ * ## What this unlocks
+ * - Hovering over buttons and interactive objects with the cursor announces them to screen readers via an ARIA live region — no focus steal required
+ * - Screen readers can discover and navigate interactive 3D objects in the scene
+ * - Drag operations update the accessibility state (busy, label changes) in real time
+ * - Custom components can participate by calling {@link updateElement}, {@link focus}, and {@link hover}
+ *
+ * Access the manager via `this.context.accessibility` from any component.
+ */
+export class AccessibilityManager {
+    context;
+    static _managers = new WeakMap();
+    /** Returns the {@link AccessibilityManager} associated with the given context or component. */
+    static get(obj) {
+        if (isComponent(obj)) {
+            return this._managers.get(obj.context);
+        }
+        else {
+            return this._managers.get(obj);
+        }
+    }
+    constructor(context) {
+        this.context = context;
+        this.root.style.cssText = `
+            position: absolute;
+            width: 1px; height: 1px;
+            padding: 0; margin: -1px;
+            overflow: hidden;
+            clip: rect(0, 0, 0, 0);
+            white-space: nowrap;
+            border: 0;
+        `;
+        this.root.setAttribute("role", "region");
+        this.root.setAttribute("aria-label", "3D Needle Engine scene");
+        // Live region for announcing hovered 3D elements without stealing focus
+        this.liveRegion.setAttribute("aria-live", "polite");
+        this.liveRegion.setAttribute("aria-atomic", "true");
+        this.liveRegion.setAttribute("role", "status");
+        this.root.appendChild(this.liveRegion);
+        this.enabled = true;
+    }
+    _enabled;
+    /** Enables or disables the accessibility overlay. When disabled, the overlay DOM is removed. */
+    set enabled(value) {
+        if (value === this._enabled)
+            return;
+        this._enabled = value;
+        if (!value) {
+            this.root.remove();
+        }
+        else {
+            AccessibilityManager._managers.set(this.context, this);
+            const target = this.context.domElement.shadowRoot || this.context.domElement;
+            target.prepend(this.root);
+        }
+    }
+    /** Removes all tracked accessibility elements, keeping only the live region. */
+    clear() {
+        this.root.childNodes.forEach(child => child.remove());
+        this.root.appendChild(this.liveRegion);
+    }
+    /** Removes the overlay from the DOM and unregisters this manager from the context. */
+    dispose() {
+        this.root.remove();
+        AccessibilityManager._managers.delete(this.context);
+    }
+    root = document.createElement("div");
+    liveRegion = document.createElement("div");
+    treeElements = new WeakMap();
+    /**
+     * Creates or updates the accessible DOM element for a 3D object or component.
+     * @param obj - The scene object or component to represent.
+     * @param data - Partial accessibility data (role, label, hidden, busy) to apply.
+     */
+    updateElement(obj, data) {
+        let el = this.treeElements.get(obj);
+        if (!el) {
+            el = document.createElement("div");
+            this.treeElements.set(obj, el);
+            this.root.appendChild(el);
+            let didSetRole = false;
+            if (typeof data === "object") {
+                if (data.role) {
+                    didSetRole = true;
+                    el.setAttribute("role", data.role);
+                }
+                if (data.label) {
+                    el.setAttribute("aria-label", data.label);
+                }
+                if (data.hidden !== undefined) {
+                    el.setAttribute("aria-hidden", String(data.hidden));
+                }
+                if (data.busy !== undefined) {
+                    el.setAttribute("aria-busy", String(data.busy));
+                }
+            }
+            // if (didSetRole) {
+            //     const role = el.getAttribute("role");
+            //     if (role) {
+            //         el.setAttribute("tabindex", "0");
+            //     } else {
+            //         el.removeAttribute("tabindex");
+            //     }
+            // }
+        }
+    }
+    /** Moves keyboard focus to the accessible element representing the given object. */
+    focus(obj) {
+        const el = this.treeElements.get(obj);
+        if (el) {
+            // if (!el.hasAttribute("tabindex")) {
+            //     el.setAttribute("tabindex", "0");
+            // }
+            el.focus();
+        }
+    }
+    /** Removes keyboard focus from the accessible element representing the given object. */
+    unfocus(obj) {
+        const el = this.treeElements.get(obj);
+        if (el) {
+            el.blur();
+        }
+    }
+    /**
+     * Announces a hover event to screen readers via the ARIA live region.
+     * @param obj - The hovered object (used to look up its label if `text` is not provided).
+     * @param text - Optional text to announce. Falls back to the element's `aria-label`.
+     */
+    hover(obj, text) {
+        const el = this.treeElements.get(obj);
+        // Update the live region text — screen reader announces this without stealing focus
+        this.liveRegion.textContent = text || el?.getAttribute("aria-label") || "";
+    }
+    /** Removes the accessible DOM element for the given object and stops tracking it. */
+    removeElement(obj) {
+        const el = this.treeElements.get(obj);
+        el?.remove();
+        this.treeElements.delete(obj);
+    }
+    set liveRegionMode(mode) {
+        this.liveRegion.setAttribute("aria-live", mode);
+    }
+}
+//# sourceMappingURL=engine_accessibility.js.map

package/lib/engine/engine_accessibility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine_accessibility.js","sourceRoot":"","sources":["../../src/engine/engine_accessibility.ts"],"names":[],"mappings":"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"}

package/lib/engine/engine_components.d.ts

@@ -2,7 +2,7 @@ import { Object3D, Scene } from "three";
 import type { ComponentInit, Constructor, ConstructorConcrete, IComponent } from "./engine_types.js";
 export declare function removeComponent<T extends IComponent>(go: Object3D, componentInstance: T): T;
 export declare function getOrAddComponent<T extends IComponent>(go: Object3D, typeName: ConstructorConcrete<T>, init?: ComponentInit<T>): T;
-export declare function addNewComponent<T extends IComponent>(obj: Object3D, componentInstance: T, callAwake?: boolean, register?: boolean): T;
+export declare function addNewComponent<T extends IComponent>(obj: Object3D, componentInstance: T, callAwake?: boolean): T;
 export declare function addComponent<T extends IComponent>(obj: Object3D, componentInstance: T | ConstructorConcrete<T>, init?: ComponentInit<T>, opts?: {
     callAwake: boolean;
 }): T;