@needle-tools/engine 5.1.0-next.1780579670.dramatic-pierogi.b8fa941 → 5.1.1

package/CHANGELOG.md

@@ -4,6 +4,125 @@ 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] - 2026-06-23
+
+### ⭐ Highlights
+
+#### **Scene Bindings — Fully Typed Scenes**
+Your glTF and GLB scenes now come with auto-generated TypeScript types. Access nodes, components, and properties with full autocomplete and type checking via `ctx.sceneData` or the new `needle` shorthand — no configuration required. Types regenerate automatically whenever your scene files change, and it works with local files, remote URLs, and Needle Cloud assets alike.
+```ts
+const cam   = ctx.sceneData.MyScene.MainCamera.$object;                      // THREE.PerspectiveCamera
+const orbit = ctx.sceneData.MyScene.MainCamera.$components.OrbitControls;    // typed!
+orbit.autoRotate = true;
+```
+
+#### **First-Class Framework Support**
+Needle Engine now feels at home in any modern web stack. SSR support lets you import the engine in SvelteKit, Next.js, and Nuxt without crashes, JSX type declarations bring full autocomplete to React, Preact, SolidJS, and friends, and the new `needle` shorthand gives you instant access to the current context from anywhere — components, button handlers, or plain JavaScript.
+```ts
+import { needle } from "@needle-tools/engine";
+needle.scene.traverse(obj => { ... });   // access the three.js scene
+needle.renderer;                          // access the WebGLRenderer
+```
+
+#### **Embed Anywhere with `<needle-app>`**
+Drop a published Needle Engine app into any web page with a single element — no build setup, custom code, or framework required. It handles cross-origin loading for you and works inside iframes.
+```html
+<needle-app src="https://your-app.needle.run"></needle-app>
+```
+
+#### **Animation & Timelines from Code** *(preview)*
+A new set of builder APIs lets you create animations, animator controllers, and timelines entirely in code, with typed keyframes and inline track definitions. Great for procedural content, runtime-generated sequences, and tooling.
+```ts
+const timeline = TimelineBuilder.create("MyTimeline")
+    .animationTrack("Walk", animator).clip(walkClip, { duration: 2 })
+    .activationTrack("FX", vfxObject).activate({ start: 1, duration: 0.5 })
+    .build();
+director.playableAsset = timeline;
+```
+
+#### **DragControls — A Big Upgrade**
+`DragControls` received a major overhaul with a new constraint system: keep-scale, two-touch scaling with min/max limits, refined hit regions, and a dedicated screen-space drag mode for AR. Single-touch dragging is now more predictable, and reliability is improved across snapping, side views, and multi-input scenarios.
+
+#### **MaterialX — Faster & Richer**
+The bundled MaterialX runtime jumps to **1.7.0** with faster environment lighting (new radiance sampling modes and PMREM support), better Three.js integration, and overall performance improvements.
+
+#### **Cleaner Component Lifecycles**
+A new `autoCleanup` API and a typed `Context.events` bus make it easy to write components that tidy up after themselves. Many subscription APIs — input, networking, and XR events — now return an unsubscribe function that pairs perfectly with `autoCleanup`.
+```ts
+onEnable() {
+    this.autoCleanup(this.context.input.addEventListener("pointerdown", evt => { ... }));
+    this.autoCleanup(this.context.connection.beginListen("my-event", data => { ... }));
+}
+```
+
+**Added**
+- **Scene Bindings** — auto-generated, fully typed access to your scenes via `ctx.sceneData` / `needle.sceneData`
+- **SSR support** for SvelteKit, Next.js, and Nuxt, plus **JSX type declarations** for React, Preact, SolidJS and more
+- **`needle` shorthand** for quick access to the current engine context from anywhere
+- **`<needle-app>`** — embed a published Needle Engine app in any web page ([docs](<https://engine.needle.tools/docs/how-to-guides/deployment/embedding>))
+- **`Context.events`** — a typed event bus for decoupled component communication:
+  ```ts
+  context.events.on("scene-content-changed", e => console.log(e.object));
+  context.events.emit<{ pts: number }>("scored", { pts: 10 });
+  ```
+- **`autoCleanup`** on `Behaviour` — register disposables and cleanup tied to the component lifecycle
+- **Builder APIs** *(preview)* — `TimelineBuilder`, `AnimatorControllerBuilder`, and `AnimationBuilder` for defining timelines, controllers, and animations in code with typed keyframes and inline tracks
+- `DragControls`: new constraint system with `keepScale`, two-touch scale limits, refined hit regions, a screen-space AR drag mode, and `EventList` support
+- `Skybox`: new `background-rotation` / `environment-rotation` attributes and `background-image-loaded` / `environment-image-loaded` events
+- `WebXRImageTracking`: per-frame `imageTracked` event with typed access to the tracked object, plus `resetImage` / `resetAllImages` to re-arm markers without restarting XR:
+  ```ts
+  imageTracking.imageTracked.addEventListener(evt => console.log(evt.object, evt.image));
+  ```
+- `AudioClip` type with standalone playback control, `AudioSource` spatial blend and `.opus` support
+- `context.lights` array and `context.mainLight` getter for quick access to scene lighting
+- `NeedleXRSession.appClipUrl` — launch a custom-branded Needle AppClip experience on iOS AR (provide your registered `appclip.needle.tools/x/…` URL or experience id) for your own App Clip card title and image (custom branding requires PRO — see [Custom Branding for iOS AR](https://engine.needle.tools/docs/how-to-guides/xr/ios-webxr-app-clip#custom-branding-for-ios-ar))
+- Physics raycast `includeTriggers` option
+- Unsubscribe functions returned from `Input`, `Networking`, and XR event subscriptions
+- `needlePlugins()` can now be called without arguments — the Vite command is resolved automatically:
+  ```js
+  export default defineConfig({ plugins: [sveltekit(), needlePlugins()] });
+  ```
+
+**Changed**
+- `OrbitControls` now uses `lookAtTarget` / `lockLookAtTarget`, with smoother focus and camera transitions
+- Postprocessing moved to core (`context.postprocessing`); tonemapping-only setups skip the extra pass
+- Timeline track classes renamed for consistency (e.g. `AnimationTrackHandler` → `TimelineAnimationTrack`)
+- `GroundProjectionEnv.applyOnAwake` now defaults to `true`, matching Unity and Blender
+
+**Fixed & Improved**
+- Major `DragControls` reliability improvements across snap points, AR drag, side views, and multi-input handover
+- More reliable camera handling (fallback camera, `fitCamera`, scene clearing)
+- More efficient `Skybox` attribute handling and load deduplication
+- Smoother, more reliable progressive LOD loading and disposal, including texture-only LODs that update correctly with camera distance
+- `AudioSource` on iOS now survives a device lock / audio-session interruption and resumes automatically
+- `SceneSwitcher`: `?scene=` honored for in-scene object references, with prefab preview support
+- `VoIP` improvements including better iOS mic handling and shared `AudioContext`
+- Faster initial loading via improved dependency chunking
+- Updated MaterialX runtime to **1.7.0** with faster environment lighting and PMREM support
+- General reliability and stability improvements throughout the engine and Vite plugin
+
+## [5.1.0-beta.1] - 2026-06-09
+
+**Fixed**
+- Progressive loading: texture LODs no longer get stuck for meshes that only have texture LODs (no mesh LODs); screen coverage is computed unconditionally again so texture LODs update with camera distance
+
+## [5.1.0-alpha.9] - 2026-06-04
+
+**Added**
+- `<needle-app>` — embed a published Needle Engine app in any web page (with custom code etc) ([docs](<https://engine.needle.tools/docs/how-to-guides/deployment/embedding>))
+
+**Changed**
+- `<needle-app>`: improved cross-origin handling and `src` parsing
+- `ScrollFollow`: now works inside an iframe (uses the top window)
+
+**Fixed**
+- iOS audio: `AudioSource` playback now survives a device lock / audio-session interruption and resumes automatically on unlock
+- `SceneSwitcher`: `?scene=` is now honored for scenes referenced as in-scene `Object3D`s; scene preview loading supports prefabs and correct parenting under the SceneSwitcher
+- `DragControls`: widened the two-pointer scale clamp range and now reads world scale from the matrix columns
+- `EventList`: corrected the arguments passed to overridden methods
+- `serializeObject`: fixed `Color` / `Euler` / object-reference serialization, and `OneEuroFilter.reset()`
+- Prevented a `TypeError` when a scene-data error proxy is coerced to a string
+
 ## [5.1.0-alpha.7] - 2026-05-29
 
 **Highlights:**