create-playcanvas 0.8.1 → 0.9.0

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

@@ -1,65 +1,25 @@
 ---
 name: override-shader-chunks
-description: Use when a PlayCanvas StandardMaterial needs custom shading its properties cannot express — procedural or stylized looks, custom vertex displacement, per-material screen effects — before writing a standalone shader from scratch.
+description: Use when a PlayCanvas StandardMaterial needs custom shading its properties cannot express, such as stylized looks or vertex displacement, before writing a ShaderMaterial.
 ---
 
-# Override shading through chunks
-
-A `StandardMaterial`'s shader is assembled from named chunks (lighting, combine, transform, and
-more). Overriding one keeps the rest of the pipeline — fog, tonemapping, shadows, skinning,
-instancing — intact. Reach for a fully custom `ShaderMaterial` only when the look needs a stage the
-chunk system does not expose at all (its own vertex/fragment pair and attribute layout); a chunk
-override is the default for everything else, since it is cheaper and stays integrated.
-
-## Pin the version, read the source
-
-Set `material.shaderChunksVersion` to the installed engine's major.minor (for example `'2.22'`)
-before shipping any override. Chunk names and their contracts — what a chunk defines, what globals
-it reads or writes — are version-keyed and change between releases. Read the installed `playcanvas`
-source for the exact chunk being touched; do not recall its contract from memory or an older
-version's documentation.
-
-## Clone before overriding a shared material
-
-Clone a material that other mesh instances share — including default and asset-imported materials —
-before changing its chunks, properties, or material-level parameters for only some meshes, and assign
-the clone. For per-mesh uniforms, use `meshInstance.setParameter()` without cloning the material.
-
-## Set chunks through the documented accessor
-
-Use `material.getShaderChunks(SHADERLANGUAGE_GLSL).set(name, source)`, and the WGSL equivalent —
-the public, documented method — not the underlying `shaderChunks` maps, which are internal. Call
-`material.update()` after any change so cached shader variants are cleared.
-
-## Emissive-only overrides
-
-An `emissivePS` override implements `void getEmission()`, writing the result into `dEmission`. When
-the override is meant to fully drive the visible color, zero the material's `diffuse`/`specular` and
-disable `useSkybox` so no other lighting term still contributes underneath it.
-
-## Uniforms are raw
-
-`setParameter` uploads exactly what it is given, with no color-space conversion. Convert any
-authored sRGB color with `Color#linear()` before calling `setParameter`; an sRGB color passed
-straight through renders visibly darker and less saturated than it was authored.
-
-## Keep vertex chunks instancing-aware
-
-A custom `transformCoreVS` (or any vertex chunk reading the model matrix) must keep the engine's
-`INSTANCING` define path — pulling the per-instance matrix under that define — with a
-non-instanced fallback that uses `matrix_model` directly, matching the stock chunk's structure.
-Dropping this path silently breaks instancing for any mesh instance using the material.
-
-## Provide GLSL and WGSL, or pin to WebGL
-
-Override both `SHADERLANGUAGE_GLSL` and `SHADERLANGUAGE_WGSL` chunks for anything touched. On a
-WebGPU device, a chunk supplied only in GLSL forces the material's entire shader — not just that
-chunk — onto a GLSL-compiled-then-transpiled path; without the optional transpiler modules loaded
-(the common case), that shader fails to compile. Supply both languages, or explicitly pin the
-graphics device to WebGL if WGSL support is not required.
-
-## Expand bounds for vertex displacement
-
-If the override displaces vertices, expand the mesh's bounds by the maximum displacement (see
-`apply-conventions`) — CPU-computed bounds never observe shader-side deformation, so culling breaks
-silently otherwise.
+# Override shader chunks
+
+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
+  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
+  `ShaderChunks.get(device, language)`; the global `shaderChunks` object is deprecated.
+- Supply both GLSL and WGSL. On WebGPU, one GLSL-only chunk sends the whole shader through a
+  transpiler that is usually not loaded, so it fails to compile. Otherwise pin the device to WebGL.
+- Clone shared materials, including imported ones, before overriding them for only some meshes.
+  Per-mesh uniforms use `meshInstance.setParameter()`.
+- Uniforms are raw; convert sRGB colours with `Color#linear()`.
+- Vertex chunks that read the model matrix, such as `transformCoreVS`, must keep the `INSTANCING`
+  path with a `matrix_model` fallback, like the stock chunk.
+- Expand mesh bounds by the maximum displacement; CPU bounds do not see shader deformation.
+- For an emissive-only look, implement `getEmission()` writing `dEmission`, zero `diffuse` and
+  `specular`, and disable `useSkybox`.

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

@@ -1,67 +1,37 @@
 ---
 name: reduce-draw-calls
-description: Use when a PlayCanvas application submits too many draw calls or frame time is CPU-bound — repeated meshes, dense grids, always-on interface elements — before hand-writing mesh merging or custom renderers.
+description: Use when a PlayCanvas app has too many draw calls or is CPU-bound, before hand-merging meshes or writing custom renderers.
 ---
 
-# Cut draw calls, ranked by cost
+# Cut draw calls
 
-Work the ladder in order and stop at the first rung that clears the budget. Each rung trades away
-less flexibility than the next; skipping straight to a custom renderer or hand-written mesh merge
-costs more engineering time than the draw calls it saves.
+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
+## 1. Stop drawing hidden things
 
-Read `app.stats.drawCalls.total` (or the `forward`/`depth`/`shadow` breakdown) before changing
-anything, or drop in `MiniStats` for a live overlay. Every rung below is proved against this number,
-not against intuition about what "looks expensive."
+An element at opacity 0 still draws. Set `enabled = false`.
 
-Draw count alone does not identify the bottleneck. Test sensitivity to pixel cost by halving the
-effective pixel ratio (`Math.min(graphicsDevice.maxPixelRatio, window.devicePixelRatio)`) and calling
-`app.resizeCanvas()`. Verify the backbuffer shrank and compare frame times at the same scene state.
-If frame time improves materially, prioritize resolution, multisampling and per-pixel shader cost.
-Otherwise profile CPU and GPU work before choosing a rung; restore the original ratio after the test.
+## 2. BatchManager
 
-## Rung 1: stop drawing invisible things
+Call `app.batcher.addGroup(name, dynamic, maxAabbSize)`, then set `batchGroupId` on render, sprite,
+or element components. Use `dynamic: false` for geometry that never moves. Members join when
+enabled in the live tree, in any order, and groups regenerate automatically when membership
+changes. Call `markGroupDirty(id)` only after moving members of a static group. Manual `AppOptions`
+bootstraps must set `batchManager`.
 
-An element at opacity 0 still submits a draw call — its mesh instance exists and is still in a
-layer, so the GPU processes it every frame for no visible result. Toggle `enabled` on the entity to
-actually skip it. Check every element that is ever fully transparent, not only the ones on screen
-when you're profiling — this rung is easy to skip precisely because nothing looks wrong.
+## 3. Hardware instancing
 
-## Rung 2: `BatchManager` — merge without touching shaders
+Use this for many copies of one mesh and material with per-frame transforms. Build a buffer with
+`VertexFormat.getDefaultInstancingFormat(device)`, one mat4 per instance, and call
+`meshInstance.setInstancing(vb)`; `instancingCount` follows the buffer.
 
-`app.batcher.addGroup(name, dynamic, maxAabbSize)`, then set `batchGroupId` on each member's
-component (render, sprite, or UI element). Use `dynamic: false` for geometry that never moves.
+There is no per-instance culling. By default the group always draws; `setInstancing(vb, true)`
+culls it as one unit against a `RenderComponent#customAabb` covering every instance. Split large
+instance sets into spatial chunks. Custom vertex chunks need the `INSTANCING` path
+(`override-shader-chunks`). Start from the `graphics/instancing-basic` and
+`graphics/instancing-custom` examples.
 
-Contract: the `batchGroupId` setter only inserts into the batcher while `entity.enabled` is true,
-and that flag requires both the local enable state and hierarchy attachment — set `batchGroupId`
-after the entity is parented into the live tree, not before, or the member silently drops out of the
-group. `BatchManager.generate()` runs once automatically on the app's first rendered frame; if group
-membership changes afterward, call `app.batcher.markGroupDirty(id)` (or `generate([id])`) yourself.
-An Engine-only app without the full `Application` bootstrap must register the class via
-`AppOptions.batchManager` before it can batch anything.
-
-## Rung 3: hardware instancing — merge without touching layout
-
-Reach for this once distinct materials or per-frame transform updates would defeat `BatchManager`.
-Build a per-instance vertex buffer with `VertexFormat.getDefaultInstancingFormat(device)` (one mat4
-per instance), call `meshInstance.setInstancing(vb)`, and set `instancingCount`. A custom vertex
-chunk needs its own `INSTANCING` code path with an identity-matrix fallback for the non-instanced
-case (cross-reference `override-shader-chunks`).
-
-Culling trade-off: instanced meshes cull as one unit against a single bounding volume — an
-off-screen instance inside an otherwise-visible group still draws unless you opt in. Pass
-`setInstancing(vb, true)` and set a `RenderComponent#customAabb` spanning every instance's world
-extent so the renderer has something correct to cull against instead of culling nothing or
-culling the whole group by one instance's bounds.
-
-Adapt the official recipes rather than deriving the buffer layout or vertex-shader wiring from
-memory: `graphics/instancing-basic` for the format/buffer contract, `graphics/instancing-custom` for
-the vertex-shader side. Locate both at the installed engine version via `find-examples`.
-
-## Prove and report
-
-Verify the rendered image is unchanged with `verify-pixels` before calling the change done —
-merging or instancing must not move a single pixel. Re-measure `app.stats.drawCalls` afterward and
-state the before/after counts in the change description; "fewer draw calls" without numbers is not
-a result.
+Confirm the image is unchanged with `verify-pixels`.

package/skills/reuse-scripts/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: reuse-scripts
-description: Use before implementing non-core PlayCanvas behavior to discover the installed Engine's curated scripts and reuse or adapt those that fit the required behavior and approved art direction.
+description: Use before writing PlayCanvas behaviour from scratch, to reuse the scripts and helpers the installed Engine already ships.
 ---
 
-# Engine scripts
+# Reuse shipped Engine code
 
-Before writing behavior from scratch, inspect the curated scripts shipped with the installed
-`playcanvas` package under `scripts/esm/**`. Discover the current set:
+Before writing behaviour, check what the installed `playcanvas` package already provides.
+
+Scripts live under `scripts/esm/**`; import only from there. List them:
 
 ```sh
 rg 'static scriptName =' node_modules/playcanvas/scripts/esm \
@@ -14,50 +15,26 @@ rg 'static scriptName =' node_modules/playcanvas/scripts/esm \
   | sort
 ```
 
-Read the selected file for its named export, `@attribute` properties, and defaults. Not every module
-is a `Script`; the parsers below `scripts/esm/parsers` are plain classes registered with a resource
-handler instead.
-
-Only import from `scripts/esm/**`. Legacy sibling directories depend on the global Engine namespace.
-After selecting a script, use `find-examples` to locate its matching versioned Engine example. When
-`node_modules/playcanvas` is a linked or source checkout, its `examples/src/examples/**` are already
-on disk; read them there and skip the fetch.
-
-## Check fit before integration
-
-Compare candidates with the required behavior, approved art direction, and runtime constraints.
-Reuse a suitable script directly or adapt its configuration and extension points. If none fits,
-state the limitation and implement only the missing behavior, preserving reusable parts and their
-lifecycle, bounds, and input invariants.
-
-For visual behavior, resolve an unclear art direction with the user before substantial implementation.
-Present references, mockups, or inexpensive variants; follow existing approval and confirm significant
-departures. A script's default appearance is only a starting point for assessing its fit.
-
-## Adapt the reference integration
-
-Treat the selected script source and its closest official example as complementary references:
+Common ones are `CameraControls`, `FirstPersonController`, `ThirdPersonController`,
+`ShadowCatcher`, `ProceduralSky`, `Water`, and `Grid`, plus XR and splat scripts. Modules under
+`scripts/esm/parsers` are resource-handler classes, not scripts.
 
-1. Read the source for exports, properties, defaults, fallbacks, required components, and lifecycle.
-2. Read the example for assets, entity references, mesh requirements, layer ordering, scene settings,
-   and render-pipeline setup.
-3. Integrate the selected behavior with its required components, assets, and passes. Adapt the look
-   to the approved direction and preserve defaults and dependencies that still apply.
-4. After a rendered frame, fail on console, shader, or missing-asset diagnostics. Exercise the
-   behavior with real input where applicable and inspect returned screenshots from representative
-   views at the final backbuffer density.
-5. Use the example to check integration correctness and the user's approved direction to judge the
-   final look. Report any remaining gap.
+Core exports that are not scripts include `CameraFrame` for post-processing, `Picker`
+(`getSelectionAsync`), `TransformGizmo`, `OutlineRenderer`, `MiniStats`, `GltfExporter`, and
+`UsdzExporter`.
 
-If no matching example exists, state that and derive the integration from installed source instead
-of inventing it from memory.
+## Integrate
 
-## Preserve grouped defaults
+1. Read the source for exports, `@attribute` properties, defaults, and required components.
+2. Find its official example with `find-examples`, and copy the assets, layers, scene settings, and
+   render setup it depends on.
+3. Adapt configuration and extension points. If nothing fits, implement only the missing part and
+   say what was missing.
+4. After a rendered frame, fail on console, shader, or missing-asset errors.
 
-Grouped property updates differ by authoring surface. Read the selected reference and preserve
-defaults that are not being changed.
+Keep a shipped script's input mapping and damping unless asked otherwise, and verify input
+directions with real input rather than deriving signs from memory.
 
-Read exactly one reference matching the code being edited:
-[direct Engine](references/direct-engine.md), [React](references/react.md), or
-[Web Components](references/web-components.md). Choose from imports and markup, not installed
-dependencies alone.
+Grouped property updates differ by surface; preserve defaults you do not change. Read only the
+reference matching the code: [direct Engine](references/direct-engine.md),
+[React](references/react.md), or [Web Components](references/web-components.md).

package/skills/reuse-scripts/references/direct-engine.md

@@ -6,9 +6,9 @@ and attach it with `entity.script.create()`. Preserve an existing script compone
 Some production helpers are core Engine exports rather than scripts. Follow the matching example's
 construction and teardown contract instead of forcing them through `script.create`.
 
-Keep script constructors at module scope. `create` takes two distinct option keys that are not
-interchangeable: `properties` is assigned straight onto the instance, while `attributes` supplies
-declared `@attribute` fields. Passing the wrong one silently does nothing.
+Keep script constructors at module scope. `create` takes two option keys: `attributes` is passed to
+the constructor for declared `@attribute` fields, while `properties` is `Object.assign`ed onto the
+instance after construction, overwriting any field it names.
 
 Prefer mutating an existing grouped property when only a few fields change; preserve other defaults
 and follow any update or rebuild contract in the selected source.

package/skills/verify-pixels/SKILL.md

@@ -1,70 +1,36 @@
 ---
 name: verify-pixels
-description: Use when changing PlayCanvas rendering code that must not visibly change the rendered image — draw-call optimization, hardware instancing, shader or material refactors, noise or lightmap bakes, or asset pipeline swaps — before shipping.
+description: Use when a PlayCanvas rendering change is meant to leave the image unchanged, to prove it with deterministic captures and pixel comparison.
 ---
 
 # Prove pixels unchanged
 
-Choose the gate before building the capture harness. Both classes require controlled captures
-that cover the affected surfaces.
+## Choose the gate
 
-## Classify the change
+- Byte-exact: the change keeps the same decoded data and the same shading math, so every pixel
+  must match.
+- Side-by-side review: the change alters sampled values, random order, precision, or where math
+  runs. Report it as "not byte-gateable" and show old and new at each pose; do not invent
+  thresholds.
 
-| Change | Gate |
-| --- | --- |
-| Batching, instancing, mesh indexing, chunking, pooling that preserves RNG order, an asset format swap with identical decoded data | Byte-exact matrix |
-| Re-rolled or re-sampled procedural noise, a changed RNG consumption order, math moved between CPU and GPU, changed precision, fewer octaves or samples | Not byte-gateable: side-by-side review |
+## Make frames deterministic
 
-For the second class, sampled values or precision can change. Report it as "not byte-gateable" and
-use the side-by-side gate after the shared capture setup below; do not invent uncalibrated perceptual
-thresholds to approve it.
+- Load every asset and match camera, canvas size, lighting, and animation time between builds. Seed
+  incidental randomness.
+- Drive animated shaders from one app-owned time value, not `Date.now()` or `performance.now()`.
+- `app.timeScale = 0` makes `dt` zero, but `update` still runs; anything counting frames or reading
+  wall-clock time still advances.
+- Set `app.autoRender = false`, then `app.renderNextFrame = true` before each frame to capture.
 
-## Cover every touched surface
+## Capture and compare
 
-List every touched material or surface and a capture pose it dominates. Use at least two
-representative poses, adding as many as coverage requires; a horizon strip does not cover a water
-shader change. For animated surfaces, include a second phase mid-animation.
+- WebGL: `await (device as WebglGraphicsDevice).readPixelsAsync(x, y, w, h, pixels)`. WebGPU:
+  render into a `RenderTarget` and read its `colorBuffer` with `Texture#read()`. Avoid colour
+  conversion and lossy encoding.
+- Capture the unmodified build twice first. The captures must match exactly, or the harness itself
+  is noisy.
+- Cover every touched surface in at least two poses, plus a mid-animation phase where relevant.
+- 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.
 
-## Make the frame deterministic
-
-For both gates, load assets fully and match the scene state, camera, canvas size, lighting, and
-animation time between builds. Seed incidental randomness so only the intended change varies.
-
-- Drive every animated shader or vertex effect from one app-owned time value, never `Date.now()` or
-  `performance.now()` read inside the render path, so a captured phase is exactly reproducible.
-- Freeze the clock with `app.timeScale = 0` before capturing; nothing should advance between frames
-  you did not explicitly step.
-- Step frames explicitly: set `app.autoRender = false` once, then set `app.renderNextFrame = true`
-  before each frame you want rendered. The engine renders exactly that frame and clears the flag —
-  do not rely on the free-running render loop plus a timed screenshot.
-
-## Gate and report the byte-exact class
-
-Read the exact backbuffer with `await device.readPixelsAsync(x, y, w, h, pixels)`. In the installed
-engine this method lives on `WebglGraphicsDevice`, so narrow to it; WebGPU needs an equivalent
-readback. An existing capture path must preserve raw pixels without colour conversion or lossy
-encoding before comparison.
-
-Before trusting any diff between the old and new build, capture the same pose × phase matrix twice
-from the *unmodified* build. Two captures of identical, frozen state must be bit-identical. If they
-are not, the capture path itself is the source of noise — an unseeded animation, an asset still
-loading, a GPU timing race — and must be fixed before it can say anything about the real change.
-
-Byte-compare each pose × phase pair between the two builds; do not diff by looking. Zero differing
-pixels passes outright. Any nonzero diff must be reviewed on-screen, and its cause and extent stated
-in the change description — never merged silently. Report the actual count every time, for example
-"0 of 65536 pixels differ" or "312 of 65536 pixels differ, confined to the object's silhouette edge".
-"Looks the same" or "no visible difference" is not a result.
-
-## Review the other class side by side
-
-For each planned pose and phase, show the controlled old and new captures together in one image
-for the user's accept or reject. State what differs and why, for example "noise tile replaces
-runtime fbm: pattern period changed, tint and amplitude match". If no difference is visible, report
-that. Skip the cross-build byte comparison for this class.
-
-## Keep the harness small
-
-Reuse the project's capture harness when available. Keep harness code out of the shipped bundle,
-behind a dev-only import or in a tools directory, and list its files in the change description.
-Capture with a headless browser and return images only at accept-or-reject points, not after every edit.
+Keep harness code out of the shipped bundle.

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.