@needle-tools/engine 4.11.5 → 4.12.0-next.ca2cebd

package/src/engine/engine_types.ts

@@ -566,6 +566,23 @@ export interface IPhysicsEngine {
      */
     boxOverlap(point: Vector3, size: Vector3, rotation: Vector4Like | null): Array<ShapeOverlapResult>;
 
+    /**
+     * Creates a collider in the physics world.
+     * 
+     * @param collider - The collider component.
+     * @param desc - The collider description.
+     * @returns The created collider.
+     * 
+     * @throws Will throw an error if the physics world is not initialized. Make sure to call `initialize()` before creating colliders.
+     * 
+     * @example
+     * ```typescript
+     * const boxColliderDesc = NEEDLE_ENGINE_MODULES.RAPIER_PHYSICS.MODULE.ColliderDesc.cuboid(1, 1, 1);
+     * const collider = physicsEngine.createCollider(myBoxColliderComponent, boxColliderDesc);
+     * ```
+     */
+    createCollider(collider: ICollider, desc: any): any;
+
     // Collider methods
     /**
      * Adds a sphere collider to the physics world

package/src/engine/engine_typestore.ts

@@ -7,6 +7,7 @@ declare type Type = new (...args: any[]) => any;
 class _TypeStore {
 
     private _types: Map<string, Type> = new Map();
+    private _reverseTypes: Map<Type, string> = new Map();
 
     constructor() {
         if (debug) console.warn("TypeStore: Created", this);
@@ -18,8 +19,10 @@ class _TypeStore {
     public add(key: string, type: Type) {
         if (debug) console.warn("ADD TYPE", key);
         const existing = this._types.get(key);
-        if (!existing)
+        if (!existing) {
             this._types.set(key, type);
+            this._reverseTypes.set(type, key);
+        }
         else {
             if (debug) {
                 if (existing !== type) {
@@ -40,11 +43,7 @@ class _TypeStore {
      * @returns the key/name for the given type if registered
      */
     public getKey(type: Type): string | null {
-        for (const [key, value] of this._types) {
-            if (value === type)
-                return key;
-        }
-        return null;
+        return this._reverseTypes.get(type) || null;
     }
 }
 

package/src/engine/webcomponents/logo-element.ts

@@ -2,6 +2,16 @@ import { madeWithNeedleSVG, needleLogoOnlySVG, needleLogoSVG } from "../assets/i
 
 const elementName = "needle-logo-element";
 
+declare global {
+    interface HTMLElementTagNameMap {
+        "needle-logo-element": NeedleLogoElement;
+    }
+}
+
+/**
+ * Needle logo web component used in the hosting UI (small, compact logo or full)
+ * @element needle-logo-element
+ */
 export class NeedleLogoElement extends HTMLElement {
 
     static get elementName() { return elementName; }
@@ -83,10 +93,12 @@ export class NeedleLogoElement extends HTMLElement {
     private readonly wrapper: HTMLDivElement;
     private readonly logoElement: HTMLImageElement;
 
+    /** Show or hide the logo element (used by the menu) */
     setLogoVisible(val: boolean) {
         this.logoElement.style.display = val ? "block" : "none";
     }
 
+    /** Switch the logo between full and compact versions */
     setType(type: "full" | "compact") {
         if (type === "full") {
             this.logoElement.src = needleLogoSVG;

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

@@ -9,6 +9,12 @@ import { getIconElement } from "../icons.js";
 import { NeedleLogoElement } from "../logo-element.js";
 import { NeedleSpatialMenu } from "./needle-menu-spatial.js";
 
+declare global {
+    interface HTMLElementTagNameMap {
+        "needle-logo-element": NeedleLogoElement;
+    }
+}
+
 const elementName = "needle-menu";
 const debug = getParam("debugmenu");
 const debugNonCommercial = getParam("debugnoncommercial");
@@ -264,6 +270,16 @@ export class NeedleMenu {
 
 }
 
+/**
+ * `<needle-menu>` web component — lightweight menu used by Needle Engine.
+ *
+ * This element is intended as an internal UI primitive for hosting application
+ * menus and buttons. Use the higher-level `NeedleMenu` API from the engine
+ * code to manipulate it programmatically. Public DOM-facing methods are
+ * documented (appendChild / append / prepend / setPosition / setVisible).
+ *
+ * @element needle-menu
+ */
 export class NeedleMenuElement extends HTMLElement {
 
     static create() {
@@ -851,6 +867,7 @@ export class NeedleMenuElement extends HTMLElement {
         }
     }
 
+    /** @private user preference for logo visibility */
     private _userRequestedLogoVisible?: boolean = undefined;
     showNeedleLogo(visible: boolean) {
         this._userRequestedLogoVisible = visible;
@@ -891,6 +908,7 @@ export class NeedleMenuElement extends HTMLElement {
         this.root.classList.add(position);
     }
 
+    /** @private user preference for menu visibility */
     private _userRequestedMenuVisible?: boolean = undefined;
     setVisible(visible: boolean) {
         this._userRequestedMenuVisible = visible;
@@ -905,14 +923,17 @@ export class NeedleMenuElement extends HTMLElement {
     }
 
     // private _root: ShadowRoot | null = null;
+    /** @private root container element inside shadow DOM */
     private readonly root: HTMLDivElement;
-    /** wraps the whole content */
+    /** @private wraps the whole content (internal layout) */
     private readonly wrapper: HTMLDivElement;
-    /** contains the buttons and dynamic elements */
+    /** @private contains the buttons and dynamic elements */
     private readonly options: HTMLDivElement;
-    /** contains the needle-logo html element */
+    /** @private contains the needle-logo html element */
     private readonly logoContainer: HTMLDivElement;
+    /** @private compact menu button element */
     private readonly compactMenuButton: HTMLButtonElement;
+    /** @private foldout container used in compact mode */
     private readonly foldout: HTMLDivElement;
 
     append(...nodes: (string | Node)[]): void {

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

@@ -2,6 +2,12 @@ import { isDevEnvironment } from "../debug/index.js";
 import { iconFontUrl, loadFont } from "./fonts.js";
 import { WebXRButtonFactory } from "./WebXRButtons.js";
 
+declare global {
+    interface HTMLElementTagNameMap {
+        "needle-button": NeedleButtonElement;
+    }
+}
+
 const htmlTagName = "needle-button";
 const isDev = isDevEnvironment();
 

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

@@ -9,13 +9,21 @@ import { NeedleLoader } from "../engine_loaders.js";
 import { Context, ContextCreateArgs } from "../engine_setup.js";
 import { nameToThreeTonemapping } from "../engine_tonemapping.js";
 import { type INeedleEngineComponent, type LoadedModel } from "../engine_types.js";
+import type { addAttributeChangeCallback } from "../engine_utils.js";
 import { getParam } from "../engine_utils.js";
 import { RGBAColor } from "../js-extensions/RGBAColor.js";
 import { ensureFonts } from "./fonts.js";
 import { arContainerClassName, AROverlayHandler } from "./needle-engine.ar-overlay.js";
-import { NeedleEngineAttributes, TonemappingAttributeOptions } from "./needle-engine.attributes.js";
+import type { registerObservableAttribute} from "./needle-engine.extras.js";
 import { calculateProgress01, EngineLoadingView, type ILoadingViewHandler } from "./needle-engine.loading.js";
 
+declare global {
+    interface HTMLElementTagNameMap {
+        "needle-engine": NeedleEngineWebComponent;
+    }
+}
+
+
 // registering loader here too to make sure it's imported when using engine via vanilla js
 registerLoader(NeedleLoader);
 
@@ -28,44 +36,69 @@ const knownClasses = [arContainerClassName, vrContainerClassName, desktopContain
 const arSessionActiveClassName = "ar-session-active";
 const desktopSessionActiveClassName = "desktop-session-active";
 
+type TonemappingAttributeOptions = "none" | "linear" | "neutral" | "agx";
+
+// #region Observables
+
+/** Keep in sync with the overloads and docs here:
+ * - {@link NeedleEngineWebComponent.setAttribute}
+ * - {@link NeedleEngineWebComponent.getAttribute} 
+ * - {@link NeedleEngineWebComponent.addEventListener} 
+ * - Docs in {@link [custom-elements.json](../../../custom-elements.json)}
+ * - {@link NeedleEngineWebComponent.attributeChangedCallback}  
+ * 
+ * Effectively, attributes used with these methods are also observable:
+ * -  {@link registerObservableAttribute} or 
+ * -  {@link addAttributeChangeCallback}
+ * */
 const observedAttributes = [
-    "public-key",
-    "version",
-
-    "hash",
+    // MainAttributes
     "src",
+    "hash",
     "camera-controls",
-    "loadstart",
-    "progress",
-    "loadfinished",
-
     "dracoDecoderPath",
     "dracoDecoderType",
     "ktx2DecoderPath",
 
+    // keep-alive: effectively observed because read when needed
+
+    // private
+    "public-key",
+    "version",
+
+    // RenderingAttributes
     "tone-mapping",
     "tone-mapping-exposure",
     "background-blurriness",
     "background-color",
     "environment-intensity",
+    // background-image: registered in Skybox.ts
+    // environment-image: registered in Skybox.ts
 
+    // scene: registered in SceneSwitcher.ts
+    // clickthrough: registered in Clickthrough.ts
     "focus-rect",
+
+    // Events
+    "loadstart",
+    "progress",
+    "loadfinished",
 ]
 
 // https://developers.google.com/web/fundamentals/web-components/customelements
 
 /** 
- * <needle-engine> web component. See {@link NeedleEngineAttributes} attributes for supported attributes    
- * The needle engine web component creates and manages a needle engine context which is responsible for rendering a 3D scene using threejs.   
- * The needle engine context is created when the src attribute is set and disposed when the needle engine is removed from the document (you can prevent this by setting the keep-alive attribute to true).  
- * The needle engine context is accessible via the context property on the needle engine element (e.g. document.querySelector("needle-engine").context).
+ * 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
  * <needle-engine src="https://example.com/scene.glb"></needle-engine>
  * @example
  * <needle-engine src="https://example.com/scene.glb" camera-controls="false"></needle-engine>
-*/
+ */
 export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngineComponent {
 
     static get observedAttributes() {
@@ -90,7 +123,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
      * @returns {boolean | null} if the attribute is not set it returns null
      */
     get cameraControls(): boolean | null {
-        const attr = this.getAttribute("camera-controls") as NeedleEngineAttributes["camera-controls"] | ({} & string)
+        const attr = this.getAttribute("camera-controls") as string;
         if (attr == null) return null;
         if (attr === null || attr === "False" || attr === "false" || attr === "0" || attr === "none") return false;
         return true;
@@ -100,7 +133,6 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
         else this.setAttribute("camera-controls", value ? "true" : "false");
     }
 
-
     /**
      * Get the current context for this web component instance. The context is created when the src attribute is set and the loading has finished.  
      * The context is disposed when the needle engine is removed from the document (you can prevent this by setting the keep-alive attribute to true).  
@@ -133,7 +165,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
     private _loadingProgress01: number = 0;
     private _loadingView?: ILoadingViewHandler;
     private _previousSrc: string | null | string[] = null;
-    /** set to true after <needle-engine> did load completely at least once. Set to false when <needle-engine> is removed from the document */
+    /** @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;
 
     constructor() {
@@ -146,6 +178,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
 
         this.attachShadow({ mode: 'open' });
         const template = document.createElement('template');
+        // #region CSS
         template.innerHTML = `<style>
     @import url('https://fonts.googleapis.com/css2?family=Roboto+Flex:opsz,wght@8..144,100..1000&display=swap');
 
@@ -224,6 +257,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
     <slot class="overlay-content"></slot>
 </div>
 `;
+        // #endregion
 
         if (this.shadowRoot)
             this.shadowRoot.appendChild(template.content.cloneNode(true));
@@ -252,7 +286,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
         this.onSetupDesktop();
 
         if (!this.getAttribute("src")) {
-            const global = globalThis["needle:codegen_files"] as unknown as string;
+            const global = (globalThis as any)["needle:codegen_files"] as unknown as string;
             if (debug) console.log("src is null, trying to load from globalThis[\"needle:codegen_files\"]", global);
             if (global) {
                 if (debug) console.log("globalThis[\"needle:codegen_files\"]", global);
@@ -296,6 +330,11 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
         }
     }
 
+    connectedMoveCallback() {
+        // we dont want needle-engine to cleanup JUST because the element is moved in the DOM. See https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks
+    }
+
+    // #region attributeChanged
     /**
      * @internal
      */
@@ -317,7 +356,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
             case "loadfinished":
                 if (typeof newValue === "string" && newValue.length > 0) {
                     if (debug) console.log(name + " attribute changed", newValue);
-                    this.registerEventFromAttribute(name, newValue);
+                    this.registerEventFromAttribute("loadfinished", newValue);
                 }
                 break;
             case "dracoDecoderPath":
@@ -441,7 +480,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
         if (allowOverridingDefaultLoading) {
             // Handle the <needle-engine hide-loading-overlay> attribute
             const hideOverlay = this.getAttribute("hide-loading-overlay");
-            if (hideOverlay !== null && hideOverlay !== undefined && hideOverlay !== "0") {
+            if (hideOverlay !== null && hideOverlay !== undefined && (hideOverlay as any) !== "0") {
                 useDefaultLoading = false;
             }
         }
@@ -555,6 +594,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
         }));
     }
 
+    // #region applyAttributes
     private applyAttributes() {
         // set tonemapping if configured
         if (this._context?.renderer) {
@@ -668,7 +708,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
         if (attributeValue)
             this.registerEventFromAttribute("loadstart", attributeValue);
     }
-    private registerEventFromAttribute(eventName: string, code: string) {
+    private registerEventFromAttribute(eventName: 'loadfinished' | 'loadstart', code: string) {
         const prev = this._previouslyRegisteredMap.get(eventName);
         if (prev) {
             this._previouslyRegisteredMap.delete(eventName);
@@ -681,6 +721,7 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
                 // const fn = new Function(newValue);
                 if (typeof fn === "function") {
                     this._previouslyRegisteredMap.set(eventName, fn);
+                    // @ts-ignore // not sure how to type this properly
                     this.addEventListener(eventName, evt => fn?.call(globalThis, this._context, evt));
                 }
             }
@@ -828,15 +869,283 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
             setKtx2TranscoderPath(customKtx2DecoderPath);
         }
     }
+
+    // #region setAttribute
+
+    // MainAttributes
+    /** Change which model gets loaded. This will trigger a reload of the scene. 
+     * @example src="path/to/scene.glb"
+     * @example src="[./path/scene1.glb, myOtherScene.gltf]"
+     * */
+    setAttribute(name: 'src', value: string): void;
+    /** Optional. String attached to the context for caching/identification. */
+    setAttribute(name: 'hash', value: string): void;
+    /** Set to automatically add {@link OrbitControls} to the loaded scene */
+    setAttribute(name: 'camera-controls', value: string): void;
+    /** Override the default draco decoder path location. */
+    setAttribute(name: 'dracoDecoderPath', value: string): void;
+    /** Override the default draco library type. */
+    setAttribute(name: 'dracoDecoderType', value: 'wasm' | 'js'): void;
+    /** Override the default KTX2 transcoder/decoder path */
+    setAttribute(name: 'ktx2DecoderPath', value: string): void;
+    /** Prevent Needle Engine context from being disposed when the element is removed from the DOM */
+    setAttribute(name: 'keep-alive', value: 'true' | 'false'): void;
+    
+    /** @private Public key used for licensing and feature gating. */
+    setAttribute(name: 'public-key', value: string): void;
+    /** @private Engine version string — usually set by the build/runtime. */
+    setAttribute(name: 'version', value: string): void;
+
+    // LoadingAttributes
+    // ...
+    
+    // SkyboxAttributes
+    /** URL to .exr, .hdr, .png, .jpg to be used as skybox */
+    setAttribute(name: 'background-image', value: string): void;
+    /** @private Rotation of the background image in degrees. */
+    setAttribute(name: 'background-rotation', value: string | number): void;
+    /** @deprecated Use 'environment-image' instead. */
+    setAttribute(name: 'skybox-image', value: string): void;
+    /** URL to .exr, .hdr, .png, .jpg to be used for lighting */
+    setAttribute(name: 'environment-image', value: string): void;
+    /** Intensity multiplier for environment lighting. */
+    setAttribute(name: 'environment-intensity', value: string): void;
+    /** Blurs the background image. Strength between 0 (sharp) and 1 (fully blurred). */
+    setAttribute(name: 'background-blurriness', value: string): void;
+    /** Intensity multiplier for the background image. */
+    setAttribute(name: 'background-intensity', value: string): void;
+    /**
+     * CSS background color value to be used if no skybox or background image is provided.
+     * @example "background-color='#ff0000'" will set the background color to red.
+     */
+    setAttribute(name: 'background-color', value: string): void;
+    
+    // RenderingAttributes
+    /** Enable/disable renderer canvas transparency. */
+    setAttribute(name: 'transparent', value: 'true' | 'false'): void;
+    /** Enable/disable contact shadows in the rendered scene */
+    setAttribute(name: 'contact-shadows', value: 'true' | 'false'): void;
+    /** Tonemapping mode. */
+    setAttribute(name: 'tone-mapping', value: TonemappingAttributeOptions): void;
+    /** Exposure multiplier for tonemapping. */
+    setAttribute(name: 'tone-mapping-exposure', value: string): void;
+
+    /** Defines a CSS selector or HTMLElement where the camera should be focused on. Content will be fit into this element. */
+    setAttribute(name: 'focus-rect', value: string | HTMLElement): void;
+    /** Allow pointer events to pass through transparent parts of the content to the underlying DOM elements. */
+    setAttribute(name: 'clickthrough', value: 'true' | 'false'): void;
+    /** Automatically fits the model into the camera view on load. */
+    setAttribute(name: 'auto-fit', value: 'true' | 'false'): void;
+    /** Automatically rotates the model until a user interacts with the scene. */
+    setAttribute(name: 'auto-rotate', value: 'true' | 'false'): void;
+    /** Play animations automatically on scene load */
+    setAttribute(name: "autoplay", value: 'true' | 'false'): void;
+    /** @private Used for switching the scene in SceneSwitcher */
+    setAttribute(name: 'scene', value: string): void;
+    
+    // setAttribute(name: 'loadstart', value: string): void;
+    
+    /** @private Experimental.*/
+    setAttribute(name: 'loading-blur', value: 'true' | 'false'): void;
+    /** @private */
+    setAttribute(name: 'alias', value: string): void;
+    /** @private */
+    setAttribute(name: 'hide-loading-overlay', value: 'true' | 'false'): void;
+    /** @private */
+    setAttribute(name: 'no-telemetry', value: 'true' | 'false'): void;
+
+    /** Generic typed setter for known Needle Engine attributes */
+    // Comment out to see errors inside NE for undocumented attributes
+    // setAttribute<T extends keyof NeedleEngineAttributes>(qualifiedName: T, value: NeedleEngineAttributes[T]): void;
+    
+    setAttribute(qualifiedName: ({} & string), value: string): void;
+    
+    // The ones we're using internally:
+    /*
+    setAttribute(name: "tabindex", value: string): void;
+    */
+    setAttribute(qualifiedName: string, value: string): void {
+        super.setAttribute(qualifiedName, value);
+    }
+
+    // #region getAttribute
+
+    // MainAttributes
+    /** Change which model gets loaded. This will trigger a reload of the scene. 
+     * @example src="path/to/scene.glb"
+     * @example src="[./path/scene1.glb, myOtherScene.gltf]"
+     * */
+    getAttribute(name: 'src'): string | null;
+    /** Optional. String attached to the context for caching/identification. */
+    getAttribute(name: 'hash'): string | null;
+    /** Set to automatically add {@link OrbitControls} to the loaded scene */
+    getAttribute(name: 'camera-controls'): "true" | "false" | "none" | null;
+    /** Override the default draco decoder path location. */
+    getAttribute(name: 'dracoDecoderPath'): string | null;
+    /** Override the default draco library type. */
+    getAttribute(name: 'dracoDecoderType'): "wasm" | "js" | null;
+    /** Override the default KTX2 transcoder/decoder path */
+    getAttribute(name: 'ktx2DecoderPath'): string | null;
+    /** Prevent Needle Engine context from being disposed when the element is removed from the DOM */
+    getAttribute(name: 'keep-alive'): string | null;
+    
+    /** @private Public key used for licensing and feature gating. */
+    getAttribute(name: 'public-key'): string | null;
+    /** @private Engine version string — usually set by the build/runtime. */
+    getAttribute(name: 'version'): string | null;
+
+    // LoadingAttributes
+    // ...
+
+    // SkyboxAttributes
+    /** URL to .exr, .hdr, .png, .jpg to be used as skybox */
+    getAttribute(name: 'background-image'): string | null;
+    /** @private Rotation of the background image in degrees. */
+    getAttribute(name: 'background-rotation'): string | null;
+    /** URL to .exr, .hdr, .png, .jpg to be used for lighting */
+    getAttribute(name: 'environment-image'): string | null;
+    /** Intensity multiplier for environment lighting. */
+    getAttribute(name: 'environment-intensity'): string | null;
+    /** Blurs the background image. Strength between 0 (sharp) and 1 (fully blurred). */
+    getAttribute(name: 'background-blurriness'): string | null;
+    /** Intensity multiplier for the background image. */
+    getAttribute(name: 'background-intensity'): string | null;
+    /**
+     * CSS background color value to be used if no skybox or background image is provided.
+     * @example "background-color='#ff0000'" will set the background color to red.
+     */
+    getAttribute(name: 'background-color'): string | null;
+
+    // RenderingAttributes
+    /** Enable/disable renderer canvas transparency. */
+    getAttribute(name: 'transparent'): string | null;
+    /** Enable/disable contact shadows in the rendered scene */
+    getAttribute(name: 'contact-shadows'): string | null;
+    /** @deprecated Use 'contact-shadows' instead. */
+    getAttribute(name: 'contactshadows'): string | null;
+    /** Tonemapping mode. */
+    getAttribute(name: 'tone-mapping'): TonemappingAttributeOptions | null;
+    /** @deprecated Use 'tone-mapping' instead. */
+    getAttribute(name: 'tonemapping'): TonemappingAttributeOptions | null;
+    /** Exposure multiplier for tonemapping. */
+    getAttribute(name: 'tone-mapping-exposure'): string | null;
+
+    /** Defines a CSS selector or HTMLElement where the camera should be focused on. Content will be fit into this element. */
+    getAttribute(name: 'focus-rect'): string | null;
+    /** Allow pointer events to pass through transparent parts of the content to the underlying DOM elements. */
+    getAttribute(name: 'clickthrough'): string | null;
+    /** Automatically fits the model into the camera view on load. */
+    getAttribute(name: 'auto-fit'): string | null;
+    /** @deprecated Use 'auto-fit' instead. */
+    getAttribute(name: 'autofit'): string | null;
+    /** Automatically rotates the model until a user interacts with the scene. */
+    getAttribute(name: 'auto-rotate'): string | null;
+    /** Play animations automatically on scene load */
+    getAttribute(name: "autoplay"): string | null;
+    /** @private Used for switching the scene in SceneSwitcher */
+    getAttribute(name: 'scene'): string | null;
+    // getAttribute(name: 'loadstart'): string | null;
+
+    /** @private Experimental.*/
+    getAttribute(name: 'loading-blur'): string | null;
+    /** @private */
+    getAttribute(name: 'alias'): string | null;
+    /** @private */
+    getAttribute(name: 'hide-loading-overlay'): string | null;
+    /** @private */
+    getAttribute(name: 'no-telemetry'): string | null;
+
+    // Comment these out to get development errors for undocumented NE attributes
+    /** Typed getter for known NeedleEngine attribute names; returns the typed shape declared in NeedleEngineAttributes or null. */
+    // getAttribute<T extends keyof NeedleEngineAttributes>(qualifiedName: T): NeedleEngineAttributes[T] | null;
+    getAttribute(qualifiedName: ({} & string)): string | null;
+    
+    // The ones we're using interally:
+    /*
+    getAttribute(name: "autostart"): string | null;
+    getAttribute(name: "tabindex"): string | null;
+    */
+    
+    getAttribute(qualifiedName: string): string | null {
+        return super.getAttribute(qualifiedName);
+    }
+
+    // #region addEventListener
+
+    /**
+     * Emitted when loading begins for the scene. The event is cancelable — calling `preventDefault()` 
+     * will stop the default loading UI behavior, so apps can implement custom loading flows.
+     */
+    addEventListener(type: 'loadstart', listener: (ev: CustomEvent<{ context: Context; alias: string | null }>) => void, options?: boolean | AddEventListenerOptions): void;
+    /** Emitted repeatedly while loading resources. Use the event detail to show progress. */
+    addEventListener(type: 'progress', listener: (ev: CustomEvent<{ context: Context; name: string; progress: ProgressEvent<EventTarget>; index: number; count: number; totalProgress01: number }>) => void, options?: boolean | AddEventListenerOptions): void;
+    /** Emitted when scene loading has finished. */
+    addEventListener(type: 'loadfinished', listener: (ev: CustomEvent<{ context: Context; src: string | null; loadedFiles: LoadedModel[] }>) => void, options?: boolean | AddEventListenerOptions): void;
+    /** Emitted when an XR session ends. */
+    addEventListener(type: 'xr-session-ended', listener: (ev: CustomEvent<{ session: XRSession | null; context: Context; sessionMode: XRSessionMode | undefined }>) => void, options?: boolean | AddEventListenerOptions): void;
+    /** Emitted when entering an AR session. */
+    addEventListener(type: 'enter-ar', listener: (ev: CustomEvent<{ session: XRSession; context: Context; htmlContainer: HTMLElement | null }>) => void, options?: boolean | AddEventListenerOptions): void;
+    /** Emitted when exiting an AR session. */
+    addEventListener(type: 'exit-ar', listener: (ev: CustomEvent<{ session: XRSession; context: Context; htmlContainer: HTMLElement | null }>) => void, options?: boolean | AddEventListenerOptions): void;
+    /** Emitted when entering a VR session. */
+    addEventListener(type: 'enter-vr', listener: (ev: CustomEvent<{ session: XRSession; context: Context }>) => void, options?: boolean | AddEventListenerOptions): void;
+    /** Emitted when exiting a VR session. */
+    addEventListener(type: 'exit-vr', listener: (ev: CustomEvent<{ session: XRSession; context: Context }>) => void, options?: boolean | AddEventListenerOptions): void;
+    /** Emitted when the engine has rendered its first frame and is ready. */
+    addEventListener(type: 'ready', listener: (ev: Event) => void, options?: boolean | AddEventListenerOptions): void;
+    /** Emitted when an XR session is started. You can do additional setup here. */
+    addEventListener(type: 'xr-session-started', listener: (ev: CustomEvent<{ session: XRSession; context: Context }>) => void, options?: boolean | AddEventListenerOptions): void;
+
+    // Sadly not enough to make types work (see comment below)
+    addEventListener<K extends keyof HTMLElementEventMap>(type: ({} & K), listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions): void;
+    // These are from the super type. Not sure how we can remove intellisense for the "regular" events while still making the types work...
+    addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+    // This would be better but doesn't completely solve it
+    // addEventListener(type: ({} & string), listener: any, options?: boolean | AddEventListenerOptions): void;
+    
+    // The ones we're using interally:
+    /* 
+    addEventListener(type: "error", listener: (ev: ErrorEvent) => void, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: "wheel", listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: "keydown", listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: "drop", listener: (ev: DragEvent) => void, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: "dragover", listener: (ev: DragEvent) => void, options?: boolean | AddEventListenerOptions): void;
+    */
+    addEventListener(type: string, listener: any, options?: boolean | AddEventListenerOptions): void
+    {
+        return super.addEventListener(type, listener as EventListenerOrEventListenerObject, options);
+    }
 }
 
 if (typeof window !== "undefined" && !window.customElements.get(htmlTagName))
     window.customElements.define(htmlTagName, NeedleEngineWebComponent);
 
+/** Quick testing for the types as declared above */
+/*
+const elem = document.querySelector("needle-engine")!;
+elem.setAttribute("src", "model.glb");
+elem.addEventListener("loadfinished", (ev) => {
+    const context = ev.detail.context;
+});
+elem.setAttribute("dracoDecoderType", "wasm");
+elem.addEventListener("enter-ar", (ev) => {
+    const session = ev.detail.session;
+});
 
+elem.addEventListener("mousedown", (ev) => {
+    console.log("regular mousedown event", ev);
+});
 
+const onDragOverEvent = (e: DragEvent) => {
 
+};
 
+elem.addEventListener("dragover", onDragOverEvent);
+*/
+/* END Type testing */
+
+// #region Utility functions
 
 function getDisplayName(str: string) {
     if (str.startsWith("blob:")) {
@@ -956,4 +1265,4 @@ function handleLoadingBlur(needleEngineElement: NeedleEngineWebComponent) {
             }
         }
     }, { once: true });
-}
+}