Complete Tilemap Studio V2 with HTML-first shell and session-only runtime behavior - PR 11.198

Author: DavidQ

docs/dev/reports/PR_11_198_report.md

@@ -1,6 +1,7 @@
 # PR_11_198 Report
 
 ## Files Changed
+- `tools/tilemap-studio-v2/index.html`
 - `tools/tilemap-studio-v2/index.js`
 - `docs/dev/reports/PR_11_198_report.md`
 
@@ -11,11 +12,18 @@
 - `node --check tools/tilemap-studio-v2/index.js`: **PASS** (exit code 0)
 
 ## Manual Test Notes
-- Open `tools/tilemap-studio-v2/index.html`: not executed in this CLI-only run (no interactive browser session available in terminal tooling).
-- Shared header mount target check (`#shared-theme-header` exists in HTML shell): **PASS** by static source inspection.
-- Missing session actionable state handling: **PASS** by source inspection of `renderMissing(...)`.
-- Valid session tilemap render path: **PASS** by source inspection of `renderTilemap(...)`.
-- Console error-free browser run: not executed in this CLI-only run (requires manual browser verification).
+- Open `tools/tilemap-studio-v2/index.html`: not executed in this CLI-only run (no interactive browser available in terminal tooling).
+- Shared header mount target (`#shared-theme-header`) and mount script path: **PASS** by static source inspection.
+- Empty state region (`#tilemapV2EmptyState`) behavior: **PASS** by source inspection.
+- Invalid state region (`#tilemapV2InvalidState`) actionable messaging: **PASS** by source inspection.
+- Valid/render region (`#tilemapV2ValidState`) tilemap preview rendering: **PASS** by source inspection.
+- Console error-free browser run: not executed in this CLI-only run (requires browser validation).
 
 ## Samples Smoke Statement
 - Full samples smoke was skipped because this PR is scoped to `tools/tilemap-studio-v2` behavior-only changes and does not modify samples, games, schemas, or shared engine runtime contracts.
+
+## Scope Guard Confirmation
+- No schema files changed.
+- No sample files changed.
+- No game files changed.
+- No Workspace Manager v1 files changed.

tools/tilemap-studio-v2/index.html

@@ -24,8 +24,12 @@ <h3>menuTool</h3>
             <section class="tilemap-v2-panel" aria-live="polite">
               <h3 id="tilemapV2Name">No tilemap loaded</h3>
               <span id="tilemapV2Count" class="badge">0 layers</span>
-              <div id="tilemapV2State">No tilemap session data found. Open Tilemap Studio V2 with a valid hostContextId session.</div>
-              <div id="tilemapV2Preview" aria-label="Tilemap Studio V2 preview"></div>
+              <div id="tilemapV2EmptyState">No tilemap session data found. Open Tilemap Studio V2 with a valid hostContextId session.</div>
+              <div id="tilemapV2InvalidState" hidden>Tilemap session data is invalid. Re-open Tilemap Studio V2 from a valid workspace session.</div>
+              <div id="tilemapV2ValidState" hidden>
+                <div id="tilemapV2State">Tilemap Studio V2 loaded the session tilemap.</div>
+                <div id="tilemapV2Preview" aria-label="Tilemap Studio V2 preview"></div>
+              </div>
             </section>
             <aside class="tilemap-v2-panel" data-menu-workspace>
               <h3>menuWorkspace</h3>

tools/tilemap-studio-v2/index.js

@@ -1,11 +1,13 @@
 class TilemapStudioV2 {
   constructor() {
+    console.log("[TilemapStudioV2]");
     document.title = "Tilemap Studio V2";
     document.body.dataset.toolId = "tilemap-studio-v2";
     this.readSession();
   }
 
   readSession() {
+    console.log("[SESSION_CONTEXT_READ]");
     try {
       if (!new URL(window.location.href).searchParams.get("hostContextId")) {
         this.renderMissing("No hostContextId was provided. Re-open Tilemap Studio V2 from a valid Tool V2 session link.");
@@ -32,6 +34,7 @@ class TilemapStudioV2 {
   }
 
   loadContract(sessionContext) {
+    console.log("[TILEMAP_V2_CONTRACT_LOADED]");
     if (!sessionContext || typeof sessionContext !== "object" || Array.isArray(sessionContext)) {
       this.renderError("Session context is invalid. Expected an object containing payloadJson.tileMapDocument.");
       return;
@@ -64,10 +67,6 @@ class TilemapStudioV2 {
       this.renderError("Tilemap session data is invalid. Expected tileMapDocument.layers[].");
       return;
     }
-    if (tileMapDocument.layers.length === 0) {
-      this.renderMissing("Tilemap Studio V2 loaded a valid tilemap document with zero layers.");
-      return;
-    }
     if (tileMapDocument.layers.some((entry) => !entry || typeof entry !== "object" || Array.isArray(entry) || typeof entry.name !== "string" || !entry.name.trim() || typeof entry.kind !== "string" || !entry.kind.trim() || !Array.isArray(entry.data))) {
       this.renderError("Tilemap session data is invalid. Every layer requires name, kind, and data[].");
       return;
@@ -78,6 +77,9 @@ class TilemapStudioV2 {
     document.getElementById("tilemapV2Name").textContent = tileMapDocument.map.name.trim();
     document.getElementById("tilemapV2Count").textContent = `${tileMapDocument.layers.length} layer${tileMapDocument.layers.length === 1 ? "" : "s"}`;
     document.getElementById("tilemapV2State").textContent = "Tilemap Studio V2 loaded the session tilemap.";
+    document.getElementById("tilemapV2EmptyState").hidden = true;
+    document.getElementById("tilemapV2InvalidState").hidden = true;
+    document.getElementById("tilemapV2ValidState").hidden = false;
     document.getElementById("tilemapV2LayerList").replaceChildren();
     tileMapDocument.layers.forEach((entry) => {
       const layerItem = document.createElement("li");
@@ -111,7 +113,10 @@ class TilemapStudioV2 {
     document.getElementById("tilemapV2WorkspaceReadout").textContent = "Workspace session context is not available.";
     document.getElementById("tilemapV2Name").textContent = "No tilemap loaded";
     document.getElementById("tilemapV2Count").textContent = "0 layers";
-    document.getElementById("tilemapV2State").textContent = message;
+    document.getElementById("tilemapV2EmptyState").textContent = message;
+    document.getElementById("tilemapV2EmptyState").hidden = false;
+    document.getElementById("tilemapV2InvalidState").hidden = true;
+    document.getElementById("tilemapV2ValidState").hidden = true;
     document.getElementById("tilemapV2LayerList").replaceChildren();
     document.getElementById("tilemapV2Preview").replaceChildren();
   }
@@ -122,7 +127,10 @@ class TilemapStudioV2 {
     document.getElementById("tilemapV2WorkspaceReadout").textContent = "Workspace writes are disabled for invalid Tilemap Studio V2 session data.";
     document.getElementById("tilemapV2Name").textContent = "Tilemap Studio V2 error";
     document.getElementById("tilemapV2Count").textContent = "0 layers";
-    document.getElementById("tilemapV2State").textContent = message;
+    document.getElementById("tilemapV2InvalidState").textContent = `${message} Re-open Tilemap Studio V2 from a host session that provides payloadJson.tileMapDocument.`;
+    document.getElementById("tilemapV2EmptyState").hidden = true;
+    document.getElementById("tilemapV2InvalidState").hidden = false;
+    document.getElementById("tilemapV2ValidState").hidden = true;
     document.getElementById("tilemapV2LayerList").replaceChildren();
     document.getElementById("tilemapV2Preview").replaceChildren();
   }