Update to use the annotations from SuperSplat Viewer

[willeastcott]

• Adds label to hotspot
• Orange hover color
• ...plus some other improvements

[Copilot]

Pull Request Overview

This PR updates the annotation system to match the style and functionality from SuperSplat Viewer. The changes include adding numeric labels to hotspots, implementing an orange hover color for better visual feedback, and refactoring the code to use shared static resources for better performance and maintainability.

• Adds label attribute to annotations for displaying numeric identifiers on hotspots
• Implements hover state with orange color highlighting
• Refactors to use shared static resources (tooltip DOM, layers, mesh) instead of per-instance resources

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 10 comments.

File	Description
examples/assets/scripts/annotation.mjs	Complete refactor of annotation system: adds label support, hover states, shared static resources, improved rendering with depth clamping, and better material handling with custom blend states
examples/annotations.html	Adds label attribute (values "1" through "7") to all seven annotation instances in the jet fighter example

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Multiple rapid calls to hideTooltip() create multiple pending setTimeout callbacks. If hideTooltip() is called multiple times quickly, earlier timeouts might incorrectly hide the tooltip even if it was shown again in between.

Consider storing the timeout ID and clearing it before setting a new one:

if (this._hideTimeoutId) {
    clearTimeout(this._hideTimeoutId);
}
this._hideTimeoutId = setTimeout(() => { ... }, 200);

[Copilot]

This document-level click listener is added every time a new annotation is initialized, creating multiple duplicate listeners. This will cause hideTooltip() to be called multiple times per document click, once for each annotation instance.

Consider moving this listener to the static initialization in _initializeStatic() method to ensure it's only added once.

[Copilot]

The 'prerender' event listener is added to this.app for every annotation instance but is never removed. This creates a memory leak where event handlers persist even after the annotation entity is destroyed. Although the 'destroy' handler on line 443 cleans up DOM elements and materials, it doesn't remove this event listener.

Consider adding this.app.off('prerender', handler) in the destroy handler, or use the built-in update() method instead of 'prerender' event for per-instance logic.

[Copilot]

The hideTooltip() method fires a 'hide' event on this (the annotation instance), but if this method is called after the annotation has been destroyed, it will attempt to fire an event on a destroyed script instance, which could cause errors.

This can occur when hideTooltip() is called from the timeout on line 514, after the entity has been destroyed. Consider checking if the instance is still valid before firing the event, or clearing the timeout in the destroy handler.

[Copilot]

Typo in comment: "Create material the base and overlay material" should be "Create the base and overlay materials".

Suggested change

	// Create material the base and overlay material
	// Create the base and overlay materials

[Copilot]

The viewMatrix.transformPoint() call modifies the position vector in place and stores the result in vec. However, position is obtained from this.entity.getPosition() which returns the entity's position vector directly (not a copy). This means the entity's actual position is being modified, which could cause unexpected behavior.

Consider creating a copy of the position before transforming it: const position = this.entity.getPosition().clone(); or use vec.copy(position) before transforming.

[Copilot]

[nitpick] The guard check if (this._styleSheet) return; was removed from _injectStyles(). Now styles are injected every time, but the method is only called once from _initializeStatic() which has its own guard. This is fine, but the method no longer protects itself from being called multiple times independently.

While this works with the current code structure, consider adding back the guard for defensive programming, or document that this method should only be called once.

Suggested change

	static _injectStyles(size) {
	static _injectStyles(size) {
	if (Annotation.styleSheet) return;

[Copilot]

Event listeners added to this.hotspotDom (click, pointerenter, pointerleave) are not explicitly removed in the destroy handler. While calling this.hotspotDom.remove() on line 444 should eventually clean up the listeners when the element is garbage collected, it's better practice to explicitly remove them to ensure immediate cleanup.

Consider storing references to the handler functions and calling removeEventListener() in the destroy handler.

[Copilot]

Finding the camera component without error handling could cause a runtime error if no camera component exists in the scene. The call app.root.findComponent('camera') could return null, and accessing .entity on null would throw an error.

Consider adding a null check or providing a more informative error message:

const cameraComponent = app.root.findComponent('camera');
if (!cameraComponent) {
    throw new Error('Annotation: No camera component found in scene');
}
Annotation.camera = cameraComponent.entity;

Suggested change

	Annotation.camera = app.root.findComponent('camera').entity;
	const cameraComponent = app.root.findComponent('camera');
	if (!cameraComponent) {
	throw new Error('Annotation: No camera component found in scene');
	}
	Annotation.camera = cameraComponent.entity;

[Copilot]

Setting material opacity on every prerender frame (line 474-477) triggers material updates even when the opacity hasn't changed. This is inefficient if Annotation.opacity is static.

Consider only updating the material parameters when Annotation.opacity actually changes, or caching the last set opacity value to avoid redundant updates.