create-playcanvas 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "create-playcanvas",
-    "version": "0.9.0",
+    "version": "0.10.0",
     "description": "Scaffold a PlayCanvas project",
     "keywords": [
         "playcanvas",
@@ -44,7 +44,7 @@
     "devDependencies": {
         "@clack/prompts": "^1.8.1",
         "@playcanvas/eslint-config": "3.0.0-beta.8",
-        "@types/node": "22.20.4",
+        "@types/node": "22.20.5",
         "eslint": "^9.39.5",
         "mri": "^1.2.0",
         "picocolors": "^1.1.1",

package/skills/apply-conventions/SKILL.md

@@ -44,6 +44,6 @@ Check version-sensitive APIs against installed `playcanvas` declarations.
 
 ## Verify in the running app
 
-Offline values cannot prove facing, poses, or placement. Log values from a `Script` or update
-callback in the running app, and judge visuals only from screenshots you have inspected. A saved
-file path is not evidence.
+Offline values cannot prove facing, poses, or placement. Read values from the running app with
+`inspect-runtime`, and judge visuals only from screenshots you have inspected. A saved file path is
+not evidence.

package/skills/assemble-scene/SKILL.md

@@ -20,7 +20,7 @@ once; if the tuning record is missing, calibrate first.
 ## Check placement
 
 After a rendered frame, measure each support or attachment at the object's actual position, using
-a mount point, raycast, or geometry sample. A positive gap floats; a negative gap penetrates.
+a mount point, raycast, or geometry sample read through `inspect-runtime`. A positive gap floats; a negative gap penetrates.
 Overlapping world AABBs between unrelated roots are a failure unless two different views prove the
 overlap is empty space.
 

package/skills/build-app/SKILL.md

@@ -19,6 +19,8 @@ reference: [direct Engine](references/direct-engine.md), [React](references/reac
   `canvas.width / canvas.clientWidth`.
 - Rigid bodies stay inert until Ammo loads through `WasmModule`. Copy the loader from the
   `physics/falling-shapes` example with `find-examples`.
+- `devtools` defaults to `true`, so debugging tools can find the app (`inspect-runtime`). Set it to
+  `false` only to hide a production build.
 
 ## Update loop
 

package/skills/configure-animation/SKILL.md

@@ -20,7 +20,7 @@ Get clip and joint names from `inspect-glb`; never guess them.
 ## Prove playback
 
 An active state or advancing state time does not prove motion. Sample two non-root joints over
-several rendered frames at idle and at both ends of each blend tree. Zero joint motion means a
+several rendered frames (`inspect-runtime`) at idle and at both ends of each blend tree. Zero joint motion means a
 binding, playback, or blend-weight failure.
 
 ## Diagnose

package/skills/inspect-runtime/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: inspect-runtime
+description: Use when reading state from a running PlayCanvas app, to reach its live Application through the Engine devtools hook without changing app code.
+---
+
+# Inspect a running app
+
+From Engine 2.23, every app announces itself to a hook at
+`globalThis[Symbol.for('playcanvas.inspector')]`. Read live state through it instead of adding
+`window.app` or debug code to the app.
+
+## Attach
+
+- Resolve `scripts/devtools-hook.js` relative to this skill and inject it as an init script that
+  runs before any page script. A hook defined later misses existing apps; reload instead.
+- Page code then reads `globalThis.__playcanvasApps`, a `Map` from each live app to
+  `{ version, revision, protocol }`. `app.init()` adds the entry and `app.destroy()` removes it.
+- The script chains a hook defined before it, such as a devtools extension's.
+- No entry means the Engine predates 2.23, the hook loaded late, or the app set
+  `devtools: false`. The Engine swallows errors thrown by the hook.
+- In 2.23.0 only the debug build (`playcanvas/debug`, `build/playcanvas.dbg.*`) announces apps; the
+  default import never calls the hook. Later 2.23 patches fix every build.
+
+## Read state
+
+- Read after `frameend`, so values reflect a rendered frame.
+- Return plain numbers and strings to the caller, not Engine objects.
+- Useful reads: `app.root.findByName()` and `findByTag()`, world positions and
+  `meshInstance.aabb`, `app.stats.drawCallCount` and `frameTime`, and
+  `entity.anim.baseLayer.activeState`.
+- Pause with `app.timeScale = 0`; `update` still runs with a zero `dt`. Step one frame by restoring
+  the scale, then zeroing it again on the next `frameend`.
+- Revert anything you change to take a measurement.
+
+## Inspector panel
+
+`@playcanvas/inspector` adds a panel for people: `new Inspector(app)` shows the hierarchy, assets,
+materials, shaders, textures, render targets, frame graph, and physics. It must import the app's
+own `playcanvas` package, so add it only to development builds. It draws over the canvas and
+applies view overrides, so destroy it before `verify-pixels` captures. Stepping through draws
+needs the debug build.

package/skills/inspect-runtime/scripts/devtools-hook.js

@@ -0,0 +1,23 @@
+// Records every PlayCanvas app (Engine 2.23+) in globalThis.__playcanvasApps, a Map from app to
+// { version, revision, protocol }. Run it before any page script; apps created earlier are missed.
+// Plain script with no imports or exports, so it runs as an init script, a <script>, or an import.
+{
+    const key = Symbol.for('playcanvas.inspector');
+    const prev = globalThis[key];
+    const apps = (globalThis.__playcanvasApps ??= new Map());
+
+    // chain a hook defined earlier, such as a devtools extension's, and install only once
+    if (!prev?.playcanvasApps) {
+        globalThis[key] = {
+            playcanvasApps: apps,
+            register(app, info) {
+                apps.set(app, info);
+                prev?.register?.(app, info);
+            },
+            unregister(app) {
+                apps.delete(app);
+                prev?.unregister?.(app);
+            }
+        };
+    }
+}

package/skills/override-shader-chunks/SKILL.md

@@ -8,7 +8,7 @@ description: Use when a PlayCanvas StandardMaterial needs custom shading its pro
 Overriding a `StandardMaterial` chunk keeps fog, tone mapping, shadows, skinning, and instancing
 intact. Use a `ShaderMaterial` only when the look needs its own vertex and fragment pair.
 
-- Set `material.shaderChunksVersion` to the installed major.minor, such as `'2.22'`. Chunk names
+- Set `material.shaderChunksVersion` to the installed major.minor, such as `'2.23'`. Chunk names
   and contracts change between versions, so read the installed chunk source, not memory.
 - Set chunks with `material.getShaderChunks(SHADERLANGUAGE_GLSL).set(name, source)` and the WGSL
   equivalent, then call `material.update()`. For every material on a device, use

package/skills/reduce-draw-calls/SKILL.md

@@ -5,10 +5,10 @@ description: Use when a PlayCanvas app has too many draw calls or is CPU-bound,
 
 # Cut draw calls
 
-Measure first with `app.stats.drawCalls.total` or `MiniStats`; the per-pass breakdown fills only in
-profiler builds. Also halve the pixel ratio and call `app.resizeCanvas()`: if frame time drops, the
-cost is fill rate, not draw calls. Stop at the first rung that meets the budget and report
-before-and-after counts.
+Measure first with `app.stats.drawCallCount` or `MiniStats`; the per-pass `app.stats.drawCalls`
+breakdown fills only in profiler builds. Also halve the pixel ratio and call `app.resizeCanvas()`:
+if frame time drops, the cost is fill rate, not draw calls. Stop at the first rung that meets the
+budget and report before-and-after counts.
 
 ## 1. Stop drawing hidden things
 

package/skills/verify-pixels/SKILL.md

@@ -33,4 +33,4 @@ description: Use when a PlayCanvas rendering change is meant to leave the image
 - Report the count, for example "0 of 65536 pixels differ", or the count and where the differences
   are. "Looks the same" is not a result.
 
-Keep harness code out of the shipped bundle.
+Keep harness code out of the shipped bundle; attach it through `inspect-runtime`.

package/templates/engine/base/README.md

@@ -17,6 +17,10 @@ npm run dev
 
 Open <http://localhost:5173>. Edit the files under `src/` and save to see the scene update.
 
+## Inspector
+
+`npm run dev` loads the [PlayCanvas Inspector](https://github.com/playcanvas/inspector), a debug panel for the hierarchy, assets, materials, textures, frame graph and physics. Press the backquote key (<kbd>&#96;</kbd>) to show or hide it, <kbd>F9</kbd> to pause and <kbd>F10</kbd> to step a frame. It is wired up in `vite.config.ts` and `src/inspector.ts` and is left out of production builds.
+
 ## Scripts
 
 | Command             | Description                       |

package/templates/engine/base/package.json

@@ -15,14 +15,15 @@
         "typecheck": "tsc --noEmit"
     },
     "dependencies": {
-        "playcanvas": "^2.22.6"
+        "playcanvas": "^2.23.0"
     },
     "devDependencies": {
         "@playcanvas/eslint-config": "3.0.0-beta.8",
+        "@playcanvas/inspector": "^0.2.0",
         "eslint": "^9.39.5",
         "prettier": "^3.9.9",
         "typescript": "~6.0.3",
-        "vite": "^8.3.1"
+        "vite": "^8.3.2"
     },
     "engines": {
         "node": ">=22.23.2"

package/templates/engine/base/src/inspector.css

@@ -0,0 +1,33 @@
+/* Inspector key hint, added on the dev server only by src/inspector.ts. Styled like the starter panels */
+.inspector-hint {
+    position: fixed;
+    bottom: 20px;
+    left: 20px;
+    z-index: 10;
+    margin: 0;
+    padding: 8px 12px;
+    border: 1px solid #ffffff24;
+    border-radius: 10px;
+    background: #0b1019d9;
+    box-shadow: 0 12px 40px #0008;
+    color: #aeb8c8;
+    font:
+        12px/1.6 Inter,
+        ui-sans-serif,
+        system-ui,
+        sans-serif;
+    backdrop-filter: blur(12px);
+    pointer-events: none;
+}
+
+.inspector-hint kbd {
+    padding: 1px 5px;
+    border-radius: 4px;
+    background: #263247;
+    color: #f8fafc;
+    font:
+        11px ui-monospace,
+        SFMono-Regular,
+        Menlo,
+        monospace;
+}

package/templates/engine/base/src/inspector.ts

@@ -0,0 +1,38 @@
+// Loaded by the dev server only (see vite.config.ts), so production builds never include it
+import { Inspector } from '@playcanvas/inspector';
+import type { AppBase } from 'playcanvas';
+
+import './inspector.css';
+
+type Hook = {
+    register?(app: AppBase, info: object): void;
+    unregister?(app: AppBase): void;
+};
+
+// Every app announces itself to this hook as it starts, whichever format created it
+const KEY = Symbol.for('playcanvas.inspector');
+const scope = globalThis as unknown as Record<symbol, Hook | undefined>;
+
+// Keep a hook installed earlier, such as a devtools extension's
+const prev = scope[KEY];
+
+scope[KEY] = {
+    register(app, info) {
+        prev?.register?.(app, info);
+
+        // Skip headless apps, such as the null apps @playcanvas/react creates for validation. Each
+        // panel destroys itself with its app
+        if (!app.graphicsDevice.isNull) new Inspector(app, { visible: false });
+    },
+    unregister(app) {
+        prev?.unregister?.(app);
+    }
+};
+
+console.info('PlayCanvas Inspector: press ` to toggle');
+
+// Key hint, a separate corner chip so the starter's own UI stays untouched
+const hint = document.createElement('p');
+hint.className = 'inspector-hint';
+hint.innerHTML = '<kbd>`</kbd> inspector · <kbd>F9</kbd> pause · <kbd>F10</kbd> step';
+document.body.append(hint);

package/templates/engine/base/tsconfig.json

@@ -21,5 +21,5 @@
         "noFallthroughCasesInSwitch": true,
         "noUncheckedSideEffectImports": true
     },
-    "include": ["src"]
+    "include": ["src", "vite.config.ts"]
 }

package/templates/engine/base/vite.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'vite';
+
+// https://vite.dev/config/
+export default defineConfig({
+    plugins: [
+        {
+            // Dev only: install the PlayCanvas Inspector before the app starts (press ` to toggle)
+            name: 'playcanvas-inspector',
+            apply: 'serve',
+            config: () => ({ optimizeDeps: { include: ['@playcanvas/inspector'] } }),
+            transformIndexHtml: () => [
+                { tag: 'script', attrs: { type: 'module', src: '/src/inspector.ts' }, injectTo: 'head-prepend' }
+            ]
+        }
+    ]
+});

package/templates/engine/interactive-sphere/src/App.ts

@@ -1,4 +1,4 @@
-import type { Layer, Texture } from 'playcanvas';
+import type { Layer } from 'playcanvas';
 import {
     createGraphicsDevice,
     AppBase,
@@ -89,7 +89,7 @@ const setupApp = async (canvas: HTMLCanvasElement, onClick: () => void) => {
     app.start();
 
     // Set up environment lighting (no skybox, just IBL)
-    app.scene.envAtlas = assets.envAtlas.resource as Texture;
+    app.scene.envAtlas = assets.envAtlas.resource!;
     const skyboxLayer = app.scene.layers.getLayerByName('Skybox');
     if (skyboxLayer) {
         skyboxLayer.enabled = false;

package/templates/engine/model-viewer/src/main.ts

@@ -1,4 +1,3 @@
-import type { ContainerResource } from 'playcanvas';
 import {
     AppBase,
     AppOptions,
@@ -57,7 +56,7 @@ await new Promise<void>((resolve) => {
 app.start();
 
 // A container asset holds the whole glTF scene, so instantiate it to get an entity hierarchy
-app.root.addChild((model.resource as ContainerResource).instantiateRenderEntity());
+app.root.addChild(model.resource!.instantiateRenderEntity());
 
 // The procedural sky is both the background and the image-based lighting, so no light or
 // environment map asset is needed. Its default luminance is scene-scale bright, so turn it down to

package/templates/engine/product-configurator/src/main.ts

@@ -1,4 +1,3 @@
-import type { ContainerResource, RenderComponent } from 'playcanvas';
 import {
     AppBase,
     AppOptions,
@@ -62,12 +61,12 @@ await new Promise<void>((resolve) => new AssetListLoader([product], app.assets).
 
 app.start();
 
-const car = (product.resource as ContainerResource).instantiateRenderEntity();
+const car = product.resource!.instantiateRenderEntity();
 car.setLocalEulerAngles(-90, -25, 0);
 app.root.addChild(car);
 app.root.syncHierarchy();
 
-const meshes = (car.findComponents('render') as RenderComponent[]).flatMap((render) => render.meshInstances);
+const meshes = car.findComponents('render').flatMap((render) => render.meshInstances);
 const bounds = meshes[0].aabb.clone();
 meshes.slice(1).forEach((mesh) => bounds.add(mesh.aabb));
 const scale = 5 / Math.max(bounds.halfExtents.x * 2, bounds.halfExtents.z * 2);
@@ -77,10 +76,10 @@ bounds.copy(meshes[0].aabb);
 meshes.slice(1).forEach((mesh) => bounds.add(mesh.aabb));
 car.setPosition(-bounds.center.x, 0.03 - bounds.getMin().y, -bounds.center.z);
 
-const body = meshes.filter((mesh) => mesh.material.name === 'material');
-const panels = meshes.filter((mesh) => mesh.material.name === 'material_1');
-const paint = body[0].material.clone() as StandardMaterial;
-const shade = panels[0].material.clone() as StandardMaterial;
+const body = meshes.filter((mesh) => mesh.material?.name === 'material');
+const panels = meshes.filter((mesh) => mesh.material?.name === 'material_1');
+const paint = body[0].material!.clone() as StandardMaterial;
+const shade = panels[0].material!.clone() as StandardMaterial;
 body.forEach((mesh) => (mesh.material = paint));
 panels.forEach((mesh) => (mesh.material = shade));
 paint.diffuse.fromString(PAINTS[0].color);

package/templates/react/base/README.md

@@ -17,6 +17,10 @@ npm run dev
 
 Open <http://localhost:5173>. Edit the files under `src/` and save to see the scene update.
 
+## Inspector
+
+`npm run dev` loads the [PlayCanvas Inspector](https://github.com/playcanvas/inspector), a debug panel for the hierarchy, assets, materials, textures, frame graph and physics. Press the backquote key (<kbd>&#96;</kbd>) to show or hide it, <kbd>F9</kbd> to pause and <kbd>F10</kbd> to step a frame. It is wired up in `vite.config.ts` and `src/inspector.ts` and is left out of production builds.
+
 ## Scripts
 
 | Command             | Description                       |

package/templates/react/base/package.json

@@ -16,19 +16,20 @@
     },
     "dependencies": {
         "@playcanvas/react": "^0.11.7",
-        "playcanvas": "^2.22.6",
+        "playcanvas": "^2.23.0",
         "react": "^19.3.0",
         "react-dom": "^19.3.0"
     },
     "devDependencies": {
         "@playcanvas/eslint-config": "3.0.0-beta.8",
+        "@playcanvas/inspector": "^0.2.0",
         "@types/react": "^19.3.0",
         "@types/react-dom": "^19.3.0",
         "@vitejs/plugin-react": "^6.1.1",
         "eslint": "^9.39.5",
         "prettier": "^3.9.9",
         "typescript": "~6.0.3",
-        "vite": "^8.3.1"
+        "vite": "^8.3.2"
     },
     "engines": {
         "node": ">=22.23.2"

package/templates/react/base/src/inspector.css

@@ -0,0 +1,33 @@
+/* Inspector key hint, added on the dev server only by src/inspector.ts. Styled like the starter panels */
+.inspector-hint {
+    position: fixed;
+    bottom: 20px;
+    left: 20px;
+    z-index: 10;
+    margin: 0;
+    padding: 8px 12px;
+    border: 1px solid #ffffff24;
+    border-radius: 10px;
+    background: #0b1019d9;
+    box-shadow: 0 12px 40px #0008;
+    color: #aeb8c8;
+    font:
+        12px/1.6 Inter,
+        ui-sans-serif,
+        system-ui,
+        sans-serif;
+    backdrop-filter: blur(12px);
+    pointer-events: none;
+}
+
+.inspector-hint kbd {
+    padding: 1px 5px;
+    border-radius: 4px;
+    background: #263247;
+    color: #f8fafc;
+    font:
+        11px ui-monospace,
+        SFMono-Regular,
+        Menlo,
+        monospace;
+}

package/templates/react/base/src/inspector.ts

@@ -0,0 +1,38 @@
+// Loaded by the dev server only (see vite.config.ts), so production builds never include it
+import { Inspector } from '@playcanvas/inspector';
+import type { AppBase } from 'playcanvas';
+
+import './inspector.css';
+
+type Hook = {
+    register?(app: AppBase, info: object): void;
+    unregister?(app: AppBase): void;
+};
+
+// Every app announces itself to this hook as it starts, whichever format created it
+const KEY = Symbol.for('playcanvas.inspector');
+const scope = globalThis as unknown as Record<symbol, Hook | undefined>;
+
+// Keep a hook installed earlier, such as a devtools extension's
+const prev = scope[KEY];
+
+scope[KEY] = {
+    register(app, info) {
+        prev?.register?.(app, info);
+
+        // Skip headless apps, such as the null apps @playcanvas/react creates for validation. Each
+        // panel destroys itself with its app
+        if (!app.graphicsDevice.isNull) new Inspector(app, { visible: false });
+    },
+    unregister(app) {
+        prev?.unregister?.(app);
+    }
+};
+
+console.info('PlayCanvas Inspector: press ` to toggle');
+
+// Key hint, a separate corner chip so the starter's own UI stays untouched
+const hint = document.createElement('p');
+hint.className = 'inspector-hint';
+hint.innerHTML = '<kbd>`</kbd> inspector · <kbd>F9</kbd> pause · <kbd>F10</kbd> step';
+document.body.append(hint);

package/templates/react/base/vite.config.ts

@@ -3,5 +3,16 @@ import { defineConfig } from 'vite';
 
 // https://vite.dev/config/
 export default defineConfig({
-    plugins: [react()]
+    plugins: [
+        react(),
+        {
+            // Dev only: install the PlayCanvas Inspector before the app starts (press ` to toggle)
+            name: 'playcanvas-inspector',
+            apply: 'serve',
+            config: () => ({ optimizeDeps: { include: ['@playcanvas/inspector'] } }),
+            transformIndexHtml: () => [
+                { tag: 'script', attrs: { type: 'module', src: '/src/inspector.ts' }, injectTo: 'head-prepend' }
+            ]
+        }
+    ]
 });

package/templates/react/product-configurator/src/App.tsx

@@ -1,7 +1,7 @@
 import { Application, Entity } from '@playcanvas/react';
 import { Camera, Light, Script } from '@playcanvas/react/components';
 import { useApp, useModel } from '@playcanvas/react/hooks';
-import type { ContainerResource, Entity as PcEntity, RenderComponent } from 'playcanvas';
+import type { ContainerResource, Entity as PcEntity } from 'playcanvas';
 import { Color, CylinderGeometry, Mesh, MeshInstance, StandardMaterial, TONEMAP_ACES2, Vec2, Vec3 } from 'playcanvas';
 import { CameraControls } from 'playcanvas/scripts/esm/camera-controls.mjs';
 import { ProceduralSky } from 'playcanvas/scripts/esm/sky/procedural-sky.mjs';
@@ -32,7 +32,7 @@ function Product({ color, shade }: { color: string; shade: string }) {
         entity.setLocalEulerAngles(-90, -25, 0);
         root.current.addChild(entity);
 
-        const meshes = (entity.findComponents('render') as RenderComponent[]).flatMap((render) => render.meshInstances);
+        const meshes = entity.findComponents('render').flatMap((render) => render.meshInstances);
         const bounds = meshes[0].aabb.clone();
         meshes.slice(1).forEach((mesh) => bounds.add(mesh.aabb));
         const scale = 5 / Math.max(bounds.halfExtents.x * 2, bounds.halfExtents.z * 2);
@@ -42,10 +42,10 @@ function Product({ color, shade }: { color: string; shade: string }) {
         meshes.slice(1).forEach((mesh) => bounds.add(mesh.aabb));
         entity.setPosition(-bounds.center.x, 0.03 - bounds.getMin().y, -bounds.center.z);
 
-        const body = meshes.filter((mesh) => mesh.material.name === 'material');
-        const panels = meshes.filter((mesh) => mesh.material.name === 'material_1');
-        paint.current = body[0].material.clone() as StandardMaterial;
-        tone.current = panels[0].material.clone() as StandardMaterial;
+        const body = meshes.filter((mesh) => mesh.material?.name === 'material');
+        const panels = meshes.filter((mesh) => mesh.material?.name === 'material_1');
+        paint.current = body[0].material!.clone() as StandardMaterial;
+        tone.current = panels[0].material!.clone() as StandardMaterial;
         body.forEach((mesh) => (mesh.material = paint.current!));
         panels.forEach((mesh) => (mesh.material = tone.current!));
         return () => {

package/templates/web-components/base/README.md

@@ -18,6 +18,10 @@ npm run dev
 
 Open <http://localhost:5173>. Edit `index.html` to change the scene.
 
+## Inspector
+
+`npm run dev` loads the [PlayCanvas Inspector](https://github.com/playcanvas/inspector), a debug panel for the hierarchy, assets, materials, textures, frame graph and physics. Press the backquote key (<kbd>&#96;</kbd>) to show or hide it, <kbd>F9</kbd> to pause and <kbd>F10</kbd> to step a frame. It is wired up in `vite.config.ts` and `src/inspector.ts` and is left out of production builds.
+
 ## Scripts
 
 | Command             | Description                       |

package/templates/web-components/base/package.json

@@ -15,15 +15,16 @@
         "typecheck": "tsc --noEmit"
     },
     "dependencies": {
-        "@playcanvas/web-components": "^0.26.0",
-        "playcanvas": "^2.22.6"
+        "@playcanvas/web-components": "^0.28.0",
+        "playcanvas": "^2.23.0"
     },
     "devDependencies": {
         "@playcanvas/eslint-config": "3.0.0-beta.8",
+        "@playcanvas/inspector": "^0.2.0",
         "eslint": "^9.39.5",
         "prettier": "^3.9.9",
         "typescript": "~6.0.3",
-        "vite": "^8.3.1"
+        "vite": "^8.3.2"
     },
     "engines": {
         "node": ">=22.23.2"

package/templates/web-components/base/src/inspector.css

@@ -0,0 +1,33 @@
+/* Inspector key hint, added on the dev server only by src/inspector.ts. Styled like the starter panels */
+.inspector-hint {
+    position: fixed;
+    bottom: 20px;
+    left: 20px;
+    z-index: 10;
+    margin: 0;
+    padding: 8px 12px;
+    border: 1px solid #ffffff24;
+    border-radius: 10px;
+    background: #0b1019d9;
+    box-shadow: 0 12px 40px #0008;
+    color: #aeb8c8;
+    font:
+        12px/1.6 Inter,
+        ui-sans-serif,
+        system-ui,
+        sans-serif;
+    backdrop-filter: blur(12px);
+    pointer-events: none;
+}
+
+.inspector-hint kbd {
+    padding: 1px 5px;
+    border-radius: 4px;
+    background: #263247;
+    color: #f8fafc;
+    font:
+        11px ui-monospace,
+        SFMono-Regular,
+        Menlo,
+        monospace;
+}

package/templates/web-components/base/src/inspector.ts

@@ -0,0 +1,38 @@
+// Loaded by the dev server only (see vite.config.ts), so production builds never include it
+import { Inspector } from '@playcanvas/inspector';
+import type { AppBase } from 'playcanvas';
+
+import './inspector.css';
+
+type Hook = {
+    register?(app: AppBase, info: object): void;
+    unregister?(app: AppBase): void;
+};
+
+// Every app announces itself to this hook as it starts, whichever format created it
+const KEY = Symbol.for('playcanvas.inspector');
+const scope = globalThis as unknown as Record<symbol, Hook | undefined>;
+
+// Keep a hook installed earlier, such as a devtools extension's
+const prev = scope[KEY];
+
+scope[KEY] = {
+    register(app, info) {
+        prev?.register?.(app, info);
+
+        // Skip headless apps, such as the null apps @playcanvas/react creates for validation. Each
+        // panel destroys itself with its app
+        if (!app.graphicsDevice.isNull) new Inspector(app, { visible: false });
+    },
+    unregister(app) {
+        prev?.unregister?.(app);
+    }
+};
+
+console.info('PlayCanvas Inspector: press ` to toggle');
+
+// Key hint, a separate corner chip so the starter's own UI stays untouched
+const hint = document.createElement('p');
+hint.className = 'inspector-hint';
+hint.innerHTML = '<kbd>`</kbd> inspector · <kbd>F9</kbd> pause · <kbd>F10</kbd> step';
+document.body.append(hint);

package/templates/web-components/base/tsconfig.json

@@ -21,5 +21,5 @@
         "noFallthroughCasesInSwitch": true,
         "noUncheckedSideEffectImports": true
     },
-    "include": ["src"]
+    "include": ["src", "vite.config.ts"]
 }

package/templates/web-components/base/vite.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'vite';
+
+// https://vite.dev/config/
+export default defineConfig({
+    plugins: [
+        {
+            // Dev only: install the PlayCanvas Inspector before the app starts (press ` to toggle)
+            name: 'playcanvas-inspector',
+            apply: 'serve',
+            config: () => ({ optimizeDeps: { include: ['@playcanvas/inspector'] } }),
+            transformIndexHtml: () => [
+                { tag: 'script', attrs: { type: 'module', src: '/src/inspector.ts' }, injectTo: 'head-prepend' }
+            ]
+        }
+    ]
+});

package/templates/web-components/interactive-sphere/src/main.ts

@@ -1,6 +1,5 @@
 import type { EntityElement } from '@playcanvas/web-components';
 import { whenReady } from '@playcanvas/web-components';
-import type { Texture } from 'playcanvas';
 import { Asset, TEXTURETYPE_RGBP } from 'playcanvas';
 import { CameraControls } from 'playcanvas/scripts/esm/camera-controls.mjs';
 import { Grid } from 'playcanvas/scripts/esm/grid.mjs';
@@ -40,7 +39,7 @@ await new Promise<void>((resolve) => {
 });
 
 // Light the scene from the environment, with the skybox itself left hidden
-app.scene.envAtlas = envAtlas.resource as Texture;
+app.scene.envAtlas = envAtlas.resource!;
 const skyboxLayer = app.scene.layers.getLayerByName('Skybox');
 if (skyboxLayer) {
     skyboxLayer.enabled = false;

package/templates/web-components/product-configurator/src/main.ts

@@ -1,6 +1,5 @@
 import type { AssetElement, EntityElement, ModelElement } from '@playcanvas/web-components';
 import { whenReady } from '@playcanvas/web-components';
-import type { RenderComponent } from 'playcanvas';
 import { Color, CylinderGeometry, Mesh, MeshInstance, StandardMaterial, Vec2, Vec3 } from 'playcanvas';
 import { CameraControls } from 'playcanvas/scripts/esm/camera-controls.mjs';
 import { ProceduralSky } from 'playcanvas/scripts/esm/sky/procedural-sky.mjs';
@@ -63,7 +62,7 @@ ground.addComponent('render', {
 const entity = model.entity!;
 entity.setLocalEulerAngles(0, -25, 0);
 entity.root.syncHierarchy();
-const meshes = (entity.findComponents('render') as RenderComponent[]).flatMap((render) => render.meshInstances);
+const meshes = entity.findComponents('render').flatMap((render) => render.meshInstances);
 const bounds = meshes[0].aabb.clone();
 meshes.slice(1).forEach((mesh) => bounds.add(mesh.aabb));
 const scale = 5 / Math.max(bounds.halfExtents.x * 2, bounds.halfExtents.z * 2);
@@ -73,10 +72,10 @@ bounds.copy(meshes[0].aabb);
 meshes.slice(1).forEach((mesh) => bounds.add(mesh.aabb));
 entity.setPosition(-bounds.center.x, 0.03 - bounds.getMin().y, -bounds.center.z);
 
-const body = meshes.filter((mesh) => mesh.material.name === 'material');
-const panels = meshes.filter((mesh) => mesh.material.name === 'material_1');
-const paint = body[0].material.clone() as StandardMaterial;
-const shade = panels[0].material.clone() as StandardMaterial;
+const body = meshes.filter((mesh) => mesh.material?.name === 'material');
+const panels = meshes.filter((mesh) => mesh.material?.name === 'material_1');
+const paint = body[0].material!.clone() as StandardMaterial;
+const shade = panels[0].material!.clone() as StandardMaterial;
 body.forEach((mesh) => (mesh.material = paint));
 panels.forEach((mesh) => (mesh.material = shade));
 paint.diffuse.fromString('#d6293e');