Skip to content

Commit 7060f86

Browse files
author
DavidQ
committed
APPLY_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD: implement composition-driven runtime scene loading with safe hot reload, validation-aware fallback, deterministic render order preservation, and focused automated coverage.
1 parent 839b440 commit 7060f86

10 files changed

Lines changed: 1150 additions & 44 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 25 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -3,24 +3,33 @@ David Quesenberry
33
04/05/2026
44
codex_commands.md
55

6-
# Codex Commands
6+
# CODEX COMMANDS
77

8-
## Recommended model
9-
- MODEL: GPT-5.4
10-
- REASONING: high
8+
## APPLY_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD
119

12-
## Command
13-
Create APPLY_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD as the implementation PR for the approved runtime scene loader and hot reload contract.
10+
MODEL: GPT-5.3-codex
11+
REASONING: high
12+
13+
COMMAND:
14+
Apply APPLY_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD as a focused implementation PR.
1415

1516
Requirements:
16-
- follow PLAN_PR -> BUILD_PR -> APPLY_PR exactly
17-
- implement only what is defined in BUILD_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD
18-
- keep changes surgical and architecture-safe
19-
- preserve locked public engine mappings
20-
- include deterministic load/reload ordering
21-
- include structured validation and error behavior
22-
- include focused tests for valid/invalid/reload-order/composition-reload paths
23-
- update docs/dev reports after validation
17+
- Implement the approved runtime scene loader and hot reload flow only
18+
- Keep orchestration above engine core; do not pollute engine systems with tool-specific quirks
19+
- Consume existing approved render pipeline/composition contracts rather than inventing new ones
20+
- Preserve deterministic render order
21+
- Add structured validation-aware reload behavior
22+
- Preserve last-known-good scene on reload failure
23+
- Add focused automated tests for load, reload, validation failure, disposal, and repeated reload stability
24+
- Keep changes surgical and architecture-aligned
25+
- Do not introduce destructive runtime-breaking changes unless absolutely required and documented
26+
- Produce repo-structured implementation delta ZIP at:
27+
<project folder>/tmp/APPLY_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD_delta.zip
28+
29+
Expected documentation updates:
30+
- docs/dev/change_summary.txt
31+
- docs/dev/file_tree.txt
32+
- docs/dev/validation_checklist.txt
2433

25-
Output zip path:
26-
- <project folder>/tmp/APPLY_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD_delta.zip
34+
Commit comment source:
35+
- docs/dev/commit_comment.txt

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,4 @@ David Quesenberry
33
04/05/2026
44
commit_comment.txt
55

6-
docs: build runtime scene loader and hot reload contract bundle
6+
apply(runtime): implement runtime scene loader and validation-aware hot reload with deterministic ordering and last-known-good fallback

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,4 @@ David Quesenberry
33
04/05/2026
44
next_command.txt
55

6-
APPLY_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD
6+
PLAN_PR_DEV_CONSOLE_AND_DEBUG_OVERLAY

‎docs/dev/change_summary.txt‎

Lines changed: 45 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,48 @@ David Quesenberry
33
04/05/2026
44
change_summary.txt
55

6-
Summary:
7-
- Added docs-only BUILD bundle for runtime scene loader and hot reload
8-
- Defined formal responsibilities for SceneCompositionLoader and RuntimeSceneLoader
9-
- Defined deterministic hot reload lifecycle and stage ordering
10-
- Locked watcher bridge boundaries and public engine mappings
11-
- Added validation/error taxonomy and composition-driven reload rules
12-
- Added APPLY-focused test plan and manual validation targets
13-
- Updated command, commit, file tree, and next-command docs/dev artifacts
6+
APPLY_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD summary
7+
8+
Implemented focused runtime orchestration module:
9+
- Added `tools/shared/runtimeSceneLoaderHotReload.js`
10+
- Keeps orchestration above engine core and consumes existing approved render pipeline contracts
11+
- Uses `runRenderContractRuntimePath` for contract validation/normalization/composition/sequencing
12+
- Preserves deterministic runtime domain ordering: parallax -> tilemap -> sprite -> vector -> overlay
13+
14+
Implemented runtime responsibilities:
15+
- `createSceneCompositionLoader` for composition/asset-document contract loading
16+
- `createRuntimeSceneLoader` for deterministic runtime domain assembly
17+
- `createHotReloadCoordinator` for validation-aware reload and scene-state management
18+
- `createWatcherBridge` for change-event normalization and watcher boundary isolation
19+
20+
Implemented reload safety behavior:
21+
- Contract validation is required before applying reload
22+
- Reload rejects invalid changes with structured reports
23+
- Last-known-good runtime scene remains active on reload failure
24+
- Targeted reload domains supported when changed paths map to composition references
25+
- Full reload used for composition changes or unknown path impact
26+
- Replaced domain handles are disposed with guarded error reporting
27+
28+
Implemented focused automated coverage:
29+
- Added `tests/tools/RuntimeSceneLoaderHotReload.test.mjs`
30+
- Covers initial load success
31+
- Covers targeted reload success
32+
- Covers validation failure fallback to last-known-good
33+
- Covers watcher bridge normalization/coalescing behavior
34+
- Covers repeated reload stability and disposal behavior
35+
36+
Test harness integration:
37+
- Updated `tests/run-tests.mjs` to include `RuntimeSceneLoaderHotReload`
38+
39+
Validation:
40+
- `node --check tools/shared/runtimeSceneLoaderHotReload.js`
41+
- `node --check tests/tools/RuntimeSceneLoaderHotReload.test.mjs`
42+
- `node --check tests/run-tests.mjs`
43+
- Targeted test run for `RuntimeSceneLoaderHotReload` passed
44+
- Full suite run passed (`112/112 explicit run() tests passed`)
45+
46+
Scope guardrails honored:
47+
- No engine-core API rewrites
48+
- No tool-specific quirks moved into engine systems
49+
- No unrelated refactors
50+
- Changes remain surgical and architecture-aligned

‎docs/dev/file_tree.txt‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,10 @@ David Quesenberry
33
04/05/2026
44
file_tree.txt
55

6-
docs/pr/BUILD_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD.md
7-
docs/dev/codex_commands.md
8-
docs/dev/commit_comment.txt
6+
tools/shared/runtimeSceneLoaderHotReload.js
7+
tests/tools/RuntimeSceneLoaderHotReload.test.mjs
8+
tests/run-tests.mjs
99
docs/dev/change_summary.txt
10-
docs/dev/validation_checklist.txt
1110
docs/dev/file_tree.txt
12-
docs/dev/next_command.txt
11+
docs/dev/validation_checklist.txt
12+
docs/dev/commit_comment.txt

‎docs/dev/validation_checklist.txt‎

Lines changed: 34 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,37 @@ David Quesenberry
33
04/05/2026
44
validation_checklist.txt
55

6-
BUILD PR validation checklist
7-
[x] Bundle is docs-only
8-
[x] No implementation code included
9-
[x] Workflow preserved: PLAN_PR -> BUILD_PR -> APPLY_PR
10-
[x] Runtime scene loader responsibilities are explicit
11-
[x] Hot reload lifecycle and deterministic order are documented
12-
[x] Watcher bridge boundaries are explicit
13-
[x] Public engine mappings are locked to public entry paths
14-
[x] Validation and structured error taxonomy are documented
15-
[x] Composition-driven reload rules are documented
16-
[x] Test plan is defined for APPLY implementation
17-
[x] Command and commit artifacts are under docs/dev
18-
[x] Repo-relative bundle structure is preserved
6+
APPLY_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD validation checklist
7+
8+
Runtime scene loader and hot reload flow
9+
[x] Runtime scene loader orchestration implemented above engine core
10+
[x] Existing approved render/composition contract runtime path is consumed
11+
[x] Deterministic runtime domain ordering preserved
12+
[x] Structured validation-aware reload behavior implemented
13+
[x] Last-known-good scene preserved on reload failure
14+
[x] Composition-driven targeted/full reload decision rules implemented
15+
16+
Watcher bridge boundaries
17+
[x] Watcher bridge normalizes project-relative path events
18+
[x] Watcher bridge remains orchestration boundary and does not own scene assembly
19+
[x] Watcher events can be coalesced by path before reload application
20+
21+
Automated tests
22+
[x] Load success test added
23+
[x] Reload success test added
24+
[x] Validation failure fallback test added
25+
[x] Disposal behavior test added
26+
[x] Repeated reload stability test added
27+
[x] New test wired into `tests/run-tests.mjs`
28+
29+
Execution evidence
30+
[x] `node --check tools/shared/runtimeSceneLoaderHotReload.js`
31+
[x] `node --check tests/tools/RuntimeSceneLoaderHotReload.test.mjs`
32+
[x] `node --check tests/run-tests.mjs`
33+
[x] Targeted runtime scene loader/hot reload test run passed
34+
[x] Full test suite passed (`112/112 explicit run() tests passed`)
35+
36+
Scope safety
37+
[x] No destructive runtime-breaking changes introduced
38+
[x] No unrelated sample/game/tool refactors introduced
39+
[x] Changes kept focused to approved APPLY scope

‎docs/pr/APPLY_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
APPLY_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD.md
5+
6+
# APPLY_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD
7+
8+
## Purpose
9+
Apply the approved runtime scene loader and hot reload design as a focused implementation PR that wires composition-driven scene loading into the existing engine without breaking engine-layer boundaries.
10+
11+
## Scope
12+
Implement only the approved runtime scene loader + hot reload flow.
13+
14+
In scope:
15+
- Add a runtime scene loader above engine systems
16+
- Add hot reload coordinator for development workflows
17+
- Consume the previously defined composition contract and per-tool asset contracts
18+
- Preserve deterministic render ordering already approved in the render pipeline contract work
19+
- Add validation-aware reload behavior
20+
- Add focused automated test coverage
21+
- Add minimal sample/dev wiring needed to verify the pipeline
22+
23+
Out of scope:
24+
- No engine rewrite
25+
- No new editor features
26+
- No new asset schema invention beyond approved contract docs
27+
- No production packaging system
28+
- No multiplayer/network sync
29+
- No destructive public API changes unless required and documented
30+
31+
## Implementation Intent
32+
Codex should implement a thin orchestration layer that:
33+
1. Reads a composition document
34+
2. Validates referenced tool outputs
35+
3. Loads/parses tool outputs into runtime-ready models
36+
4. Applies deterministic stage ordering
37+
5. Swaps the active scene safely in dev workflows on reload
38+
6. Surfaces structured validation/runtime errors without silent failure
39+
40+
## Required Deliverables
41+
### Runtime loading
42+
- Runtime scene loader module
43+
- Composition resolver
44+
- Contract validation bridge
45+
- Tool asset loader adapters only where needed by the approved contracts
46+
- Deterministic stage assembly
47+
48+
### Hot reload
49+
- Development-only hot reload coordinator
50+
- Safe disposal + replacement flow
51+
- Reload debouncing/coalescing if file-watch events can burst
52+
- Reload failure fallback that preserves last known good scene
53+
54+
### Tests
55+
- Composition load success path
56+
- Missing asset / invalid contract rejection
57+
- Render order preservation after reload
58+
- Scene disposal occurs before replacement
59+
- Last-known-good fallback behavior
60+
- No duplicate runtime entities/systems after repeated reloads
61+
62+
## Architecture Constraints
63+
- Loader/orchestrator stays above engine core
64+
- Engine remains reusable and tool-agnostic
65+
- Samples consume public runtime contracts only
66+
- Games are not introduced as a dependency
67+
- Tool-specific quirks are not embedded into engine systems
68+
- Existing engine APIs remain stable unless absolutely necessary and documented
69+
70+
## Suggested File Targets
71+
These are guidance targets. Codex may adjust exact paths if the repo requires better placement while keeping architecture boundaries intact.
72+
73+
- engine/scene/RuntimeSceneLoader.js
74+
- engine/scene/SceneCompositionResolver.js
75+
- engine/validation/RuntimeContractValidator.js
76+
- engine/debug/HotReloadCoordinator.js
77+
- samples/<target-sample>/ or tools/dev harness wiring as appropriate
78+
- tests/scene/RuntimeSceneLoader.test.mjs
79+
- tests/debug/HotReloadCoordinator.test.mjs
80+
81+
## Safe Reload Rules
82+
- Validate before swap
83+
- Build next runtime state before tearing down current scene when possible
84+
- Dispose current scene exactly once before replacement
85+
- Preserve last known good scene if reload fails
86+
- Log structured error output for invalid composition or invalid referenced assets
87+
- Do not leak timers, handlers, subscriptions, or duplicate entities across reload cycles
88+
89+
## Render Ordering
90+
Preserve previously approved stage order:
91+
92+
1. Parallax background
93+
2. Tilemap world
94+
3. Runtime entities / gameplay visuals
95+
4. Sprite effects / foreground sprite layers as approved by contract
96+
5. Vector overlays / debug / UI overlays
97+
98+
If the implementation needs internal sub-stages, document them in code comments/tests while preserving public ordering.
99+
100+
## Acceptance Criteria
101+
- A composition document can load a mixed scene from approved tool outputs
102+
- Hot reload refreshes changed assets/scenes without full restart in dev workflow
103+
- Invalid changes do not crash the running last-known-good scene
104+
- Render order remains deterministic before and after reload
105+
- Repeated reloads do not duplicate objects or corrupt state
106+
- Tests pass
107+
- A repo-structured implementation ZIP is produced at:
108+
- <project folder>/tmp/APPLY_PR_RUNTIME_SCENE_LOADER_AND_HOT_RELOAD_delta.zip
109+
110+
## Validation Checklist
111+
- [ ] Runtime scene loader created
112+
- [ ] Composition-driven scene assembly works
113+
- [ ] Validation blocks malformed inputs
114+
- [ ] Safe dispose/replace behavior confirmed
115+
- [ ] Last-known-good fallback confirmed
116+
- [ ] Deterministic render ordering confirmed
117+
- [ ] Tests added and passing
118+
- [ ] No engine-layer pollution from tool-specific logic

‎tests/run-tests.mjs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,7 @@ import { run as runCloudRuntime } from './tools/CloudRuntime.test.mjs';
107107
import { run as runGameTemplates } from './tools/GameTemplates.test.mjs';
108108
import { run as runPublishingPipeline } from './tools/PublishingPipeline.test.mjs';
109109
import { run as runRenderPipelineContractAll4Tools } from './tools/RenderPipelineContractAll4Tools.test.mjs';
110+
import { run as runRuntimeSceneLoaderHotReload } from './tools/RuntimeSceneLoaderHotReload.test.mjs';
110111
import { run as runVectorAssetSystem } from './tools/VectorAssetSystem.test.mjs';
111112
import { run as runVectorNativeTemplate } from './tools/VectorNativeTemplate.test.mjs';
112113
import { run as runVectorTemplateSampleGame } from './tools/VectorTemplateSampleGame.test.mjs';
@@ -212,6 +213,7 @@ const tests = [
212213
['GameTemplates', runGameTemplates],
213214
['PublishingPipeline', runPublishingPipeline],
214215
['RenderPipelineContractAll4Tools', runRenderPipelineContractAll4Tools],
216+
['RuntimeSceneLoaderHotReload', runRuntimeSceneLoaderHotReload],
215217
['VectorAssetSystem', runVectorAssetSystem],
216218
['VectorNativeTemplate', runVectorNativeTemplate],
217219
['VectorTemplateSampleGame', runVectorTemplateSampleGame],

0 commit comments

Comments
 (0)