create-playcanvas 0.8.1 → 0.10.0

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');

package/skills/build-hud/SKILL.md

@@ -1,38 +0,0 @@
----
-name: build-hud
-description: Use when building a PlayCanvas game's on-screen interface such as ready, pause, and victory overlays, menus, and live indicators like gauges, timers, or reload meters, so the interface is driven by game state, readable over the scene, and separate from the 3D hierarchy.
----
-
-# Game interface
-
-A HUD is a view of game state, not a source of it. Render it from the current state each frame or on
-each transition; never store gameplay truth in the DOM or a UI element.
-
-## Choose the UI layer
-
-- Build the interface in the natural UI layer for the surface — a DOM or React overlay, or the
-  Engine `screen` and `element` UI — decided with the `build-app` skill. Keep it outside gameplay
-  model hierarchies, as `assemble-scene` requires.
-- For a screen-space Engine UI, adapt a user-interface example with `find-examples` rather than
-  guessing element anchoring, scaling, and font handling.
-
-## Drive from state
-
-- Map each overlay to a game state and each indicator to a snapshot field. A transition shows or
-  hides overlays; it does not duplicate the state the game already owns (see `manage-game-state`).
-- An indicator that is idle most of the time toggles `enabled` with its visibility; an element left
-  drawing at opacity 0 still costs a draw call every frame (see `reduce-draw-calls`).
-- Anchor and scale elements to the viewport so the layout holds at the target resolution and on
-  resize. Verify at the acceptance resolution, not the default window size.
-- Keep copy minimal and legible over the scene: back text with a plate or shadow where the frame is
-  bright, and unify interface colour with the scene's grade from `light-scene`.
-
-## Prove it reflects state
-
-Drive real input through every transition and confirm with screenshots that the correct overlay
-shows and each indicator tracks the snapshot — a reload meter empties and refills, a timer advances,
-a menu appears only in its state. A saved filepath or a visibility flag is not visual evidence;
-inspect the returned pixels as the local agent guide requires.
-
-Choose the authoring surface with the `build-app` skill and build the interface through its own UI
-primitives before reaching into the Engine.

package/skills/manage-game-state/SKILL.md

@@ -1,48 +0,0 @@
----
-name: manage-game-state
-description: Use when structuring a PlayCanvas game's control flow — a small state machine such as ready, playing, paused, and over, pointer-lock capture, pausing on focus or pointer-lock loss, a full reset, and a stable clock and timestep — so the loop stays deterministic and recoverable.
----
-
-# Game state and loop
-
-Model the game as a small explicit state machine with one owner of the clock. Every transition names
-its states; behaviour, input, and the interface read the current state rather than a scatter of
-booleans.
-
-## States and transitions
-
-- Enumerate the states — for example ready, playing, paused, over — and make transitions explicit
-  and total. Do not infer state from side effects.
-- Gate the simulation on the active state: advance gameplay, timers, and physics only while playing.
-
-## Capture input and pause
-
-- Request pointer lock from a user gesture such as a click, never on load. Treat loss of pointer lock
-  and tab blur as a pause: freeze the simulation and the clock, and resume on the next gesture.
-- Make `pointerlockchange` idempotent: when `document.pointerLockElement` is the canvas, transition
-  ready or paused to playing and leave playing unchanged; only transition playing to paused when the
-  element is no longer the canvas. Never implement it as a toggle. Browsers and automation can both
-  report an already-acquired lock, and a duplicate enter event must not pause the game.
-- Clamp the per-frame delta before integrating anything, as `build-app` requires, so a backgrounded
-  tab or a slow frame cannot inject one large step into movement, cooldowns, or the clock.
-
-## Reset
-
-- A reset restores every owned system to its ready values — entities, camera, clock, timers,
-  cooldowns, effects, and overlays — not only the player. Route reset through the same setup the
-  initial state uses, so ready and reset cannot drift apart.
-- Transition to `ready` explicitly before releasing pointer lock. Never derive the reset state from
-  `document.pointerLockElement`; pointer lock is an input side effect, not the state machine.
-- Define timer semantics once and keep them literal in state and snapshots. A field named `reload`
-  is remaining cooldown time: `0` means ready, firing assigns a positive duration, and the active
-  loop counts it down to exactly `0`. Do not expose a normalized readiness value under that name.
-
-## Prove the loop
-
-Drive the full cycle with real input: enter play, lose pointer lock and confirm the clock and
-simulation freeze, resume, reset and confirm every field returns to its ready value, then reach the
-end state and restart. Read these from the app's own state snapshot, never from console mutation —
-manufactured state is not evidence.
-
-Choose the authoring surface with the `build-app` skill and own the loop and lifecycle in the surface
-that creates the application.