Add no-imageDataUrl policy and queue Samples2Tools cleanup steps

- AGENTS: forbid `imageDataUrl` in persisted project/runtime/workspace JSON; require path-based image refs.
- Roadmap: add next-execution `imageDataUrl` elimination plan (remove dependency, remove fallback, migrate legacy + remove legacy dependency).

Author: DavidQ

AGENTS.md

@@ -13,6 +13,7 @@
 - Stop and report on ambiguity
 - Do not modify engine core unless explicitly in scope
 - Do not modify start_of_day folders unless explicitly requested
+- Never use `imageDataUrl` in project/runtime/workspace JSON contracts; use file/path fields (for example `imageName` or equivalent) as the only persisted source of truth
 
 ## Windows Execution
 - Prefer Node.js or Python for file operations, rename work, path handling, and ZIP work

docs/dev/roadmaps/MASTER_ROADMAP_SAMPLES2TOOLS.md

@@ -20,6 +20,19 @@
 - [.] Roadmap kickoff started
 - [.] Phase 1 vertical slice target selected: `Parallax Scene Studio`
 - [.] Batch 1 implementation start
+- [ ] Next execution queued: remove all `imageDataUrl` usage/dependency across Samples2Tools lane
+
+## Next Execution - imageDataUrl Elimination
+- [ ] 1) Remove dependency
+- [ ] Remove all code paths that require or rely on `imageDataUrl` for normal sample/tool/workspace flow.
+- [ ] Persist and pass only file/path-based image references (`imageName` or equivalent canonical path fields).
+- [ ] 2) Remove fallback
+- [ ] Remove `imageDataUrl` fallback reads (`imageDataUrl || imageSource`) after path-based flow is fully validated.
+- [ ] Remove temporary/in-memory-only fallback logic once equivalent preview behavior exists without `imageDataUrl`.
+- [ ] 3) Legacy needs to be updated and remove any dependency
+- [ ] Update legacy sample/tool payloads to canonical path-based image references.
+- [ ] Remove any remaining legacy compatibility branches tied to `imageDataUrl`.
+- [ ] Validate that older payloads in active lanes are migrated and no active launcher depends on `imageDataUrl`.
 
 ## Canonical Data Contract
 - [.] File naming standard: `samples/phase-xx/xxxx/sample-xxxx.json`

samples/phase-03/0306/parallax-editor-sample-0306.json

@@ -25,7 +25,6 @@
           "name": "Zone Band Far",
           "drawOrder": 0,
           "imageSource": "/samples/phase-03/0306/assets/data/parallax/sample-0306-far.svg",
-          "imageDataUrl": "",
           "scrollFactorX": 0.2,
           "scrollFactorY": 0,
           "offsetX": 0,
@@ -41,7 +40,6 @@
           "name": "Zone Band Near",
           "drawOrder": 1,
           "imageSource": "/samples/phase-03/0306/assets/data/parallax/sample-0306-near.svg",
-          "imageDataUrl": "",
           "scrollFactorX": 0.45,
           "scrollFactorY": 0,
           "offsetX": 0,

samples/phase-12/1204/parallax-editor-sample-1204.json

@@ -25,7 +25,6 @@
           "name": "Hero Band Far",
           "drawOrder": 0,
           "imageSource": "/samples/phase-12/1204/assets/data/parallax/sample-1204-far.svg",
-          "imageDataUrl": "",
           "scrollFactorX": 0.16,
           "scrollFactorY": 0,
           "offsetX": 0,
@@ -41,7 +40,6 @@
           "name": "Hero Band Mid",
           "drawOrder": 1,
           "imageSource": "/samples/phase-12/1204/assets/data/parallax/sample-1204-mid.svg",
-          "imageDataUrl": "",
           "scrollFactorX": 0.3,
           "scrollFactorY": 0,
           "offsetX": 0,
@@ -57,7 +55,6 @@
           "name": "Hero Band Near",
           "drawOrder": 2,
           "imageSource": "/samples/phase-12/1204/assets/data/parallax/sample-1204-near.svg",
-          "imageDataUrl": "",
           "scrollFactorX": 0.52,
           "scrollFactorY": 0,
           "offsetX": 0,

samples/phase-12/1205/parallax-editor-sample-1205.json

@@ -25,7 +25,6 @@
           "name": "Multi Band Far",
           "drawOrder": 0,
           "imageSource": "/samples/phase-12/1205/assets/data/parallax/sample-1205-far.svg",
-          "imageDataUrl": "",
           "scrollFactorX": 0.16,
           "scrollFactorY": 0,
           "offsetX": 0,
@@ -41,7 +40,6 @@
           "name": "Multi Band Mid",
           "drawOrder": 1,
           "imageSource": "/samples/phase-12/1205/assets/data/parallax/sample-1205-mid.svg",
-          "imageDataUrl": "",
           "scrollFactorX": 0.3,
           "scrollFactorY": 0,
           "offsetX": 0,
@@ -57,7 +55,6 @@
           "name": "Multi Band Near",
           "drawOrder": 2,
           "imageSource": "/samples/phase-12/1205/assets/data/parallax/sample-1205-near.svg",
-          "imageDataUrl": "",
           "scrollFactorX": 0.52,
           "scrollFactorY": 0,
           "offsetX": 0,

samples/phase-12/1208/ToolFormattedTilesParallaxScene.js

@@ -214,7 +214,6 @@ export default class ToolFormattedTilesParallaxScene extends Scene {
 
     const loadOperations = layerDefinitions.map(async (layerDefinition, index) => {
       const assetPath = layerDefinition.asset
-        || layerDefinition.imageDataUrl
         || layerDefinition.imageSource;
       if (!assetPath) {
         throw new Error(`Parallax layer ${layerDefinition.id || index} missing image source.`);
@@ -637,7 +636,6 @@ function extractParallaxLayers(parallaxExport) {
       .map((layer) => ({
         id: layer.id,
         imageSource: layer.imageSource,
-        imageDataUrl: layer.imageDataUrl,
         scrollFactorX: Number(layer.scrollFactorX),
         offsetY: Number(layer.offsetY) || 0,
         opacity: Number(layer.opacity),
@@ -717,9 +715,6 @@ function extractTilesetImagePath(tileExport, atlas) {
   if (typeof atlas?.imageName === 'string' && atlas.imageName) {
     return atlas.imageName;
   }
-  if (typeof atlas?.imageDataUrl === 'string' && atlas.imageDataUrl) {
-    return atlas.imageDataUrl;
-  }
   return '';
 }
 
@@ -739,7 +734,6 @@ function extractTilesetImageCandidates(tileExport, atlas) {
   if (typeof atlas?.imageName === 'string' && atlas.imageName.includes('/assets/tileset/')) {
     add(atlas.imageName.replace('/assets/tileset/', '/assets/images/tileset/'));
   }
-  add(atlas?.imageDataUrl);
 
   return candidates;
 }

samples/phase-12/1208/data/toolFormattedParallax.js

@@ -16,7 +16,6 @@ export default {
       "name": "Far Mountains",
       "drawOrder": 0,
       "imageSource": "/samples/phase-12/1208/assets/data/parallax/layer-far-mountains.svg",
-      "imageDataUrl": "",
       "scrollFactorX": 0.2,
       "scrollFactorY": 0.05,
       "offsetX": 0,
@@ -32,7 +31,6 @@ export default {
       "name": "Mid Cliffs",
       "drawOrder": 1,
       "imageSource": "/samples/phase-12/1208/assets/data/parallax/layer-mid-cliffs.svg",
-      "imageDataUrl": "",
       "scrollFactorX": 0.45,
       "scrollFactorY": 0.16,
       "offsetX": 0,
@@ -48,7 +46,6 @@ export default {
       "name": "Near Forest",
       "drawOrder": 2,
       "imageSource": "/samples/phase-12/1208/assets/data/parallax/layer-near-forest.svg",
-      "imageDataUrl": "",
       "scrollFactorX": 0.7,
       "scrollFactorY": 0.28,
       "offsetX": 0,

samples/phase-12/1208/data/toolFormattedParallax.json

@@ -16,7 +16,6 @@
       "name": "Far Mountains",
       "drawOrder": 0,
       "imageSource": "/samples/phase-12/1208/assets/data/parallax/layer-far-mountains.svg",
-      "imageDataUrl": "",
       "scrollFactorX": 0.2,
       "scrollFactorY": 0.05,
       "offsetX": 0,
@@ -32,7 +31,6 @@
       "name": "Mid Cliffs",
       "drawOrder": 1,
       "imageSource": "/samples/phase-12/1208/assets/data/parallax/layer-mid-cliffs.svg",
-      "imageDataUrl": "",
       "scrollFactorX": 0.45,
       "scrollFactorY": 0.16,
       "offsetX": 0,
@@ -48,7 +46,6 @@
       "name": "Near Forest",
       "drawOrder": 2,
       "imageSource": "/samples/phase-12/1208/assets/data/parallax/layer-near-forest.svg",
-      "imageDataUrl": "",
       "scrollFactorX": 0.7,
       "scrollFactorY": 0.28,
       "offsetX": 0,

samples/phase-12/1208/data/toolFormattedTileMap.js

@@ -54,8 +54,7 @@ export default {
   ],
   "tilesetAtlas": {
     "schema": "toolbox.tileset-atlas/1",
-    "imageDataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAJAAAAAwCAYAAAD+WvNWAAAB60lEQVR4AeyWMU7DMBiFrUychYlDcAJ2DoCEQIIrMCKkIiFugdhYWGFm4gJcgq0oQ6KmNnbbyPn97K+SVcV2/L//vS9pu6fV/XpzfPzcTa6HNZX5Qa/K9+vb51p5dI4PDsxwYALQydmv+3o58o5TmfeEM5HdgQlA2atRoDoHRoBU3jL/6awuGZGGRoBCP119DyrzvVbG8g6MAC1fmoo1OHAwQDU0Tw/zHQCg+R42fYI8QA+Pz0553F6eO+UhD1DTj38BzXfKT2+vvQAPm5bAG6jp+Oc3Lw/Q6vTYKY/5EdqesDxAtv1KVr+5unDbo5RGAMg4iW0wQtchiaF9FnMAFEqHuZ0dAKCdrWJjyAEPoM0/pKEbrNdDmpizc8ADyE4KlRUdACDF1ArS7AF0/f7thhHSOaz138uuh6oxZ+2AB5C1IOprOQBAWnkVpxaAiotESxAAaeVVnFoAKi4SLUEApJVXcWpbAKg402sSBEA1pWnQCwAZmF5TSQCqKU2DXgDIwPSaSgJQTWka9AJABqbXVBKAImmylHYAgNIesSPiAABFzGEp7QAApT1iR8QBAIqYw1LaAQBKe8SOiAMAFDGHpbQDAJT2aP8dDd0BQA2FnaNVAMrhakNnAlBDYedoFYByuNrQmQDUUNg5Wv0DAAD//6PRWCUAAAAGSURBVAMAfqRVji4/TksAAAAASUVORK5CYII=",
-    "imageName": "./assets/images/tileset/demo1208-terrain-tileset-orig.png",
+    "imageName": "/samples/phase-12/1208/assets/images/tileset/demo1208-terrain-tileset-orig.png",
     "imageWidth": 144,
     "imageHeight": 48,
     "tileWidth": 48,
@@ -4114,3 +4113,4 @@ export default {
     "notes": "Tile Map Editor toolbox.tilemap/1 format for Sample 1208 runtime import."
   }
 };
+

samples/phase-12/1208/parallax-editor-sample-1208.json

@@ -27,7 +27,6 @@
           "name": "Far Mountains",
           "drawOrder": 0,
           "imageSource": "/samples/phase-12/1208/assets/data/parallax/layer-far-mountains.svg",
-          "imageDataUrl": "",
           "scrollFactorX": 0.2,
           "scrollFactorY": 0.05,
           "offsetX": 0,
@@ -43,7 +42,6 @@
           "name": "Mid Cliffs",
           "drawOrder": 1,
           "imageSource": "/samples/phase-12/1208/assets/data/parallax/layer-mid-cliffs.svg",
-          "imageDataUrl": "",
           "scrollFactorX": 0.45,
           "scrollFactorY": 0.16,
           "offsetX": 0,
@@ -59,7 +57,6 @@
           "name": "Near Forest",
           "drawOrder": 2,
           "imageSource": "/samples/phase-12/1208/assets/data/parallax/layer-near-forest.svg",
-          "imageDataUrl": "",
           "scrollFactorX": 0.7,
           "scrollFactorY": 0.28,
           "offsetX": 0,