PR_08_03_TOOL_LIVE_PREVIEW_SYNC v2

DavidQ · DavidQ · commit 6aa68ce8c031 · 2026-04-13T19:47:56.000-04:00
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -2,4 +2,4 @@ MODEL: GPT-5.4
 REASONING: medium
 
 COMMAND:
-Implement PR_08_02_TOOL_SAMPLE_ROUNDTRIP.
+Implement PR_08_03_TOOL_LIVE_PREVIEW_SYNC.
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1 +1 @@
-PR_08_02_TOOL_SAMPLE_ROUNDTRIP
+PR_08_03_TOOL_LIVE_PREVIEW_SYNC
diff --git a/docs/dev/reports/live_sync_model.txt b/docs/dev/reports/live_sync_model.txt
@@ -0,0 +1,36 @@
+﻿PR: PR_08_03_TOOL_LIVE_PREVIEW_SYNC
+
+Live Sync Channel
+- Added shared bridge utility at tools/shared/livePreviewSyncChannel.js.
+- Channel name: world-game-tool-live-preview-sync.
+- Transport order:
+  1. BroadcastChannel when available.
+  2. localStorage storage-event fallback when BroadcastChannel is unavailable.
+- Envelope fields: channel, sourceId, eventType, updatedAt, payload.
+- Loop prevention: per-source filtering and payload signature de-duplication.
+
+Tool Publishers
+- tools/Tilemap Studio/main.js publishes tileMapDocument snapshots on:
+  - init
+  - new project
+  - load project
+  - document update
+- tools/Parallax Scene Studio/main.js publishes parallaxDocument snapshots on:
+  - init
+  - load sample
+  - new project
+  - load project
+  - document update
+- Both publishers batch same-frame updates with requestAnimationFrame (setTimeout fallback).
+
+Sample Consumer
+- samples/phase-12/1208/main.js subscribes to live sync channel.
+- samples/phase-12/1208/ToolFormattedTilesParallaxScene.js applies updates through queued async processing.
+- Tile updates reuse existing tile import and asset load path.
+- Parallax updates reuse existing layer extraction and asset load path.
+- Status surface updated with sync success/failure and version counter.
+
+Compatibility / Boundaries
+- No engine core API changes.
+- No sample navigation/index reshaping.
+- Sync is additive and isolated to tool/sample integration surface.
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,8 +1,25 @@
-PR_08_02_TOOL_SAMPLE_ROUNDTRIP - checklist
+﻿PR: PR_08_03_TOOL_LIVE_PREVIEW_SYNC
 
-[x] Tool launcher retains sample link entry points for Sample 1208.
-[x] Sample 1208 exposes direct links back to relevant tools.
-[x] No tool runtime implementation redesign.
-[x] No game/network behavior changes.
-[x] Roundtrip path (tool -> sample -> tool) is present.
-[x] Smoke validation passed.
+Validation Commands
+- node --check tools/shared/livePreviewSyncChannel.js
+- node --check "tools/Tilemap Studio/main.js"
+- node --check "tools/Parallax Scene Studio/main.js"
+- node --check samples/phase-12/1208/main.js
+- node --check samples/phase-12/1208/ToolFormattedTilesParallaxScene.js
+- node tests/runtime/LaunchSmokeAllEntries.test.mjs
+
+Results
+- Syntax checks: PASS
+- Runtime smoke: PASS
+
+Scope Verification
+- Changed implementation files:
+  - tools/shared/livePreviewSyncChannel.js
+  - tools/Tilemap Studio/main.js
+  - tools/Parallax Scene Studio/main.js
+  - samples/phase-12/1208/main.js
+  - samples/phase-12/1208/ToolFormattedTilesParallaxScene.js
+- Deliverable docs:
+  - docs/dev/reports/live_sync_model.txt
+  - docs/dev/reports/validation_checklist.txt
+- No engine core API modifications performed.
diff --git a/docs/pr/PR_08_03_TOOL_LIVE_PREVIEW_SYNC.md b/docs/pr/PR_08_03_TOOL_LIVE_PREVIEW_SYNC.md
@@ -0,0 +1,20 @@
+# PR_08_03_TOOL_LIVE_PREVIEW_SYNC
+
+## Purpose
+Enable live preview syncing between tools and running samples.
+
+## Scope
+- live sync only
+- no redesign
+
+## Tasks
+1. Define live update channel between tool and sample.
+2. Apply changes in real-time preview.
+3. Validate sync stability.
+
+## Deliverables
+- docs/dev/reports/live_sync_model.txt
+- docs/dev/reports/validation_checklist.txt
+
+## Output
+<project folder>/tmp/PR_08_03_TOOL_LIVE_PREVIEW_SYNC.zip
diff --git a/samples/phase-12/1208/ToolFormattedTilesParallaxScene.js b/samples/phase-12/1208/ToolFormattedTilesParallaxScene.js
@@ -39,6 +39,8 @@ export default class ToolFormattedTilesParallaxScene extends Scene {
     this.contentStatus = 'Loading tool-formatted tile/parallax content...';
     this.contentLoaded = false;
     this.contentError = null;
+    this.liveSyncVersion = 0;
+    this.liveSyncPending = Promise.resolve();
     this.tilesetAssetPath = '';
     this.tilesetImage = null;
     this.tileFrameById = {};
@@ -415,6 +417,41 @@ export default class ToolFormattedTilesParallaxScene extends Scene {
       }
     }
   }
+
+  applyLivePreviewUpdate(update = {}) {
+    this.liveSyncPending = this.liveSyncPending
+      .then(() => this.applyLivePreviewUpdateInternal(update))
+      .catch(() => {});
+    return this.liveSyncPending;
+  }
+
+  async applyLivePreviewUpdateInternal(update = {}) {
+    const nextTileDocument = update && typeof update.tileMapDocument === 'object' ? update.tileMapDocument : null;
+    const nextParallaxDocument = update && typeof update.parallaxDocument === 'object' ? update.parallaxDocument : null;
+    if (!nextTileDocument && !nextParallaxDocument) {
+      return;
+    }
+
+    try {
+      let tileAssetCount = this.tilesetImage ? 1 : 0;
+      if (nextTileDocument) {
+        this.applyTileExportData(nextTileDocument);
+        tileAssetCount = await this.loadTileAssets(extractTileEntries(nextTileDocument));
+      }
+
+      if (nextParallaxDocument) {
+        this.parallaxLayers = await this.loadParallaxAssets(extractParallaxLayers(nextParallaxDocument));
+      }
+
+      this.liveSyncVersion += 1;
+      this.contentLoaded = tileAssetCount > 0 && this.parallaxLayers.length > 0;
+      this.contentError = null;
+      this.contentStatus = `Live preview synced (${this.liveSyncVersion}).`;
+    } catch (error) {
+      this.contentError = error instanceof Error ? error.message : String(error);
+      this.contentStatus = 'Live preview sync failed.';
+    }
+  }
 }
 
 function loadImageFromRelativePath(relativePath, baseUrl) {
diff --git a/samples/phase-12/1208/main.js b/samples/phase-12/1208/main.js
@@ -8,6 +8,7 @@ import Engine from '/src/engine/core/Engine.js';
 import { InputService } from '/src/engine/input/index.js';
 import { Theme, ThemeTokens } from '/src/engine/theme/index.js';
 import ToolFormattedTilesParallaxScene from './ToolFormattedTilesParallaxScene.js';
+import { createLivePreviewSyncBridge } from '/tools/shared/livePreviewSyncChannel.js';
 
 const theme = new Theme(ThemeTokens);
 theme.applyDocumentTheme();
@@ -23,5 +24,10 @@ const engine = new Engine({
   input,
 });
 
-engine.setScene(new ToolFormattedTilesParallaxScene());
+const scene = new ToolFormattedTilesParallaxScene();
+const livePreviewSync = createLivePreviewSyncBridge({ sourceId: 'sample-1208-live-preview' });
+livePreviewSync.subscribe((payload) => {
+  scene.applyLivePreviewUpdate(payload);
+});
+engine.setScene(scene);
 engine.start();
diff --git a/tools/Parallax Scene Studio/main.js b/tools/Parallax Scene Studio/main.js
@@ -31,6 +31,7 @@ import { buildProjectPackage, summarizeProjectPackaging } from "../shared/projec
 import { buildEditorExperienceLayer, summarizeEditorExperienceLayer } from "../shared/editorExperienceLayer.js";
 import { buildDebugVisualizationLayer, summarizeDebugVisualizationLayer } from "../shared/debugVisualizationLayer.js";
 import { registerToolBootContract } from "../shared/toolBootContract.js";
+import { createLivePreviewSyncBridge } from "../shared/livePreviewSyncChannel.js";
 
 const SAMPLE_DIRECTORY_PATH = "./samples/";
 const SAMPLE_MANIFEST_PATH = "./samples/sample-manifest.json";
@@ -390,6 +391,9 @@ class ParallaxEditorApp {
     this.lastRuntimeResult = null;
     this.editorExperienceResult = null;
     this.debugVisualizationResult = null;
+    this.livePreviewSync = createLivePreviewSyncBridge({ sourceId: "parallax-editor" });
+    this.livePreviewSyncFrame = 0;
+    this.pendingLivePreviewReason = "init";
   }
 
   invalidateImageCache() {
@@ -402,6 +406,7 @@ class ParallaxEditorApp {
     this.attachEvents();
     this.syncInputsFromDocument();
     this.renderAll();
+    this.queueLivePreviewSync("init");
     this.loadSampleManifest();
   }
 
@@ -539,6 +544,32 @@ class ParallaxEditorApp {
 
   touchDocument() {
     this.documentModel.metadata.updatedAt = new Date().toISOString();
+    this.queueLivePreviewSync("document-update");
+  }
+
+  publishLivePreviewSync(reason = "update") {
+    this.livePreviewSync.publish(
+      {
+        toolId: "parallax-editor",
+        reason,
+        parallaxDocument: cloneDeep(this.documentModel)
+      },
+      "tool-live-preview-sync"
+    );
+  }
+
+  queueLivePreviewSync(reason = "update") {
+    this.pendingLivePreviewReason = reason;
+    if (this.livePreviewSyncFrame) {
+      return;
+    }
+    const schedule = typeof requestAnimationFrame === "function"
+      ? requestAnimationFrame
+      : (callback) => setTimeout(callback, 16);
+    this.livePreviewSyncFrame = schedule(() => {
+      this.livePreviewSyncFrame = 0;
+      this.publishLivePreviewSync(this.pendingLivePreviewReason);
+    });
   }
 
   updateStatus(message) {
@@ -933,6 +964,7 @@ class ParallaxEditorApp {
       this.cameraY = 0;
       this.syncInputsFromDocument();
       this.renderAll();
+      this.queueLivePreviewSync("load-sample");
       this.updateStatus(`Loaded sample ${selectedPath}.`);
     } catch (error) {
       this.updateStatus(`Sample load failed: ${error instanceof Error ? error.message : "unknown error"}`);
@@ -948,6 +980,7 @@ class ParallaxEditorApp {
     this.cameraY = 0;
     this.syncInputsFromDocument();
     this.renderAll();
+    this.queueLivePreviewSync("new-project");
     this.updateStatus("Created new parallax document.");
   }
 
@@ -1151,6 +1184,7 @@ class ParallaxEditorApp {
         this.cameraY = 0;
         this.syncInputsFromDocument();
         this.renderAll();
+        this.queueLivePreviewSync("load-project");
         const validation = this.validateProjectAssets();
         if (resolution.resolvedCount > 0) {
           this.updateStatus(`Loaded ${file.name} (${resolution.resolvedCount} layer image refs restored from asset registry, validation: ${summarizeAssetValidation(validation)}).`);
diff --git a/tools/Tilemap Studio/main.js b/tools/Tilemap Studio/main.js
@@ -31,6 +31,7 @@ import { buildProjectPackage, summarizeProjectPackaging } from "../shared/projec
 import { buildEditorExperienceLayer, summarizeEditorExperienceLayer } from "../shared/editorExperienceLayer.js";
 import { buildDebugVisualizationLayer, summarizeDebugVisualizationLayer } from "../shared/debugVisualizationLayer.js";
 import { registerToolBootContract } from "../shared/toolBootContract.js";
+import { createLivePreviewSyncBridge } from "../shared/livePreviewSyncChannel.js";
 
 const DEFAULT_TILESET = [
   { id: 0, name: "Empty", color: "transparent" },
@@ -581,13 +582,17 @@ class TileMapEditorApp {
     this.lastRuntimeResult = null;
     this.editorExperienceResult = null;
     this.debugVisualizationResult = null;
+    this.livePreviewSync = createLivePreviewSyncBridge({ sourceId: "tile-map-editor" });
+    this.livePreviewSyncFrame = 0;
+    this.pendingLivePreviewReason = "init";
   }
 
   init(rootDocument) {
     this.captureRefs(rootDocument);
     this.attachEvents();
     this.syncInputsFromDocument();
     this.renderAll();
+    this.queueLivePreviewSync("init");
     void this.reloadTilesetImageFromDocument({ quiet: true });
     void this.preloadIndividualTileImages({ quiet: true });
     this.loadSampleManifest();
@@ -764,6 +769,7 @@ class TileMapEditorApp {
     this.tilesetImageCache = new Map();
     this.syncInputsFromDocument();
     this.renderAll();
+    this.queueLivePreviewSync("new-project");
     this.updateStatus("Created a new map document.");
   }
 
@@ -947,6 +953,7 @@ class TileMapEditorApp {
         this.tilesetImageCache = new Map();
         this.syncInputsFromDocument();
         this.renderAll();
+        this.queueLivePreviewSync("load-project");
         const validation = this.validateProjectAssets();
         void this.reloadTilesetImageFromDocument({ quiet: true });
         void this.preloadIndividualTileImages({ quiet: true });
@@ -1554,6 +1561,32 @@ class TileMapEditorApp {
 
   touchDocument() {
     this.documentModel.metadata.updatedAt = new Date().toISOString();
+    this.queueLivePreviewSync("document-update");
+  }
+
+  publishLivePreviewSync(reason = "update") {
+    this.livePreviewSync.publish(
+      {
+        toolId: "tile-map-editor",
+        reason,
+        tileMapDocument: cloneDeep(this.documentModel)
+      },
+      "tool-live-preview-sync"
+    );
+  }
+
+  queueLivePreviewSync(reason = "update") {
+    this.pendingLivePreviewReason = reason;
+    if (this.livePreviewSyncFrame) {
+      return;
+    }
+    const schedule = typeof requestAnimationFrame === "function"
+      ? requestAnimationFrame
+      : (callback) => setTimeout(callback, 16);
+    this.livePreviewSyncFrame = schedule(() => {
+      this.livePreviewSyncFrame = 0;
+      this.publishLivePreviewSync(this.pendingLivePreviewReason);
+    });
   }
 
   syncInputsFromDocument() {
diff --git a/tools/shared/livePreviewSyncChannel.js b/tools/shared/livePreviewSyncChannel.js

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-PR_08_02_TOOL_SAMPLE_ROUNDTRIP`
	`1`	`+PR_08_03_TOOL_LIVE_PREVIEW_SYNC`