Final docs

.claude/scene.md

@@ -86,10 +86,38 @@ The shader used for each renderable:
 
 ## Transitioning between scenes
 
-To move to a new scene from JS, call the scene module's transition
-function (exact API in the `scene` JS module). The C side defers the
-actual switch to the start of the next `sceneUpdate` call so the
-current tick completes cleanly before any dispose runs.
+Scene transitions are handled entirely in JS via the `Scene` global.
+The `Scene` object is a singleton with:
+
+```js
+// Switch to a new scene. Calls dispose() on the current scene, then
+// init() on the new one. Both happen synchronously this tick.
+Scene.set(newSceneObject);
+
+// The current scene object (may be null):
+Scene.current
+```
+
+Typical scene-switch pattern:
+
+```js
+// Inside a scene's update or event handler:
+const nextScene = require("scenes/gameplay.js");
+Scene.set(nextScene);
+```
+
+`Scene.set` is synchronous -- it calls `dispose` on the old scene and
+`init` on the new scene before returning. If `init` needs async work
+(loading assets), use an async function and `await` inside `init`:
+
+```js
+nextScene.init = async function() {
+  await batch.load();  // wait for assets before proceeding
+};
+```
+
+The C side does not defer the transition; the switch happens inside
+the current `sceneUpdate` call.
 
 ## Relationship to the engine loop