@playcanvas/web-components 0.12.0 → 0.13.1

package/README.md

@@ -30,7 +30,7 @@ PlayCanvas Web Components are a set of custom HTML elements for building 3D inte
 
 ## Examples
 
-<img width="3840" height="2160" alt="image" src="https://github.com/user-attachments/assets/e113cd2a-300d-4713-a1f4-ada647a8f04c" />
+<img width="5120" height="2160" alt="examples" src="https://github.com/user-attachments/assets/92cf1156-c93f-46b5-8d05-e576967ceaf3" />
 
 See PlayCanvas Web Components in action here: https://playcanvas.github.io/web-components/examples
 

package/dist/app.d.cts

@@ -0,0 +1,281 @@
+import type { Entity } from 'playcanvas';
+import { AppBase } from 'playcanvas';
+import { AsyncElement } from './async-element.cjs';
+import type { EntityBaseElement } from './entity-base.cjs';
+/**
+ * The AppElement interface provides properties and methods for manipulating
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-app/ | `<pc-app>`} elements.
+ * The AppElement interface also inherits the properties and methods of the
+ * {@link HTMLElement} interface.
+ *
+ * The element is sized like a replaced element such as `<video>`: a block-level box that the
+ * page's CSS controls, 300x150 by default. The application's canvas always fills the element,
+ * and the drawing buffer resolution follows the element's size (capped by `max-pixel-ratio`),
+ * tracked live via a ResizeObserver — so the element can be embedded at any size, resized by
+ * its container, or made fullscreen with ordinary CSS such as `width: 100vw; height: 100dvh`.
+ *
+ * @fires {ProgressEvent} progress - Fired while the application preloads its assets. `loaded` and
+ * `total` are asset counts, not bytes, and an asset that fails to load still counts as loaded.
+ * Fired at least once per boot, and the final event always has `loaded` equal to `total`. Does
+ * not bubble.
+ *
+ * @fires {ErrorEvent} error - Fired when the application cannot boot because no graphics device
+ * could be created (for example, a browser with WebGL disabled). `message` names the requested
+ * backends and `error` holds the underlying failure. The element never becomes ready
+ * and `app` stays `null` — listen for this event to show a fallback UI. Removing the element and
+ * re-inserting it retries the boot with its current attributes. Does not bubble.
+ */
+declare class AppElement extends AsyncElement {
+    /**
+     * The canvas element.
+     */
+    private _canvas;
+    private _alpha;
+    private _backend;
+    private _antialias;
+    private _depthBuffer;
+    private _stencilBuffer;
+    private _maxPixelRatio;
+    private _loadingBar;
+    /**
+     * Set once the graphics options above have been handed to `createGraphicsDevice`, after which
+     * writing any of them changes nothing. Guards the warning in {@link _warnIfBooted}, and is
+     * cleared on disconnect so a re-connected element boots from its current attributes.
+     */
+    private _optionsLocked;
+    private _bar;
+    /**
+     * Incremented on every connect and disconnect. Boot captures the value on entry and abandons
+     * itself wherever it resumes from an await if the value has moved on — so a boot whose
+     * element was removed cannot complete against a torn-down element, and a boot whose element
+     * was removed and re-inserted (which starts a boot of its own) cannot race the newer one.
+     */
+    private _bootGeneration;
+    /**
+     * The elements backing this application's entities, keyed by the entity itself. Registered
+     * by EntityElement at creation (and NodeElement at binding) and removed when an entity is
+     * destroyed or unbound, this joins engine scene nodes back to their owning elements by
+     * identity - never by name.
+     */
+    private _entityElements;
+    private _picker;
+    private _hasPointerListeners;
+    private _hoveredEntity;
+    private _pickToken;
+    private _pointerHandlers;
+    private _app;
+    private _loadProgress;
+    /**
+     * Tracks the element's box so the drawing buffer and picker follow it. Created per boot once
+     * the application exists, and disconnected on teardown. `null` where ResizeObserver is
+     * unavailable (jsdom), where the boot-time resolution set is the only sizing that happens.
+     */
+    private _resizeObserver;
+    /**
+     * The PlayCanvas application instance. `null` until the element is ready, and again once it
+     * has been removed from the document — await {@link whenReady} or the element's `ready()`
+     * promise before accessing it.
+     * @returns The application instance, or `null`.
+     */
+    get app(): AppBase | null;
+    /**
+     * The asset preload progress of the application, as a fraction from 0 to 1. It is 0 until
+     * preloading begins (and again once the element has been removed from the document), and 1
+     * once preloading has finished — including when there was nothing to preload. Read this to
+     * initialize a loading UI; subsequent updates arrive via the `progress` event.
+     * @returns The preload progress.
+     */
+    get loadProgress(): number;
+    /**
+     * Creates a new AppElement instance.
+     *
+     * @ignore
+     */
+    constructor();
+    connectedCallback(): Promise<void>;
+    disconnectedCallback(): void;
+    /**
+     * Syncs the drawing buffer and the picker to the canvas's current CSS size. The picker must
+     * track the buffer, or picks would land at stale coordinates after a resize. Skipped while
+     * an XR session presents - the session owns the buffer size.
+     */
+    private _syncCanvasSize;
+    private _pickerCreate;
+    private _pickerDestroy;
+    /**
+     * Returns the `<pc-entity>` or `<pc-node>` element whose backing entity is `entity`, or
+     * `null` if the entity is not fronted by an element of this application - for example, an
+     * unbound node inside a model's instantiated hierarchy, or an entity created through the
+     * engine API.
+     *
+     * @param entity - The entity to look up.
+     * @returns The element fronting the entity, or `null`.
+     */
+    elementFromEntity(entity: Entity): EntityBaseElement | null;
+    /**
+     * Resolves the element that owns a picked node: the nearest node up the parent chain -
+     * starting with the node itself - that is fronted by a `<pc-entity>` or `<pc-node>` of this
+     * application. A hit inside a model's instantiated hierarchy therefore resolves to the
+     * nearest bound `<pc-node>`, or failing that the element hosting the model.
+     *
+     * @param node - The picked node, or `null`.
+     * @returns The owning element, or `null`.
+     */
+    private _elementFromNode;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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 _pickNode;
+    private _onPointerMove;
+    private _onPointerDown;
+    private _onPointerUp;
+    private _onPointerListenerAdded;
+    private _onPointerListenerRemoved;
+    /**
+     * 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
+     * only the element's own property - silently, without this.
+     *
+     * @param name - The name of the option, as its attribute.
+     */
+    private _warnIfBooted;
+    /**
+     * Sets whether the frame buffer has an alpha channel, which is what lets the page show through
+     * wherever the scene has not drawn. Read only when the application boots.
+     * @param value - The alpha flag.
+     */
+    set alpha(value: boolean);
+    /**
+     * Gets whether the frame buffer has an alpha channel.
+     * @returns The alpha flag.
+     */
+    get alpha(): boolean;
+    /**
+     * Sets whether the frame buffer is anti-aliased. Read only when the application boots.
+     * @param value - The antialias flag.
+     */
+    set antialias(value: boolean);
+    /**
+     * Gets whether the frame buffer is anti-aliased.
+     * @returns The antialias flag.
+     */
+    get antialias(): boolean;
+    /**
+     * Sets the graphics backend. Defaults to 'webgpu', which falls back to 'webgl2' if WebGPU
+     * is not supported by the browser. Read only when the application boots.
+     * @param value - The graphics backend ('webgpu', 'webgl2', or 'null').
+     */
+    set backend(value: 'webgpu' | 'webgl2' | 'null');
+    /**
+     * Gets the graphics backend.
+     * @returns The graphics backend.
+     */
+    get backend(): "webgpu" | "webgl2" | "null";
+    /**
+     * Sets whether the frame buffer has a depth buffer, which the renderer needs to resolve which
+     * surface is nearest the camera. Read only when the application boots.
+     * @param value - The depth buffer flag.
+     */
+    set depthBuffer(value: boolean);
+    /**
+     * Gets whether the frame buffer has a depth buffer.
+     * @returns The depth buffer flag.
+     */
+    get depthBuffer(): boolean;
+    /**
+     * Sets whether the application shows its built-in loading bar while it boots and preloads its
+     * assets. Enabled by default; setting `false` removes the bar immediately, while setting
+     * `true` has no effect until the element is next connected. The bar can be themed with the
+     * CSS custom properties `--pc-loading-bar-color`, `--pc-loading-bar-background` and
+     * `--pc-loading-bar-height`.
+     * @param value - The loading bar flag.
+     */
+    set loadingBar(value: boolean);
+    /**
+     * Gets whether the application shows its built-in loading bar while it boots and preloads
+     * its assets.
+     * @returns The loading bar flag.
+     */
+    get loadingBar(): boolean;
+    /**
+     * Sets the cap on the pixel ratio the application renders at. The canvas is sized by the
+     * smaller of this value and the display's own device pixel ratio, so the default of `Infinity`
+     * renders at full physical resolution, `1` renders at CSS resolution, and an intermediate
+     * value such as `2` keeps a dense display sharp without paying for every one of its pixels.
+     * Must be greater than 0. Unlike the other graphics options, this applies immediately.
+     * @param value - The maximum pixel ratio.
+     */
+    set maxPixelRatio(value: number);
+    /**
+     * Gets the cap on the pixel ratio the application renders at.
+     * @returns The maximum pixel ratio.
+     */
+    get maxPixelRatio(): number;
+    /**
+     * Sets whether the frame buffer has a stencil buffer, which stencil-based effects and UI
+     * masking need. Read only when the application boots.
+     * @param value - The stencil buffer flag.
+     */
+    set stencilBuffer(value: boolean);
+    /**
+     * Gets whether the frame buffer has a stencil buffer.
+     * @returns The stencil buffer flag.
+     */
+    get stencilBuffer(): boolean;
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+}
+export { AppElement };

package/dist/app.d.ts

@@ -1,17 +1,29 @@
 import type { Entity } from 'playcanvas';
 import { AppBase } from 'playcanvas';
-import { AsyncElement } from './async-element';
-import type { EntityBaseElement } from './entity-base';
+import { AsyncElement } from './async-element.js';
+import type { EntityBaseElement } from './entity-base.js';
 /**
  * The AppElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-app/ | `<pc-app>`} elements.
  * The AppElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * The element is sized like a replaced element such as `<video>`: a block-level box that the
+ * page's CSS controls, 300x150 by default. The application's canvas always fills the element,
+ * and the drawing buffer resolution follows the element's size (capped by `max-pixel-ratio`),
+ * tracked live via a ResizeObserver — so the element can be embedded at any size, resized by
+ * its container, or made fullscreen with ordinary CSS such as `width: 100vw; height: 100dvh`.
+ *
  * @fires {ProgressEvent} progress - Fired while the application preloads its assets. `loaded` and
  * `total` are asset counts, not bytes, and an asset that fails to load still counts as loaded.
  * Fired at least once per boot, and the final event always has `loaded` equal to `total`. Does
  * not bubble.
+ *
+ * @fires {ErrorEvent} error - Fired when the application cannot boot because no graphics device
+ * could be created (for example, a browser with WebGL disabled). `message` names the requested
+ * backends and `error` holds the underlying failure. The element never becomes ready
+ * and `app` stays `null` — listen for this event to show a fallback UI. Removing the element and
+ * re-inserting it retries the boot with its current attributes. Does not bubble.
  */
 declare class AppElement extends AsyncElement {
     /**
@@ -53,6 +65,12 @@ declare class AppElement extends AsyncElement {
     private _pointerHandlers;
     private _app;
     private _loadProgress;
+    /**
+     * Tracks the element's box so the drawing buffer and picker follow it. Created per boot once
+     * the application exists, and disconnected on teardown. `null` where ResizeObserver is
+     * unavailable (jsdom), where the boot-time resolution set is the only sizing that happens.
+     */
+    private _resizeObserver;
     /**
      * The PlayCanvas application instance. `null` until the element is ready, and again once it
      * has been removed from the document — await {@link whenReady} or the element's `ready()`
@@ -76,7 +94,12 @@ declare class AppElement extends AsyncElement {
     constructor();
     connectedCallback(): Promise<void>;
     disconnectedCallback(): void;
-    private _onWindowResize;
+    /**
+     * Syncs the drawing buffer and the picker to the canvas's current CSS size. The picker must
+     * track the buffer, or picks would land at stale coordinates after a resize. Skipped while
+     * an XR session presents - the session owns the buffer size.
+     */
+    private _syncCanvasSize;
     private _pickerCreate;
     private _pickerDestroy;
     /**
@@ -108,10 +131,45 @@ declare class AppElement extends AsyncElement {
      * @returns The nearest listening element, or `null`.
      */
     private _elementWithListener;
+    /**
+     * 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;
+    /**
+     * 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;
     /**
      * 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

package/dist/asset.d.cts

@@ -0,0 +1,224 @@
+import { Asset } from 'playcanvas';
+import { AsyncElement } from './async-element.cjs';
+type AddressMode = 'repeat' | 'clamp' | 'mirror';
+type MinFilterMode = 'nearest' | 'linear' | 'nearest-mip-nearest' | 'linear-mip-nearest' | 'nearest-mip-linear' | 'linear-mip-linear';
+type MagFilterMode = 'nearest' | 'linear';
+/**
+ * The AssetElement interface provides properties and methods for manipulating
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-asset/ | `<pc-asset>`} elements.
+ * The AssetElement interface also inherits the properties and methods of the
+ * {@link HTMLElement} interface.
+ *
+ * The element becomes ready once the containing application has started and the asset is in the
+ * state declared by the markup: loaded for preloaded assets (even if loading failed — check the
+ * asset's `resource`), or registered and awaiting a load for `lazy` assets. Elements inserted
+ * while the application is running are created and registered on insertion, and begin loading
+ * immediately unless `lazy`. A `pc-asset` must be a direct child of `pc-app` — elements placed
+ * elsewhere, or with an unsupported asset type, never become ready.
+ *
+ * A `lazy` asset loads on first use: the first time any element resolves it by `id` — a model,
+ * a material map, a sky, a script `asset:` reference — or when the `lazy` attribute is removed,
+ * whichever comes first. Until then it stays registered and unloaded.
+ *
+ * For `texture` and `textureatlas` assets, the texture options (`address-u`, `address-v`,
+ * `min-filter`, `mag-filter`, `anisotropy`, `mipmaps`, `srgb`, `flip-y`) apply when the texture is
+ * created and — like `lazy` — are observed: changing one updates a texture that has already
+ * loaded, and removing one restores the engine default. Changing `srgb` or `mipmaps` on a loaded
+ * texture recreates the underlying GPU resource, so prefer declaring those up front. Each option
+ * overrides the matching key in the `data` JSON; options left unset write nothing, leaving the
+ * engine's per-format defaults in force.
+ *
+ * Apart from `lazy` and the texture options, these attributes are read once when the asset is
+ * created, so changing them later has no effect.
+ *
+ * @attribute {string} id - The identifier used to reference the asset from other elements.
+ * @attribute {string} src - The URL of the asset to load.
+ * @attribute {string} type - The asset type. Inferred from the `src` file extension when omitted.
+ * @attribute {string} data - Additional asset data, as a JSON object.
+ * @attribute {string} atlas - For a `sprite` asset, the `id` of the texture atlas asset it uses.
+ * The atlas must be declared before the sprite.
+ * @attribute {string} frame-keys - For a `sprite` asset, the atlas frame keys it uses, separated
+ * by spaces or commas.
+ * @attribute {number} pixels-per-unit - For a `sprite` asset, the number of pixels per world unit.
+ * @attribute {'simple' | 'sliced' | 'tiled'} render-mode - For a `sprite` asset, how the sprite is
+ * rendered when resized.
+ *
+ * @fires {Event} load - Fired each time the asset finishes loading, including a `lazy` asset
+ * loaded later and any subsequent reloads. Does not bubble — listen on this element, or use a
+ * capture-phase listener on an ancestor to observe every asset.
+ * @fires {ErrorEvent} error - Fired when the asset fails to load, with the engine's error in
+ * `message`. Does not bubble. The element still becomes ready — readiness means the load settled,
+ * not that it succeeded.
+ */
+declare class AssetElement extends AsyncElement {
+    private _addressU;
+    private _addressV;
+    private _anisotropy;
+    private _flipY;
+    private _lazy;
+    private _magFilter;
+    private _minFilter;
+    private _mipmaps;
+    private _srgb;
+    /**
+     * The asset that is loaded. Available once the element is ready — await
+     * {@link whenReady} or the element's `ready()` promise before accessing it.
+     */
+    asset: Asset | null;
+    connectedCallback(): Promise<void>;
+    disconnectedCallback(): void;
+    private _onAssetLoad;
+    private _onAssetError;
+    /**
+     * Builds the `data` object for the asset from an optional inline `data` attribute (JSON), the
+     * texture option attributes (for `texture` and `textureatlas` assets), and the sprite
+     * convenience attributes (`atlas`, `frame-keys`, `pixels-per-unit`, `render-mode`). An
+     * attribute overrides the matching `data` JSON key. Returns `undefined` when there is no data
+     * to apply.
+     * @param type - The resolved asset type.
+     * @returns The asset data, or `undefined`.
+     */
+    private _buildData;
+    /**
+     * Returns the engine texture behind this asset, when there is one: the resource itself for a
+     * `texture` asset, the atlas's texture for a `textureatlas` asset, `null` otherwise
+     * (including before the asset has loaded).
+     * @returns The texture, or `null`.
+     */
+    private _texture;
+    /**
+     * Writes one texture option through to the created asset, if any. The engine-JSON key is
+     * written into `asset.data`, mutated in place - replacing the whole object would make the
+     * registry re-patch every key, and a re-patched `srgb` or `mipmaps` recreates the texture
+     * even when unchanged. The in-place key is what a not-yet-started load reads at texture
+     * construction, and what any later reload reads. When the texture already exists, the
+     * corresponding property is assigned directly; `null` (attribute removed) deletes the key
+     * and restores the engine default. Assets of any other type are left untouched.
+     *
+     * @param key - The engine texture JSON key in `asset.data`.
+     * @param property - The Texture property to assign.
+     * @param dataValue - The engine-JSON value for `asset.data`, or `null` to delete the key.
+     * @param textureValue - The value for the Texture property, or `null` for the engine default.
+     */
+    private _applyTextureOption;
+    private _destroyAsset;
+    /**
+     * Sets the texture's horizontal (U) address mode: how texture coordinates outside the 0 to 1
+     * range sample the texture. Applies to `texture` and `textureatlas` assets, both when the
+     * texture is created and after it has loaded.
+     * @param value - The address mode, or `null` to use the engine default of 'repeat'.
+     */
+    set addressU(value: AddressMode | null);
+    /**
+     * Gets the texture's horizontal (U) address mode.
+     * @returns The address mode, or `null` when unset.
+     */
+    get addressU(): AddressMode | null;
+    /**
+     * Sets the texture's vertical (V) address mode: how texture coordinates outside the 0 to 1
+     * range sample the texture. Applies to `texture` and `textureatlas` assets, both when the
+     * texture is created and after it has loaded.
+     * @param value - The address mode, or `null` to use the engine default of 'repeat'.
+     */
+    set addressV(value: AddressMode | null);
+    /**
+     * Gets the texture's vertical (V) address mode.
+     * @returns The address mode, or `null` when unset.
+     */
+    get addressV(): AddressMode | null;
+    /**
+     * Sets the texture's maximum anisotropic filtering level, which improves quality at oblique
+     * viewing angles. Applies to `texture` and `textureatlas` assets, both when the texture is
+     * created and after it has loaded.
+     * @param value - The anisotropy level, or `null` to use the engine default of 1.
+     */
+    set anisotropy(value: number | null);
+    /**
+     * Gets the texture's maximum anisotropic filtering level.
+     * @returns The anisotropy level, or `null` when unset.
+     */
+    get anisotropy(): number | null;
+    /**
+     * Sets whether the texture's image data is flipped vertically at upload. Applies to `texture`
+     * and `textureatlas` assets, both when the texture is created and after it has loaded.
+     * @param value - The flip flag, or `null` to use the engine default of `false`.
+     */
+    set flipY(value: boolean | null);
+    /**
+     * Gets whether the texture's image data is flipped vertically at upload.
+     * @returns The flip flag, or `null` when unset.
+     */
+    get flipY(): boolean | null;
+    /**
+     * Sets whether the asset should be loaded lazily. A lazy asset is registered without being
+     * loaded; it loads on first use - the first time any element resolves it by `id` - or when
+     * this flag is cleared on a registered asset, whichever comes first.
+     * @param value - The lazy loading flag.
+     */
+    set lazy(value: boolean);
+    /**
+     * Gets whether the asset should be loaded lazily.
+     * @returns The lazy loading flag.
+     */
+    get lazy(): boolean;
+    /**
+     * Sets the texture's magnification filter, used when the texture is displayed larger than its
+     * source size. Applies to `texture` and `textureatlas` assets, both when the texture is
+     * created and after it has loaded.
+     * @param value - The filter, or `null` to use the engine default of 'linear'.
+     */
+    set magFilter(value: MagFilterMode | null);
+    /**
+     * Gets the texture's magnification filter.
+     * @returns The filter, or `null` when unset.
+     */
+    get magFilter(): MagFilterMode | null;
+    /**
+     * Sets the texture's minification filter, used when the texture is displayed smaller than its
+     * source size. The mip variants blend within (and, for the second `linear`, between) mipmap
+     * levels. Applies to `texture` and `textureatlas` assets, both when the texture is created
+     * and after it has loaded.
+     * @param value - The filter, or `null` to use the engine default of 'linear-mip-linear'.
+     */
+    set minFilter(value: MinFilterMode | null);
+    /**
+     * Gets the texture's minification filter.
+     * @returns The filter, or `null` when unset.
+     */
+    get minFilter(): MinFilterMode | null;
+    /**
+     * Sets whether the texture generates and uses mipmaps. Changing this on a loaded texture
+     * recreates the underlying GPU resource, so prefer declaring it up front. Applies to
+     * `texture` and `textureatlas` assets.
+     * @param value - The mipmaps flag, or `null` to use the engine default of `true`.
+     */
+    set mipmaps(value: boolean | null);
+    /**
+     * Gets whether the texture generates and uses mipmaps.
+     * @returns The mipmaps flag, or `null` when unset.
+     */
+    get mipmaps(): boolean | null;
+    /**
+     * Sets whether the texture holds sRGB (gamma-encoded) color data, enabling hardware gamma
+     * decode. Free when set before the texture loads; changing it on a loaded texture recreates
+     * the underlying GPU resource. Applies to `texture` and `textureatlas` assets.
+     * @param value - The sRGB flag, or `null` to use the engine default of `false`.
+     */
+    set srgb(value: boolean | null);
+    /**
+     * Gets whether the texture holds sRGB (gamma-encoded) color data.
+     * @returns The sRGB flag, or `null` when unset.
+     */
+    get srgb(): boolean | null;
+    /**
+     * Returns the {@link Asset} created by the `<pc-asset>` element with the given `id`, or
+     * `undefined` if there is no such element or its asset has not been created yet.
+     *
+     * @param id - The `id` of the `<pc-asset>` element.
+     * @returns The asset, or `undefined`.
+     */
+    static get(id: string): Asset | null | undefined;
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+}
+export { AssetElement };

package/dist/asset.d.ts

@@ -1,5 +1,5 @@
 import { Asset } from 'playcanvas';
-import { AsyncElement } from './async-element';
+import { AsyncElement } from './async-element.js';
 type AddressMode = 'repeat' | 'clamp' | 'mirror';
 type MinFilterMode = 'nearest' | 'linear' | 'nearest-mip-nearest' | 'linear-mip-nearest' | 'nearest-mip-linear' | 'linear-mip-linear';
 type MagFilterMode = 'nearest' | 'linear';
@@ -16,6 +16,10 @@ type MagFilterMode = 'nearest' | 'linear';
  * immediately unless `lazy`. A `pc-asset` must be a direct child of `pc-app` — elements placed
  * elsewhere, or with an unsupported asset type, never become ready.
  *
+ * A `lazy` asset loads on first use: the first time any element resolves it by `id` — a model,
+ * a material map, a sky, a script `asset:` reference — or when the `lazy` attribute is removed,
+ * whichever comes first. Until then it stays registered and unloaded.
+ *
  * For `texture` and `textureatlas` assets, the texture options (`address-u`, `address-v`,
  * `min-filter`, `mag-filter`, `anisotropy`, `mipmaps`, `srgb`, `flip-y`) apply when the texture is
  * created and — like `lazy` — are observed: changing one updates a texture that has already
@@ -146,7 +150,9 @@ declare class AssetElement extends AsyncElement {
      */
     get flipY(): boolean | null;
     /**
-     * Sets whether the asset should be loaded lazily.
+     * Sets whether the asset should be loaded lazily. A lazy asset is registered without being
+     * loaded; it loads on first use - the first time any element resolves it by `id` - or when
+     * this flag is cleared on a registered asset, whichever comes first.
      * @param value - The lazy loading flag.
      */
     set lazy(value: boolean);