@needle-tools/engine 5.1.0-alpha.1 → 5.1.0-canary.0d9f44e

package/plugins/vite/logging.js

@@ -97,8 +97,8 @@ export function needleLog(pluginName, message, level = 'log', options = undefine
             ? (dimBody ? leveledBody.split('\n').map(l => colors.dim(l)).join('\n') : leveledBody)
             : "";
         const payloadCore = emitHeader
-            ? (body.length > 0 ? `${header}\n${body}\n` : `${header}\n`)
-            : (body.length > 0 ? `${body}\n` : "");
+            ? (body.length > 0 ? `${header}\n${body}` : `${header}`)
+            : (body.length > 0 ? `${body}` : "");
         const payload = leadingNewline ? `\n${payloadCore}` : payloadCore;
         log(payload);
         return;

package/plugins/vite/meta.js

@@ -13,8 +13,7 @@ import { needleGreenBold, needleLog } from './logging.js';
  */
 export function needleMeta(command, config, userSettings) {
 
-    // we can check if this is a build
-    const isBuild = command === 'build';
+    let isBuild = command === 'build';
 
     async function updateConfig() {
         config = await loadConfig();
@@ -25,6 +24,9 @@ export function needleMeta(command, config, userSettings) {
     return {
         // replace meta tags
         name: 'needle:meta',
+        configResolved(resolvedConfig) {
+            isBuild = resolvedConfig.command === 'build';
+        },
         transformIndexHtml: {
             order: 'pre',
             handler(/** @type {string} */ html, /** @type {unknown} */ _ctx) {

package/plugins/vite/poster.d.ts

@@ -1,8 +1,8 @@
 export function getPosterPath(): string;
 /**
- * @param {"build" | "serve"} command
+ * @param {"build" | "serve" | undefined} _command
  * @param {import('../types/needleConfig').needleMeta | null | undefined} config
  * @param {import('../types').userSettings} userSettings
  * @returns {import('vite').Plugin | undefined}
  */
-export function needlePoster(command: "build" | "serve", config: import("../types/needleConfig").needleMeta | null | undefined, userSettings: import("../types").userSettings): import("vite").Plugin | undefined;
+export function needlePoster(_command: "build" | "serve" | undefined, config: import("../types/needleConfig").needleMeta | null | undefined, userSettings: import("../types").userSettings): import("vite").Plugin | undefined;

package/plugins/vite/poster.js

@@ -10,19 +10,17 @@ export function getPosterPath() {
 }
 
 /**
- * @param {"build" | "serve"} command
+ * @param {"build" | "serve" | undefined} _command
  * @param {import('../types/needleConfig').needleMeta | null | undefined} config
  * @param {import('../types').userSettings} userSettings
  * @returns {import('vite').Plugin | undefined}
  */
-export function needlePoster(command, config, userSettings) {
-    // only relevant for local development
-    if (command === 'build') return [];
-
+export function needlePoster(_command, config, userSettings) {
     if (userSettings.noPoster) return;
 
     return {
         name: 'needle:poster',
+        apply: 'serve',
         configureServer(server) {
             const hot = server.hot ?? server.ws;
             hot.on('needle:screenshot', async (data, client) => {

package/plugins/vite/reload.d.ts

@@ -1,7 +1,7 @@
 /**
- * @param {"build" | "serve"} command
+ * @param {"build" | "serve" | undefined} _command
  * @param {import('../types/needleConfig').needleMeta | null} config
  * @param {import('../types').userSettings} userSettings
  * @returns {import('vite').Plugin | undefined}
  */
-export function needleReload(command: "build" | "serve", config: import("../types/needleConfig").needleMeta | null, userSettings: import("../types").userSettings): import("vite").Plugin | undefined;
+export function needleReload(_command: "build" | "serve" | undefined, config: import("../types/needleConfig").needleMeta | null, userSettings: import("../types").userSettings): import("vite").Plugin | undefined;

package/plugins/vite/reload.js

@@ -15,14 +15,12 @@ const filesUsingHotReload = new Set();
 let assetsDirectory = "";
 
 /**
- * @param {"build" | "serve"} command
+ * @param {"build" | "serve" | undefined} _command
  * @param {import('../types/needleConfig').needleMeta | null} config
  * @param {import('../types').userSettings} userSettings
  * @returns {import('vite').Plugin | undefined}
  */
-export function needleReload(command, config, userSettings) {
-    if (command === "build") return undefined;
-
+export function needleReload(_command, config, userSettings) {
     if (userSettings?.noReload === true) return undefined;
 
 
@@ -51,6 +49,7 @@ export function needleReload(command, config, userSettings) {
 
     return {
         name: 'needle:reload',
+        apply: 'serve',
         /** @param {import('vite').UserConfig} config */
         config(config) {
             if (!config.server) config.server = { watch: { ignored: [] } };
@@ -172,8 +171,9 @@ async function handleReload({ file, server, modules: _modules, read, buildDirect
     // Check if codegen files actually changed their content
     // this will return false if its the first update
     // meaning if its the first export after the server starts those will not trigger a reload
+    // Ignore d.ts
     const shouldCheckIfContentChanged = file.includes("/codegen/") || file.includes("/generated/") || file.endsWith("gen.js");// || file.endsWith(".glb") || file.endsWith(".gltf") || file.endsWith(".bin");
-    if (shouldCheckIfContentChanged) {
+    if (!file.includes("/.svelte-kit/") && !file.endsWith(".d.ts") && !file.endsWith("needle-html-data.json") && shouldCheckIfContentChanged) {
         if (reloadIsScheduled) {
             return [];
         }

package/src/engine/api.ts

@@ -336,6 +336,9 @@ export { loadPMREM } from "./engine_pmrem.js";
 /** Scene lighting data and environment configuration */
 export * from "./engine_scenelighting.js";
 
+/** Typed scene data proxy — maps SceneData interface to live component instances */
+export { getSceneData, needle } from "./engine_scenedata.js";
+
 
 // ============================================================================
 // SERIALIZATION
@@ -436,4 +439,15 @@ export * from "./webcomponents/needle-engine.loading.js";
  * XR API: NeedleXRSession, NeedleXRController, XRRig.
  * @see {@link https://engine.needle.tools/docs/xr.html | XR Documentation}
  */
-export * from "./xr/api.js"
+export * from "./xr/api.js"
+
+/**
+ * HTML ↔ 3D component binding types, similar to Svelte's `PageData`.
+ * `SceneData` is a nested interface augmented per-project by the `needle:dts-generator`
+ * Vite plugin — it maps scene node names to their components and typed fields.
+ *
+ * @example
+ * import type { SceneData } from "@needle-tools/engine";
+ * type OrbitSettings = SceneData["Camera"]["OrbitControls"];
+ */
+export type { SceneData } from "needle-bindings";

package/src/engine/debug/debug_environment.ts

@@ -15,7 +15,7 @@ export function isDevEnvironment(): boolean {
     let res = isLocalNetwork();
     if (!res) {
         // is stackblitz?
-        res = window.location.hostname.endsWith(".local-credentialless.webcontainer.io");
+        res = typeof window !== "undefined" && window.location.hostname.endsWith(".local-credentialless.webcontainer.io");
     }
     _cachedDevEnvironment = res;
     return res;

package/src/engine/engine_application.ts

@@ -31,12 +31,14 @@ export function internalOnUserInputRegistered() {
     userInteractionCallbacks.length = 0;
     copy.forEach(cb => cb());
 }
-document.addEventListener('mousedown', internalOnUserInputRegistered);
-document.addEventListener('pointerup', internalOnUserInputRegistered);
-document.addEventListener('click', internalOnUserInputRegistered);
-document.addEventListener('dragstart', internalOnUserInputRegistered);
-document.addEventListener('touchend', internalOnUserInputRegistered);
-document.addEventListener('keydown', internalOnUserInputRegistered);
+if (typeof document !== "undefined") {
+    document.addEventListener('mousedown', internalOnUserInputRegistered);
+    document.addEventListener('pointerup', internalOnUserInputRegistered);
+    document.addEventListener('click', internalOnUserInputRegistered);
+    document.addEventListener('dragstart', internalOnUserInputRegistered);
+    document.addEventListener('touchend', internalOnUserInputRegistered);
+    document.addEventListener('keydown', internalOnUserInputRegistered);
+}
 
 
 // User Activation should be available across browsers since November 2023 https://developer.mozilla.org/en-US/docs/Web/API/UserActivation

package/src/engine/engine_constants.ts

@@ -1,6 +1,8 @@
 import { getParam } from "../engine/engine_utils.js";
 const debug = getParam("debugdefines");
 
+// #region global defines
+
 // We jump through hoops like this to support 3 cases:
 // 1) Vanilla js or angular js where global defines are not guaranteed to be made
 // 2) Vite where global defines are made, vite defines are also automatically set to globalThis
@@ -11,11 +13,6 @@ tryEval(`if(!globalThis["NEEDLE_ENGINE_GENERATOR"]) globalThis["NEEDLE_ENGINE_GE
 tryEval(`if(!globalThis["NEEDLE_PROJECT_BUILD_TIME"]) globalThis["NEEDLE_PROJECT_BUILD_TIME"] = "unknown";`);
 tryEval(`if(!globalThis["NEEDLE_PUBLIC_KEY"]) globalThis["NEEDLE_PUBLIC_KEY"] = "unknown";`);
 
-declare const NEEDLE_ENGINE_VERSION: string
-declare const NEEDLE_ENGINE_GENERATOR: string;
-declare const NEEDLE_PROJECT_BUILD_TIME: string;
-declare const NEEDLE_PUBLIC_KEY: string;
-
 // Make sure to wrap the new global this define in underscores to prevent the bundler from replacing it with the actual value
 tryEval(`globalThis["__NEEDLE_ENGINE_VERSION__"] = "` + NEEDLE_ENGINE_VERSION + `";`);
 tryEval(`globalThis["__NEEDLE_ENGINE_GENERATOR__"] = "` + NEEDLE_ENGINE_GENERATOR + `";`);
@@ -50,4 +47,12 @@ function tryEval(str: string) {
         if (debug)
             console.error(err);
     }
-}
+}
+
+
+
+// #region treeshake flags
+// globalThis fallbacks for vanilla JS environments (no bundler define)
+globalThis["NEEDLE_USE_RAPIER"] = globalThis["NEEDLE_USE_RAPIER"] !== undefined ? globalThis["NEEDLE_USE_RAPIER"] : true;
+globalThis["NEEDLE_USE_POSTPROCESSING"] = globalThis["NEEDLE_USE_POSTPROCESSING"] !== undefined ? globalThis["NEEDLE_USE_POSTPROCESSING"] : true;
+// #endregion treeshake flags

package/src/engine/engine_context.ts

@@ -37,6 +37,8 @@ import { NetworkConnection } from './engine_networking.js';
 import { Physics } from './engine_physics.js';
 import { PlayerViewManager } from './engine_playerview.js';
 import { RendererData as SceneLighting } from './engine_scenelighting.js';
+import { getSceneData } from './engine_scenedata.js';
+import type { SceneData } from 'needle-bindings';
 import { getTempColor, logHierarchy } from './engine_three_utils.js';
 import { Time } from './engine_time.js';
 import { patchTonemapping } from './engine_tonemapping.js';
@@ -475,6 +477,33 @@ export class Context implements IContext {
 	 * The main camera of the scene - this camera is used for rendering   
 	 * Use `setCurrentCamera` for updating the main camera.
 	 */
+	/**
+	 * Typed proxy providing direct access to scene components by node and component name.
+	 * Types are auto-generated from your GLB assets by the `needle:dts-generator` Vite plugin
+	 * and written to `src/generated/needle-bindings.d.ts` on every dev-server start and GLB change.
+	 *
+	 * Each property access traverses the live scene graph on demand — no caching, always fresh.
+	 * This is a convenience shorthand for `getComponent` lookups; the same result can be
+	 * achieved manually via `scene.getObjectByName(name)` + `getComponent(node, Type)`.
+	 *
+	 * @example
+	 * // Toggle auto-rotate on the orbit camera
+	 * ctx.sceneData.Camera.OrbitControls.autoRotate = true;
+	 *
+	 * @example
+	 * // Change the background color
+	 * ctx.sceneData.Camera.Camera.backgroundColor = new RGBAColor(1, 0, 0, 1);
+	 *
+	 * @example
+	 * // Equivalent manual approach (without sceneData)
+	 * const node = ctx.scene.getObjectByName("Camera");
+	 * const orbit = getComponent(node, OrbitControls);
+	 * if (orbit) orbit.autoRotate = true;
+	 */
+	get sceneData(): SceneData {
+		return getSceneData(this);
+	}
+
 	get mainCamera(): Camera {
 		if (this._mainCamera) {
 			return this._mainCamera;
@@ -513,8 +542,22 @@ export class Context implements IContext {
 	connection: NetworkConnection;
 	/**  @deprecated AssetDatabase is deprecated */
 	assets: AssetDatabase;
-	/** The main light in the scene */
-	mainLight: ILight | null = null;
+
+	/** All registered lights in the scene, maintained by the Light component */
+	readonly lights: Set<ILight> = new Set();
+
+	/** The brightest registered directional light, or null if none are registered
+	 * @see lights
+	 */
+	get mainLight(): ILight | null {
+		let best: ILight | null = null;
+		for (const light of this.lights) {
+			if (light.type !== "directional") continue;
+			if (!best || light.intensity > best.intensity) best = light;
+		}
+		return best;
+	}
+
 	/** @deprecated Use sceneLighting */
 	get rendererData() { return this.sceneLighting }
 	/** Access the scene lighting manager to control lighting settings in the context */
@@ -829,6 +872,8 @@ export class Context implements IContext {
 		this._onBeforeRenderListeners.clear();
 		this._onAfterRenderListeners.clear();
 
+		this.lights.clear();
+
 		if (!this.isManagedExternally) {
 			if (this.renderer) {
 				this.renderer.renderLists.dispose();

package/src/engine/engine_context_registry.ts

@@ -1,6 +1,6 @@
 import { type IComponent, type IContext, type LoadedModel } from "./engine_types.js";
 
-const debug = typeof window !== undefined ? window.location.search.includes("debugcontext") : false;
+const debug = typeof window !== "undefined" ? window.location.search.includes("debugcontext") : false;
 
 /** The various events that can be dispatched by a Needle Engine {@link IContext} instance
  */

package/src/engine/engine_init.ts

@@ -11,6 +11,8 @@ import { initCameraExtensions } from "./js-extensions/Camera.js";
 import { patchLayers } from "./js-extensions/Layers.js";
 import { initObject3DExtensions } from "./js-extensions/Object3D.js";
 import { initVectorExtensions } from "./js-extensions/Vector.js";
+import { SSR } from "./engine_ssr.js";
+import { initLicense } from "./engine_license.js";
 import { initWebComponents } from "./webcomponents/init.js";
 import { initPhysics } from "./engine_physics_rapier.js";
 import { initXR } from "./xr/init.js";
@@ -28,6 +30,7 @@ let initialized = false;
  */
 export function initEngine() {
     if (initialized) return;
+    if (SSR) return;
     initialized = true;
 
     initWebComponents();
@@ -46,4 +49,5 @@ export function initEngine() {
     initSceneSwitcherAttributes();
     initPhysics();
     initXR();
+    initLicense();
 }

package/src/engine/engine_input.ts

@@ -1,6 +1,7 @@
 import { Intersection, Matrix4, Object3D, Ray, Vector2, Vector3 } from 'three';
 
 import { showBalloonMessage, showBalloonWarning } from './debug/debug.js';
+import { PointerEventBase, KeyboardEventBase } from './engine_ssr.js';
 import { Context } from './engine_setup.js';
 import { getTempVector, getWorldQuaternion } from './engine_three_utils.js';
 import type { ButtonName, CursorTypeName, IGameObject, IInput, MouseButtonName, Vec2 } from './engine_types.js';
@@ -116,7 +117,7 @@ export declare type NEPointerEventIntersection = Intersection & { event?: NEPoin
  * @see {@link Input} for the input management system
  * @see {@link PointerType} for available pointer types
  */
-export class NEPointerEvent extends PointerEvent {
+export class NEPointerEvent extends PointerEventBase {
 
     /**
      * Spatial input data
@@ -242,7 +243,7 @@ export class NEPointerEvent extends PointerEvent {
         if (debug) console.warn("Stop propagation...", this.pointerId, this.pointerType)
     }
 }
-export class NEKeyboardEvent extends KeyboardEvent {
+export class NEKeyboardEvent extends KeyboardEventBase {
     source?: Event
     constructor(type: InputEvents, source: Event, init: KeyboardEventInit) {
         super(type, init)

package/src/engine/engine_license.ts

@@ -1,6 +1,3 @@
-import { dof } from "three/src/nodes/TSL.js";
-
-import { isDevEnvironment } from "./debug/index.js";
 import { BUILD_TIME, GENERATOR, PUBLIC_KEY, VERSION } from "./engine_constants.js";
 import { ContextEvent, ContextRegistry } from "./engine_context_registry.js";
 import { onInitialized } from "./engine_lifecycle_api.js";
@@ -8,7 +5,7 @@ import { isLocalNetwork } from "./engine_networking_utils.js";
 import { Context } from "./engine_setup.js";
 import type { IContext } from "./engine_types.js";
 import { getParam } from "./engine_utils.js";
-import { InternalAttributeUtils } from "./engine_utils_attributes.js";
+import { SSR } from "./engine_ssr.js";
 
 const debug = getParam("debuglicense");
 
@@ -77,18 +74,22 @@ function invokeLicenseCheckResultChanged(result: boolean) {
 // #region Telemetry
 export namespace Telemetry {
 
-    window.addEventListener("error", (event: ErrorEvent) => {
-        sendError(Context.Current, "unhandled_error", event);
-    });
-    window.addEventListener("unhandledrejection", (event: PromiseRejectionEvent) => {
-        sendError(Context.Current, "unhandled_promise_rejection", {
-            message: event.reason?.message,
-            stack: event.reason?.stack,
-            timestamp: Date.now(),
+    if (typeof window !== "undefined") {
+        window.addEventListener("error", (event: ErrorEvent) => {
+            sendError(Context.Current, "unhandled_error", event);
         });
-    });
+        window.addEventListener("unhandledrejection", (event: PromiseRejectionEvent) => {
+            sendError(Context.Current, "unhandled_promise_rejection", {
+                message: event.reason?.message,
+                stack: event.reason?.stack,
+                timestamp: Date.now(),
+            });
+        });
+    }
 
-    onInitialized((ctx => sendPageViewEvent(ctx)), { once: true });
+    export function init() {
+        if(!SSR) onInitialized((ctx => sendPageViewEvent(ctx)), { once: true });
+    }
 
     function sendPageViewEvent(ctx: IContext): Promise<void> | void {
         if (!isAllowed(ctx)) {
@@ -241,11 +242,14 @@ export namespace Telemetry {
 }
 
 
-ContextRegistry.registerCallback(ContextEvent.ContextRegistered, evt => {
-    showLicenseInfo(evt.context);
-    handleForbidden(evt.context);
-    setTimeout(() => sendUsageMessageToAnalyticsBackend(evt.context), 2000);
-});
+export function initLicense() {
+    Telemetry.init();
+    ContextRegistry.registerCallback(ContextEvent.ContextRegistered, evt => {
+        showLicenseInfo(evt.context);
+        handleForbidden(evt.context);
+        setTimeout(() => sendUsageMessageToAnalyticsBackend(evt.context), 2000);
+    });
+}
 
 export let runtimeLicenseCheckPromise: Promise<void> | undefined = undefined;
 let applicationIsForbidden = false;

package/src/engine/engine_lifecycle_functions_internal.ts

@@ -1,5 +1,6 @@
 import { type Context, FrameEvent } from "./engine_context.js";
 import { ContextEvent } from "./engine_context_registry.js";
+import { SSR } from "./engine_ssr.js";
 
 export declare type Event = ContextEvent | FrameEvent;
 
@@ -38,6 +39,12 @@ let methodsWarningCounter = 0;
  * @param evt the event to call the function at
  */
 export function registerFrameEventCallback(cb: LifecycleMethod, evt: Event, opts?: LifecycleMethodOptions) {
+    
+    // Don't register the callback if we are in SSR, because it will never be called and might cause memory leaks
+    if(SSR) {
+        return;
+    }
+
     if (!newMethods.has(evt)) {
         newMethods.set(evt, new Array());
     }

package/src/engine/engine_networking_blob.ts

@@ -1,11 +1,9 @@
-import * as _md5 from "md5";
-// CJS interop: md5 may appear as { default: fn } or fn depending on bundler
-const md5 = typeof _md5 === "function" ? _md5 : (_md5 as any).default;
 import { FileLoader } from "three";
 
 import { showBalloonWarning } from "./debug/index.js";
 import { hasCommercialLicense } from "./engine_license.js";
 import { delay } from "./engine_utils.js";
+import { md5Hex, md5AsBytes, sha256Base64 } from "./engine_utils_hash.js";
 
 
 export namespace BlobStorage {
@@ -22,21 +20,17 @@ export namespace BlobStorage {
     /**
      * Generates an md5 hash from a given buffer
      * @param buffer The buffer to hash
-     * @returns The md5 hash
+     * @returns The md5 hash as a hex string
      */
     export function hashMD5(buffer: ArrayBuffer): string {
-        return md5(new Uint8Array(buffer))
+        return md5Hex(new Uint8Array(buffer));
     }
     export function hashMD5_Base64(buffer: ArrayBuffer): string {
-        const bytes = md5(new Uint8Array(buffer), { encoding: "binary", asBytes: true });
+        const bytes = md5AsBytes(new Uint8Array(buffer));
         return btoa(String.fromCharCode(...bytes));
     }
     export function hashSha256(buffer: ArrayBuffer): Promise<string> {
-        const bytes = new Uint8Array(buffer);
-        const hash = crypto.subtle.digest('SHA-256', bytes).then(res => {
-            return btoa(String.fromCharCode(...new Uint8Array(res)));
-        })
-        return hash;
+        return sha256Base64(buffer);
     }
 
     export type Upload_Result = {

package/src/engine/engine_physics_rapier.ts

@@ -44,9 +44,6 @@ const $bodyKey = Symbol("physics body");
 const $colliderRigidbody = Symbol("rigidbody");
 
 
-declare const NEEDLE_USE_RAPIER: boolean;
-globalThis["NEEDLE_USE_RAPIER"] = globalThis["NEEDLE_USE_RAPIER"] !== undefined ? globalThis["NEEDLE_USE_RAPIER"] : true;
-
 /** Register the Rapier physics backend. Called from {@link initEngine}
  * to ensure it runs regardless of tree-shaking. */
 export function initPhysics() {

package/src/engine/engine_pmrem.ts

@@ -1,8 +1,8 @@
 import { createLoaders } from "@needle-tools/gltf-progressive";
 import { CubeUVReflectionMapping, EquirectangularRefractionMapping, SRGBColorSpace, Texture, TextureLoader, WebGLRenderer } from "three";
-import { EXRLoader } from "three/examples/jsm/loaders/EXRLoader";
-import { KTX2Loader } from "three/examples/jsm/loaders/KTX2Loader";
-import { RGBELoader } from "three/examples/jsm/loaders/RGBELoader";
+import { EXRLoader } from "three/examples/jsm/loaders/EXRLoader.js";
+import { KTX2Loader } from "three/examples/jsm/loaders/KTX2Loader.js";
+import { RGBELoader } from "three/examples/jsm/loaders/RGBELoader.js";
 
 const running: Map<string, Promise<Texture | null>> = new Map();
 

package/src/engine/engine_scenedata.ts

@@ -0,0 +1,133 @@
+import type { SceneData } from "needle-bindings";
+export type { SceneData };
+import type { IContext } from "./engine_types.js";
+import { getComponent } from "./engine_components.js";
+import { TypeStore } from "./engine_typestore.js";
+import { isDevEnvironment } from "./debug/index.js";
+import { ContextRegistry } from "./engine_context_registry.js";
+
+/**
+ * Global proxy for the primary Needle Engine context.
+ * Resolves lazily on property access via `ContextRegistry.Current` —
+ * safe to import at module level, including in SSR environments
+ * (returns a silent error proxy when no context is active).
+ *
+ * Use this outside of Needle component lifecycle (e.g. in Svelte/React/Vue
+ * components, button handlers, or vanilla JS) instead of threading `ctx` around.
+ *
+ * For multiple `<needle-engine>` elements on the same page, use `ctx` directly.
+ *
+ * @example
+ * import { needle } from "@needle-tools/engine";
+ * button.onclick = () => {
+ *   needle.sceneData.Camera.OrbitControls.autoRotate = true;
+ * };
+ */
+export const needle: IContext = new Proxy({} as IContext, {
+    get(_target, prop: string) {
+        if (prop === "then") return undefined; // not a Promise
+        const ctx = ContextRegistry.Current;
+        if (!ctx) {
+            const fn = isDevEnvironment() ? console.error : console.warn;
+            fn(`[needle] needle.${prop} accessed before scene started`);
+            return makeErrorProxy(`needle not ready — scene hasn't started yet`);
+        }
+        const val = (ctx as any)[prop];
+        return typeof val === "function" ? val.bind(ctx) : val;
+    },
+    set(_target, prop: string, value: unknown) {
+        const ctx = ContextRegistry.Current;
+        if (!ctx) {
+            const fn = isDevEnvironment() ? console.error : console.warn;
+            fn(`[needle] needle.${prop} set before scene started`);
+            return true;
+        }
+        (ctx as any)[prop] = value;
+        return true;
+    },
+});
+
+const cache = new WeakMap<IContext, SceneData>();
+
+/**
+ * Returns a proxy that silently absorbs any property get/set and logs a
+ * developer-friendly warning. Used when a node or component lookup fails so
+ * that chained access like `ctx.sceneData.Foo.Bar.baz = 1` never throws.
+ */
+function makeErrorProxy(message: string): object {
+    const handler: ProxyHandler<object> = {
+        get(_t, prop: string) {
+            if (prop === "then") return undefined; // not a Promise
+            const fn = isDevEnvironment() ? console.error : console.warn;
+            fn(`[SceneData] ${message}`);
+            return makeErrorProxy(message);
+        },
+        set(_t, prop: string) {
+            const fn = isDevEnvironment() ? console.error : console.warn;
+            fn(`[SceneData] ${message} (tried to set "${prop}")`);
+            return true; // suppress TypeError
+        },
+    };
+    return new Proxy({}, handler);
+}
+
+/**
+ * Returns a proxy for a scene node that exposes `$object`, `$components`,
+ * and child nodes as nested properties.
+ */
+function makeNodeProxy(ctx: IContext, node: import("three").Object3D): object {
+    return new Proxy({}, {
+        get(_t, prop: string) {
+            if (prop === "$object") return node;
+            if (prop === "$components") {
+                return new Proxy({}, {
+                    get(_t2, compName: string) {
+                        if (compName === "then") return undefined;
+                        const ctor = TypeStore.get(compName);
+                        if (!ctor) return makeErrorProxy(`Component type "${compName}" not registered (node "${node.name}")`);
+                        const comp = getComponent(node, ctor);
+                        if (!comp) return makeErrorProxy(`Component "${compName}" not found on node "${node.name}"`);
+                        return comp;
+                    }
+                });
+            }
+            // Child node lookup by name
+            const child = node.children.find(c => c.name === prop) ?? null;
+            if (!child) return makeErrorProxy(`Child "${prop}" not found on node "${node.name}"`);
+            return makeNodeProxy(ctx, child);
+        }
+    });
+}
+
+/**
+ * Returns a lazily-resolved proxy typed as {@link SceneData}.
+ * The proxy is cached per context — each context gets exactly one instance.
+ *
+ * Shape mirrors the generated `needle-bindings.gen.d.ts`:
+ *   ctx.sceneData.MyGlb.Camera.$components.OrbitControls.autoRotate = true;
+ *   ctx.sceneData.MyGlb.Camera.$object  // → THREE.Camera
+ *   ctx.sceneData.MyGlb.UI.Button.$components.Button  // → Needle Button component
+ *
+ * GLB name is ignored at runtime (scene is already loaded).
+ * Node lookup starts at the scene root.
+ */
+export function getSceneData(ctx: IContext): SceneData {
+    let proxy = cache.get(ctx);
+    if (!proxy) {
+        proxy = new Proxy({} as SceneData, {
+            get(_target, _glbName: string) {
+                // GLB name level — ignored at runtime, return node-name proxy
+                return new Proxy({}, {
+                    get(_target, nodeName: string) {
+                        if (nodeName === "then") return undefined;
+                        const node = ctx.scene.getObjectByName(nodeName) ?? null;
+                        if (!node) return makeErrorProxy(`Node "${nodeName}" not found in scene`);
+                        return makeNodeProxy(ctx, node);
+                    }
+                });
+            }
+        });
+        cache.set(ctx, proxy);
+    }
+    return proxy;
+}