plan(parallax-editor): adopt project asset registry integration

Author: ToolboxAid

docs/dev/CODEX_COMMANDS.md

@@ -1,99 +1,14 @@
 MODEL: GPT-5.3-codex
 REASONING: high
 
-BUILD_PR_DEMO1208_TOOL_FORMATTED_TILES_PARALLAX
+COMMAND:
+Create BUILD_PR_PARALLAX_EDITOR_ASSET_REGISTRY_ADOPTION.
 
-THIS IS A MANDATORY CHANGE.
-A NO-OP RESULT IS INVALID.
+Requirements:
+- Integrate Parallax Editor with project asset registry
+- Use ID-based references (no direct paths)
+- Maintain backward compatibility
+- Do not modify engine core APIs
 
-PRIMARY GOAL
-Implement Demo 1208 - Tool Formatted Tiles Parallax as a runnable authoring-pipeline validation demo.
-
-SECONDARY REQUIRED FIX
-Fix samples/index.html so Demo 1207 no longer links to README.md and instead opens the runnable demo entry page.
-
-FOUNDATION TO PRESERVE
-- tilemap
-- hero movement
-- Space-to-jump
-- gravity
-- grounded behavior
-- collision
-- camera follow
-- parallax
-- larger-than-viewport scrolling world
-
-NEW CONCEPT FOR THIS PR
-Use content formatted as if it came from the user's tools:
-- tile content shaped like Tile Map Editor output
-- SVG parallax content shaped like Parallax Editor output
-
-REQUIRED WORK
-1. Implement Demo 1208 using repo-consistent demo structure
-2. Add actual tile assets for Demo 1208
-3. Add actual SVG parallax assets for Demo 1208
-4. Add sample-local config/data shaped like tool exports
-5. Preserve proven hero movement, jump, gravity, collision, camera follow, and parallax behavior
-6. Ensure the world is larger than the viewport and visibly scrolls
-7. Update samples/index.html:
-   - fix Demo 1207 link to point to runnable index.html, not README.md
-   - point Demo 1208 to runnable index.html
-8. Keep README.md accurate
-
-ALLOWED CHANGES
-Primary:
-- samples/Phase 12 - Demo Games/Demo 1208 - Tool Formatted Tiles Parallax/**
-Secondary:
-- samples/index.html
-Tertiary only if strictly required for the 1207 broken link fix:
-- samples/Phase 12 - Demo Games/Demo 1207 - Switch Checkpoint Marker/**
-
-BLOCKED CHANGES
-- engine changes
-- tool changes
-- tests changes
-- games changes
-- non-Phase-12 changes beyond samples/index.html
-- new gameplay systems
-- enemies
-- inventory
-- menus
-- save/load
-
-VALIDATION (FAIL IF NOT TRUE)
-- Demo 1208 launches
-- actual tile assets are used
-- actual SVG parallax assets are used
-- hero is visible
-- Left/Right movement works
-- Space triggers jump
-- gravity is active
-- collision works
-- camera follows hero cleanly
-- parallax is visible
-- tilemap is larger than viewport
-- scrolling is visible during play
-- Demo 1207 index target opens runnable page, not README.md
-- Demo 1208 index target opens runnable page
-- no diff outside:
-  - samples/Phase 12 - Demo Games/Demo 1208 - Tool Formatted Tiles Parallax/**
-  - samples/index.html
-  - Demo 1207 files only if strictly required for the link fix
-- no engine/tools/tests/games changes
-- README matches actual behavior
-
-COMMIT MESSAGE
-BUILD_PR: implement Demo 1208 tool-formatted tiles parallax and fix Demo 1207 index link
-
-- add runnable Demo 1208 using tool-shaped tile and SVG parallax assets
-- preserve proven movement, jump, collision, camera follow, and parallax behavior
-- fix samples/index.html so Demo 1207 opens runnable index.html instead of README.md
-- keep change limited to Phase 12 demos and index
-- no engine, tools, tests, or games changes
-
-OUTPUT CONTRACT (MANDATORY)
-- Produce a repo-structured delta ZIP
-- Output path:
-  <project folder>/tmp/BUILD_PR_DEMO1208_TOOL_FORMATTED_TILES_PARALLAX_delta.zip
-- ZIP must contain only changed/added files for this BUILD_PR
-- ZIP must not be empty
+Package:
+HTML-JavaScript-Gaming/tmp/BUILD_PR_PARALLAX_EDITOR_ASSET_REGISTRY_ADOPTION_delta.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1,7 +1 @@
-BUILD_PR: implement Demo 1208 tool-formatted tiles parallax and fix Demo 1207 index link
-
-- add runnable Demo 1208 using tool-shaped tile and SVG parallax assets
-- preserve proven movement, jump, collision, camera follow, and parallax behavior
-- fix samples/index.html so Demo 1207 opens runnable index.html instead of README.md
-- keep change limited to Phase 12 demos and index
-- no engine, tools, tests, or games changes
+plan(parallax-editor): adopt project asset registry integration

docs/dev/change_summary.txt

@@ -0,0 +1 @@
+Introduces Parallax Editor adoption of asset registry (docs-only).

docs/dev/file_tree.txt

@@ -0,0 +1,6 @@
+docs/pr/PLAN_PR_PARALLAX_EDITOR_ASSET_REGISTRY_ADOPTION.md
+docs/dev/codex_commands.md
+docs/dev/commit_comment.txt
+docs/dev/change_summary.txt
+docs/dev/validation_checklist.txt
+docs/dev/file_tree.txt

docs/dev/reports/change_summary.txt

@@ -1,6 +1,6 @@
-Created APPLY bundle for APPLY_PR_TILEMAP_EDITOR_ASSET_REGISTRY_ADOPTION.
+Created implementation bundle for BUILD_PR_PARALLAX_EDITOR_ASSET_REGISTRY_ADOPTION.
 
 Summary:
-- Confirms the built Tile Map Editor registry adoption slice is ready to apply as implemented.
-- Verifies build/package scope stays limited to the approved Tile Map Editor registry files and docs.
-- Reaffirms legacy compatibility, additive registry preservation, and no engine or Parallax scope expansion.
+- Updates Parallax Editor to save registry-managed layers via ID-based references.
+- Preserves additive `images` and `parallaxSources` registry behavior through shared helpers.
+- Maintains backward compatibility for legacy direct-path parallax and tilemap documents.

docs/dev/reports/file_tree.txt

@@ -1,9 +1,13 @@
-APPLY_PR_TILEMAP_EDITOR_ASSET_REGISTRY_ADOPTION_delta/
-└── docs/
-    ├── dev/
-    │   └── reports/
-    │       ├── change_summary.txt
-    │       ├── file_tree.txt
-    │       └── validation_checklist.txt
-    └── pr/
-        └── APPLY_PR_TILEMAP_EDITOR_ASSET_REGISTRY_ADOPTION.md
+BUILD_PR_PARALLAX_EDITOR_ASSET_REGISTRY_ADOPTION_delta/
+├── docs/
+│   ├── dev/
+│   │   └── reports/
+│   │       ├── change_summary.txt
+│   │       ├── file_tree.txt
+│   │       └── validation_checklist.txt
+│   └── pr/
+│       └── BUILD_PR_PARALLAX_EDITOR_ASSET_REGISTRY_ADOPTION.md
+└── tools/
+    └── Parallax Editor/
+        ├── README.md
+        └── main.js

docs/dev/reports/validation_checklist.txt

@@ -1,9 +1,8 @@
-APPLY VALIDATION CHECKLIST
+BUILD VALIDATION CHECKLIST
 
-- [x] Build artifact `tmp/BUILD_PR_TILEMAP_EDITOR_ASSET_REGISTRY_ADOPTION_delta.zip` exists
-- [x] Build artifact contents confirmed limited to approved PR files
-- [x] Plan/build/apply alignment confirmed for Tile Map Editor registry adoption
-- [x] Legacy compatibility and additive registry preservation confirmed in apply notes
-- [x] No engine core API changes or Parallax Editor scope expansion introduced during APPLY
-- [x] Syntax validation re-confirmed for changed JS files
-- [x] APPLY bundle is docs-only
+- [x] Parallax Editor integrated with project asset registry
+- [x] Registry-managed saves use ID-based references instead of direct paths
+- [x] Backward compatibility preserved for legacy parallax/tilemap JSON
+- [x] No engine core API changes introduced
+- [x] Shared registry helpers reused without destructive registry replacement
+- [x] Syntax validation passed for changed JS files

docs/dev/validation_checklist.txt

@@ -0,0 +1,3 @@
+- No code changes in PLAN
+- Contracts clearly defined
+- Backward compatibility documented

docs/pr/BUILD_PR_PARALLAX_EDITOR_ASSET_REGISTRY_ADOPTION.md

@@ -0,0 +1,39 @@
+Toolbox Aid
+David Quesenberry
+04/04/2026
+BUILD_PR_PARALLAX_EDITOR_ASSET_REGISTRY_ADOPTION.md
+
+# BUILD_PR_PARALLAX_EDITOR_ASSET_REGISTRY_ADOPTION
+
+## Goal
+Integrate Parallax Editor with the shared project asset registry using ID-based references while preserving backward compatibility and avoiding engine core API changes.
+
+## Implemented scope
+- Reused shared registry helpers already used by Sprite Editor and Tile Map Editor.
+- Kept additive registry integration for Parallax Editor:
+  - load/save `project.assets.json`
+  - additive `images` and `parallaxSources` upserts
+  - persisted layer-level `parallaxSourceId`
+  - persisted document-level `assetRefs.parallaxSourceIds`
+- Switched registry-managed parallax saves to prefer ID-based references:
+  - saved parallax JSON omits direct `imageSource` paths for registry-managed layers
+  - tilemap parallax patch export uses the same ID-first shape
+- Preserved backward compatibility:
+  - legacy parallax and tilemap documents with direct paths still load
+  - registry resolution restores missing paths lazily when ids are available
+  - unresolved refs degrade with status messaging instead of hard failure
+
+## Scope boundaries honored
+- No engine core API changes
+- No Sprite Editor or Tile Map Editor rework
+- No destructive registry replacement behavior
+
+## Validation summary
+- Syntax checks passed:
+  - `node --check tools/shared/projectAssetRegistry.js`
+  - `node --check tools/Parallax Editor/main.js`
+- Validation checklist updated and all items marked pass in `docs/dev/reports/validation_checklist.txt`.
+
+## Packaging
+- Delta ZIP: `tmp/BUILD_PR_PARALLAX_EDITOR_ASSET_REGISTRY_ADOPTION_delta.zip`
+- ZIP contains only files relevant to this PR.

docs/pr/PLAN_PR_PARALLAX_EDITOR_ASSET_REGISTRY_ADOPTION.md

@@ -0,0 +1,24 @@
+# PLAN_PR_PARALLAX_EDITOR_ASSET_REGISTRY_ADOPTION
+
+## Goal
+Adopt project asset registry within Parallax Editor while maintaining backward compatibility.
+
+## Scope
+- Read/write parallax layers via project asset registry
+- Reference assets via IDs (not paths)
+- Maintain legacy file support
+
+## Constraints
+- No engine changes
+- No breaking existing tools
+- Registry is source of truth
+
+## Contracts
+- layer.assetRefs.imageId
+- lazy resolution
+- fallback for missing assets
+
+## Validation
+- Load existing parallax JSON
+- Save new registry-based project
+- No runtime errors