@needle-tools/engine 5.1.0-canary.e9062c0 → 5.1.0-canary.f57972c

package/CHANGELOG.md

@@ -4,6 +4,117 @@ 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.5] - 2026-05-08
+**Added**
+- `Context.events` — typed event bus for decoupled component communication. Known events get autocomplete; custom events can be typed at the call site:
+  ```ts
+  context.events.on("scene-content-changed", e => console.log(e.object));
+  context.events.emit<{ pts: number }>("scored", { pts: 10 });
+  ```
+- `ContactShadows` auto-refit — when `autoFit` is enabled, shadows automatically refit when scene content changes (e.g. SceneSwitcher load, DropListener asset loading)
+- `Input.addEventListener` now returns an unsubscribe function (works with `autoCleanup`):
+  ```ts
+  this.autoCleanup(this.context.input.addEventListener("pointerdown", (evt) => { ... }));
+  ```
+- `AnimationBuilder` — low-level API for defining animation tracks with typed keyframes and tween shorthands. Used by `AnimatorControllerBuilder` and `TimelineBuilder` for inline `.track()` calls
+- `TimelineBuilder` typed track builder interfaces per track type (`AnimationTrackBuilder`, `AudioTrackBuilder`, etc.) with inline `.track()` support for keyframe animation
+- `AnimatorControllerBuilder`: inline `.track()` for defining animation directly on states, support for `TrackDescriptor` arrays as clip sources, simplified `exitTime` (replaces separate `hasExitTime` flag)
+- Physics raycast `includeTriggers` option — opt-in to hitting trigger/sensor colliders (skipped by default)
+
+**Changed**
+- Timeline track classes renamed for consistency: `AnimationTrackHandler` → `TimelineAnimationTrack`, `AudioTrackHandler` → `TimelineAudioTrack`, `ActivationTrackHandler` → `TimelineActivationTrack`, `ControlTrackHandler` → `TimelineControlTrack`, `MarkerTrackHandler` → `TimelineMarkerTrack`, `TrackHandler` → `TimelineTrackHandler`
+- `OrbitControls.fitCamera` deprecated overload removed from type declarations (runtime still accepts `Object3D` for backwards compat — use `fitCamera({ objects: [...] })` instead)
+
+**Fixed**
+- `OrbitControls`: programmatic camera transitions (e.g. `fitCamera`) no longer interrupted continuously during an ongoing drag — only at interaction start
+- `fitCamera` with `centerCamera: "y"` producing incorrect camera elevation when camera was above the scene center
+- `Animator`: switching `runtimeAnimatorController` now properly disposes the previous controller
+- `AnimatorController.dispose()` guard against missing mixer
+- `CursorFollow.snapToSurface` incorrect property description removed
+- Vite 8 compatibility fixes
+
+## [5.1.0-alpha.4] - 2026-05-06
+#### Added
+- `autoCleanup` on `Behaviour` — register disposables or cleanup functions tied to the component lifecycle. Automatically cleaned up on disable or destroy depending on when registered:
+  ```ts
+  onEnable() {
+      this.autoCleanup(on(window, "resize", () => { ... }));
+      this.autoCleanup(this.context.connection.beginListen("my-event", () => { ... }));
+  }
+  ```
+- `TimelineBuilder` API for building timeline assets from code:
+  ```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;
+  ```
+- `PlayableDirector`: expose `tracks` and `activationTracks` getters, support runtime `playableAsset` assignment with automatic graph rebuild
+- `PhysicsCollider`: expose `density` property, add `@validate` decorator for automatic property updates at runtime
+- Timeline `AudioTrack` volume getter/setter
+- `Networking`: `beginListen` now returns an unsubscribe function (backwards compatible — `stopListen` still works):
+  ```ts
+  const unsub = this.context.connection.beginListen("my-event", (data) => { ... });
+  unsub(); // or use this.autoCleanup(unsub)
+  ```
+
+#### Changed
+- Serialization: consolidated instantiate reference resolution into a unified system — fixes cloned timelines, EventLists, SignalReceivers, and deep component references not resolving correctly after `instantiate()`
+- Removed legacy `AvatarLoader`, `AvatarBlink_Simple`, `AvatarEyeLook_Rotation`, `Avatar_Brain_LookAt`, `Avatar_MouthShapes`, `Avatar_MustacheShake` components
+
+#### Fixed
+- `@validate` decorator wrapping `__internalAwake` multiple times when components were re-activated
+- Instantiated scenes with timeline `SignalReceiver` not resolving EventList object references
+- `instantiate()` not including cloned Object3D GUIDs in the guids map
+- `Light` component throwing on unsupported light types (now logs error without breaking deserialization)
+- Worker URLs producing incorrect paths for SPA deployments
+- Vite license and project identifier error handling for non-500 status codes
+- Rapier physics `dispose()` not clearing internal state (freed world could cause crashes)
+
+## [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 +147,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

package/SKILL.md

@@ -58,6 +58,9 @@ export class HelloWorld extends Behaviour {
 **Code-only (no Unity/Blender):**
 Scaffold a project with `npm create needle`, write TypeScript components, and build scenes entirely from code. Use `onStart`, `onUpdate`, and other lifecycle hooks to set up scenes, or create components extending `Behaviour`. This is a fully supported first-class workflow.
 
+**CDN with import maps (no bundler):**
+For quick prototypes, embedding in existing sites, or projects without a build pipeline. Use `<script type="importmap">` to map bare specifiers to CDN URLs, then write standard ES module code with `import` statements — no Vite, no npm, no `node_modules` required. **Important:** three.js must come from `@needle-tools/engine/dist/three.min.js`, not a standalone three.js CDN. See [CDN & Import Maps](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/integration.md) for full examples and rules.
+
 **Unity or Blender as visual editors:**
 Unity/Blender export scenes as GLB files into `assets/`, with component data serialized in glTF extensions. At runtime, the engine deserializes this into TypeScript components. A component compiler auto-generates C# stubs (Unity) or JSON (Blender) so custom TS components appear in the editor inspector. The editors are tools for visual scene setup; the runtime is pure web/TypeScript. Note: the editor controls the engine version in `package.json` — to force a version, use `"@needle-tools/engine": "npm:@needle-tools/engine@5.0.1"`.
 
@@ -417,7 +420,7 @@ Read these **only when needed** — don't load them all upfront:
 - 🌐 [Networking](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/networking.md) — connection API, SyncedRoom, PlayerSync, @syncField, SyncedTransform, Voip, ScreenCapture, guid persistence
 - 🥽 [WebXR](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/xr.md) — VR/AR sessions, XRRig, controllers, pointer events in XR, image tracking, depth sensing, camera access, mesh detection, DOM overlay, iOS AR, multiplayer avatars
 - 🚀 [Deployment](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/deployment.md) — Needle Cloud (GitHub Actions, CLI), Vercel, Netlify, other platforms
-- 🔗 [Framework Integration](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/integration.md) — React, Svelte, Vue, Next.js, SvelteKit patterns
+- 🔗 [Framework Integration](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/integration.md) — React, Svelte, Vue, Next.js, SvelteKit patterns, CDN with import maps
 - 💡 [Component Examples](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/examples.md) — practical examples: click handling, runtime loading, networking, materials, code-only scenes, input, coroutines
 - 🐛 [Troubleshooting](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/references/troubleshooting.md) — error messages, unexpected behavior, build failures, **runtime logs at `node_modules/.needle/logs/`**, build info
 - 🧩 [Component Template](https://raw.githubusercontent.com/needle-tools/ai/refs/heads/main/providers/claude/plugin/skills/needle-engine/templates/my-component.ts) — annotated starting point for new components