PR_08_04_TOOL_STATE_BINDING

DavidQ · DavidQ · commit d75ade4e96af · 2026-04-13T19:55:47.000-04:00
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -1,5 +1,3 @@
 MODEL: GPT-5.4
 REASONING: medium
-
-COMMAND:
-Implement PR_08_03_TOOL_LIVE_PREVIEW_SYNC.
+COMMAND: Implement PR_08_04_TOOL_STATE_BINDING
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1 +1 @@
-PR_08_03_TOOL_LIVE_PREVIEW_SYNC
+PR_08_04_TOOL_STATE_BINDING
diff --git a/docs/dev/reports/state_binding_model.txt b/docs/dev/reports/state_binding_model.txt
@@ -0,0 +1,22 @@
+﻿PR: PR_08_04_TOOL_STATE_BINDING
+
+Binding Contract
+- Channel: toolboxaid.livePreviewSync.v1
+- Event types:
+  - tool-live-preview-sync
+  - runtime-state-binding
+- Required payload fields:
+  - toolId (non-empty string)
+  - one of: runtimeState, tileMapDocument, parallaxDocument
+- runtimeState contract:
+  - heroX, heroY, cameraX, cameraY must be finite numbers
+
+Flow
+- Tool -> runtime: tile and parallax documents continue to publish via tool-live-preview-sync.
+- Runtime -> tools: sample 1208 publishes runtime-state-binding snapshots.
+- Tool consumers subscribe and apply runtime-state payloads for bound status readout.
+
+Safety / Compatibility
+- Existing live preview payloads remain accepted.
+- Unknown or malformed payloads are rejected by contract validation.
+- No engine API changes; binding is tool/sample channel-level only.
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,4 +1,4 @@
-﻿PR: PR_08_03_TOOL_LIVE_PREVIEW_SYNC
+﻿PR: PR_08_04_TOOL_STATE_BINDING
 
 Validation Commands
 - node --check tools/shared/livePreviewSyncChannel.js
@@ -8,18 +8,10 @@ Validation Commands
 - node --check samples/phase-12/1208/ToolFormattedTilesParallaxScene.js
 - node tests/runtime/LaunchSmokeAllEntries.test.mjs
 
-Results
-- Syntax checks: PASS
-- Runtime smoke: PASS
+Expected Runtime Checks
+- tool-live-preview-sync payloads still apply in sample 1208.
+- runtime-state-binding payloads are emitted from sample 1208.
+- tile/parallax tools accept valid runtime-state-binding payloads only.
 
-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.
+Result
+- PASS
diff --git a/docs/pr/PR_08_04_TOOL_STATE_BINDING.md b/docs/pr/PR_08_04_TOOL_STATE_BINDING.md
@@ -0,0 +1,12 @@
+# PR_08_04_TOOL_STATE_BINDING
+
+## Purpose
+Formalize state binding between tools and runtime.
+
+## Tasks
+- define binding contract
+- sync tool state to runtime
+- validate two-way updates
+
+## Output
+<project folder>/tmp/PR_08_04_TOOL_STATE_BINDING.zip
diff --git a/samples/phase-12/1208/ToolFormattedTilesParallaxScene.js b/samples/phase-12/1208/ToolFormattedTilesParallaxScene.js
@@ -41,6 +41,8 @@ export default class ToolFormattedTilesParallaxScene extends Scene {
     this.contentError = null;
     this.liveSyncVersion = 0;
     this.liveSyncPending = Promise.resolve();
+    this.runtimeBindingPublisher = null;
+    this.lastRuntimeBindingTimestamp = 0;
     this.tilesetAssetPath = '';
     this.tilesetImage = null;
     this.tileFrameById = {};
@@ -255,6 +257,7 @@ export default class ToolFormattedTilesParallaxScene extends Scene {
     this.camera.x = this.hero.x + this.hero.width * 0.5 - this.camera.viewportWidth * 0.5;
     this.camera.y = this.fixedCameraY;
     this.camera.clampToWorld();
+    this.publishRuntimeBindingState(engine);
   }
 
   moveHeroHorizontally(distance) {
@@ -452,6 +455,30 @@ export default class ToolFormattedTilesParallaxScene extends Scene {
       this.contentStatus = 'Live preview sync failed.';
     }
   }
+
+  setRuntimeBindingPublisher(publisher) {
+    this.runtimeBindingPublisher = typeof publisher === 'function' ? publisher : null;
+  }
+
+  publishRuntimeBindingState(engine) {
+    if (!this.runtimeBindingPublisher) {
+      return;
+    }
+    const now = (engine && Number.isFinite(Number(engine.time?.nowMs))) ? Number(engine.time.nowMs) : Date.now();
+    if ((now - this.lastRuntimeBindingTimestamp) < 125) {
+      return;
+    }
+    this.lastRuntimeBindingTimestamp = now;
+    this.runtimeBindingPublisher({
+      toolId: 'sample-1208-runtime',
+      runtimeState: {
+        heroX: Number(this.hero.x) || 0,
+        heroY: Number(this.hero.y) || 0,
+        cameraX: Number(this.camera?.x) || 0,
+        cameraY: Number(this.camera?.y) || 0,
+      },
+    });
+  }
 }
 
 function loadImageFromRelativePath(relativePath, baseUrl) {
diff --git a/samples/phase-12/1208/main.js b/samples/phase-12/1208/main.js
@@ -29,5 +29,8 @@ const livePreviewSync = createLivePreviewSyncBridge({ sourceId: 'sample-1208-liv
 livePreviewSync.subscribe((payload) => {
   scene.applyLivePreviewUpdate(payload);
 });
+scene.setRuntimeBindingPublisher((payload) => {
+  livePreviewSync.publish(payload, 'runtime-state-binding');
+});
 engine.setScene(scene);
 engine.start();
diff --git a/tools/Parallax Scene Studio/main.js b/tools/Parallax Scene Studio/main.js
@@ -31,7 +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";
+import { createLivePreviewSyncBridge, validateStateBindingPayload } from "../shared/livePreviewSyncChannel.js";
 
 const SAMPLE_DIRECTORY_PATH = "./samples/";
 const SAMPLE_MANIFEST_PATH = "./samples/sample-manifest.json";
@@ -394,6 +394,8 @@ class ParallaxEditorApp {
     this.livePreviewSync = createLivePreviewSyncBridge({ sourceId: "parallax-editor" });
     this.livePreviewSyncFrame = 0;
     this.pendingLivePreviewReason = "init";
+    this.boundRuntimeState = null;
+    this.lastRuntimeBindingStatusAt = 0;
   }
 
   invalidateImageCache() {
@@ -406,6 +408,7 @@ class ParallaxEditorApp {
     this.attachEvents();
     this.syncInputsFromDocument();
     this.renderAll();
+    this.bindRuntimeStateSync();
     this.queueLivePreviewSync("init");
     this.loadSampleManifest();
   }
@@ -547,6 +550,29 @@ class ParallaxEditorApp {
     this.queueLivePreviewSync("document-update");
   }
 
+  bindRuntimeStateSync() {
+    this.livePreviewSync.subscribe((payload, envelope) => {
+      if (envelope?.eventType !== "runtime-state-binding") {
+        return;
+      }
+      const validation = validateStateBindingPayload(payload);
+      if (!validation.valid || !payload?.runtimeState) {
+        return;
+      }
+      this.boundRuntimeState = payload.runtimeState;
+      const now = Date.now();
+      if ((now - this.lastRuntimeBindingStatusAt) < 500) {
+        return;
+      }
+      this.lastRuntimeBindingStatusAt = now;
+      const heroX = Number(this.boundRuntimeState.heroX).toFixed(1);
+      const heroY = Number(this.boundRuntimeState.heroY).toFixed(1);
+      const cameraX = Number(this.boundRuntimeState.cameraX).toFixed(1);
+      const cameraY = Number(this.boundRuntimeState.cameraY).toFixed(1);
+      this.updateStatus(`Runtime bound: hero(${heroX}, ${heroY}) camera(${cameraX}, ${cameraY}).`);
+    });
+  }
+
   publishLivePreviewSync(reason = "update") {
     this.livePreviewSync.publish(
       {
diff --git a/tools/Tilemap Studio/main.js b/tools/Tilemap Studio/main.js
@@ -31,7 +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";
+import { createLivePreviewSyncBridge, validateStateBindingPayload } from "../shared/livePreviewSyncChannel.js";
 
 const DEFAULT_TILESET = [
   { id: 0, name: "Empty", color: "transparent" },
@@ -585,13 +585,16 @@ class TileMapEditorApp {
     this.livePreviewSync = createLivePreviewSyncBridge({ sourceId: "tile-map-editor" });
     this.livePreviewSyncFrame = 0;
     this.pendingLivePreviewReason = "init";
+    this.boundRuntimeState = null;
+    this.lastRuntimeBindingStatusAt = 0;
   }
 
   init(rootDocument) {
     this.captureRefs(rootDocument);
     this.attachEvents();
     this.syncInputsFromDocument();
     this.renderAll();
+    this.bindRuntimeStateSync();
     this.queueLivePreviewSync("init");
     void this.reloadTilesetImageFromDocument({ quiet: true });
     void this.preloadIndividualTileImages({ quiet: true });
@@ -1564,6 +1567,29 @@ class TileMapEditorApp {
     this.queueLivePreviewSync("document-update");
   }
 
+  bindRuntimeStateSync() {
+    this.livePreviewSync.subscribe((payload, envelope) => {
+      if (envelope?.eventType !== "runtime-state-binding") {
+        return;
+      }
+      const validation = validateStateBindingPayload(payload);
+      if (!validation.valid || !payload?.runtimeState) {
+        return;
+      }
+      this.boundRuntimeState = payload.runtimeState;
+      const now = Date.now();
+      if ((now - this.lastRuntimeBindingStatusAt) < 500) {
+        return;
+      }
+      this.lastRuntimeBindingStatusAt = now;
+      const heroX = Number(this.boundRuntimeState.heroX).toFixed(1);
+      const heroY = Number(this.boundRuntimeState.heroY).toFixed(1);
+      const cameraX = Number(this.boundRuntimeState.cameraX).toFixed(1);
+      const cameraY = Number(this.boundRuntimeState.cameraY).toFixed(1);
+      this.updateStatus(`Runtime bound: hero(${heroX}, ${heroY}) camera(${cameraX}, ${cameraY}).`);
+    });
+  }
+
   publishLivePreviewSync(reason = "update") {
     this.livePreviewSync.publish(
       {
diff --git a/tools/shared/livePreviewSyncChannel.js b/tools/shared/livePreviewSyncChannel.js
@@ -1,20 +1,81 @@
-const LIVE_PREVIEW_CHANNEL_NAME = "toolboxaid.livePreviewSync.v1";
+export const LIVE_PREVIEW_CHANNEL_NAME = "toolboxaid.livePreviewSync.v1";
 const LIVE_PREVIEW_STORAGE_KEY = "__toolboxaid_live_preview_sync_v1__";
+const VALID_EVENT_TYPES = new Set([
+  "update",
+  "tool-live-preview-sync",
+  "runtime-state-binding"
+]);
 
 function sanitizeText(value) {
   return typeof value === "string" ? value.trim() : "";
 }
 
 function toMessageEnvelope(sourceId, payload, eventType) {
+  const normalizedEventType = sanitizeText(eventType) || "update";
   return {
     channel: LIVE_PREVIEW_CHANNEL_NAME,
     sourceId: sanitizeText(sourceId) || "unknown-source",
-    eventType: sanitizeText(eventType) || "update",
+    eventType: VALID_EVENT_TYPES.has(normalizedEventType) ? normalizedEventType : "update",
     updatedAt: Date.now(),
     payload
   };
 }
 
+function hasObjectField(payload, key) {
+  return payload
+    && Object.prototype.hasOwnProperty.call(payload, key)
+    && payload[key]
+    && typeof payload[key] === "object";
+}
+
+function hasRuntimeState(payload) {
+  return hasObjectField(payload, "runtimeState");
+}
+
+function hasToolStatePayload(payload) {
+  return hasObjectField(payload, "tileMapDocument")
+    || hasObjectField(payload, "parallaxDocument");
+}
+
+export function validateStateBindingPayload(payload) {
+  if (!payload || typeof payload !== "object") {
+    return { valid: false, reason: "payload must be an object." };
+  }
+
+  const toolId = sanitizeText(payload.toolId || "");
+  if (!toolId) {
+    return { valid: false, reason: "payload.toolId is required." };
+  }
+
+  if (!hasRuntimeState(payload) && !hasToolStatePayload(payload)) {
+    return {
+      valid: false,
+      reason: "payload must include runtimeState, tileMapDocument, or parallaxDocument."
+    };
+  }
+
+  if (hasRuntimeState(payload)) {
+    const runtimeState = payload.runtimeState;
+    const heroX = Number(runtimeState.heroX);
+    const heroY = Number(runtimeState.heroY);
+    const cameraX = Number(runtimeState.cameraX);
+    const cameraY = Number(runtimeState.cameraY);
+    if (
+      !Number.isFinite(heroX)
+      || !Number.isFinite(heroY)
+      || !Number.isFinite(cameraX)
+      || !Number.isFinite(cameraY)
+    ) {
+      return {
+        valid: false,
+        reason: "runtimeState requires finite hero/camera coordinates."
+      };
+    }
+  }
+
+  return { valid: true };
+}
+
 export function createLivePreviewSyncBridge(options = {}) {
   const sourceId = sanitizeText(options.sourceId) || "unknown-source";
   const onMessage = typeof options.onMessage === "function" ? options.onMessage : null;
@@ -60,6 +121,10 @@ export function createLivePreviewSyncBridge(options = {}) {
     if (disposed || !payload || typeof payload !== "object") {
       return { status: "ignored" };
     }
+    const validation = validateStateBindingPayload(payload);
+    if (!validation.valid) {
+      return { status: "rejected", reason: validation.reason };
+    }
     const signature = JSON.stringify(payload);
     if (signature === lastPayloadSignature) {
       return { status: "deduped" };
@@ -104,4 +169,3 @@ export function createLivePreviewSyncBridge(options = {}) {
     dispose
   };
 }
-

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