Normalize scene vs scenes into one engine boundary

BUILD_PR_LEVEL_01_SCENE_SCENES_BOUNDARY_NORMALIZATION

Author: DavidQ

docs/architecture/engine-scene-transitions.md

@@ -8,9 +8,9 @@ The transition layer exists to own scene handoff effects so that individual scen
 
 ## Added files
 
-- `src/engine/scenes/SceneTransition.js`
-- `src/engine/scenes/TransitionScene.js`
-- `src/engine/scenes/index.js`
+- `src/engine/scene/SceneTransition.js`
+- `src/engine/scene/TransitionScene.js`
+- `src/engine/scene/index.js`
 
 ## Responsibilities
 

docs/dev/CODEX_COMMANDS.md

@@ -2,25 +2,27 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Create `BUILD_PR_LEVEL_01_RENDERER_RENDERING_BOUNDARY_NORMALIZATION`.
+Create `BUILD_PR_LEVEL_01_SCENE_SCENES_BOUNDARY_NORMALIZATION`.
 
-Implement one clear rendering boundary decision:
+Implement one clear scene boundary decision:
 
-1. Do NOT keep both `renderer` and `rendering` as competing top-level engine concepts.
-2. Prefer `src/engine/rendering/` as the single domain boundary.
-3. Treat renderer as an implementation/class/module inside rendering, not as a separate parallel boundary.
+1. Do NOT keep both `scene` and `scenes` as competing top-level engine concepts when they overlap.
+2. Prefer `src/engine/scene/` as the single engine domain boundary.
+3. Treat plural "scenes" as content collections/instances owned by games or samples where appropriate, not as a competing engine boundary.
 4. Normalize imports/exports to that one truth.
-5. Keep the structure simple:
-   - do NOT over-split into `vector/`, `sprite/`, `layer/` unless the repo already has enough stable clustered content to justify it
-   - prefer a flatter rendering boundary first
-6. Update roadmap/status only if needed and only by status markers or additive truth-safe structure clarification.
-7. Validate:
+5. Keep ownership clear:
+   - engine owns reusable scene runtime logic only
+   - game/sample-specific scene content stays in its owning layer unless truly reusable
+6. Keep the changes surgical.
+7. Update roadmap/status only if needed and only by status markers or additive truth-safe structure clarification.
+8. Validate:
    - imports remain green
-   - no duplicate renderer/rendering top-level ambiguity remains
-   - any subfolders added are truthfully justified, not speculative
+   - no duplicate scene/scenes top-level ambiguity remains
+   - engine scene ownership is clearer
+   - section 1 residue is reduced or closed truthfully
 
 Final packaging step is REQUIRED:
-`<project folder>/tmp/BUILD_PR_LEVEL_01_RENDERER_RENDERING_BOUNDARY_NORMALIZATION.zip`
+`<project folder>/tmp/BUILD_PR_LEVEL_01_SCENE_SCENES_BOUNDARY_NORMALIZATION.zip`
 
 Hard rules:
 - implementation by Codex

docs/dev/COMMIT_COMMENT.txt

@@ -1,2 +1,2 @@
-Normalize renderer vs rendering into one engine boundary
-BUILD_PR_LEVEL_01_RENDERER_RENDERING_BOUNDARY_NORMALIZATION
+Normalize scene vs scenes into one engine boundary
+BUILD_PR_LEVEL_01_SCENE_SCENES_BOUNDARY_NORMALIZATION

docs/dev/reports/change_summary.txt

@@ -1,3 +1,3 @@
-- Added PR to collapse renderer/rendering ambiguity into one engine boundary
-- Recommends keeping rendering as the folder/domain and renderer as an implementation inside it
-- Avoids premature vector/sprite/layer over-structuring unless justified by real content
+- Added PR to collapse scene/scenes ambiguity into one engine boundary
+- Recommends keeping scene as the engine domain and moving content-owned scenes to their owning layer
+- Keeps section-1 normalization surgical and truth-based

docs/dev/reports/validation_checklist.txt

@@ -1,7 +1,7 @@
-- only one top-level rendering boundary remains
-- renderer no longer competes with rendering as a parallel concept
+- only one top-level engine scene boundary remains
+- scene no longer competes with scenes as a parallel engine concept
 - imports/exports normalized and valid
-- no speculative subfolder explosion introduced
+- game/sample scene content ownership is clearer
 - roadmap/status handling remains truth-safe
 - output ZIP created at:
-  <project folder>/tmp/BUILD_PR_LEVEL_01_RENDERER_RENDERING_BOUNDARY_NORMALIZATION.zip
+  <project folder>/tmp/BUILD_PR_LEVEL_01_SCENE_SCENES_BOUNDARY_NORMALIZATION.zip

docs/pr/BUILD_PR_LEVEL_01_SCENE_SCENES_BOUNDARY_NORMALIZATION.md

@@ -0,0 +1,61 @@
+# BUILD_PR_LEVEL_01_SCENE_SCENES_BOUNDARY_NORMALIZATION
+
+## Purpose
+Normalize engine scene runtime to one boundary: `src/engine/scene`.
+
+## Applied Delta
+
+### 1) Single top-level engine scene boundary enforced
+- Removed competing boundary directory:
+  - `src/engine/scenes/` (deleted)
+- Kept singular engine runtime boundary:
+  - `src/engine/scene/`
+
+### 2) Engine scene runtime ownership clarified
+- Replaced prior `scene` proxy wrappers with real runtime implementation files in `src/engine/scene/`:
+  - `Scene.js`
+  - `SceneManager.js`
+  - `SceneTransition.js`
+  - `SceneTransitionController.js`
+  - `TransitionScene.js`
+  - `AttractModeController.js`
+  - `index.js`
+- Engine continues to own reusable scene runtime logic only.
+- Game/sample scene content remains in game/sample-owned paths.
+
+### 3) Import/export normalization to one truth
+- Normalized all active runtime/test/sample imports from `src/engine/scenes/...` to `src/engine/scene/...` across:
+  - `games/*/game/*Scene.js`
+  - `samples/phase-*/**/*Scene*.js` and related sample mains
+  - `tests/scenes/*.test.mjs`
+  - `tests/core/EngineSceneLifecycle.test.mjs`
+  - `tests/final/PlatformUxSystems.test.mjs`
+- Updated documentation path references where touched:
+  - `docs/architecture/engine-scene-transitions.md`
+  - `docs/samples/sample-template.md`
+- Updated sample metadata references:
+  - `samples/metadata/samples.shared.boundaries.report.json`
+  - `samples/metadata/samples.index.metadata.json`
+
+## Roadmap Handling
+- No roadmap status-marker change was required.
+- No roadmap prose text was rewritten.
+
+## Validation
+- `node --check` across all changed JS/MJS files (`236` files checked, `0` parse failures).
+- Focused scene validation tests:
+  - `node tests/scenes/SceneManager.test.mjs`
+  - `node tests/scenes/TransitionScene.test.mjs`
+  - `node tests/scenes/AttractModeController.test.mjs`
+  - `node tests/core/EngineSceneLifecycle.test.mjs`
+  - `node tests/final/PlatformUxSystems.test.mjs`
+- Boundary checks:
+  - no remaining `src/engine/scenes` imports in `src`, `games`, `samples`, `tests`, `tools`, `docs/architecture`, `docs/samples`
+  - `src/engine` contains `scene` and no `scenes`
+
+## Packaging
+`<project folder>/tmp/BUILD_PR_LEVEL_01_SCENE_SCENES_BOUNDARY_NORMALIZATION.zip`
+
+## Scope guard
+- surgical implementation only
+- no unrelated repo changes

docs/samples/sample-template.md

@@ -16,11 +16,11 @@ Late samples may instead use shared sample-owned helpers from `samples/_shared/`
 ## main.js Rules
 - bootstrap only
 - import `Engine` from `src/engine/core/Engine.js` when booting directly
-- prefer public engine barrels such as `src/engine/input/index.js`, `src/engine/theme/index.js`, and `src/engine/scenes/index.js`
+- prefer public engine barrels such as `src/engine/input/index.js`, `src/engine/theme/index.js`, and `src/engine/scene/index.js`
 - set the scene and start the engine
 
 ## Scene Rules
-- extend `Scene` from `src/engine/scenes/index.js`
+- extend `Scene` from `src/engine/scene/index.js`
 - own sample-specific state, update, and render logic
 - do not own engine construction or document-wide wiring
 

games/AITargetDummy/game/AITargetDummyScene.js

@@ -4,7 +4,7 @@ David Quesenberry
 03/25/2026
 AITargetDummyScene.js
 */
-import { Scene } from '/src/engine/scenes/index.js';
+import { Scene } from '/src/engine/scene/index.js';
 import AITargetDummyDebugOverlay from './AITargetDummyDebugOverlay.js';
 import AITargetDummyInputController from './AITargetDummyInputController.js';
 import AITargetDummyWorld from './AITargetDummyWorld.js';

games/Asteroids/game/AsteroidsGameScene.js

@@ -4,7 +4,7 @@ David Quesenberry
 03/22/2026
 AsteroidsGameScene.js
 */
-import { AttractModeController, Scene } from '/src/engine/scenes/index.js';
+import { AttractModeController, Scene } from '/src/engine/scene/index.js';
 import { ParticleSystem } from '/src/engine/fx/index.js';
 import AsteroidsSession from './AsteroidsSession.js';
 import AsteroidsWorld from './AsteroidsWorld.js';

games/Gravity/game/GravityScene.js

@@ -4,7 +4,7 @@ David Quesenberry
 03/24/2026
 GravityScene.js
 */
-import { Scene } from '/src/engine/scenes/index.js';
+import { Scene } from '/src/engine/scene/index.js';
 import GravityAudio from './GravityAudio.js';
 import GravityInputController from './GravityInputController.js';
 import GravityWorld from './GravityWorld.js';