@playcanvas/web-components 0.8.2 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcanvas/web-components",
-  "version": "0.8.2",
+  "version": "0.10.0",
   "author": "PlayCanvas <support@playcanvas.com>",
   "homepage": "https://playcanvas.com",
   "description": "Web Components for the PlayCanvas Engine",
@@ -25,8 +25,11 @@
   },
   "main": "dist/pwc.cjs",
   "module": "dist/pwc.mjs",
-  "browser": "dist/pwc.js",
+  "unpkg": "dist/pwc.min.js",
+  "jsdelivr": "dist/pwc.min.js",
   "types": "dist/index.d.ts",
+  "customElements": "dist/custom-elements.json",
+  "web-types": "dist/web-types.json",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -44,21 +47,31 @@
   "scripts": {
     "prebuild": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
     "build": "rollup -c",
+    "postbuild": "npm run cem",
+    "cem": "cem analyze && node utils/cem/validate.mjs",
     "dev": "concurrently \"npm run watch\" \"npm run serve\"",
     "docs": "typedoc",
-    "lint": "eslint examples/js examples/assets/scripts src",
+    "lint": "eslint examples/js examples/assets/scripts src test vitest.config.ts",
     "serve": "serve",
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:unit": "vitest run --project unit",
+    "test:elements": "vitest run --project elements",
+    "test:integration": "vitest run --project integration",
     "publint": "publint",
-    "type-check": "tsc --noEmit",
-    "type-check:watch": "npm run type-check -- --watch",
+    "type-check": "npm run type-check:src && npm run type-check:test",
+    "type-check:src": "tsc --noEmit -p tsconfig.json",
+    "type-check:test": "tsc --noEmit -p tsconfig.test.json",
+    "type-check:watch": "npm run type-check:src -- --watch",
     "watch": "rollup -c -w"
   },
   "peerDependencies": {
     "playcanvas": "^2.20.1"
   },
   "devDependencies": {
-    "@mediapipe/tasks-vision": "0.10.35",
+    "@custom-elements-manifest/analyzer": "0.11.0",
+    "@mediapipe/tasks-vision": "1.0.1",
     "@playcanvas/eslint-config": "2.1.0",
     "@rollup/plugin-commonjs": "29.0.3",
     "@rollup/plugin-node-resolve": "16.0.3",
@@ -67,20 +80,25 @@
     "@tweenjs/tween.js": "25.0.0",
     "@typescript-eslint/eslint-plugin": "8.65.0",
     "@typescript-eslint/parser": "8.65.0",
-    "concurrently": "10.0.3",
+    "@vitest/coverage-v8": "4.1.10",
+    "concurrently": "10.0.4",
+    "custom-element-jet-brains-integration": "1.7.0",
+    "custom-element-vs-code-integration": "1.5.0",
     "earcut": "3.2.3",
     "eslint": "9.39.5",
     "eslint-import-resolver-typescript": "4.4.5",
-    "globals": "17.7.0",
-    "mediabunny": "1.51.0",
+    "globals": "17.9.0",
+    "jsdom": "30.0.1",
+    "mediabunny": "1.52.2",
     "opentype.js": "2.0.0",
-    "playcanvas": "2.21.0",
-    "publint": "0.3.21",
-    "rollup": "4.62.2",
+    "playcanvas": "2.21.3",
+    "publint": "0.3.22",
+    "rollup": "4.62.4",
     "serve": "14.2.6",
     "tslib": "2.8.1",
     "typedoc": "0.28.20",
     "typedoc-plugin-mdn-links": "5.1.1",
-    "typescript": "6.0.3"
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
   }
 }

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 './parse';
 
 /**
  * The AppElement interface provides properties and methods for manipulating
@@ -86,7 +87,7 @@ class AppElement extends AsyncElement {
 
     private _alpha = true;
 
-    private _backend: 'webgpu' | 'webgl2' | 'null' = 'webgl2';
+    private _backend: 'webgpu' | 'webgl2' | 'null' = 'webgpu';
 
     private _antialias = true;
 
@@ -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
@@ -506,7 +528,8 @@ class AppElement extends AsyncElement {
     }
 
     /**
-     * Sets the graphics backend.
+     * Sets the graphics backend. Defaults to 'webgpu', which falls back to 'webgl2' if WebGPU
+     * is not supported by the browser.
      * @param value - The graphics backend ('webgpu', 'webgl2', or 'null').
      */
     set backend(value: 'webgpu' | 'webgl2' | 'null') {
@@ -586,27 +609,25 @@ class AppElement extends AsyncElement {
         return ['alpha', 'antialias', 'backend', 'depth', 'stencil', 'high-resolution'];
     }
 
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
         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'], 'webgpu', 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 +635,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 './parse';
 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]
@@ -15,11 +16,13 @@ const extToType = new Map([
     ['frag', 'shader'],
     ['glb', 'container'],
     ['glsl', 'shader'],
+    ['gltf', 'container'],
     ['hdr', 'texture'],
     ['html', 'html'],
     ['jpg', 'texture'],
     ['js', 'script'],
     ['json', 'json'],
+    ['ktx2', 'texture'],
     ['mp3', 'audio'],
     ['mjs', 'script'],
     ['ply', 'gsplat'],
@@ -74,15 +77,74 @@ 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.
+ *
+ * Apart from `lazy`, 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.
  */
-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 +229,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 +249,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 +284,19 @@ class AssetElement extends HTMLElement {
         return ['lazy'];
     }
 
-    attributeChangedCallback(name: string, _oldValue: string, _newValue: string) {
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
         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

@@ -3,6 +3,9 @@ import { EntityElement } from './entity';
 
 /**
  * Base class for all PlayCanvas Web Components that initialize asynchronously.
+ *
+ * @fires {CustomEvent} ready - Fired once the element is fully initialized. Bubbles and is
+ * composed.
  */
 class AsyncElement extends HTMLElement {
     private _readyPromise: Promise<void>;
@@ -26,16 +29,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 +48,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 };

package/src/components/button-component.ts

@@ -2,9 +2,9 @@ import { BUTTON_TRANSITION_MODE_SPRITE_CHANGE, BUTTON_TRANSITION_MODE_TINT, Butt
 
 import { AssetElement } from '../asset';
 import { ComponentElement } from './component';
-import { getEntity, parseColor, parseEnum, parseVec4 } from '../utils';
+import { getEntity, parseBool, parseColor, parseEnum, parseNumber, parseVec4 } from '../parse';
 
-const transitionModes = new Map<string, number>([
+const transitionModes = new Map<'tint' | 'sprite', number>([
     ['tint', BUTTON_TRANSITION_MODE_TINT],
     ['sprite', BUTTON_TRANSITION_MODE_SPRITE_CHANGE]
 ]);
@@ -24,7 +24,7 @@ class ButtonComponentElement extends ComponentElement {
 
     private _hitPadding = new Vec4(0, 0, 0, 0);
 
-    private _transitionMode: number = BUTTON_TRANSITION_MODE_TINT;
+    private _transitionMode: 'tint' | 'sprite' = 'tint';
 
     private _hoverTint = new Color(1, 1, 1, 1);
 
@@ -55,7 +55,7 @@ class ButtonComponentElement extends ComponentElement {
         const data: Record<string, any> = {
             active: this._active,
             hitPadding: this._hitPadding,
-            transitionMode: this._transitionMode,
+            transitionMode: transitionModes.get(this._transitionMode),
             hoverTint: this._hoverTint,
             pressedTint: this._pressedTint,
             inactiveTint: this._inactiveTint,
@@ -94,8 +94,8 @@ class ButtonComponentElement extends ComponentElement {
      * Gets the underlying PlayCanvas button component.
      * @returns The button component.
      */
-    get component(): ButtonComponent | null {
-        return super.component as ButtonComponent | null;
+    get component(): ButtonComponent {
+        return super.component as ButtonComponent;
     }
 
     /**
@@ -158,13 +158,14 @@ class ButtonComponentElement extends ComponentElement {
     }
 
     /**
-     * Sets how the button reacts to being hovered/pressed. Can be `tint` (0) or `sprite` (1).
+     * Sets how the button reacts to being hovered/pressed. Can be `tint` or `sprite`. Defaults to
+     * `tint`.
      * @param value - The transition mode.
      */
-    set transitionMode(value: number) {
+    set transitionMode(value: 'tint' | 'sprite') {
         this._transitionMode = value;
         if (this.component) {
-            this.component.transitionMode = value;
+            this.component.transitionMode = transitionModes.get(value) ?? BUTTON_TRANSITION_MODE_TINT;
         }
     }
 
@@ -395,51 +396,51 @@ class ButtonComponentElement extends ComponentElement {
         ];
     }
 
-    attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
         super.attributeChangedCallback(name, _oldValue, newValue);
 
         switch (name) {
             case 'active':
-                this.active = newValue !== 'false';
+                this.active = parseBool(newValue, true);
                 break;
             case 'image':
-                this.image = newValue;
+                this.image = newValue ?? '';
                 break;
             case 'hit-padding':
-                this.hitPadding = parseVec4(newValue);
+                this.hitPadding = parseVec4(newValue, Vec4.ZERO, name);
                 break;
             case 'transition-mode':
-                this.transitionMode = parseEnum(newValue, transitionModes, BUTTON_TRANSITION_MODE_TINT);
+                this.transitionMode = parseEnum(newValue, transitionModes, 'tint', name);
                 break;
             case 'hover-tint':
-                this.hoverTint = parseColor(newValue);
+                this.hoverTint = parseColor(newValue, Color.WHITE, name);
                 break;
             case 'pressed-tint':
-                this.pressedTint = parseColor(newValue);
+                this.pressedTint = parseColor(newValue, Color.WHITE, name);
                 break;
             case 'inactive-tint':
-                this.inactiveTint = parseColor(newValue);
+                this.inactiveTint = parseColor(newValue, Color.WHITE, name);
                 break;
             case 'fade-duration':
-                this.fadeDuration = Number(newValue);
+                this.fadeDuration = parseNumber(newValue, 0, name);
                 break;
             case 'hover-sprite-asset':
-                this.hoverSpriteAsset = newValue;
+                this.hoverSpriteAsset = newValue ?? '';
                 break;
             case 'hover-sprite-frame':
-                this.hoverSpriteFrame = Number(newValue);
+                this.hoverSpriteFrame = parseNumber(newValue, 0, name);
                 break;
             case 'pressed-sprite-asset':
-                this.pressedSpriteAsset = newValue;
+                this.pressedSpriteAsset = newValue ?? '';
                 break;
             case 'pressed-sprite-frame':
-                this.pressedSpriteFrame = Number(newValue);
+                this.pressedSpriteFrame = parseNumber(newValue, 0, name);
                 break;
             case 'inactive-sprite-asset':
-                this.inactiveSpriteAsset = newValue;
+                this.inactiveSpriteAsset = newValue ?? '';
                 break;
             case 'inactive-sprite-frame':
-                this.inactiveSpriteFrame = Number(newValue);
+                this.inactiveSpriteFrame = parseNumber(newValue, 0, name);
                 break;
         }
     }
@@ -447,4 +448,10 @@ class ButtonComponentElement extends ComponentElement {
 
 customElements.define('pc-button', ButtonComponentElement);
 
+declare global {
+    interface HTMLElementTagNameMap {
+        'pc-button': ButtonComponentElement;
+    }
+}
+
 export { ButtonComponentElement };