@playcanvas/web-components 0.20.0 → 0.21.0

package/src/app.ts

@@ -1,4 +1,4 @@
-import type { CameraComponent, GraphicsDevice, GraphNode, GSplatComponent, Entity } from 'playcanvas';
+import type { GraphicsDevice, GraphNode, Entity } from 'playcanvas';
 import {
     AppBase,
     AppOptions,
@@ -7,7 +7,6 @@ import {
     FILLMODE_NONE,
     Keyboard,
     Mouse,
-    Picker,
     RESOLUTION_AUTO,
     AnimComponentSystem,
     AnimationComponentSystem,
@@ -60,8 +59,7 @@ import {
     BatchManager,
     SoundManager,
     Lightmapper,
-    XrManager,
-    MeshInstance
+    XrManager
 } from 'playcanvas';
 
 import type { AssetElement } from './asset';
@@ -72,57 +70,9 @@ import type { EntityOwnerElement } from './entity-owner';
 import { LoadingBar } from './loading-bar';
 import type { MaterialElement } from './material';
 import { parseBool, parseEnum, parseNumber } from './parse';
+import { PointerController } from './pointer-controller';
 import type { WasmElement } from './wasm';
 
-/**
- * The event types whose listeners make an element a hover target. Hover resolution walks past
- * elements listening for none of them, so a silent element never swallows an ancestor's
- * enter/leave pair.
- */
-const hoverEventTypes = ['pointerenter', 'pointerleave', 'pointermove'] as const;
-
-/**
- * The canvas listeners each synthesized event type is driven by. Enter and leave are derived
- * from move picks. A click is concluded from the down/up pair, with pointercancel discarding a
- * press the browser takes back (for example a touch that becomes a scroll).
- */
-const canvasEventsFor: Record<(typeof SYNTHESIZED_EVENTS)[number], readonly string[]> = {
-    pointermove: ['pointermove'],
-    pointerenter: ['pointermove'],
-    pointerleave: ['pointermove'],
-    pointerdown: ['pointerdown'],
-    pointerup: ['pointerup'],
-    click: ['pointerdown', 'pointerup', 'pointercancel']
-};
-
-/**
- * How long after a click a further click on the same target still raises the click count that
- * `detail` carries, approximating the platform's double-click time.
- */
-const CLICK_CHAIN_MS = 500;
-
-/**
- * Finds the nearest common inclusive ancestor of two picked nodes - the node a click belongs to
- * when the press and the release picked different geometry, exactly as the DOM assigns a click
- * whose down and up have different targets.
- *
- * @param a - The node the press picked, or `null`.
- * @param b - The node the release picked, or `null`.
- * @returns The nearest common inclusive ancestor, or `null` when there is none.
- */
-const commonAncestor = (a: GraphNode | null, b: GraphNode | null): GraphNode | null => {
-    const ancestors = new Set<GraphNode>();
-    for (let node = a; node !== null; node = node.parent) {
-        ancestors.add(node);
-    }
-    for (let node = b; node !== null; node = node.parent) {
-        if (ancestors.has(node)) {
-            return node;
-        }
-    }
-    return null;
-};
-
 /**
  * Gives `pc-app` the sizing contract of a replaced element (`<video>`, `<img>`): a block-level
  * box that the page's CSS sizes, defaulting to the canvas's own 300x150 intrinsic size, with the
@@ -220,44 +170,16 @@ class AppElement extends AsyncElement {
      */
     private _entityElements = new Map<GraphNode, EntityBaseElement>();
 
-    private _picker: Picker | null = null;
-
-    private _hoveredEntity: EntityBaseElement | null = null;
-
-    // Identifies the newest in-flight hover pick, so out-of-order results can be discarded
-    private _pickToken = 0;
-
-    private _pointerHandlers: Record<string, EventListener | null> = {
-        pointermove: null,
-        pointerdown: null,
-        pointerup: null,
-        pointercancel: null
-    };
-
-    /**
-     * The pick of each pointer's primary-button press, keyed by pointerId and kept while a click
-     * may still conclude it. The promise is stored rather than its result, so a release can
-     * await a press pick that has not resolved yet. Entries are removed by the matching
-     * pointerup or pointercancel, and only ever stored while some element listens for click -
-     * which is also what keeps those two canvas listeners attached.
-     */
-    private _downPicks = new Map<number, Promise<GraphNode | null>>();
-
-    /** Whether any element in the tree listens for click. Maintained by _syncCanvasListeners. */
-    private _clickListened = false;
-
-    /**
-     * The previous click's target, time and count, for chaining successive clicks into the
-     * click count that `detail` carries. `null` until a click has fired.
-     */
-    private _lastClick: { element: EntityBaseElement; time: number; count: number } | null = null;
-
     /**
-     * Serializes dispatch of the discrete synthesized events (pointerdown, pointerup, click),
-     * whose picks resolve in GPU order, not canvas-event order. Replaced on teardown, so a pick
-     * that never resolves cannot stall the dispatches of a later boot.
+     * The pointer-input subsystem: the picker, the canvas handlers, and the synthesized-event
+     * dispatch. The element drives its lifecycle (connect on boot, resize with the drawing
+     * buffer, listener syncs, disconnect on teardown) and hands it the two lookups it needs -
+     * everything else about pointer input lives in the controller.
      */
-    private _dispatchChain: Promise<void> = Promise.resolve();
+    private _pointer = new PointerController({
+        elementFromNode: (node) => this._entityElements.get(node) ?? null,
+        pointerTargets: () => Array.from(this.querySelectorAll<EntityBaseElement>('pc-entity, pc-model, pc-node'))
+    });
 
     private _app: AppBase | null = null;
 
@@ -303,8 +225,8 @@ class AppElement extends AsyncElement {
         // entities. Registered once here rather than on every boot - the sync no-ops while there
         // is no canvas, and a re-booted element must not stack a second set.
         SYNTHESIZED_EVENTS.forEach((type) => {
-            this.addEventListener(`${type}:connect`, () => this._syncCanvasListeners());
-            this.addEventListener(`${type}:disconnect`, () => this._syncCanvasListeners());
+            this.addEventListener(`${type}:connect`, () => this._pointer.syncListeners());
+            this.addEventListener(`${type}:disconnect`, () => this._pointer.syncListeners());
         });
     }
 
@@ -497,7 +419,7 @@ class AppElement extends AsyncElement {
         app.setCanvasFillMode(FILLMODE_NONE);
         app.setCanvasResolution(RESOLUTION_AUTO);
 
-        this._pickerCreate();
+        this._pointer.connect(app, this._canvas!);
 
         // Track the element's box rather than the window: containers resize without any window
         // event (splitter drags, flex reflow, animations). Guarded because jsdom has no
@@ -607,7 +529,7 @@ class AppElement extends AsyncElement {
         this._bootGeneration++;
 
         this._optionsLocked = false;
-        this._pickerDestroy();
+        this._pointer.disconnect();
 
         // Clean up the application. Destroying it destroys every entity, whose destroy hooks
         // unregister them - clear() covers any entity the engine no longer reached.
@@ -648,57 +570,7 @@ class AppElement extends AsyncElement {
         }
         this.app.updateCanvasSize();
         const { width, height } = this.app.graphicsDevice;
-        this._picker?.resize(width, height);
-    }
-
-    private _pickerCreate() {
-        const { width, height } = this.app!.graphicsDevice;
-        this._picker = new Picker(this.app!, width, height);
-
-        // Create bound handlers but don't attach them yet. The move handler is async, so it is
-        // wrapped to discard the promise - a listener must not return one.
-        const listener = (handler: (event: PointerEvent) => void | Promise<void>): EventListener => {
-            return (event: Event) => {
-                handler.call(this, event as PointerEvent);
-            };
-        };
-
-        this._pointerHandlers.pointermove = listener(this._onPointerMove);
-        this._pointerHandlers.pointerdown = listener(this._onPointerDown);
-        this._pointerHandlers.pointerup = listener(this._onPointerUp);
-        this._pointerHandlers.pointercancel = (event: Event) => {
-            this._downPicks.delete((event as PointerEvent).pointerId);
-        };
-
-        // Attach canvas listeners for element listeners registered before this boot (e.g.
-        // handlers created from inline attributes when their elements were first upgraded, or
-        // listeners carried over from before a re-boot)
-        this._syncCanvasListeners();
-    }
-
-    private _pickerDestroy() {
-        if (this._canvas) {
-            Object.entries(this._pointerHandlers).forEach(([type, handler]) => {
-                if (handler) {
-                    this._canvas!.removeEventListener(type, handler);
-                }
-            });
-        }
-
-        this._picker = null;
-        this._hoveredEntity = null;
-        this._pointerHandlers = {
-            pointermove: null,
-            pointerdown: null,
-            pointerup: null,
-            pointercancel: null
-        };
-        this._downPicks.clear();
-        this._clickListened = false;
-        this._lastClick = null;
-
-        // Replace the chain: a pick that never resolves must not stall a later boot's dispatches
-        this._dispatchChain = Promise.resolve();
+        this._pointer.resize(width, height);
     }
 
     /**
@@ -736,313 +608,6 @@ class AppElement extends AsyncElement {
         return this._entityElements.get(entity) ?? null;
     }
 
-    /**
-     * Resolves the element that owns hover for a picked node: the nearest node up the parent
-     * chain - starting with the node itself - whose element listens for any of the hover event
-     * types. Skipping silent elements matches {@link _elementWithListener}, so a registered
-     * element with no hover listeners (a `<pc-model>` host, a plain child entity) is transparent
-     * to hover rather than swallowing a listening ancestor's enter/leave pair.
-     *
-     * @param node - The picked node, or `null`.
-     * @returns The hover-owning element, or `null`.
-     */
-    private _hoverTarget(node: GraphNode | null): EntityBaseElement | null {
-        while (node !== null) {
-            const element = this._entityElements.get(node);
-            if (element && hoverEventTypes.some((type) => element._hasListeners(type))) {
-                return element;
-            }
-            node = node.parent;
-        }
-        return null;
-    }
-
-    /**
-     * Like {@link _elementFromNode}, but skips elements without a listener for `type`, so a hit
-     * on an unlistened child still reaches a listening ancestor.
-     *
-     * @param node - The picked node, or `null`.
-     * @param type - The pointer event type a listener is required for.
-     * @returns The nearest listening element, or `null`.
-     */
-    private _elementWithListener(node: GraphNode | null, type: string): EntityBaseElement | null {
-        while (node !== null) {
-            const element = this._entityElements.get(node);
-            if (element?._hasListeners(type)) {
-                return element;
-            }
-            node = node.parent;
-        }
-        return null;
-    }
-
-    /**
-     * Converts a pointer event's client coordinates into drawing-buffer coordinates - the space
-     * the pick buffer and the camera viewports are laid out in. When the canvas has no CSS box
-     * to map through (jsdom; a hidden canvas receives no pointer events in a browser), the
-     * client coordinates are passed through unmapped and `mapped` is false, so callers know the
-     * coordinates correspond to no real geometry.
-     *
-     * @param event - The pointer event to convert.
-     * @param canvas - The canvas the event was dispatched on.
-     * @returns The buffer-space coordinates, and whether they were actually mapped.
-     */
-    private _getPickerCoordinates(
-        event: PointerEvent,
-        canvas: HTMLCanvasElement
-    ): { x: number; y: number; mapped: boolean } {
-        const canvasRect = canvas.getBoundingClientRect();
-        if (canvasRect.width === 0 || canvasRect.height === 0) {
-            return { x: event.clientX, y: event.clientY, mapped: false };
-        }
-        const scaleX = canvas.width / canvasRect.width;
-        const scaleY = canvas.height / canvasRect.height;
-        return {
-            x: (event.clientX - canvasRect.left) * scaleX,
-            y: (event.clientY - canvasRect.top) * scaleY,
-            mapped: true
-        };
-    }
-
-    /**
-     * Whether a camera's viewport contains the point. A camera renders into its normalized
-     * `rect`, whose origin is the bottom-left of the canvas while buffer coordinates run from
-     * the top-left - so the vertical test flips, as the engine's ElementInput flips it for UI
-     * input. The right and bottom edges are exclusive: a viewport rasterizes the half-open
-     * pixel range [left, right) x [top, bottom), so a coordinate on a shared edge belongs to
-     * the viewport whose first pixel it is - never to the one it just left, whose pick buffer
-     * holds nothing there.
-     *
-     * @param camera - The camera to test.
-     * @param x - The x coordinate, in buffer space.
-     * @param y - The y coordinate, in buffer space.
-     * @param canvas - The canvas the coordinates are relative to.
-     * @returns Whether the camera's viewport contains the point.
-     */
-    private _cameraContains(camera: CameraComponent, x: number, y: number, canvas: HTMLCanvasElement): boolean {
-        const rect = camera.rect;
-        const left = rect.x * canvas.width;
-        const bottom = (1 - rect.y) * canvas.height;
-        const top = bottom - rect.w * canvas.height;
-        return x >= left && x < left + rect.z * canvas.width && y >= top && y < bottom;
-    }
-
-    /**
-     * Picks the scene under the pointer and returns the graph node that was hit, or `null`.
-     *
-     * The camera is resolved the way the engine's ElementInput resolves it for UI input:
-     * enabled cameras are tried topmost-first (they render in ascending `priority` order),
-     * skipping cameras that render to a texture and cameras whose viewport `rect` does not
-     * contain the pointer. A camera that picks nothing ends the search if it clears the color
-     * buffer - its background visually owns the pixel - and otherwise cedes to the cameras
-     * beneath it, so an overlay camera only intercepts picks where it actually drew something.
-     * The pick buffer is prepared per camera, so each camera picks from its own layers.
-     *
-     * The read back is asynchronous because the synchronous {@link Picker.getSelection} is not
-     * supported on WebGPU, where it returns an empty selection rather than failing - which
-     * silently disabled every `onpointer*` handler once WebGPU became the resolved backend. The
-     * async variant works on both backends and does not block the main thread on a GPU read.
-     *
-     * @param event - The pointer event to pick under.
-     * @returns The graph node under the pointer, or `null` if nothing was hit.
-     */
-    private async _pickNode(event: PointerEvent): Promise<GraphNode | null> {
-        const app = this.app;
-        const picker = this._picker;
-        const canvas = this._canvas;
-        if (!app || !picker || !canvas) return null;
-
-        const { x, y, mapped } = this._getPickerCoordinates(event, canvas);
-
-        // Walked from the end: the array is sorted by ascending priority, so the last camera
-        // renders last and sits on top. Read through .at() because a pick handler may remove
-        // cameras while an earlier iteration's read back is in flight.
-        const cameras = app.systems.camera?.cameras ?? [];
-        for (let i = cameras.length - 1; i >= 0; i--) {
-            const camera = cameras.at(i);
-
-            // A camera rendering to a texture is not on the canvas.
-            if (!camera || camera.renderTarget) continue;
-
-            // Coordinates that could not be mapped cannot be tested for containment.
-            if (mapped && !this._cameraContains(camera, x, y, canvas)) continue;
-
-            picker.prepare(camera, app.scene);
-            const selection = await picker.getSelectionAsync(x, y);
-
-            // The element may have disconnected while the read back was in flight.
-            if (!this._picker || !this.app) return null;
-
-            if (selection.length > 0) {
-                const item = selection[0];
-                return item instanceof MeshInstance ? item.node : (item as GSplatComponent).entity;
-            }
-
-            // Nothing hit. A camera that clears the color buffer paints its background over
-            // everything beneath it, so the miss is final; one that does not is an overlay
-            // that the cameras beneath show through, so they get their turn.
-            if (camera.clearColorBuffer) return null;
-        }
-
-        return null;
-    }
-
-    private async _onPointerMove(event: PointerEvent) {
-        if (!this._picker || !this.app) return;
-
-        // Moves arrive faster than a pick resolves, so results can land out of order. Only the
-        // newest pick may update the hover state - an older one describes a pointer position the
-        // user has already left.
-        const token = ++this._pickToken;
-        const node = await this._pickNode(event);
-        if (token !== this._pickToken || !this._picker) return;
-
-        // The hovered element is the nearest one up the node's parent chain with a hover
-        // listener - the nearest-listener rule down/up use. Dispatch is still gated per event
-        // type below: having any hover listener selects the target, each event needs its own.
-        const newHoverEntity = this._hoverTarget(node);
-
-        // Handle enter/leave events
-        if (this._hoveredEntity !== newHoverEntity) {
-            if (this._hoveredEntity && this._hoveredEntity._hasListeners('pointerleave')) {
-                this._hoveredEntity.dispatchEvent(new PointerEvent('pointerleave', event));
-            }
-            if (newHoverEntity && newHoverEntity._hasListeners('pointerenter')) {
-                newHoverEntity.dispatchEvent(new PointerEvent('pointerenter', event));
-            }
-        }
-
-        // Update hover state
-        this._hoveredEntity = newHoverEntity;
-
-        // Handle pointermove event
-        if (newHoverEntity && newHoverEntity._hasListeners('pointermove')) {
-            newHoverEntity.dispatchEvent(new PointerEvent('pointermove', event));
-        }
-    }
-
-    /**
-     * Appends a dispatch step to {@link _dispatchChain}. Must be called synchronously from the
-     * canvas event handler - the order of appends is what carries canvas-event order. A step
-     * that rejects is reported and released, so the steps queued behind it still dispatch.
-     *
-     * @param step - The dispatch work to run once every earlier step has finished.
-     */
-    private _chainDispatch(step: () => Promise<void>) {
-        this._dispatchChain = this._dispatchChain.then(step).catch((error) => {
-            console.error(error);
-        });
-    }
-
-    private _onPointerDown(event: PointerEvent) {
-        if (!this._picker || !this.app) return;
-
-        // Picks stay concurrent - only the dispatch of the results is serialized
-        const pick = this._pickNode(event);
-
-        // A click concludes on the matching pointerup, which needs to know what the press
-        // picked. Primary button only - the only button a click can conclude from - and only
-        // while click is listened for, since it is the click mapping that keeps the pointerup
-        // and pointercancel listeners attached to clean the entry up again.
-        if (this._clickListened && event.button === 0) {
-            this._downPicks.set(event.pointerId, pick);
-        }
-
-        this._chainDispatch(async () => {
-            const node = await pick;
-            if (!this._picker) return; // the element disconnected while the pick was in flight
-
-            const entityElement = this._elementWithListener(node, 'pointerdown');
-            if (entityElement) {
-                entityElement.dispatchEvent(new PointerEvent('pointerdown', event));
-            }
-        });
-    }
-
-    private _onPointerUp(event: PointerEvent) {
-        if (!this._picker || !this.app) return;
-
-        // The press pick this release may conclude as a click. Claimed synchronously, so the
-        // entry is gone before any other event for this pointer can be handled.
-        const downPick = this._downPicks.get(event.pointerId);
-        this._downPicks.delete(event.pointerId);
-
-        const pick = this._pickNode(event);
-
-        this._chainDispatch(async () => {
-            const node = await pick;
-            if (!this._picker) return; // the element disconnected while the pick was in flight
-
-            const entityElement = this._elementWithListener(node, 'pointerup');
-            if (entityElement) {
-                entityElement.dispatchEvent(new PointerEvent('pointerup', event));
-            }
-        });
-
-        // A click fires where the DOM fires it: at the nearest common inclusive ancestor of
-        // what the press and the release picked, for the primary button only. Appended after
-        // the release's own step, so it dispatches after the pointerup that concludes it.
-        if (!downPick || event.button !== 0) return;
-
-        this._chainDispatch(async () => {
-            // A rejected pick was already reported by the press or release step that awaited it;
-            // here it just means no click can conclude.
-            const picked = await Promise.all([downPick, pick]).catch(() => null);
-            if (!picked || !this._picker) return;
-
-            const [downNode, upNode] = picked;
-            const clickElement = this._elementWithListener(commonAncestor(downNode, upNode), 'click');
-            if (clickElement) {
-                const click = new PointerEvent('click', event);
-
-                // The init above copied pointerup's `detail`, which the Pointer Events spec fixes
-                // at 0 - but click is exempt: its detail is the click count, chained here as the
-                // platform chains it (same target, within the double-click window). Overridden
-                // with defineProperty because an event instance used as an init dict cannot have
-                // single fields replaced.
-                const time = performance.now();
-                const last = this._lastClick;
-                const count =
-                    last && last.element === clickElement && time - last.time <= CLICK_CHAIN_MS ? last.count + 1 : 1;
-                this._lastClick = { element: clickElement, time, count };
-                Object.defineProperty(click, 'detail', { value: count });
-
-                clickElement.dispatchEvent(click);
-            }
-        });
-    }
-
-    /**
-     * Attaches exactly the canvas listeners the tree's current element listeners need, and
-     * detaches the rest. Recomputed whenever a listener connects or disconnects anywhere under
-     * this element: several synthesized types can need the same canvas listener (enter, leave
-     * and move all ride the move pick; click rides the down/up pair), so one type's removal
-     * must not detach a listener another type still uses. Re-attaching an attached listener is
-     * a no-op by EventTarget semantics, so no attach state is kept.
-     */
-    private _syncCanvasListeners() {
-        const canvas = this._canvas;
-        if (!canvas) return; // not booted yet: _pickerCreate syncs once the handlers exist
-
-        const elements = Array.from(this.querySelectorAll<EntityBaseElement>('pc-entity, pc-model, pc-node'));
-        const needed = new Set<string>();
-        for (const type of SYNTHESIZED_EVENTS) {
-            if (elements.some((element) => element._hasListeners(type))) {
-                canvasEventsFor[type].forEach((canvasType) => needed.add(canvasType));
-            }
-        }
-        this._clickListened = elements.some((element) => element._hasListeners('click'));
-
-        Object.entries(this._pointerHandlers).forEach(([canvasType, handler]) => {
-            if (!handler) return;
-            if (needed.has(canvasType)) {
-                canvas.addEventListener(canvasType, handler);
-            } else {
-                canvas.removeEventListener(canvasType, handler);
-            }
-        });
-    }
-
     /**
      * Warns that a graphics option was written too late to have any effect. These options are read
      * once, when the element connects and creates its graphics device, so a later write updates

package/src/asset-binding.ts

@@ -0,0 +1,141 @@
+import type { Asset, EventHandle } from 'playcanvas';
+
+import { useAsset } from './asset';
+
+// Keep `export` on these declarations. TypeScript removes the declaration and its inline export
+// when `stripInternal` is enabled. A separate `export { ... }` statement would remain in the
+// generated .d.ts file and refer to a declaration that had been removed.
+
+/**
+ * Functions called when an {@link AssetBinding} finishes loading an asset or encounters an
+ * error.
+ *
+ * @internal
+ */
+export type AssetBindingCallbacks = {
+    /**
+     * Called when the asset has a usable resource. If it was already loaded, this can run before
+     * {@link AssetBinding.bind} returns. Otherwise it runs when the asset fires `load`.
+     */
+    load: (asset: Asset) => void;
+
+    /**
+     * Called when the asset fails to load, including when it had already failed before
+     * {@link AssetBinding.bind} was called. If this is omitted, the binding keeps waiting so a
+     * later successful reload can still call `load`.
+     */
+    error?: (err: string | Error) => void;
+};
+
+/**
+ * Watches the asset currently selected by an element.
+ *
+ * An element can change its asset while the old one is still loading, or disconnect before the
+ * load finishes. This class makes sure callbacks from those older loads do nothing. Calling
+ * {@link bind} stops watching the previous asset and starts watching the new one. Calling
+ * {@link cancel} stops watching altogether.
+ *
+ * Asset lookup goes through {@link useAsset}, so selecting a lazy asset starts its load. The
+ * caller still decides what to do with the result, such as creating scene content, reporting an
+ * error, or marking an element ready.
+ *
+ * Reuse one `AssetBinding` for each asset-valued property throughout the element's lifetime. It
+ * is safe for a callback to call `bind` again: the new asset remains active after the callback
+ * returns.
+ *
+ * @internal
+ */
+export class AssetBinding {
+    /**
+     * Each bind or cancel gets a new number. Event handlers remember the number they were created
+     * with and return if it is no longer current. Old listeners are normally removed as well, but
+     * this check also protects against an event that was already in progress when removal
+     * happened.
+     */
+    private _generation = 0;
+
+    private _loadHandle: EventHandle | null = null;
+
+    private _errorHandle: EventHandle | null = null;
+
+    private _detach() {
+        this._loadHandle?.off();
+        this._loadHandle = null;
+        this._errorHandle?.off();
+        this._errorHandle = null;
+    }
+
+    /**
+     * Stops watching the current asset and prevents its callbacks from running. The binding can
+     * be used again by calling {@link bind}.
+     */
+    cancel() {
+        this._generation++;
+        this._detach();
+    }
+
+    /**
+     * Starts watching the asset registered under `id` and stops watching the previous one. A
+     * missing `id` still clears the previous binding. Looking up a lazy asset starts its load.
+     *
+     * If the asset has already loaded successfully, `load` runs before this method returns. An
+     * earlier failure calls `error` immediately when that callback is provided; without one, the
+     * binding waits for a later successful reload. Assets still loading are watched for the same
+     * two outcomes. Once an event is handled, both listeners are removed.
+     *
+     * @param id - The `id` of the `<pc-asset>` element to bind to.
+     * @param callbacks - Functions to call when loading succeeds or fails.
+     * @returns The selected asset, or `undefined` if no asset has this `id`. The caller decides
+     * how to handle a missing asset.
+     */
+    bind(id: string, callbacks: AssetBindingCallbacks): Asset | undefined {
+        const generation = ++this._generation;
+        this._detach();
+
+        const asset = useAsset(id);
+        if (!asset) {
+            return undefined;
+        }
+
+        const { error } = callbacks;
+
+        if (asset.loaded) {
+            // PlayCanvas sets `loaded` after both success and failure, so a resource must also be
+            // present before this counts as success. Use `!= null` deliberately: `undefined` and
+            // `null` both mean there is no resource, while a valid resource can still be falsy
+            // (for example, an empty text file produces '').
+            if (asset.resource != null) {
+                callbacks.load(asset);
+                return asset;
+            }
+            if (error) {
+                error(`asset '${id}' failed to load`);
+                return asset;
+            }
+        }
+
+        // Old listeners are normally removed by bind or cancel. The number check is a second
+        // safeguard for a late event. Check it before _detach so an old callback cannot remove
+        // the listeners for the current asset. Whichever current event runs first removes both
+        // listeners.
+        this._loadHandle = asset.once('load', () => {
+            if (generation !== this._generation) {
+                return;
+            }
+            this._detach();
+            callbacks.load(asset);
+        });
+
+        if (error) {
+            this._errorHandle = asset.once('error', (err: string | Error) => {
+                if (generation !== this._generation) {
+                    return;
+                }
+                this._detach();
+                error(err);
+            });
+        }
+
+        return asset;
+    }
+}