@needle-tools/engine 5.1.0-canary.db0c38f → 5.1.0-canary.e7c2511

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,49 @@ 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-29
+#### Added
+- `AudioClip` type with standalone playback control — use with `@serializable(AudioClip)` for direct audio clip references
+- `AudioSource` spatial blend support via dual-path audio graph for smooth 2D/3D crossfade
+- UI Text default static font from Needle CDN with absolute font URL support
+- `DragControls` EventList support
+
+#### Fixed
+- UI Text font URL resolution when loading GLBs from external hosts (e.g. CDN)
+- `AudioSource` spatial rolloff factor and `play()` reliability
+- `Animation` `play()` with `{ exclusive: false }` not stopping already-running clips
+- XR lifecycle — spurious `onLeaveXR` calls for scripts that never entered XR
+- `OrbitControls` lookBounds lerp and distance-relative gizmo sizes
+- `CursorFollow` self-intersection and snapToSurface raycast direction
+- Vite `makeFilesLocal` and alias plugins now respect `vite.config` `base`
+- `three-mesh-bvh` worker failing to load in local dev server
+- `VideoPlayer` URL serializer tree-shaken out in code-only projects
+- `ReflectionProbe` not cleaning up overrides when removed
+## [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 +79,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