@needle-tools/engine 5.1.0-canary.52c25a9 → 5.1.0-canary.5c9f618

package/.needle/generated/needle-bindings.gen.d.ts

@@ -0,0 +1,5 @@
+// Auto-generated by @needle-tools/engine — do not edit
+// Regenerated on each vite dev-server start and GLB change.
+declare module "needle-bindings" {
+  interface SceneData {}
+}

package/CHANGELOG.md

@@ -4,6 +4,44 @@ All notable changes to this package will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [5.1.0-alpha.3] - 2026-04-28
+- Add: `AudioClip` type with standalone playback control (play, pause, stop) — use with `@serializable(AudioClip)` for direct audio clip references
+- Add: AudioSource spatial blend support (via dual-path audio graph, enabling smooth crossfade between 2D and 3D audio)
+- Fix: Animation `play()` with `{ exclusive: false }` not stopping other running animations when the target clip was already playing
+- Fix: AudioSource spatial audio rolloff factor not applied correctly
+- Fix: AudioSource `play()` not working correctly in some cases
+- Fix: UI components initializing in wrong order
+- Fix: XR lifecycle — `onLeaveXR` was called spuriously for scripts that never received `onEnterXR` (e.g. during scene switching)
+- Fix: VideoPlayer and URL serializer being tree-shaken out in code-only projects
+- Fix: ReflectionProbe not cleaning up `envMapRotation` and `envMapIntensity` overrides when removed
+- Improved: XR image tracking now includes "emulated" tracking state, preventing reticle from hiding prematurely
+- Improved: AudioSource error logging when audio clips fail to load
+
+## [5.1.0-alpha.2] - 2026-04-13
+- **NEW**: Scene Bindings (experimental) — auto-generated TypeScript types from your glTF scenes, providing typed access to nodes, components, and properties via `ctx.sceneData` or `needle.sceneData`. Types are generated automatically by a Vite plugin whenever your scene files change — no configuration needed. Works with any glTF/GLB assigned as `src` on `<needle-engine>`, including remote URLs and Needle Cloud assets. The API shape (particularly `$components` and `$object` accessors) may evolve based on feedback. Can be disabled with `dts: { enabled: false }` in your Vite plugin config.
+  ```ts
+  // fully typed, with autocomplete for every node and component
+  const cam = ctx.sceneData.MyScene.MainCamera.$object;                      // THREE.PerspectiveCamera
+  const orbit = ctx.sceneData.MyScene.MainCamera.$components.OrbitControls;  // typed!
+  ```
+- **NEW**: SSR support (experimental) — import Needle Engine in Node.js/SSR frameworks (SvelteKit, Next.js, Nuxt) without `ReferenceError` crashes. The engine now provides SSR-safe base classes and skips browser-dependent initialization on the server. Core rendering still happens client-side — SSR support means your app can import and reference engine code server-side without errors.
+- **NEW**: JSX type declarations for `<needle-engine>` and other web components — first-class support for React, Preact, SolidJS, and other JSX-based frameworks with full autocomplete and type checking
+- **NEW**: `needle` shorthand (experimental) — quick access to the current engine context from anywhere without passing `ctx` around. Works in React/Svelte/Vue components, button handlers, or plain JavaScript. SSR-safe.
+  ```ts
+  import { needle } from "@needle-tools/engine";
+  needle.scene.traverse(obj => { ... });  // access the three.js scene
+  needle.renderer;                         // access the WebGLRenderer
+  needle.sceneData.MyScene.Camera.$components.OrbitControls.autoRotate = true;
+  ```
+- **NEW**: `context.lights` array and `context.mainLight` getter for easy access to all scene lights and the primary directional light
+- Add: `needlePlugins()` can now be called without arguments — the Vite command is resolved automatically. This simplifies setup in frameworks like SvelteKit where `defineConfig` doesn't expose the command:
+  ```js
+  export default defineConfig({ plugins: [sveltekit(), needlePlugins()] });
+  ```
+- Fix: BloomEffect and Sharpening were pulling in the entire `postprocessing` library even in projects that don't use postprocessing, increasing bundle size unnecessarily
+- Fix: SceneSwitcher now shows the object name in the URL when referencing scene objects (instead of just an index)
+- Improved: Vite plugin reliability (fewer unnecessary reloads, cleaner log output)
+
 ## [5.1.0-alpha.1] - 2026-04-10
 - Add: `AnimatorControllerBuilder` for building animator controllers from code (experimental)
 - Add: XR global events now return an unsubscribe function + `onBeforeXRSessionRequest` event
@@ -36,6 +74,15 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Fix: HTML mobile icon not rendering
 - Fix: UI `Text` component absolute font URL handling
 
+## [5.0.4] - 2026-04-20
+- Fix: VideoPlayer not working when tree-shaking is enabled due to URL serializer being removed
+- Fix: ReflectionProbe not cleaning up `envMapRotation` and `envMapIntensity` overrides when removing envMap
+
+## [5.0.3] - 2026-04-08
+- Add: PMREM / FastHDR support for GroundProjection with shader-based blurriness, blending, and alpha controls
+- Fix: MaterialPropertyBlock multi-material change from opaque to transparent
+- Improved: OrbitControls JSDoc for `targetBounds`
+
 ## [5.0.2] - 2026-04-03
 - Updated `@needle-tools/materialx` to 1.6.0:
   - UV coordinate convention handling (glTF ↔ OpenGL) — fixes UV-dependent effects like displacement and procedural noise in the browser