@needle-tools/engine 5.1.0-canary.deec6e4 → 5.1.0-canary.e6680fa

package/CHANGELOG.md

@@ -4,6 +4,104 @@ 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.6] - 2026-05-12
+- `WebXRImageTracking.imageTracked` event — invoked every frame an image is tracked, with typed access to the tracked object instance:
+  ```ts
+  imageTracking.imageTracked.addEventListener(evt => {
+      console.log(evt.object, evt.image);
+  });
+  ```
+- `WebXRImageTracking.resetImage`, `resetAllImages`, and `WebXRTrackedImage.reset()` — reset Needle's image tracking object state so a marker can be re-armed without restarting XR.
+- `?debugimagetracking-reset` URL parameter adds a Needle menu button for resetting image tracking state during testing.
+- `?stats` URL parameter now also logs renderer info (DPR, window DPR, antialias, MSAA samples, drawing buffer resolution)
+
+
+## [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
@@ -4170,4 +4268,4 @@ better lighting response
 - fixated flatbuffers dependency to 2.0.4 due to breaking changes and bugs in 2.0.6
 
 ## [1.0.0-pre] - 2022-04-19
-- initial release
+- initial release

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