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

package/src/engine/engine_ssr.ts

@@ -0,0 +1,48 @@
+/**
+ * SSR-safe base classes for browser globals that are not available in Node/SSR environments.
+ *
+ * Use these instead of extending browser globals directly so that class definitions
+ * do not throw a ReferenceError at module evaluation time in SSR/Node contexts
+ * (SvelteKit, Next.js, etc.).
+ *
+ * In browser environments each constant is the real global; in SSR it falls back
+ * to a plain empty class so that `class Foo extends HTMLElementBase` is valid.
+ */
+
+
+/** True when running in an SSR/Node environment (no browser globals). */
+export const SSR: boolean = typeof window === "undefined";
+
+/** SSR-safe base class for web components. */
+export const HTMLElementBase: typeof HTMLElement =
+    typeof HTMLElement !== "undefined" ? HTMLElement : (class { } as unknown as typeof HTMLElement);
+
+/** SSR-safe base class for pointer events. */
+export const PointerEventBase: typeof PointerEvent =
+    typeof PointerEvent !== "undefined" ? PointerEvent : (class { } as unknown as typeof PointerEvent);
+
+/** SSR-safe base class for keyboard events. */
+export const KeyboardEventBase: typeof KeyboardEvent =
+    typeof KeyboardEvent !== "undefined" ? KeyboardEvent : (class { } as unknown as typeof KeyboardEvent);
+
+
+
+
+// #region minimal polyfills
+// Three.js FileLoader uses ProgressEvent in fetch stream callbacks.
+// It doesn't exist in Node — install a minimal stub so SSR doesn't crash.
+if (typeof globalThis.ProgressEvent === "undefined") {
+    (globalThis as any).ProgressEvent = class ProgressEvent {
+        readonly type: string;
+        readonly lengthComputable: boolean;
+        readonly loaded: number;
+        readonly total: number;
+        constructor(type: string, init?: { lengthComputable?: boolean; loaded?: number; total?: number }) {
+            this.type = type;
+            this.lengthComputable = init?.lengthComputable ?? false;
+            this.loaded = init?.loaded ?? 0;
+            this.total = init?.total ?? 0;
+        }
+    };
+}
+// #endregion

package/src/engine/engine_three_utils.ts

@@ -493,13 +493,21 @@ void main(){
  * Utility class to perform various graphics operations like copying textures to canvas
  */
 export class Graphics {
-    private static readonly planeGeometry = new PlaneGeometry(2, 2, 1, 1);
-    private static readonly renderer: WebGLRenderer = new WebGLRenderer({ antialias: false, alpha: true });
-    private static readonly perspectiveCam = new PerspectiveCamera();
-    private static readonly orthographicCam = new OrthographicCamera();
-    private static readonly scene = new Scene();
-    private static readonly blitMaterial: BlitMaterial = new BlitMaterial();
-    private static readonly mesh: Mesh = new Mesh(Graphics.planeGeometry, Graphics.blitMaterial);
+    private static _planeGeometry: PlaneGeometry | undefined;
+    private static _renderer: WebGLRenderer | undefined;
+    private static _perspectiveCam: PerspectiveCamera | undefined;
+    private static _orthographicCam: OrthographicCamera | undefined;
+    private static _scene: Scene | undefined;
+    private static _blitMaterial: BlitMaterial | undefined;
+    private static _mesh: Mesh | undefined;
+
+    private static get planeGeometry() { return this._planeGeometry ??= new PlaneGeometry(2, 2, 1, 1); }
+    private static get renderer() { return this._renderer ??= new WebGLRenderer({ antialias: false, alpha: true }); }
+    private static get perspectiveCam() { return this._perspectiveCam ??= new PerspectiveCamera(); }
+    private static get orthographicCam() { return this._orthographicCam ??= new OrthographicCamera(); }
+    private static get scene() { return this._scene ??= new Scene(); }
+    private static get blitMaterial() { return this._blitMaterial ??= new BlitMaterial(); }
+    private static get mesh() { return this._mesh ??= new Mesh(Graphics.planeGeometry, Graphics.blitMaterial); }
 
 
     /** 

package/src/engine/engine_types.ts

@@ -258,6 +258,8 @@ export declare interface ICameraController {
 export declare interface ILight extends IComponent {
     intensity: number;
     color: Color;
+    /** The type of light as a lowercase string: `"directional"`, `"point"`, `"spot"` */
+    readonly type: "directional" | "point" | "spot";
 }
 
 export declare interface ISharedMaterials {

package/src/engine/engine_utils.ts

@@ -597,6 +597,7 @@ export namespace DeviceUtilities {
     /** @returns `true` for MacOS or Windows devices. `false` for Hololens and other headsets. */
     export function isDesktop() {
         if (_isDesktop !== undefined) return _isDesktop;
+        if (typeof window === "undefined") return _isDesktop = false;
         const ua = window.navigator.userAgent;
         const standalone = /Windows|MacOS|Mac OS/.test(ua);
         const isHololens = /Windows NT/.test(ua) && /Edg/.test(ua) && !/Win64/.test(ua);

package/src/engine/engine_utils_hash.ts

@@ -0,0 +1,65 @@
+/**
+ * Pure-JS hashing utilities — no external dependencies, works in browser and Node/SSR.
+ */
+
+// MD5 based on the public-domain RSA Data Security MD5 algorithm.
+function md5Bytes(input: Uint8Array): number[] {
+    function safeAdd(x: number, y: number) { const lsw = (x & 0xffff) + (y & 0xffff); return ((x >> 16) + (y >> 16) + (lsw >> 16)) << 16 | lsw & 0xffff; }
+    function bitRotateLeft(num: number, cnt: number) { return num << cnt | num >>> 32 - cnt; }
+    function md5cmn(q: number, a: number, b: number, x: number, s: number, t: number) { return safeAdd(bitRotateLeft(safeAdd(safeAdd(a, q), safeAdd(x, t)), s), b); }
+    function md5ff(a: number, b: number, c: number, d: number, x: number, s: number, t: number) { return md5cmn(b & c | ~b & d, a, b, x, s, t); }
+    function md5gg(a: number, b: number, c: number, d: number, x: number, s: number, t: number) { return md5cmn(b & d | c & ~d, a, b, x, s, t); }
+    function md5hh(a: number, b: number, c: number, d: number, x: number, s: number, t: number) { return md5cmn(b ^ c ^ d, a, b, x, s, t); }
+    function md5ii(a: number, b: number, c: number, d: number, x: number, s: number, t: number) { return md5cmn(c ^ (b | ~d), a, b, x, s, t); }
+
+    const len8 = input.length;
+    const padded = new Uint8Array((Math.ceil((len8 + 9) / 64) * 64));
+    padded.set(input);
+    padded[len8] = 0x80;
+    const view = new DataView(padded.buffer);
+    view.setUint32(padded.length - 8, len8 << 3, true);
+    view.setUint32(padded.length - 4, (len8 / 0x20000000) | 0, true);
+
+    let a = 0x67452301, b = 0xefcdab89, c = 0x98badcfe, d = 0x10325476;
+    for (let i = 0; i < padded.length >> 2; i += 16) {
+        const M = (j: number) => view.getInt32((i + j) * 4, true);
+        const [oa, ob, oc, od] = [a, b, c, d];
+        a = md5ff(a,b,c,d,M(0),7,-680876936); d=md5ff(d,a,b,c,M(1),12,-389564586); c=md5ff(c,d,a,b,M(2),17,606105819); b=md5ff(b,c,d,a,M(3),22,-1044525330);
+        a=md5ff(a,b,c,d,M(4),7,-176418897); d=md5ff(d,a,b,c,M(5),12,1200080426); c=md5ff(c,d,a,b,M(6),17,-1473231341); b=md5ff(b,c,d,a,M(7),22,-45705983);
+        a=md5ff(a,b,c,d,M(8),7,1770035416); d=md5ff(d,a,b,c,M(9),12,-1958414417); c=md5ff(c,d,a,b,M(10),17,-42063); b=md5ff(b,c,d,a,M(11),22,-1990404162);
+        a=md5ff(a,b,c,d,M(12),7,1804603682); d=md5ff(d,a,b,c,M(13),12,-40341101); c=md5ff(c,d,a,b,M(14),17,-1502002290); b=md5ff(b,c,d,a,M(15),22,1236535329);
+        a=md5gg(a,b,c,d,M(1),5,-165796510); d=md5gg(d,a,b,c,M(6),9,-1069501632); c=md5gg(c,d,a,b,M(11),14,643717713); b=md5gg(b,c,d,a,M(0),20,-373897302);
+        a=md5gg(a,b,c,d,M(5),5,-701558691); d=md5gg(d,a,b,c,M(10),9,38016083); c=md5gg(c,d,a,b,M(15),14,-660478335); b=md5gg(b,c,d,a,M(4),20,-405537848);
+        a=md5gg(a,b,c,d,M(9),5,568446438); d=md5gg(d,a,b,c,M(14),9,-1019803690); c=md5gg(c,d,a,b,M(3),14,-187363961); b=md5gg(b,c,d,a,M(8),20,1163531501);
+        a=md5gg(a,b,c,d,M(13),5,-1444681467); d=md5gg(d,a,b,c,M(2),9,-51403784); c=md5gg(c,d,a,b,M(7),14,1735328473); b=md5gg(b,c,d,a,M(12),20,-1926607734);
+        a=md5hh(a,b,c,d,M(5),4,-378558); d=md5hh(d,a,b,c,M(8),11,-2022574463); c=md5hh(c,d,a,b,M(11),16,1839030562); b=md5hh(b,c,d,a,M(14),23,-35309556);
+        a=md5hh(a,b,c,d,M(1),4,-1530992060); d=md5hh(d,a,b,c,M(4),11,1272893353); c=md5hh(c,d,a,b,M(7),16,-155497632); b=md5hh(b,c,d,a,M(10),23,-1094730640);
+        a=md5hh(a,b,c,d,M(13),4,681279174); d=md5hh(d,a,b,c,M(0),11,-358537222); c=md5hh(c,d,a,b,M(3),16,-722521979); b=md5hh(b,c,d,a,M(6),23,76029189);
+        a=md5hh(a,b,c,d,M(9),4,-640364487); d=md5hh(d,a,b,c,M(12),11,-421815835); c=md5hh(c,d,a,b,M(15),16,530742520); b=md5hh(b,c,d,a,M(2),23,-995338651);
+        a=md5ii(a,b,c,d,M(0),6,-198630844); d=md5ii(d,a,b,c,M(7),10,1126891415); c=md5ii(c,d,a,b,M(14),15,-1416354905); b=md5ii(b,c,d,a,M(5),21,-57434055);
+        a=md5ii(a,b,c,d,M(12),6,1700485571); d=md5ii(d,a,b,c,M(3),10,-1894986606); c=md5ii(c,d,a,b,M(10),15,-1051523); b=md5ii(b,c,d,a,M(1),21,-2054922799);
+        a=md5ii(a,b,c,d,M(8),6,1873313359); d=md5ii(d,a,b,c,M(15),10,-30611744); c=md5ii(c,d,a,b,M(6),15,-1560198380); b=md5ii(b,c,d,a,M(13),21,1309151649);
+        a=md5ii(a,b,c,d,M(4),6,-145523070); d=md5ii(d,a,b,c,M(11),10,-1120210379); c=md5ii(c,d,a,b,M(2),15,718787259); b=md5ii(b,c,d,a,M(9),21,-343485551);
+        a=safeAdd(a,oa); b=safeAdd(b,ob); c=safeAdd(c,oc); d=safeAdd(d,od);
+    }
+    const result = new DataView(new ArrayBuffer(16));
+    result.setUint32(0, a, true); result.setUint32(4, b, true); result.setUint32(8, c, true); result.setUint32(12, d, true);
+    return Array.from(new Uint8Array(result.buffer));
+}
+
+/** Returns the MD5 hash of the given bytes as a lowercase hex string. */
+export function md5Hex(input: Uint8Array): string {
+    return md5Bytes(input).map(b => b.toString(16).padStart(2, "0")).join("");
+}
+
+/** Returns the MD5 hash of the given bytes as a raw byte array. */
+export function md5AsBytes(input: Uint8Array): number[] {
+    return md5Bytes(input);
+}
+
+/** Returns the SHA-256 hash of the given buffer as a base64 string. */
+export function sha256Base64(buffer: ArrayBuffer): Promise<string> {
+    return crypto.subtle.digest("SHA-256", new Uint8Array(buffer)).then(res =>
+        btoa(String.fromCharCode(...new Uint8Array(res)))
+    );
+}

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

@@ -1,4 +1,5 @@
 import { madeWithNeedleSVG, needleLogoOnlySVG, needleLogoSVG } from "../assets/index.js";
+import { HTMLElementBase } from "../engine_ssr.js";
 
 const elementName = "needle-logo-element";
 
@@ -6,13 +7,21 @@ declare global {
     interface HTMLElementTagNameMap {
         "needle-logo-element": NeedleLogoElement;
     }
+    namespace JSX {
+        interface IntrinsicElements {
+            "needle-logo-element": NeedleLogoElementJSXAttributes;
+        }
+    }
+    interface NeedleLogoElementJSXAttributes extends Partial<Omit<HTMLElement, "style" | "children">> {
+        style?: Partial<CSSStyleDeclaration>;
+    }
 }
 
 /**
  * Needle logo web component used in the hosting UI (small, compact logo or full)
  * @element needle-logo-element
  */
-export class NeedleLogoElement extends HTMLElement {
+export class NeedleLogoElement extends HTMLElementBase {
 
     static get elementName() { return elementName; }
 

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

@@ -1,4 +1,5 @@
 import { showBalloonMessage } from "../../debug/debug.js";
+import { HTMLElementBase } from "../../engine_ssr.js";
 import type { Context } from "../../engine_context.js";
 import { hasCommercialLicense, onLicenseCheckResultChanged, Telemetry } from "../../engine_license.js";
 import { isLocalNetwork } from "../../engine_networking_utils.js";
@@ -13,7 +14,15 @@ import { NeedleSpatialMenu } from "./needle-menu-spatial.js";
 
 declare global {
     interface HTMLElementTagNameMap {
-        "needle-logo-element": NeedleLogoElement;
+        "needle-menu": NeedleMenuElement;
+    }
+    namespace JSX {
+        interface IntrinsicElements {
+            "needle-menu": NeedleMenuJSXAttributes;
+        }
+    }
+    interface NeedleMenuJSXAttributes extends Partial<Omit<HTMLElement, "style" | "children">> {
+        style?: Partial<CSSStyleDeclaration>;
     }
 }
 
@@ -303,7 +312,7 @@ export class NeedleMenu {
  *
  * @element needle-menu
  */
-export class NeedleMenuElement extends HTMLElement {
+export class NeedleMenuElement extends HTMLElementBase {
 
     static create() {
         // Ensure the element is registered before creating — guards against

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

@@ -1,4 +1,5 @@
 import { isDevEnvironment } from "../debug/index.js";
+import { HTMLElementBase } from "../engine_ssr.js";
 import { ButtonsFactory } from "./buttons.js";
 import { iconFontUrl, loadFont } from "./fonts.js";
 import { WebXRButtonFactory } from "./WebXRButtons.js";
@@ -7,6 +8,19 @@ declare global {
     interface HTMLElementTagNameMap {
         "needle-button": NeedleButtonElement;
     }
+    namespace JSX {
+        interface IntrinsicElements {
+            "needle-button": NeedleButtonJSXAttributes;
+        }
+    }
+    interface NeedleButtonJSXAttributes extends Partial<Omit<HTMLElement, "style" | "children">> {
+        style?: Partial<CSSStyleDeclaration>;
+        ar?: boolean | string;
+        vr?: boolean | string;
+        quicklook?: boolean | string;
+        qrcode?: boolean | string;
+        unstyled?: boolean | string;
+    }
 }
 
 const isDev = isDevEnvironment();
@@ -65,7 +79,7 @@ const isDev = isDevEnvironment();
  * @see {@link NeedleEngineWebComponent} for the main &lt;needle-engine&gt; element
  * @see {@link NeedleMenu} for the built-in menu component that can display similar buttons
  */
-export class NeedleButtonElement extends HTMLElement {
+export class NeedleButtonElement extends HTMLElementBase {
 
     static observedAttributes = ["ar", "vr", "quicklook", "qrcode"];
 

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

@@ -1,4 +1,5 @@
 import { isDevEnvironment, showBalloonWarning } from "../debug/index.js";
+import { HTMLElementBase } from "../engine_ssr.js";
 import { PUBLIC_KEY, VERSION } from "../engine_constants.js";
 import { ContextEvent, ContextRegistry } from "../engine_context_registry.js";
 import { hasCommercialLicense } from "../engine_license.js";
@@ -20,6 +21,12 @@ declare global {
     interface HTMLElementTagNameMap {
         "needle-engine": NeedleEngineWebComponent;
     }
+    // JSX support — allows <needle-engine> in React, Preact, SolidJS and any other JSX-based framework.
+    namespace JSX {
+        interface IntrinsicElements {
+            "needle-engine": NeedleEngineAttributes;
+        }
+    }
 }
 
 const debug = getParam("debugwebcomponent");
@@ -153,7 +160,7 @@ const observedAttributes = [
  * @see {@link NeedleButtonElement} for adding AR/VR/Quicklook buttons via &lt;needle-button&gt;
  * @see {@link NeedleMenu} for the built-in menu configuration component
  */
-export class NeedleEngineWebComponent extends HTMLElement implements INeedleEngineComponent {
+export class NeedleEngineWebComponent extends HTMLElementBase implements INeedleEngineComponent {
 
     static get observedAttributes() {
         return observedAttributes;

package/src/engine/xr/NeedleXRSession.ts

@@ -207,7 +207,7 @@ function waitForContextLoadingFinished(): Promise<void> {
 }
 
 
-if (DeviceUtilities.isDesktop() && isDevEnvironment()) {
+if (typeof window !== "undefined" && DeviceUtilities.isDesktop() && isDevEnvironment()) {
     window.addEventListener("keydown", (evt) => {
         if (evt.key === "x" || evt.key === "Escape") {
             if (NeedleXRSession.active) {

package/src/engine-components/Light.ts

@@ -1,7 +1,9 @@
 import { CameraHelper, Color, DirectionalLight, DirectionalLightHelper, Light as ThreeLight, OrthographicCamera, PointLight, SpotLight, Vector3 } from "three";
+import { CSM } from "three/examples/jsm/csm/CSM.js";
+import { CSMHelper } from "three/examples/jsm/csm/CSMHelper.js";
 
 import { serializable } from "../engine/engine_serialization_decorator.js";
-import { FrameEvent } from "../engine/engine_setup.js";
+
 import { setWorldPositionXYZ } from "../engine/engine_three_utils.js";
 import type { ILight } from "../engine/engine_types.js";
 import { getParam } from "../engine/engine_utils.js";
@@ -106,11 +108,40 @@ enum LightShadows {
 export class Light extends Behaviour implements ILight {
 
     /**
-     * The type of light (spot, directional, point, etc.)  
-     * Can not be changed at runtime.  
+     * The type of light as a lowercase string: `"directional"`, `"point"`, `"spot"`.
+     * Implements {@link ILight.type}. Can not be changed at runtime.
      */
+    get type(): ILight["type"] {
+        return this._type;
+    }
+
+    /** Numeric LightType serialized from Unity/Blender — converts to string on write */
     @serializable()
-    private type: LightType = 0;
+    set type(value: LightType | ILight["type"]) {
+        if (this.light && this.__didAwake) {
+            throw new Error("Changing the light type at runtime is not supported");
+        }
+        switch (value) {
+            case LightType.Directional:
+                this._type = "directional";
+                break;
+            case LightType.Point:
+                this._type = "point";
+                break;
+            case LightType.Spot:
+                this._type = "spot";
+                break;
+            case "directional":
+            case "point":
+            case "spot":
+                this._type = value;
+                break;
+            default:
+                throw new Error("Invalid light type: " + value);
+        }
+    }
+    private _type: ILight["type"] = "point";
+
 
     /**
      * The maximum distance the light affects.  
@@ -174,6 +205,9 @@ export class Light extends Behaviour implements ILight {
         if (this.light !== undefined) {
             this.light.color = val;
         }
+        if (this._csm) {
+            for (const l of this._csm.lights) l.color.copy(val);
+        }
     }
     get color(): Color {
         if (this.light) return this.light.color;
@@ -259,6 +293,9 @@ export class Light extends Behaviour implements ILight {
         if (this.light) {
             this.light.intensity = val;
         }
+        if (this._csm) {
+            for (const l of this._csm.lights) l.intensity = val;
+        }
         if (debug) console.log("Set light intensity to " + this._intensity, val, this)
     }
     get intensity(): number { return this._intensity; }
@@ -312,6 +349,24 @@ export class Light extends Behaviour implements ILight {
     }
     private _shadowResolution?: number = undefined;
 
+    /**
+     * Number of shadow cascade levels (only used when `useCascades` is true)
+     */
+    @serializable()
+    cascades: number = 3;
+
+    /**
+     * Cascade split mode (only used when `useCascades` is true):
+     * - `practical` — balanced (default, recommended)
+     * - `logarithmic` — more resolution close up
+     * - `uniform` — equal splits
+     */
+    @serializable()
+    cascadeMode: "practical" | "logarithmic" | "uniform" = "practical";
+
+    private _csm?: CSM;
+    private _csmHelper?: CSMHelper;
+
     /**
      * Whether this light's illumination is entirely baked into lightmaps
      */
@@ -345,7 +400,7 @@ export class Light extends Behaviour implements ILight {
      */
     public getWorldPosition(vec: Vector3): Vector3 {
         if (this.light) {
-            if (this.type === LightType.Directional) {
+            if (this.type === "directional") {
                 return this.light.getWorldPosition(vec).multiplyScalar(1);
             }
             return this.light.getWorldPosition(vec);
@@ -372,12 +427,21 @@ export class Light extends Behaviour implements ILight {
             else if (this.light.parent !== this.gameObject)
                 this.gameObject.add(this.light);
         }
-        if (this.type === LightType.Directional)
-            this.startCoroutine(this.updateMainLightRoutine(), FrameEvent.LateUpdate);
+        this.context.lights.add(this);
     }
 
     onDisable() {
         if (debug) console.log("DISABLE LIGHT", this.name);
+        this.context.lights.delete(this);
+        if (this._csm) {
+            this._csm.remove();
+            this._csm.dispose();
+            this._csm = undefined;
+            if (this._csmHelper) {
+                this._csmHelper.removeFromParent();
+                this._csmHelper = undefined;
+            }
+        }
         if (this.light) {
             if (this.selfIsLight)
                 this.light.intensity = 0;
@@ -386,6 +450,27 @@ export class Light extends Behaviour implements ILight {
         }
     }
 
+    onBeforeRender() {
+        if (this.type === "directional" && this.shadows !== LightShadows.None) {
+            // context.mainLight is computed — always returns the brightest registered directional light
+            const isMain = this.context.mainLight === this;
+            if (isMain) {
+                if (!this._csm) this.createCSM();
+            } else if (this._csm) {
+                // this light is no longer the main light (a brighter one took over) — tear down CSM
+                this._csm.remove();
+                this._csm.dispose();
+                this._csm = undefined;
+            }
+        }
+        if (this._csm) {
+            // keep lightDirection in sync with the gameObject's world orientation
+            this._csm.lightDirection.copy(this.gameObject.worldForward);
+            this._csm.update();
+            if (this._csmHelper) this._csmHelper.update();
+        }
+    }
+
     /**
      * Creates the appropriate three.js light based on the configured light type
      * and applies all settings like shadows, intensity, and color.
@@ -399,14 +484,14 @@ export class Light extends Behaviour implements ILight {
             this._intensity = this.light.intensity;
 
             switch (this.type) {
-                case LightType.Directional:
+                case "directional":
                     this.setDirectionalLight(this.light as DirectionalLight);
                     break;
             }
         }
         else if (!this.light) {
             switch (this.type) {
-                case LightType.Directional:
+                case "directional":
                     // console.log(this);
                     const dirLight = new DirectionalLight(this.color, this.intensity * Math.PI);
                     // directional light target is at 0 0 0 by default
@@ -425,7 +510,7 @@ export class Light extends Behaviour implements ILight {
                     }
                     break;
 
-                case LightType.Spot:
+                case "spot":
                     const spotLight = new SpotLight(this.color, this.intensity * Math.PI, this.range, toRadians(this.spotAngle / 2), 1 - toRadians(this.innerSpotAngle / 2) / toRadians(this.spotAngle / 2), 2);
                     spotLight.position.set(0, 0, 0);
                     spotLight.rotation.set(0, 0, 0);
@@ -437,7 +522,7 @@ export class Light extends Behaviour implements ILight {
                     spotLightTarget.rotation.set(0, 0, 0);
                     break;
 
-                case LightType.Point:
+                case "point":
                     const pointLight = new PointLight(this.color, this.intensity * Math.PI, this.range);
                     this.light = pointLight;
 
@@ -526,22 +611,6 @@ export class Light extends Behaviour implements ILight {
 
     }
 
-    /**
-     * Coroutine that updates the main light reference in the context
-     * if this directional light should be the main light
-     */
-    *updateMainLightRoutine() {
-        while (true) {
-            if (this.type === LightType.Directional) {
-                if (!this.context.mainLight || this.intensity > this.context.mainLight.intensity) {
-                    this.context.mainLight = this;
-                }
-                yield;
-            }
-            break;
-        }
-    }
-
     /**
      * Controls whether the renderer's shadow map type can be changed when soft shadows are used
      */
@@ -598,6 +667,41 @@ export class Light extends Behaviour implements ILight {
         }
     }
 
+    /**
+     * Creates and initializes a CSM instance for this directional light.
+     * CSM manages its own cascade DirectionalLights internally.
+     */
+    private createCSM() {
+        const camera = this.context.mainCamera;
+        if (!camera) {
+            if (debug) console.warn("CSM: no main camera found, deferring");
+            return;
+        }
+
+        this._csm = new CSM({
+            camera,
+            parent: this.context.scene,
+            cascades: this.cascades,
+            mode: this.cascadeMode,
+            maxFar: this._shadowDistance ?? shadowMaxDistance,
+            shadowMapSize: this._shadowResolution ?? 2048,
+            shadowBias: this._shadowBias,
+            lightDirection: this.gameObject.worldForward.clone(),
+            lightIntensity: this._intensity >= 0 ? this._intensity : 1,
+        });
+        this._csm.fade = true;
+
+        // apply color to all cascade lights
+        for (const l of this._csm.lights) {
+            l.color.copy(this._color);
+        }
+
+        if (debug) {
+            this._csmHelper = new CSMHelper(this._csm);
+            this.context.scene.add(this._csmHelper);
+        }
+    }
+
     /**
      * Configures a directional light by adding and positioning its target
      * @param dirLight The directional light to set up
@@ -610,4 +714,5 @@ export class Light extends Behaviour implements ILight {
 }
 
 const vec = new Vector3(0, 0, 0);
+const _csmLightDir = new Vector3();
 

package/src/engine-components/RigidBody.ts

@@ -382,12 +382,12 @@ export class Rigidbody extends Behaviour implements IRigidbody {
         this._watch.start(true, true);
         this.startCoroutine(this.beforePhysics(), FrameEvent.LateUpdate);
         if (isDevEnvironment()) {
-            if (!globalThis["NEEDLE_USE_RAPIER"])
-                console.warn(`Rigidbody could not be created: Rapier physics are explicitly disabled.`);
+            if (globalThis["NEEDLE_USE_RAPIER"] === false)
+                console.warn(`RAPIER physics are disabled in your build. Enable them by setting NEEDLE_USE_RAPIER to true in your build config: Rigidbody could not be created.`);
             else {
                 MODULES.RAPIER_PHYSICS.ready().then(async () => {
                     await delayForFrames(3);
-                    if (!this.context.physics.engine?.getBody(this))
+                    if (this.activeAndEnabled && !this.context.physics.engine?.getBody(this))
                         console.warn(`Rigidbody could not be created. Ensure \"${this.name}\" has a Collider component.`);
                 })
             }

package/src/engine-components/SceneSwitcher.ts

@@ -723,6 +723,7 @@ export class SceneSwitcher extends Behaviour {
                     // unless the user defines that he wants to use the scene name
                     if (this.useSceneName) {
                         if (scene instanceof Object3D) queryParameterValue = scene.name;
+                        else if (scene instanceof AssetReference && scene.asset?.name) queryParameterValue = scene.asset.name;
                         else if (scene.url) queryParameterValue = sceneUriToName(scene.url);
                     }
                     // save the loaded scene as an url parameter

package/src/engine-components/postprocessing/Effects/BloomEffect.ts

@@ -1,4 +1,4 @@
-import { BloomEffect as _BloomEffect, EffectAttribute } from "postprocessing";
+import type { BloomEffect as _BloomEffect } from "postprocessing";
 import { MathUtils } from "three";
 
 import { MODULES } from "../../../engine/engine_modules.js";

package/src/engine-components/postprocessing/Effects/Sharpening.ts

@@ -1,4 +1,3 @@
-import { EffectAttribute } from "postprocessing";
 import { Uniform } from "three";
 
 import { MODULES } from "../../../engine/engine_modules.js";
@@ -138,7 +137,7 @@ function createSharpeningEffectType() {
                     ["radius", new Uniform(1)],
                     // ["threshold", new Uniform(0)],
                 ]),
-                attributes: EffectAttribute.CONVOLUTION
+                attributes: MODULES.POSTPROCESSING.MODULE.EffectAttribute.CONVOLUTION
             });
         }
     }

package/src/engine-components/postprocessing/PostProcessingHandler.ts

@@ -14,10 +14,6 @@ import { threeToneMappingToEffectMode } from "./Effects/Tonemapping.utils.js";
 import { PostProcessingEffect, PostProcessingEffectContext } from "./PostProcessingEffect.js";
 import { orderEffects, PostprocessingEffectData, PostProcessingEffectOrder } from "./utils.js";
 
-declare const NEEDLE_USE_POSTPROCESSING: boolean;
-globalThis["NEEDLE_USE_POSTPROCESSING"] = globalThis["NEEDLE_USE_POSTPROCESSING"] !== undefined ? globalThis["NEEDLE_USE_POSTPROCESSING"] : true;
-
-
 const debug = getParam("debugpost");
 
 const activeKey = Symbol("needle:postprocessing-handler");
@@ -58,13 +54,13 @@ export class PostProcessingHandler implements IPostProcessingHandler {
 
     apply(components: PostProcessingEffect[]): Promise<void> {
         if ("env" in import.meta && (import.meta as any /* webpack support */ ).env.VITE_NEEDLE_USE_POSTPROCESSING === "false") {
-            if (debug) console.warn("Postprocessing is disabled via vite env setting");
-            else console.debug("Postprocessing is disabled via vite env setting");
+            if (debug) console.warn("POSTPROCESSING is disabled via vite env setting");
+            else console.debug("POSTPROCESSING is disabled via vite env setting");
             return Promise.resolve();
         }
         if (!NEEDLE_USE_POSTPROCESSING) {
-            if (debug) console.warn("Postprocessing is disabled via global vite define setting");
-            else console.debug("Postprocessing is disabled via vite define");
+            if (debug || isDevEnvironment()) console.warn("POSTPROCESSING is disabled via global vite define setting");
+            else console.debug("POSTPROCESSING is disabled via vite define");
             return Promise.resolve();
         }
 

package/src/engine-components/web/ScrollFollow.ts

@@ -1,5 +1,5 @@
-// For firefox ViewTimeline support
-import "scroll-timeline-polyfill/dist/scroll-timeline.js";
+// For firefox ViewTimeline support — dynamic import to avoid SSR crashes (polyfill accesses window at module level)
+if (typeof window !== "undefined") import("scroll-timeline-polyfill/dist/scroll-timeline.js");
 
 import { Box3, Object3D } from "three";
 

package/src/needle-engine.ts

@@ -1,3 +1,5 @@
+/// <reference path="../plugins/types/needle-bindings.d.ts" />
+
 import { initEngine } from "./engine/engine_init.js";
 initEngine();
 import "./engine/webcomponents/needle-engine.js";