@needle-tools/engine 4.15.0-next.f391a30 → 4.16.0-next.0798cbb

package/plugins/vite/reload.js

@@ -15,14 +15,14 @@ const filesUsingHotReload = new Set();
 let assetsDirectory = "";
 
 /**
- * @param {string} command
+ * @param {"build" | "serve"} command
  * @param {import('../types').userSettings | null} config
  * @param {import('../types').userSettings} userSettings
  */
 export const needleReload = (command, config, userSettings) => {
-    if (command === "build") return;
+    if (command === "build") return undefined;
 
-    if (userSettings?.noReload === true) return;
+    if (userSettings?.noReload === true) return undefined;
 
 
     let isUpdatingConfig = false;
@@ -31,7 +31,7 @@ export const needleReload = (command, config, userSettings) => {
         isUpdatingConfig = true;
         const res = await loadConfig();
         isUpdatingConfig = false;
-        if (res) config = res;
+        if (res) config = /** @type {import('../types').userSettings} */ (res);
     }
 
     const projectConfig = tryLoadProjectConfig();
@@ -54,11 +54,12 @@ export const needleReload = (command, config, userSettings) => {
         config(config) {
             if (!config.server) config.server = { watch: { ignored: [] } };
             else if (!config.server.watch) config.server.watch = { ignored: [] };
-            else if (!config.server.watch.ignored) config.server.watch.ignored = [];
+            else if (!config.server.watch?.ignored) config.server.watch.ignored = [];
             for (const pattern of ignorePatterns)
+                // @ts-ignore - watch.ignored is guaranteed to be string[] by the guards above
                 config.server.watch.ignored.push(pattern);
-            if (config?.debug === true || userSettings?.debug === true)
-                setTimeout(() => needleLog("needle-reload", "Updated server ignore patterns: " + JSON.stringify(config.server.watch.ignored)), 100);
+            if (userSettings?.debug === true)
+                setTimeout(() => needleLog("needle-reload", "Updated server ignore patterns: " + JSON.stringify(config.server?.watch?.ignored)), 100);
         },
         /** @param {{file: string, server: import('vite').ViteDevServer, modules: unknown[], read: (file?: string) => Promise<string>, buildDirectory?: string}} args */
         handleHotUpdate(args) {
@@ -67,10 +68,10 @@ export const needleReload = (command, config, userSettings) => {
         },
         /** @param {string} src @param {string} id */
         transform(src, id) {
-            if (!id.includes(".ts")) return;
+            if (!id.includes(".ts")) return undefined;
             updateConfig();
-            if (config?.allowHotReload === false) return;
-            if (userSettings?.allowHotReload === false) return;
+            if (config?.allowHotReload === false) return undefined;
+            if (userSettings?.allowHotReload === false) return undefined;
             src = insertScriptRegisterHotReloadCode(src, id);
             return insertScriptHotReloadCode(src, id);
         },
@@ -118,24 +119,25 @@ function notifyClientWillReload(server, file) {
 
 /**
  * @param {{file: string, server: import('vite').ViteDevServer, modules: unknown[], read: (file?: string) => Promise<string>, buildDirectory?: string}} param0
+ * @returns {Promise<any>}
  */
-async function handleReload({ file, server, modules, read, buildDirectory }) {
+async function handleReload({ file, server, modules: _modules, read, buildDirectory }) {
 
     // dont reload the full page on css changes
     const isCss = file.endsWith(".css") || file.endsWith(".scss") || file.endsWith(".sass")
-    if (isCss) return;
+    if (isCss) return null;
 
     // Dont reload the whole server when a file that is using hot reload changes
     if (filesUsingHotReload.has(file)) {
         console.log("File is using hot reload: " + file);
-        return;
+        return null;
     }
 
     // the poster is generated after the server has started
     // we dont want to specifically handle the png or webp that gets generated
-    if (file.includes(posterPath)) return;
+    if (file.includes(posterPath)) return null;
 
-    if (file.endsWith("build.log")) return;
+    if (file.endsWith("build.log")) return null;
 
     // if (file.endsWith("/codegen/register_types.js" || file.endsWith("/generated/register_types.js"))) {
     //     console.log("Ignore change in codegen file: " + file);
@@ -178,24 +180,25 @@ async function handleReload({ file, server, modules, read, buildDirectory }) {
     // these are known file types we export from integrations
     const knownExportFileTypes = [ ".glb", ".gltf", ".bin", "exr", ".ktx2", ".mp3", ".ogg", ".mp4", ".webm" ];
     if (!knownExportFileTypes.some((type) => file.endsWith(type)))
-        return;
+        return null;
 
     // we only care about exports into "assets"
     if (!path.resolve(file).startsWith(assetsDirectory))
-        return;
+        return null;
 
     if (file.endsWith(".svelte") || file.endsWith(".vue") || file.endsWith(".ts") || file.endsWith(".js") || file.endsWith(".jsx") || file.endsWith(".tsx"))
-        return;
+        return null;
 
-    if (file.endsWith(lockFileName)) return;
-    let fileSize = "";
+    if (file.endsWith(lockFileName)) return null;
+    /** @type {number} */
+    let fileSize = 0;
     const isGlbOrGltfFile = file.endsWith(".glb") || file.endsWith(".bin");
     if (isGlbOrGltfFile && existsSync(file)) {
         fileSize = statSync(file).size;
         // the file is about to be created/written to
         if (fileSize <= 0) {
             // console.log("> File is changing: " + getFileNameLog(file));
-            return;
+            return null;
         }
     }
 
@@ -307,8 +310,8 @@ const HOT_RELOAD_END_MARKER = "NEEDLE_HOT_RELOAD_END";
 
 /** @param {string} src @param {string} filePath @returns {{code: string, map: null} | undefined} */
 function insertScriptHotReloadCode(src, filePath) {
-    if (filePath.includes("engine_hot_reload")) return;
-    if (filePath.includes(".vite")) return;
+    if (filePath.includes("engine_hot_reload")) return undefined;
+    if (filePath.includes(".vite")) return undefined;
 
     const originalFilePath = filePath;
 
@@ -326,7 +329,7 @@ function insertScriptHotReloadCode(src, filePath) {
     if (filePath.includes("@needle-tools/engine")) {
         // only make engine components hot reloadable
         if (!filePath.includes("engine/engine-components"))
-            return;
+            return undefined;
         // make import path from engine package
         const fullPathToHotReload = process.cwd() + "/node_modules/@needle-tools/engine/src/engine/engine_hot_reload.ts";
         // console.log(fullPathToHotReload);

package/src/asap/needle-asap.ts

@@ -15,7 +15,7 @@ let needleEngineElement: HTMLElement | null = null;
 startup();
 handleSessionGrantedASAP({ debug });
 
-function startup(iteration: number = 0): number | undefined {
+function startup(iteration: number = 0): ReturnType<typeof setTimeout> | undefined {
 
 
     needleEngineElement = document.querySelector("needle-engine");

package/src/engine/debug/debug.ts

@@ -1,6 +1,6 @@
 import { isLocalNetwork } from "../engine_networking_utils.js";
 import { getParam } from "../engine_utils.js";
-import { addLog, clearMessages, LogType, setAllowBalloonMessages, setAllowOverlayMessages } from "./debug_overlay.js";
+import { addLog, BalloonOptions, clearMessages, LogType, setAllowBalloonMessages, setAllowOverlayMessages } from "./debug_overlay.js";
 
 export {
     clearMessages as clearBalloonMessages,
@@ -15,18 +15,19 @@ export { enableSpatialConsole } from "./debug_spatial_console.js";
 
 const noDevLogs = getParam("nodevlogs");
 
+
 /** Displays a debug message on screen for a certain amount of time */
-export function showBalloonMessage(text: string, logType: LogType = LogType.Log): void {
-    addLog(logType, text);
+export function showBalloonMessage(text: string, options?: Partial<BalloonOptions>): void {
+    addLog(options?.type ?? LogType.Log, text, options);
 }
 
 /** Displays a warning message on screen for a certain amount of time */
-export function showBalloonWarning(text: string): void {
-    showBalloonMessage(text, LogType.Warn);
+export function showBalloonWarning(text: string, options?: Partial<BalloonOptions>): void {
+    showBalloonMessage(text, { ...options, type: LogType.Warn });
 }
 /** Displays an error message on screen for a certain amount of time */
-export function showBalloonError(text: string): void {
-    showBalloonMessage(text, LogType.Error);
+export function showBalloonError(text: string, options?: Partial<BalloonOptions>): void {
+    showBalloonMessage(text, { ...options, type: LogType.Error });
 }
 
 let _manuallySetDevEnvironment: boolean | undefined;

package/src/engine/debug/debug_overlay.ts

@@ -13,6 +13,21 @@ export enum LogType {
     Warn,
     Error
 }
+export type BalloonOptions = {
+    type: LogType,
+    /**
+     * A key can be used to update an existing message instead of showing a new one.
+     */
+    key?: string,
+    /**
+     * If true, only show this message once. If the same message is logged again, it will be ignored. Note that messages are considered the same if their text is identical, so using this with dynamic values might lead to unexpected results.
+     */
+    once?: boolean,
+    /** 
+     * Duration in seconds for how long the message should be shown. By default, messages will be shown for 10 seconds.
+     */
+    duration?: number,
+}
 
 export function getErrorCount() {
     return _errorCount;
@@ -42,7 +57,7 @@ const originalConsoleError = console.error;
 const patchedConsoleError = function (...args: any[]) {
     originalConsoleError.apply(console, args);
     onParseError(args);
-    addLog(LogType.Error, args, null, null);
+    addLog(LogType.Error, args, {}, null, null);
     onReceivedError(...args);
 }
 
@@ -74,14 +89,14 @@ export function makeErrorsVisibleForDevelopment() {
                 console.warn("Received unknown error", event, event.target);
             return;
         }
-        addLog(LogType.Error, message, event.filename, event.lineno);
+        addLog(LogType.Error, message, {}, event.filename, event.lineno);
         onReceivedError(event);
     }, true);
     window.addEventListener("unhandledrejection", (event) => {
         if (hide) return;
         if (!event) return;
         if (event.reason)
-            addLog(LogType.Error, event.reason.message, event.reason.stack);
+            addLog(LogType.Error, event.reason.message, {}, event.reason.stack);
         else
             addLog(LogType.Error, "unhandled rejection");
         onReceivedError(event);
@@ -107,8 +122,30 @@ function onParseError(args: Array<any>) {
     }
 }
 
-export function addLog(type: LogType, message: string | any[], _file?: string | null, _line?: number | null) {
+const seen = new Set<string>();
+
+export function addLog(type: LogType, message: string | any[], opts: Omit<BalloonOptions, "type"> = {}, _file?: string | null, _line?: number | null) {
     if (hide) return;
+
+    if (opts.once === true) {
+        let key = "";
+        if (Array.isArray(message)) {
+            for (let i = 0; i < message.length; i++) {
+                let msgPart = message[i];
+                if (msgPart instanceof Error) {
+                    msgPart = msgPart.message;
+                }
+                if (typeof msgPart === "object") continue;
+                if (i > 0) key += " ";
+                key += msgPart;
+            }
+        } else if (typeof message === "string") {
+            key = message;
+        }
+        if (seen.has(key)) return;
+        seen.add(key);
+    }
+
     const context = ContextRegistry.Current;
     let domElement = context?.domElement ?? document.querySelector("needle-engine");
     // check if we're in webxr dom overlay
@@ -130,7 +167,7 @@ export function addLog(type: LogType, message: string | any[], _file?: string |
         message = newMessage;
     }
     if (!message || message.length <= 0) return;
-    showMessage(type, domElement, message);
+    showMessage(type, domElement, message, opts);
 }
 
 // function getLocation(err: Error): string {
@@ -147,10 +184,13 @@ export function addLog(type: LogType, message: string | any[], _file?: string |
 /**
  * 
  */
-const currentMessages = new Map<string, Function>();
-
+const currentMessages = new Map<string, {
+    update: (newText: string, opts: Omit<BalloonOptions, "type">) => void,
+    removeFunction: () => void,
+}>();
+const minDuration = .2; // minimum duration in seconds for messages to be shown, to prevent flicker
 
-function showMessage(type: LogType, element: HTMLElement, msg: string | null | undefined) {
+function showMessage(type: LogType, element: HTMLElement, msg: string | null | undefined, opts: Omit<BalloonOptions, "type"> = {}) {
     if (msg === null || msg === undefined) return;
 
     const container = getLogsContainer(element);
@@ -161,9 +201,11 @@ function showMessage(type: LogType, element: HTMLElement, msg: string | null | u
     // truncate long messages before they go into the cache/set
     if (msg.length > 400) msg = msg.substring(0, 400) + "...";
 
-    const key = msg;
+    const key = opts.key ?? msg;
 
     if (currentMessages.has(key)) {
+        const existing = currentMessages.get(key);
+        existing?.update(msg, opts);
         return;
     }
 
@@ -174,9 +216,21 @@ function showMessage(type: LogType, element: HTMLElement, msg: string | null | u
         currentMessages.delete(key);
         returnMessageContainer(msgcontainer);
     };
-    currentMessages.set(key, removeFunction);
+    
+    let timeout = setTimeout(removeFunction, (Math.max(minDuration, opts.duration ?? 10)) * 1000);
+    
+    currentMessages.set(key, {
+        update: (newText, newOpts) => {
+            if (newText.length > 400) newText = newText.substring(0, 400) + "...";
+            msgcontainer.innerHTML = newText;
+            if (newOpts.duration) {
+                clearTimeout(timeout);
+                timeout = setTimeout(removeFunction, Math.max(minDuration, newOpts.duration) * 1000);
+            }
+        },
+        removeFunction
+    });
 
-    setTimeout(removeFunction, 10_000);
 }
 
 /**
@@ -185,7 +239,7 @@ function showMessage(type: LogType, element: HTMLElement, msg: string | null | u
 export function clearMessages() {
     if (debug) console.log("Clearing messages");
     for (const cur of currentMessages.values()) {
-        cur?.call(cur);
+        cur?.removeFunction.call(cur);
     }
     currentMessages.clear();
 }

package/src/engine/debug/debug_spector.ts

@@ -29,7 +29,7 @@ export function initSpectorIfAvailable(_context: Context, canvas: HTMLCanvasElem
             waitForFrameAndCapture();
             return;
 
-            function waitForFrameAndCapture() {
+            function waitForFrameAndCapture(): number | void {
                 if (frame > _context.time.frame) return window.requestAnimationFrame(() => waitForFrameAndCapture());
                 const res = spector.captureCanvas(canvas);
                 if (res && res instanceof Promise) res.then(() => spector.displayUI());

package/src/engine/engine_addressables.ts

@@ -328,12 +328,20 @@ export class AssetReference {
     }
 
     // TODO: we need a way to abort loading a resource
-    /** Loads the asset and creates one instance (assigned to `asset`)
-     * @returns the loaded asset
+    /** Loads the asset and returns a single shared instance (assigned to {@link asset}).
+     * Calling this multiple times will **not** create additional instances — it returns the same `Object3D`.
+     * To create a new independent clone, use {@link instantiate} instead.
+     * @param prog Optional progress callback invoked during download.
+     * @returns The loaded root `Object3D`, or `null` if loading fails.
      */
     async loadAssetAsync(prog?: ProgressCallback | null): Promise<Object3D | null> {
         if (debug) console.log("[AssetReference] loadAssetAsync", this.url);
-        if (!this.mustLoad) return this.asset;
+        if (!this.mustLoad) {
+            if (this.asset?.parent) {
+                console.warn(`[AssetReference] "${this.urlName}" is already loaded and parented to "${this.asset.parent.name || "scene"}". loadAssetAsync() returns the same shared instance — use .instantiate() to create a new copy.`);
+            }
+            return this.asset;
+        }
 
         if (prog) this._progressListeners.push(prog);
 

package/src/engine/engine_application.ts

@@ -29,13 +29,6 @@ document.addEventListener('touchend', internalOnUserInputRegistered);
 document.addEventListener('keydown', internalOnUserInputRegistered);
 
 
-declare global {
-    interface Navigator {
-        userActivation?: {
-            isActive: boolean;
-        };
-    }
-}
 // User Activation should be available across browsers since November 2023 https://developer.mozilla.org/en-US/docs/Web/API/UserActivation
 if (typeof window !== "undefined" && "userActivation" in navigator && navigator.userActivation?.isActive) {
     if (isDevEnvironment()) console.debug("[Needle Engine] User input already active: Media playback is now allowed.");

package/src/engine/engine_context.ts

@@ -1424,7 +1424,7 @@ export class Context implements IContext {
 			catch (err) {
 				this._renderlooperrors += 1;
 				if ((isDevEnvironment() || debug) && (err instanceof Error || err instanceof TypeError))
-					showBalloonMessage(`Caught unhandled exception during render-loop - see console for details.`, LogType.Error);
+					showBalloonMessage(`Caught unhandled exception during render-loop - see console for details.`, { type: LogType.Error });
 				console.error("Frame #" + this.time.frame + "\n", err);
 				if (this._renderlooperrors >= 3) {
 					console.warn("Stopping render loop due to error")

package/src/engine/engine_gltf_builtin_components.ts

@@ -280,7 +280,7 @@ async function onCreateBuiltinComponents(context: SerializationContext, obj: Obj
         console.warn(`Unknown components in scene: ${unknown}`);
         unknownComponentsBuffer.length = 0;
         if (isLocalNetwork())
-            showBalloonMessage(`<strong>Unknown components in scene</strong>:\n\n${unknown}\n\nThis could mean you forgot to add a npmdef to your ExportInfo\n<a href="https://engine.needle.tools/docs/project_structure.html#creating-and-installing-a-npmdef" target="_blank">documentation</a>`, LogType.Warn);
+            showBalloonMessage(`<strong>Unknown components in scene</strong>:\n\n${unknown}\n\nThis could mean you forgot to add a npmdef to your ExportInfo\n<a href="https://engine.needle.tools/docs/project_structure.html#creating-and-installing-a-npmdef" target="_blank">documentation</a>`, { type: LogType.Warn });
     }
 }
 

package/src/engine/engine_loaders.ts

@@ -102,10 +102,13 @@ async function onCreateLoader(url: string, context: Context, sourceId: SourceIde
 }
 
 /**
- * Load a 3D model file from a remote URL
- * @param url URL to glTF, FBX or OBJ file
- * @param options
- * @returns A promise that resolves to the loaded model or undefined if the loading failed
+ * Load a 3D model file from a URL (glTF, glb, FBX, OBJ, or any format with a registered loader).
+ * @param url URL to the model file.
+ * @param options Optional loading configuration.
+ * @param options.context The Needle Engine context to load into. Defaults to `Context.Current`.
+ * @param options.seed Seed for generating unique component IDs.
+ * @param options.onprogress Callback invoked with download progress events.
+ * @returns A promise that resolves to the loaded {@link Model} (`GLTF | FBX | OBJ | CustomModel`), or `undefined` if loading fails.
  */
 export function loadAsset(url: string, options?: { context?: Context, path?: string, seed?: number, onprogress?: (evt: ProgressEvent) => void }): Promise<Model | undefined> {
     return loadSync(options?.context || Context.Current, url, url, options?.seed || null, options?.onprogress);

package/src/engine/engine_networking_streams.ts

@@ -616,6 +616,7 @@ export class NetworkedStreams extends EventDispatcher<any> {
             if (this.debug)
                 console.log("PEER USER CONNECTED", user.guid, user, this._sendingStreams.size);
             const stream = this._sendingStreams.keys().next().value;
+            if (!stream) return;
 
             // check if we already have a call with this user
             // const existing = this._outgoingCalls.find(c => c.call.peer === peerId && c.stream === stream);

package/src/engine/engine_util_decorator.ts

@@ -58,7 +58,7 @@ function createPropertyWrapper(target: IComponent | any, _propertyKey: string |
     // we currently only support validation of fields
     if (descriptor !== undefined) {
         console.error("Invalid usage of validate decorator. Only fields can be validated.", target, _propertyKey, descriptor);
-        showBalloonMessage("Invalid usage of validate decorator. Only fields can be validated. Property: " + _propertyKey, LogType.Error);
+        showBalloonMessage("Invalid usage of validate decorator. Only fields can be validated. Property: " + _propertyKey, { type: LogType.Error });
         return;
     }
 
@@ -75,7 +75,7 @@ function createPropertyWrapper(target: IComponent | any, _propertyKey: string |
         target.__internalAwake = function () {
 
             if (!this.onValidate) {
-                if(isDevEnvironment()) console.warn("Usage of @validate decorate detected but there is no onValidate method in your class: \"" + target.constructor?.name + "\"")
+                if (isDevEnvironment()) console.warn("Usage of @validate decorate detected but there is no onValidate method in your class: \"" + target.constructor?.name + "\"")
                 return;
             }
 

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

@@ -20,13 +20,8 @@ export class NeedleLogoElement extends HTMLElement {
         return document.createElement(elementName) as NeedleLogoElement;
     }
 
-    private _didInitialize = false;
-
     constructor() {
         super();
-    }
-
-    private initializeDom() {
         this._root = this.attachShadow({ mode: 'closed' });
         const template = document.createElement('template');
         template.innerHTML = `<style>
@@ -88,37 +83,25 @@ export class NeedleLogoElement extends HTMLElement {
         this.addEventListener("click", () => {
             globalThis.open("https://needle.tools", "_blank");
         });
-    }
 
-    ensureInitialized() {
-        if (!this._didInitialize) {
-            this._didInitialize = true;
-            this.initializeDom();
-        }
     }
 
     connectedCallback() {
-        this.ensureInitialized();
-        if (!this.wrapper) return;
         this.wrapper.setAttribute("title", "Made with Needle Engine");
         this.setAttribute("aria-label", "Needle Engine logo. Click to open the Needle Engine website.");
     }
 
-    private _root!: ShadowRoot;
-    private wrapper!: HTMLDivElement;
-    private logoElement!: HTMLImageElement;
+    private readonly _root: ShadowRoot;
+    private readonly wrapper: HTMLDivElement;
+    private readonly logoElement: HTMLImageElement;
 
     /** Show or hide the logo element (used by the menu) */
     setLogoVisible(val: boolean) {
-        this.ensureInitialized();
-        if (!this.logoElement) return;
         this.logoElement.style.display = val ? "block" : "none";
     }
 
     /** Switch the logo between full and compact versions */
     setType(type: "full" | "compact") {
-        this.ensureInitialized();
-        if (!this.logoElement) return;
         if (type === "full") {
             this.logoElement.src = needleLogoSVG;
             this.logoElement.classList.remove("with-text");

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

@@ -129,7 +129,6 @@ 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);
@@ -310,6 +309,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);
     }
 
@@ -337,13 +337,9 @@ 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
@@ -677,9 +673,6 @@ export class NeedleMenuElement extends HTMLElement {
             padding: .6em .5em;
             width: 100%;
         }
-        .compact.has-options {
-            padding-left: 1em;
-        }
         .compact.has-options .logo {
             border: none;
             padding-left: 0;
@@ -700,6 +693,7 @@ export class NeedleMenuElement extends HTMLElement {
                 display: flex;
                 flex-basis: 100%;
                 min-height: 3rem;
+                min-width: 3rem;
             }
             & > button.row2 {
                 //border: 1px solid red !important;
@@ -799,7 +793,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 element is initialized
+        // we need to assign it in the timeout because the reference is set *after* the constructor did run
         setTimeout(() => context = this._context);
 
         // watch changes
@@ -868,21 +862,13 @@ 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 initialization runs
+        // the dom element is set after the constructor runs
         setTimeout(() => {
             this._domElement?.addEventListener("resize", this.handleSizeChange);
             this._domElement?.addEventListener("click", this.#onClick);
@@ -970,19 +956,19 @@ export class NeedleMenuElement extends HTMLElement {
 
     // private _root: ShadowRoot | null = null;
     /** @private root container element inside shadow DOM */
-    private root!: HTMLDivElement;
+    private readonly root: HTMLDivElement;
     /** @private wraps the whole content (internal layout) */
-    private wrapper!: HTMLDivElement;
+    private readonly wrapper: HTMLDivElement;
     /** @private contains the buttons and dynamic elements */
-    private options!: HTMLDivElement;
+    private readonly options: HTMLDivElement;
     /** @private contains options visible when in compact mode */
-    private optionsCompactMode!: HTMLDivElement;
+    private readonly optionsCompactMode: HTMLDivElement;
     /** @private contains the needle-logo html element */
-    private logoContainer!: HTMLDivElement;
+    private readonly logoContainer: HTMLDivElement;
     /** @private compact menu button element */
-    private compactMenuButton!: HTMLButtonElement;
+    private readonly compactMenuButton: HTMLButtonElement;
     /** @private foldout container used in compact mode */
-    private foldout!: HTMLDivElement;
+    private readonly foldout: HTMLDivElement;
 
 
     private readonly trackedElements: WeakSet<Node> = new WeakSet();

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

@@ -168,30 +168,19 @@ 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();
 
@@ -292,7 +281,6 @@ export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngi
      * @internal
      */
     async connectedCallback() {
-        this.ensureInitialized();
         if (debug) {
             console.log("<needle-engine> connected");
         }