@needle-tools/engine 5.1.0-alpha.3 → 5.1.0-alpha.5

package/plugins/vite/dependencies.js

@@ -77,7 +77,7 @@ export function needleDependencies(command, config, userSettings) {
                     if (req.url) {
                         for (const pkg of rewritePackages) {
                             const marker = `/${pkg}/`;
-                            if (req.url.includes(marker) && !req.url.startsWith(`/node_modules/${pkg}/`)) {
+                            if (req.url.includes(marker) && !req.url.startsWith(`/node_modules/${pkg}/`) && !req.url.startsWith('/@fs/')) {
                                 const idx = req.url.indexOf(marker);
                                 const rewritten = '/node_modules' + req.url.slice(idx);
                                 needleLog('needle-dependencies', `Rewriting worker URL → ${rewritten}`);
@@ -187,16 +187,6 @@ function handleOptimizeDeps(config) {
             config.optimizeDeps.exclude.push('@needle-tools/engine');
             needleLog("needle-dependencies", 'Detected local @needle-tools/engine package → will exclude it from optimization');
         }
-        // When engine is excluded from optimizeDeps, three-mesh-bvh must also be excluded.
-        // The BVH worker (generateMeshBVH.worker.js) uses bare imports like `import 'three'`
-        // which only resolve correctly when served through Vite's dev server module system.
-        // If three-mesh-bvh is pre-bundled, the worker URL points into the cache and bare
-        // imports fail at runtime → "Unknown error. Please check the server console."
-        if (!config.optimizeDeps.include?.includes('three-mesh-bvh') &&
-            !config.optimizeDeps.exclude.includes('three-mesh-bvh')) {
-            config.optimizeDeps.exclude.push('three-mesh-bvh');
-            needleLog("needle-dependencies", 'Detected local @needle-tools/engine package → will also exclude three-mesh-bvh from optimization');
-        }
     }
 }
 

package/plugins/vite/dependency-watcher.js

@@ -98,7 +98,7 @@ function watchPackageJson(server, projectDir, packageJsonPath, cachePath) {
 
     setTimeout(() => {
         requireInstall = testIfInstallIsRequired(projectDir, packageJson);
-    }, 1000);
+    }, 1000).unref();
 
     setInterval(() => {
         if (!packageJson || lastEditTime === undefined) return;
@@ -149,7 +149,7 @@ function watchPackageJson(server, projectDir, packageJsonPath, cachePath) {
                 restart(server, projectDir, cachePath);
             }
         }
-    }, 2000);
+    }, 2000).unref();
 }
 
 /** @param {string} projectDir @param {PackageJson | undefined} packageJson @returns {boolean} */

package/plugins/vite/editor-connection.js

@@ -27,7 +27,7 @@ export async function editorConnection(command, config, userSettings, pluginsArr
     if (typeof config.generator === "string" && !config.generator.includes("Unity")) return;
 
     if (!config) {
-        setTimeout(() => needleLog("needle-editor-sync", "Needle Editor Sync can not be installed automatically to vite: missing config", "warn"), 1000);
+        setTimeout(() => needleLog("needle-editor-sync", "Needle Editor Sync can not be installed automatically to vite: missing config", "warn"), 1000).unref();
         return createPlugin(false);
     }
 
@@ -42,14 +42,14 @@ export async function editorConnection(command, config, userSettings, pluginsArr
     //     }
     // }
     if (needleEditorSettings && needleEditorSettings.enabled === false) {
-        setTimeout(() => needleLog("needle-editor-sync", "Needle Editor Sync is not enabled. Add a 'Needle Editor Sync' component to your scene to enable", "warn"), 1000);
+        setTimeout(() => needleLog("needle-editor-sync", "Needle Editor Sync is not enabled. Add a 'Needle Editor Sync' component to your scene to enable", "warn"), 1000).unref();
         return createPlugin(false);
     }
 
     // Check if the editor package is installed
     let path = root + `/node_modules/${editorSyncPackageName}/plugins/index.js`;
     if (existsSync(path) === false) {
-        setTimeout(() => needleLog("needle-editor-sync", `${editorSyncPackageName} is not installed: Add the "Needle Editor Sync" component to your scene if you want to send changes directly from the Unity Editor to web app`, "warn"), 1000);
+        setTimeout(() => needleLog("needle-editor-sync", `${editorSyncPackageName} is not installed: Add the "Needle Editor Sync" component to your scene if you want to send changes directly from the Unity Editor to web app`, "warn"), 1000).unref();
         return createPlugin(false);
     }
 

package/plugins/vite/license.js

@@ -9,6 +9,7 @@ import { loadConfig } from './config.js';
  */
 export function needleLicense(command, config, userSettings) {
     let license = undefined;
+    let appliedLicense = false;
 
     return {
         name: "needle:license",
@@ -31,7 +32,15 @@ export function needleLicense(command, config, userSettings) {
 
         },
         async transform(src, id) {
-            const isNeedleEngineFile = id.includes("engine/engine_license") || id.includes("needle-tools_engine");
+            if (appliedLicense === true) {
+                return;
+            }
+
+            // Vite 4 and 8 handling:
+            const isNeedleEngineFile = id.includes("engine/engine_license")
+                || id.includes("needle-tools_engine")
+                || id.includes("@needle-tools")
+                || id.includes("needle-engine");
             // sometimes the actual license parameter is in a unnamed chunk file
             const isViteChunkFile = id.includes("chunk") && id.includes(".vite");
             if (isNeedleEngineFile || isViteChunkFile) {
@@ -44,12 +53,21 @@ export function needleLicense(command, config, userSettings) {
                 if (index >= 0) {
                     const end = src.indexOf(";", index);
                     if (end >= 0) {
+                        appliedLicense = true;
                         const line = src.substring(index, end);
                         const replaced = "NEEDLE_ENGINE_LICENSE_TYPE = \"" + license + "\"";
                         src = src.replace(line, replaced);
                         return { code: src, map: null }
                     }
                 }
+                // @TODO: detect local needle engine dev setup and log error if not found
+            }
+        },
+        buildEnd() {
+            if (!appliedLicense) {
+                if (process.env.NEEDLE_TEST_ENV) {
+                    console.error("ERR: License was not applied!");
+                }
             }
         }
     }

package/plugins/vite/reload.js

@@ -225,7 +225,7 @@ async function scheduleReload(server, level = 0) {
     if (existsSync(lockFile)) {
         if (level === 0)
             needleLog(pluginName, "Lock file exists, waiting for export to finish...");
-        setTimeout(() => scheduleReload(server, level += 1), 300);
+        setTimeout(() => scheduleReload(server, level += 1), 300).unref();
         return;
     }
 

package/plugins/vite/server.js

@@ -60,7 +60,8 @@ export function needleServer(command, config, userSettings) {
                             })
                             .catch((err) => console.error("ERR: [needle:server] 'open' package not found - please make sure to install 'open' in your package.json\n", err));
                     }
-                }, 100)
+                }, 100);
+                i.unref();
             }
         },
     }

package/src/engine/api.ts

@@ -167,6 +167,9 @@ export * from "./engine_constants.js";
  */
 export * from "./engine_context.js";
 
+/** Typed event bus for decoupled component communication via {@link Context.events} */
+export * from "./engine_context_eventbus.js";
+
 /** Registry for managing multiple engine contexts */
 export * from "./engine_context_registry.js";
 
@@ -176,6 +179,10 @@ export * from "./engine_context_registry.js";
  */
 export * from "./engine_coroutine.js"
 
+/** DisposableStore for managing lifecycle-bound cleanup in components */
+export { DisposableStore, on, isDisposable } from "./engine_disposable.js";
+export type { DisposeFn, IDisposable } from "./engine_disposable.js";
+
 /** Factory functions for creating primitives and objects */
 export * from "./engine_create_objects.js";
 

package/src/engine/codegen/register_types.ts

@@ -7,11 +7,6 @@ import { Animation } from "../../engine-components/Animation.js";
 import { Animator } from "../../engine-components/Animator.js";
 import { AudioListener } from "../../engine-components/AudioListener.js";
 import { AudioSource } from "../../engine-components/AudioSource.js";
-import { Avatar_Brain_LookAt } from "../../engine-components/avatar/Avatar_Brain_LookAt.js";
-import { Avatar_MouthShapes } from "../../engine-components/avatar/Avatar_MouthShapes.js";
-import { Avatar_MustacheShake } from "../../engine-components/avatar/Avatar_MustacheShake.js";
-import { AvatarBlink_Simple } from "../../engine-components/avatar/AvatarBlink_Simple.js";
-import { AvatarEyeLook_Rotation } from "../../engine-components/avatar/AvatarEyeLook_Rotation.js";
 import { AxesHelper } from "../../engine-components/AxesHelper.js";
 import { BasicIKConstraint } from "../../engine-components/BasicIKConstraint.js";
 import { BoxHelperComponent } from "../../engine-components/BoxHelperComponent.js";
@@ -106,11 +101,12 @@ import { TestRunner } from "../../engine-components/TestRunner.js";
 import { TestSimulateUserData } from "../../engine-components/TestRunner.js";
 import { PlayableDirector } from "../../engine-components/timeline/PlayableDirector.js";
 import { SignalReceiver } from "../../engine-components/timeline/SignalAsset.js";
-import { AnimationTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
-import { AudioTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
-import { MarkerTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
+import { TimelineAnimationTrack } from "../../engine-components/timeline/TimelineTracks.js";
+import { TimelineAudioTrack } from "../../engine-components/timeline/TimelineTracks.js";
+import { TimelineMarkerTrack } from "../../engine-components/timeline/TimelineTracks.js";
 import { SignalTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
-import { ControlTrackHandler } from "../../engine-components/timeline/TimelineTracks.js";
+import { TimelineActivationTrack } from "../../engine-components/timeline/TimelineTracks.js";
+import { TimelineControlTrack } from "../../engine-components/timeline/TimelineTracks.js";
 import { TransformGizmo } from "../../engine-components/TransformGizmo.js";
 import { BaseUIComponent } from "../../engine-components/ui/BaseUIComponent.js";
 import { UIRootComponent } from "../../engine-components/ui/BaseUIComponent.js";
@@ -167,11 +163,6 @@ export function initBuiltinTypes() {
 	TypeStore.add("Animator", Animator);
 	TypeStore.add("AudioListener", AudioListener);
 	TypeStore.add("AudioSource", AudioSource);
-	TypeStore.add("Avatar_Brain_LookAt", Avatar_Brain_LookAt);
-	TypeStore.add("Avatar_MouthShapes", Avatar_MouthShapes);
-	TypeStore.add("Avatar_MustacheShake", Avatar_MustacheShake);
-	TypeStore.add("AvatarBlink_Simple", AvatarBlink_Simple);
-	TypeStore.add("AvatarEyeLook_Rotation", AvatarEyeLook_Rotation);
 	TypeStore.add("AxesHelper", AxesHelper);
 	TypeStore.add("BasicIKConstraint", BasicIKConstraint);
 	TypeStore.add("BoxHelperComponent", BoxHelperComponent);
@@ -266,11 +257,12 @@ export function initBuiltinTypes() {
 	TypeStore.add("TestSimulateUserData", TestSimulateUserData);
 	TypeStore.add("PlayableDirector", PlayableDirector);
 	TypeStore.add("SignalReceiver", SignalReceiver);
-	TypeStore.add("AnimationTrackHandler", AnimationTrackHandler);
-	TypeStore.add("AudioTrackHandler", AudioTrackHandler);
-	TypeStore.add("MarkerTrackHandler", MarkerTrackHandler);
+	TypeStore.add("TimelineAnimationTrack", TimelineAnimationTrack);
+	TypeStore.add("TimelineAudioTrack", TimelineAudioTrack);
+	TypeStore.add("TimelineMarkerTrack", TimelineMarkerTrack);
 	TypeStore.add("SignalTrackHandler", SignalTrackHandler);
-	TypeStore.add("ControlTrackHandler", ControlTrackHandler);
+	TypeStore.add("TimelineActivationTrack", TimelineActivationTrack);
+	TypeStore.add("TimelineControlTrack", TimelineControlTrack);
 	TypeStore.add("TransformGizmo", TransformGizmo);
 	TypeStore.add("BaseUIComponent", BaseUIComponent);
 	TypeStore.add("UIRootComponent", UIRootComponent);

package/src/engine/engine_camera.fit.ts

@@ -257,12 +257,23 @@ export function fitCamera(options?: FitCameraOptions): null | FitCameraReturnTyp
     else {
         direction.sub(camera.worldPosition);
     }
-    if (centerCamera === "y")
-        direction.y = 0;
+    if (centerCamera === "y") {
+        // Preserve the camera's current elevation angle when it's already above the center,
+        // but clamp to a minimum elevation to prevent the camera from ending up at or below
+        // the scene center (which causes a "looking up from below" effect).
+        // direction points FROM camera TO center, so negative Y = camera is above center.
+        const horizontalLen = Math.sqrt(direction.x * direction.x + direction.z * direction.z);
+        if (horizontalLen > 0.0001) {
+            const minY = -horizontalLen * verticalOffset * 4;
+            if (direction.y > minY) direction.y = minY;
+        }
+        else {
+            // Camera is directly above/below center — pick a default slight angle from +Z
+            direction.set(0, -verticalOffset * 4, 1);
+        }
+    }
     direction.normalize();
     direction.multiplyScalar(distance);
-    if (centerCamera === "y")
-        direction.y += -verticalOffset * 4 * distance;
 
     let cameraLocalPosition = center.clone().sub(direction);
     if (options.cameraOffset) {

package/src/engine/engine_context.ts

@@ -23,6 +23,7 @@ import { Application } from './engine_application.js';
 import { AssetDatabase } from './engine_assetdatabase.js';
 import { FocusRect, FocusRectSettings, updateCameraFocusRect } from './engine_camera.js';
 import { VERSION } from './engine_constants.js';
+import { EventBus } from './engine_context_eventbus.js';
 import { ContextEvent, ContextRegistry } from './engine_context_registry.js';
 import { WaitForPromise } from './engine_coroutine.js';
 import { ObjectUtils } from "./engine_create_objects.js";
@@ -151,7 +152,7 @@ export function registerComponent(script: IComponent, context?: Context) {
 }
 
 /**
- * The Needle Engine context is the main access point that holds all the data and state of a Needle Engine application. 
+ * The Needle Engine context is the main access point that holds all the data and state of a Needle Engine application.
  * It can be used to access the {@link Context.scene}, {@link Context.renderer}, {@link Context.mainCamera}, {@link Context.input}, {@link Context.physics}, {@link Context.time}, {@link Context.connection} (networking), and more.
  * 
  * The context is automatically created when using the `<needle-engine>` web component.  
@@ -522,19 +523,31 @@ export class Context implements IContext {
 	private _fallbackCamera: PerspectiveCamera | null = null;
 
 	/** access application state (e.g. if all audio should be muted) */
-	application: Application;
+	get application(): Application { return this._application; }
+	private _application!: Application;
 	/** access animation mixer used by components in the scene */
-	animations: AnimationsRegistry;
+	get animations(): AnimationsRegistry { return this._animations; }
+	private _animations!: AnimationsRegistry;
 	/** access timings (current frame number, deltaTime, timeScale, ...) */
-	time: Time;
+	get time(): Time { return this._time; }
+	private _time!: Time;
 	/** access input data (e.g. click or touch events) */
-	input: Input;
+	get input(): Input { return this._input; }
+	private _input!: Input;
 	/** access physics related methods (e.g. raycasting). To access the phyiscs engine use `context.physics.engine` */
-	physics: Physics;
+	get physics(): Physics { return this._physics; }
+	private _physics!: Physics;
 	/** access postprocessing effects stack. Add/remove effects and configure adaptive performance settings */
-	postprocessing: PostProcessing;
+	get postprocessing(): PostProcessing { return this._postprocessing; }
+	private _postprocessing!: PostProcessing;
 	/** access networking methods (use it to send or listen to messages or join a networking backend) */
-	connection: NetworkConnection;
+	get connection(): NetworkConnection { return this._connection; }
+	private _connection!: NetworkConnection;
+	/** context-level event bus for decoupled component communication
+	 * @see {@link ContextEventMap} for known event types
+	 */
+	get events(): EventBus { return this._events; }
+	private _events = new EventBus();
 	/**  @deprecated AssetDatabase is deprecated */
 	assets: AssetDatabase;
 
@@ -606,12 +619,12 @@ export class Context implements IContext {
 		else this.scene = new Scene();
 		if (args?.camera) this._mainCamera = args.camera;
 
-		this.application = new Application(this);
-		this.time = new Time();
-		this.input = new Input(this);
-		this.physics = new Physics(this);
-		this.postprocessing = new PostProcessing(this);
-		this.connection = new NetworkConnection(this);
+		this._application = new Application(this);
+		this._time = new Time();
+		this._input = new Input(this);
+		this._physics = new Physics(this);
+		this._postprocessing = new PostProcessing(this);
+		this._connection = new NetworkConnection(this);
 		// eslint-disable-next-line @typescript-eslint/no-deprecated
 		this.assets = new AssetDatabase();
 		this.sceneLighting = new SceneLighting(this);
@@ -620,7 +633,7 @@ export class Context implements IContext {
 		this.players = new PlayerViewManager(this);
 		this.menu = new NeedleMenu(this);
 		this.lodsManager = new LODsManager(this);
-		this.animations = new AnimationsRegistry(this);
+		this._animations = new AnimationsRegistry(this);
 		this.accessibility = new AccessibilityManager(this);
 
 
@@ -863,12 +876,14 @@ export class Context implements IContext {
 		this.scene = new Scene();
 		this.addressables?.dispose();
 		this.lightmaps?.clear();
-		this.physics?.engine?.clearCaches();
+		this.physics?.engine?.dispose();
 		this.lodsManager.disable();
 		this.accessibility?.clear();
 
 		this._onBeforeRenderListeners.clear();
 		this._onAfterRenderListeners.clear();
+		this._events.clear();
+		this._events = new EventBus();
 
 		this.lights.length = 0;
 
@@ -912,6 +927,7 @@ export class Context implements IContext {
 		this.scene = null!;
 		this.renderer = null!;
 		this.input.dispose();
+		this.connection.dispose();
 		this.menu.onDestroy();
 		this.animations.onDestroy();
 		for (const cb of this._disposeCallbacks) {

package/src/engine/engine_context_eventbus.ts

@@ -0,0 +1,73 @@
+import type { Object3D } from "three";
+
+import type { IComponent } from "./engine_types.js";
+
+/** Typed event map for {@link Context.events}.
+ * Known events get full autocomplete; custom events can be typed at the call site via generic parameter.
+ */
+export interface ContextEventMap {
+	"scene-content-changed": {
+		/** The component that triggered the change (e.g. SceneSwitcher, DropListener) */
+		readonly source: IComponent;
+		/** The root object that was added/loaded */
+		readonly object: Object3D;
+	};
+}
+
+/** Options for {@link EventBus.on}. */
+export interface EventBusListenerOptions {
+	/** If true the listener is automatically removed after the first invocation. */
+	once?: boolean;
+}
+
+/** Typed event bus. Known {@link ContextEventMap} events get full autocomplete.
+ * Custom events can be typed at the call site via generic parameter.
+ * @example Known events
+ * ```ts
+ * context.events.on("scene-content-changed", e => e.object);
+ * ```
+ * @example Custom events — type at call site
+ * ```ts
+ * context.events.emit<{ pts: number }>("scored", { pts: 10 });
+ * context.events.on<{ pts: number }>("scored", e => e.pts);
+ * ```
+ * @example Once
+ * ```ts
+ * context.events.on("scene-content-changed", e => { ... }, { once: true });
+ * ```
+ */
+export class EventBus {
+	private _listeners = new Map<string, Function[]>();
+
+	/** Emit a known {@link ContextEventMap} event */
+	emit<K extends keyof ContextEventMap & string>(type: K, detail?: ContextEventMap[K]): void;
+	/** Emit a custom event with user-provided type */
+	emit<T>(type: string, detail?: T): void;
+	emit(type: string, detail?: unknown): void {
+		const arr = this._listeners.get(type);
+		if (arr) for (const cb of [...arr]) cb(detail);
+	}
+
+	/** Subscribe to a known {@link ContextEventMap} event. Returns an unsubscribe function. */
+	on<K extends keyof ContextEventMap & string>(type: K, callback: (args: ContextEventMap[K]) => void, options?: EventBusListenerOptions): () => void;
+	/** Subscribe to a custom event with user-provided type. Returns an unsubscribe function. */
+	on<T>(type: string, callback: (args: T) => void, options?: EventBusListenerOptions): () => void;
+	on(type: string, callback: Function, options?: EventBusListenerOptions): () => void {
+		let arr = this._listeners.get(type);
+		if (!arr) { arr = []; this._listeners.set(type, arr); }
+		const unsub = () => {
+			const i = arr.indexOf(wrapped);
+			if (i >= 0) arr.splice(i, 1);
+		};
+		const wrapped = options?.once
+			? (...args: unknown[]) => { unsub(); callback(...args); }
+			: callback;
+		arr.push(wrapped);
+		return unsub;
+	}
+
+	/** Remove all listeners. Called when the context is cleared or destroyed. */
+	clear(): void {
+		this._listeners.clear();
+	}
+}

package/src/engine/engine_disposable.ts

@@ -0,0 +1,214 @@
+/** A function that performs cleanup when called */
+export type DisposeFn = () => void;
+
+/**
+ * Interface for objects that hold resources and can be disposed.
+ * Implement this interface on any object that needs deterministic cleanup.
+ *
+ * @example
+ * ```ts
+ * class MyResource implements IDisposable {
+ *     dispose() { /* release resources *\/ }
+ * }
+ * ```
+ *
+ * @category Utilities
+ * @group Lifecycle
+ */
+export interface IDisposable {
+    dispose(): void;
+}
+
+/**
+ * Type guard to check if an object implements {@link IDisposable}.
+ *
+ * @example
+ * ```ts
+ * if (isDisposable(obj)) {
+ *     obj.dispose(); // safe to call
+ * }
+ * ```
+ */
+export function isDisposable(value: unknown): value is IDisposable {
+    return value !== null
+        && typeof value === "object"
+        && "dispose" in (value as object)
+        && typeof (value as IDisposable).dispose === "function";
+}
+
+/**
+ * @experimental
+ * Subscribe to a DOM event on any {@link EventTarget} (window, document, HTML elements, etc.)
+ * and return an {@link IDisposable} that removes the listener when disposed.
+ *
+ * Provides full TypeScript event type inference — the callback parameter
+ * is automatically typed based on the event name (e.g. `"resize"` → `UIEvent`,
+ * `"click"` → `MouseEvent`).
+ *
+ * Use with {@link DisposableStore.add} for automatic lifecycle cleanup in components.
+ *
+ * @param target The EventTarget to listen on (window, document, an element, etc.)
+ * @param type The event name (e.g. `"resize"`, `"click"`, `"keydown"`)
+ * @param listener The event handler callback
+ * @param options Optional addEventListener options (passive, capture, once, signal)
+ * @returns An {@link IDisposable} that removes the event listener when disposed
+ *
+ * @example Standalone usage
+ * ```ts
+ * import { on } from "@needle-tools/engine";
+ *
+ * const sub = on(window, "resize", (ev) => {
+ *     // ev is typed as UIEvent
+ *     console.log("resized", ev.target);
+ * });
+ *
+ * // Later: clean up
+ * sub.dispose();
+ * ```
+ *
+ * @example With autoCleanup in a component
+ * ```ts
+ * import { Behaviour, on } from "@needle-tools/engine";
+ *
+ * export class MyComponent extends Behaviour {
+ *     onEnable() {
+ *         this.autoCleanup(on(window, "resize", (ev) => { /* UIEvent *\/ }));
+ *         this.autoCleanup(on(document, "keydown", (ev) => { /* KeyboardEvent *\/ }));
+ *         this.autoCleanup(on(this.context.domElement, "click", (ev) => { /* MouseEvent *\/ }));
+ *     }
+ *     // All listeners removed automatically on disable!
+ * }
+ * ```
+ *
+ * @category Utilities
+ * @group Lifecycle
+ */
+// #region on
+export function on<K extends keyof WindowEventMap>(target: Window, type: K, listener: (ev: WindowEventMap[K]) => void, options?: boolean | AddEventListenerOptions): IDisposable;
+export function on<K extends keyof DocumentEventMap>(target: Document, type: K, listener: (ev: DocumentEventMap[K]) => void, options?: boolean | AddEventListenerOptions): IDisposable;
+export function on<K extends keyof HTMLElementEventMap>(target: HTMLElement, type: K, listener: (ev: HTMLElementEventMap[K]) => void, options?: boolean | AddEventListenerOptions): IDisposable;
+export function on(target: EventTarget, type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): IDisposable;
+export function on(target: EventTarget, type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): IDisposable {
+    target.addEventListener(type, listener, options);
+    return {
+        dispose() {
+            target.removeEventListener(type, listener, options);
+        }
+    };
+}
+
+
+/**
+ * A store for managing disposable resources (event subscriptions, listeners, callbacks)
+ * that should be cleaned up together.
+ *
+ * DisposableStore collects disposables and disposes them all at once when
+ * {@link dispose} is called. After disposal, the store can be reused — new items
+ * can be added and a subsequent {@link dispose} call will clean those up.
+ *
+ * This is the same pattern used internally by VSCode for lifecycle-bound resource management.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { DisposableStore, on } from "@needle-tools/engine";
+ *
+ * const store = new DisposableStore();
+ *
+ * // Register a DOM event listener (typed!)
+ * store.add(on(window, "resize", (ev) => console.log(ev)));
+ *
+ * // Register the return value of EventList.on()
+ * store.add(myEventList.on(data => console.log(data)));
+ *
+ * // Register a raw cleanup function
+ * store.add(() => someSDK.off("event", handler));
+ *
+ * // Later: dispose everything at once
+ * store.dispose();
+ * ```
+ *
+ * @example Use with Needle Engine components
+ * ```ts
+ * import { Behaviour, serializable, EventList, on } from "@needle-tools/engine";
+ *
+ * export class MyComponent extends Behaviour {
+ *     @serializable(EventList)
+ *     onClick?: EventList;
+ *
+ *     onEnable() {
+ *         // DOM events — fully typed
+ *         this.autoCleanup(on(window, "resize", (ev) => this.onResize(ev)));
+ *
+ *         // EventList — .on() returns a function, autoCleanup accepts it
+ *         this.autoCleanup(this.onClick?.on(() => console.log("clicked!")));
+ *     }
+ *     // No onDisable needed — cleaned up automatically!
+ * }
+ * ```
+ *
+ * @category Utilities
+ * @group Lifecycle
+ */
+// #region DisposableStore
+export class DisposableStore implements IDisposable {
+
+    private _disposables: Array<DisposeFn> = [];
+
+    /** The number of registered disposables */
+    get size() { return this._disposables.length; }
+
+    /**
+     * Register a disposable resource. Accepts:
+     * - An {@link IDisposable} object (has a `dispose()` method) — e.g. from {@link on}
+     * - A cleanup function (e.g. return value of `EventList.on()`)
+     * - `null` or `undefined` (safe no-op for conditional subscriptions)
+     *
+     * When {@link dispose} is called, all registered resources are cleaned up.
+     *
+     * @param disposable The resource to register for disposal
+     *
+     * @example
+     * ```ts
+     * const store = new DisposableStore();
+     *
+     * // IDisposable object from on()
+     * store.add(on(window, "resize", handler));
+     *
+     * // Function returned by EventList.on()
+     * store.add(myEvent.on(handler));
+     *
+     * // Raw cleanup function
+     * store.add(() => connection.close());
+     *
+     * // Conditional — safe with undefined
+     * store.add(this.maybeEvent?.on(handler));
+     * ```
+     */
+    add(disposable: IDisposable | DisposeFn | Function | null | undefined): void {
+        if (!disposable) return;
+        if (typeof disposable === "function") {
+            this._disposables.push(disposable as DisposeFn);
+        }
+        else if (typeof disposable === "object" && "dispose" in disposable) {
+            this._disposables.push(() => disposable.dispose());
+        }
+    }
+
+    /**
+     * Dispose all registered resources. Each registered disposable is cleaned up,
+     * then the internal list is cleared. The store can be reused after disposal.
+     *
+     * Called automatically by the engine when a component's `onDisable` lifecycle fires.
+     */
+    dispose(): void {
+        for (let i = this._disposables.length - 1; i >= 0; i--) {
+            try {
+                this._disposables[i]();
+            }
+            catch (err) {
+                console.error("Error disposing resource", err);
+            }
+        }
+        this._disposables.length = 0;
+    }
+}