@playcanvas/web-components 0.8.1 → 0.9.0

package/dist/scene.d.ts

@@ -31,22 +31,26 @@ declare class SceneElement extends AsyncElement {
      * The gravity of the scene.
      */
     private _gravity;
+    private _scene;
     /**
-     * The PlayCanvas scene instance.
+     * The PlayCanvas scene instance. Available once the element is ready — await
+     * {@link whenReady} or the element's `ready()` promise before accessing it.
+     * @returns The scene instance.
      */
-    scene: Scene | null;
+    get scene(): Scene;
     connectedCallback(): Promise<void>;
     updateSceneSettings(): void;
     /**
-     * Sets the fog type of the scene.
+     * Sets the fog type of the scene. Can be `none`, `linear`, `exp` or `exp2`. Defaults to
+     * `none`.
      * @param value - The fog type.
      */
-    set fog(value: string);
+    set fog(value: "linear" | "none" | "exp" | "exp2");
     /**
      * Gets the fog type of the scene.
      * @returns The fog type.
      */
-    get fog(): string;
+    get fog(): "linear" | "none" | "exp" | "exp2";
     /**
      * Sets the fog color of the scene.
      * @param value - The fog color.
@@ -100,4 +104,9 @@ declare class SceneElement extends AsyncElement {
     static get observedAttributes(): string[];
     attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
 }
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-scene': SceneElement;
+    }
+}
 export { SceneElement };

package/dist/sky.d.ts

@@ -15,6 +15,7 @@ declare class SkyElement extends AsyncElement {
     private _scale;
     private _type;
     private _scene;
+    private _appElement;
     connectedCallback(): void;
     disconnectedCallback(): void;
     private _generateSkybox;
@@ -103,4 +104,9 @@ declare class SkyElement extends AsyncElement {
     static get observedAttributes(): string[];
     attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
 }
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-sky': SkyElement;
+    }
+}
 export { SkyElement };

package/dist/utils.d.ts

@@ -1,50 +1,108 @@
 import { Color, Entity, Quat, Vec2, Vec3, Vec4 } from 'playcanvas';
 /**
- * Parse a color string into a Color object. String can be in the format of '#rgb', '#rgba',
- * '#rrggbb', '#rrggbbaa', or a string of 3 or 4 comma-delimited numbers.
+ * Parse a boolean attribute value. The same rules apply to every boolean attribute:
  *
- * @param value - The color string to parse.
+ * - Attribute absent (or removed): the supplied default is used.
+ * - Attribute set to the string 'false': `false`.
+ * - Attribute present with any other value, including the empty string of a bare boolean
+ *   attribute (e.g. `<pc-light cast-shadows>`): `true`.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or removed.
+ * @returns The parsed boolean.
+ */
+export declare const parseBool: (value: string | null, defaultValue: boolean) => boolean;
+/**
+ * Splits an attribute value into exactly `count` numeric components. Returns `null` when the
+ * value does not consist of exactly `count` whitespace-separated finite numbers.
+ *
+ * @param value - The value to split.
+ * @param count - The required number of components.
+ * @returns The parsed components, or `null`.
+ * @ignore
+ */
+export declare const parseComponents: (value: string, count: number) => number[] | null;
+/**
+ * Parse a color attribute value. The expected format is a CSS color name (e.g. 'rebeccapurple'),
+ * a hex color (e.g. '#ff0000' or '#f00'), or 3 or 4 space-separated numbers in the range 0 to 1
+ * (e.g. '1 0.5 0.5' or '1 0.5 0.5 0.5'). Returns `defaultValue` (cloned, when it is a color)
+ * when the attribute is absent (`null`), or when the value is malformed — the latter also logs
+ * a warning.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or invalid.
+ * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Color object.
  */
-export declare const parseColor: (value: string) => Color;
+export declare const parseColor: <T extends Color | null>(value: string | null, defaultValue: T, attribute: string) => Color | T;
 /**
- * Parse an Euler angles string into a Quat object. String can be in the format of 'x,y,z'.
+ * Parse an Euler-angles attribute value into a quaternion. The expected format is 3
+ * space-separated angles in degrees (e.g. '0 90 0'). Returns `defaultValue` (cloned, when it is
+ * a quaternion) when the attribute is absent (`null`), or when the value is malformed — the
+ * latter also logs a warning.
  *
- * @param value - The Euler angles string to parse.
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or invalid.
+ * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Quat object.
  */
-export declare const parseQuat: (value: string) => Quat;
+export declare const parseQuat: <T extends Quat | null>(value: string | null, defaultValue: T, attribute: string) => Quat | T;
 /**
- * Parse a Vec2 string into a Vec2 object. String can be in the format of 'x,y'.
+ * Parse a Vec2 attribute value. The expected format is 2 space-separated numbers (e.g. '1 2').
+ * Returns `defaultValue` (cloned, when it is a vector) when the attribute is absent (`null`),
+ * or when the value is malformed — the latter also logs a warning.
  *
- * @param value - The Vec2 string to parse.
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or invalid.
+ * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Vec2 object.
  */
-export declare const parseVec2: (value: string) => Vec2;
+export declare const parseVec2: <T extends Vec2 | null>(value: string | null, defaultValue: T, attribute: string) => Vec2 | T;
 /**
- * Parse a Vec3 string into a Vec3 object. String can be in the format of 'x,y,z'.
+ * Parse a Vec3 attribute value. The expected format is 3 space-separated numbers (e.g. '1 2 3').
+ * Returns `defaultValue` (cloned, when it is a vector) when the attribute is absent (`null`),
+ * or when the value is malformed — the latter also logs a warning.
  *
- * @param value - The Vec3 string to parse.
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or invalid.
+ * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Vec3 object.
  */
-export declare const parseVec3: (value: string) => Vec3;
+export declare const parseVec3: <T extends Vec3 | null>(value: string | null, defaultValue: T, attribute: string) => Vec3 | T;
 /**
- * Parse a Vec4 string into a Vec4 object. String can be in the format of 'x,y,z,w'.
+ * Parse a Vec4 attribute value. The expected format is 4 space-separated numbers
+ * (e.g. '1 2 3 4'). Returns `defaultValue` (cloned, when it is a vector) when the attribute is
+ * absent (`null`), or when the value is malformed — the latter also logs a warning.
  *
- * @param value - The Vec4 string to parse.
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or invalid.
+ * @param attribute - The attribute name, used in the warning message.
  * @returns The parsed Vec4 object.
  */
-export declare const parseVec4: (value: string) => Vec4;
+export declare const parseVec4: <T extends Vec4 | null>(value: string | null, defaultValue: T, attribute: string) => Vec4 | T;
+/**
+ * Resolves an enum attribute value against its set of valid names. Returns the value when it is
+ * one of the valid names. Returns `defaultValue` when the attribute is absent (`null`), or when
+ * the value is invalid — the latter also logs a warning listing the valid names.
+ *
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param valid - The valid names: an array, or a map whose keys are the valid names.
+ * @param defaultValue - The value to use when the attribute is absent or invalid.
+ * @param attribute - The attribute name, used in the warning message.
+ * @returns The resolved enum name.
+ */
+export declare const parseEnum: <T extends string>(value: string | null, valid: readonly T[] | ReadonlyMap<T, number>, defaultValue: T, attribute: string) => T;
 /**
- * Resolves an enum value supplied as either a named string (looked up in `map`) or a numeric
- * string. Falls back to `defaultValue` when the value is neither a known name nor a finite number.
+ * Parses a number attribute value. Returns the parsed number when the value is a finite number.
+ * Returns `defaultValue` when the attribute is absent (`null`), or when the value is not a
+ * finite number — the latter also logs a warning.
  *
- * @param value - The attribute value to parse.
- * @param map - A map of named values to their numeric enum equivalents.
- * @param defaultValue - The value to return when parsing fails.
- * @returns The resolved numeric enum value.
+ * @param value - The attribute value to parse (`null` when the attribute is absent).
+ * @param defaultValue - The value to use when the attribute is absent or invalid.
+ * @param attribute - The attribute name, used in the warning message.
+ * @returns The parsed number.
  */
-export declare const parseEnum: (value: string, map: Map<string, number>, defaultValue: number) => number;
+export declare const parseNumber: <T extends number | null>(value: string | null, defaultValue: T, attribute: string) => number | T;
 /**
  * Resolves a reference string to the {@link Entity} backing a `<pc-entity>` element. The reference
  * can be a CSS selector (e.g. `#my-id`, `pc-entity[name="Foo"]`), a bare element id, or a bare

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcanvas/web-components",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "author": "PlayCanvas <support@playcanvas.com>",
   "homepage": "https://playcanvas.com",
   "description": "Web Components for the PlayCanvas Engine",
@@ -27,12 +27,22 @@
   "module": "dist/pwc.mjs",
   "browser": "dist/pwc.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/pwc.mjs",
+      "require": "./dist/pwc.cjs"
+    },
+    "./dist/*": "./dist/*",
+    "./package.json": "./package.json"
+  },
   "type": "module",
   "files": [
     "dist",
     "src"
   ],
   "scripts": {
+    "prebuild": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
     "build": "rollup -c",
     "dev": "concurrently \"npm run watch\" \"npm run serve\"",
     "docs": "typedoc",
@@ -48,28 +58,28 @@
     "playcanvas": "^2.20.1"
   },
   "devDependencies": {
-    "@mediapipe/tasks-vision": "0.10.35",
+    "@mediapipe/tasks-vision": "1.0.0",
     "@playcanvas/eslint-config": "2.1.0",
     "@rollup/plugin-commonjs": "29.0.3",
     "@rollup/plugin-node-resolve": "16.0.3",
     "@rollup/plugin-terser": "1.0.0",
     "@rollup/plugin-typescript": "12.3.0",
     "@tweenjs/tween.js": "25.0.0",
-    "@typescript-eslint/eslint-plugin": "8.62.1",
-    "@typescript-eslint/parser": "8.62.1",
-    "concurrently": "10.0.3",
-    "earcut": "3.2.2",
-    "eslint": "9.39.4",
+    "@typescript-eslint/eslint-plugin": "8.65.0",
+    "@typescript-eslint/parser": "8.65.0",
+    "concurrently": "10.0.4",
+    "earcut": "3.2.3",
+    "eslint": "9.39.5",
     "eslint-import-resolver-typescript": "4.4.5",
-    "globals": "17.7.0",
-    "mediabunny": "1.50.3",
+    "globals": "17.8.0",
+    "mediabunny": "1.51.0",
     "opentype.js": "2.0.0",
-    "playcanvas": "2.20.4",
-    "publint": "0.3.21",
-    "rollup": "4.62.2",
+    "playcanvas": "2.21.3",
+    "publint": "0.3.22",
+    "rollup": "4.62.3",
     "serve": "14.2.6",
     "tslib": "2.8.1",
-    "typedoc": "0.28.19",
+    "typedoc": "0.28.20",
     "typedoc-plugin-mdn-links": "5.1.1",
     "typescript": "6.0.3"
   }

package/src/app.ts

@@ -71,6 +71,7 @@ import { AsyncElement } from './async-element';
 import { EntityElement } from './entity';
 import { MaterialElement } from './material';
 import { ModuleElement } from './module';
+import { parseBool, parseEnum } from './utils';
 
 /**
  * The AppElement interface provides properties and methods for manipulating
@@ -116,10 +117,16 @@ class AppElement extends AsyncElement {
         pointerup: null
     };
 
+    private _app: AppBase | null = null;
+
     /**
-     * The PlayCanvas application instance.
+     * The PlayCanvas application instance. Available once the element is ready — await
+     * {@link whenReady} or the element's `ready()` promise before accessing it.
+     * @returns The application instance.
      */
-    app: AppBase | null = null;
+    get app(): AppBase {
+        return this._app!;
+    }
 
     /**
      * Creates a new AppElement instance.
@@ -227,7 +234,7 @@ class AppElement extends AsyncElement {
         createOptions.batchManager = BatchManager;
         createOptions.xr = XrManager;
 
-        this.app = new AppBase(this._canvas);
+        this._app = new AppBase(this._canvas);
         this.app.init(createOptions);
 
         this.app.setCanvasFillMode(FILLMODE_FILL_WINDOW);
@@ -282,7 +289,7 @@ class AppElement extends AsyncElement {
         // Clean up the application
         if (this.app) {
             this.app.destroy();
-            this.app = null;
+            this._app = null;
         }
 
         // Remove event listeners
@@ -314,6 +321,14 @@ class AppElement extends AsyncElement {
         ['pointermove', 'pointerdown', 'pointerup', 'pointerenter', 'pointerleave'].forEach((type) => {
             this.addEventListener(`${type}:connect`, () => this._onPointerListenerAdded(type));
             this.addEventListener(`${type}:disconnect`, () => this._onPointerListenerRemoved(type));
+
+            // Attach canvas handlers for listeners registered before this point (e.g. handlers
+            // created from onpointer* attributes when their elements were first upgraded)
+            const anyListeners = Array.from(this.querySelectorAll<EntityElement>('pc-entity'))
+            .some(entity => entity.hasListeners(type));
+            if (anyListeners) {
+                this._onPointerListenerAdded(type);
+            }
         });
     }
 
@@ -332,6 +347,13 @@ class AppElement extends AsyncElement {
             pointerdown: null,
             pointerup: null
         };
+        this._hasPointerListeners = {
+            pointerenter: false,
+            pointerleave: false,
+            pointerdown: false,
+            pointerup: false,
+            pointermove: false
+        };
     }
 
     // New helper to convert CSS coordinates to canvas (picker) coordinates
@@ -589,24 +611,22 @@ class AppElement extends AsyncElement {
     attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
         switch (name) {
             case 'alpha':
-                this.alpha = newValue !== 'false';
+                this.alpha = parseBool(newValue, true);
                 break;
             case 'antialias':
-                this.antialias = newValue !== 'false';
+                this.antialias = parseBool(newValue, true);
                 break;
             case 'backend':
-                if (newValue === 'webgpu' || newValue === 'webgl2' || newValue === 'null') {
-                    this.backend = newValue;
-                }
+                this.backend = parseEnum(newValue, ['webgpu', 'webgl2', 'null'], 'webgl2', name);
                 break;
             case 'depth':
-                this.depth = newValue !== 'false';
+                this.depth = parseBool(newValue, true);
                 break;
             case 'high-resolution':
-                this.highResolution = newValue !== 'false';
+                this.highResolution = parseBool(newValue, true);
                 break;
             case 'stencil':
-                this.stencil = newValue !== 'false';
+                this.stencil = parseBool(newValue, true);
                 break;
         }
     }
@@ -614,4 +634,10 @@ class AppElement extends AsyncElement {
 
 customElements.define('pc-app', AppElement);
 
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-app': AppElement;
+    }
+}
+
 export { AppElement };

package/src/asset.ts

@@ -1,9 +1,10 @@
 import { Asset, SPRITE_RENDERMODE_SIMPLE, SPRITE_RENDERMODE_SLICED, SPRITE_RENDERMODE_TILED } from 'playcanvas';
 
-import { parseEnum } from './utils';
+import { AsyncElement } from './async-element';
+import { parseBool, parseEnum, parseNumber } from './utils';
 import { MeshoptDecoder } from '../lib/meshopt_decoder.module.js';
 
-const renderModes = new Map<string, number>([
+const renderModes = new Map<'simple' | 'sliced' | 'tiled', number>([
     ['simple', SPRITE_RENDERMODE_SIMPLE],
     ['sliced', SPRITE_RENDERMODE_SLICED],
     ['tiled', SPRITE_RENDERMODE_TILED]
@@ -74,15 +75,59 @@ const processBufferView = (
  * {@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.
  */
-class AssetElement extends HTMLElement {
+class AssetElement extends AsyncElement {
     private _lazy: boolean = false;
 
     /**
-     * The asset that is loaded.
+     * 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 = null;
 
+    async connectedCallback() {
+        const appElement = this.closestApp;
+        if (!appElement) return;
+
+        // Assets must be direct children of pc-app (matches the boot query ':scope > pc-asset')
+        if (this.parentElement !== appElement) {
+            console.warn(`pc-asset '${this.getAttribute('id') ?? this.getAttribute('src')}' must be a direct child of pc-app - asset not created`);
+            return;
+        }
+
+        await appElement.ready();
+
+        // The element may have been removed or re-parented while waiting for the app
+        if (!this.isConnected || this.parentElement !== appElement) return;
+
+        // Assets present at startup are created by AppElement's boot; this branch handles
+        // elements inserted (or re-inserted) after the app is already running
+        if (!this.asset) {
+            const app = appElement.app;
+            if (!app) return; // pc-app is re-connecting; its own boot will create this asset
+
+            this.createAsset();
+            if (this.asset) {
+                app.assets.add(this.asset); // add() auto-loads when preload is true
+                if (!this.lazy) {
+                    app.assets.load(this.asset);
+                }
+            }
+        }
+
+        // Never ready if createAsset failed (unsupported asset type)
+        if (this.asset) {
+            this._onReady();
+        }
+    }
+
     disconnectedCallback() {
         this.destroyAsset();
     }
@@ -167,12 +212,12 @@ class AssetElement extends HTMLElement {
 
             const pixelsPerUnit = this.getAttribute('pixels-per-unit');
             if (pixelsPerUnit !== null) {
-                data.pixelsPerUnit = Number(pixelsPerUnit);
+                data.pixelsPerUnit = parseNumber(pixelsPerUnit, 1, 'pixels-per-unit');
             }
 
             const renderMode = this.getAttribute('render-mode');
             if (renderMode !== null) {
-                data.renderMode = parseEnum(renderMode, renderModes, SPRITE_RENDERMODE_SIMPLE);
+                data.renderMode = renderModes.get(parseEnum(renderMode, renderModes, 'simple', 'render-mode'));
             }
 
             // Apply engine defaults for any values not supplied.
@@ -187,6 +232,8 @@ class AssetElement extends HTMLElement {
 
     destroyAsset() {
         if (this.asset) {
+            // Deregister first so unload() can still notify the registry
+            this.asset.registry?.remove(this.asset);
             this.asset.unload();
             this.asset = null;
         }
@@ -220,13 +267,19 @@ class AssetElement extends HTMLElement {
         return ['lazy'];
     }
 
-    attributeChangedCallback(name: string, _oldValue: string, _newValue: string) {
+    attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
         if (name === 'lazy') {
-            this.lazy = this.hasAttribute('lazy');
+            this.lazy = parseBool(newValue, false);
         }
     }
 }
 
 customElements.define('pc-asset', AssetElement);
 
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-asset': AssetElement;
+    }
+}
+
 export { AssetElement };

package/src/async-element.ts

@@ -26,16 +26,18 @@ class AsyncElement extends HTMLElement {
     }
 
     /**
-     * Called when the element is fully initialized and ready.
-     * Subclasses should call this when they're ready.
+     * Called when the element is fully initialized and ready. Subclasses should call this when
+     * they're ready. Resolves the ready promise and dispatches a bubbling, composed `ready`
+     * event.
      */
     protected _onReady() {
         this._readyResolve();
-        this.dispatchEvent(new CustomEvent('ready'));
+        this.dispatchEvent(new CustomEvent('ready', { bubbles: true, composed: true }));
     }
 
     /**
-     * Returns a promise that resolves with this element when it's ready.
+     * Returns a promise that resolves with this element when it's ready. This is the low-level
+     * primitive underlying {@link whenReady}, which is the recommended way to wait for elements.
      * @returns A promise that resolves with this element when it's ready.
      */
     ready(): Promise<this> {
@@ -43,4 +45,83 @@ class AsyncElement extends HTMLElement {
     }
 }
 
-export { AsyncElement };
+/**
+ * A union of the tag names of all elements that initialize asynchronously (i.e. elements whose
+ * classes extend {@link AsyncElement}).
+ */
+type AsyncElementTagName = {
+    [K in keyof HTMLElementTagNameMap]: HTMLElementTagNameMap[K] extends AsyncElement ? K : never
+}[keyof HTMLElementTagNameMap];
+
+/**
+ * Waits for the first element matching the given tag name to be fully initialized. Note that the
+ * promise never settles if the element cannot finish initializing (for example, a `<pc-script>`
+ * that is not a direct child of `<pc-scripts>`). A component element outside a `<pc-entity>` is
+ * the exception: it still becomes ready, but its `component` is `null`. Either way, a misplaced
+ * element logs a warning naming the parent it requires.
+ * @param target - The tag name of the element to wait for (e.g. `'pc-app'`).
+ * @returns A promise that resolves with the element once it's ready.
+ * @example
+ * const { app } = await whenReady('pc-app');
+ */
+function whenReady<K extends AsyncElementTagName>(target: K): Promise<HTMLElementTagNameMap[K]>;
+/**
+ * Waits for the given element to be fully initialized. Note that the promise never settles if
+ * the element cannot finish initializing (for example, an element that is never added to the
+ * document).
+ * @param target - The element to wait for.
+ * @returns A promise that resolves with the element once it's ready.
+ * @example
+ * const appElement = document.createElement('pc-app');
+ * document.body.appendChild(appElement);
+ * const { app } = await whenReady(appElement);
+ */
+function whenReady<T extends AsyncElement>(target: T): Promise<T>;
+/**
+ * Waits for the first element matching the given CSS selector to be fully initialized. Note that
+ * the promise never settles if the element cannot finish initializing (for example, a `<pc-script>`
+ * that is not a direct child of `<pc-scripts>`). A component element outside a `<pc-entity>` is
+ * the exception: it still becomes ready, but its `component` is `null`. Either way, a misplaced
+ * element logs a warning naming the parent it requires.
+ * @param target - A CSS selector matching the element to wait for (e.g. `'#my-app'`).
+ * @returns A promise that resolves with the element once it's ready.
+ * @example
+ * // In TypeScript, supply the element type when using an arbitrary selector
+ * const { entity } = await whenReady<EntityElement>('pc-entity[name="camera"]');
+ */
+function whenReady<T extends AsyncElement = AsyncElement, S extends string = string>(
+    target: S extends Exclude<keyof HTMLElementTagNameMap, AsyncElementTagName> ? never : S
+): Promise<T>;
+async function whenReady(target: string | AsyncElement): Promise<AsyncElement> {
+    let element: Element | null;
+    if (typeof target === 'string') {
+        if (document.readyState === 'loading') {
+            await new Promise((resolve) => {
+                document.addEventListener('DOMContentLoaded', resolve, { once: true });
+            });
+        }
+
+        try {
+            element = document.querySelector(target);
+        } catch {
+            throw new Error(`whenReady: '${target}' is not a valid CSS selector`);
+        }
+        if (!element) {
+            throw new Error(`whenReady: no element found matching '${target}'`);
+        }
+    } else {
+        element = target;
+    }
+
+    if (!(element instanceof AsyncElement)) {
+        const description = element instanceof Element ? `<${element.tagName.toLowerCase()}>` : String(target);
+        throw new Error(`whenReady: ${description} does not initialize asynchronously`);
+    }
+
+    await element.ready();
+
+    return element;
+}
+
+export { AsyncElement, whenReady };
+export type { AsyncElementTagName };