Align Tilemap Studio to unified contract with stable selection, canvas rendering, and workspace behavior - PR 10.10

Author: DavidQ

docs/dev/codex_commands.md

@@ -1,11 +1,12 @@
 model: gpt-5.3-codex
 reasoning: medium
 
-Apply PR_10_9_SPRITE_EDITOR_UAT
+Apply PR_10_10_TILEMAP_STUDIO_UAT
 
-- Add first-frame auto-selection
-- Fix preview rendering mismatch
-- Enforce control enable/disable rules
-- Ensure no flicker/reset
+- Enforce empty state messaging
+- Add first-tile auto-selection
+- Add selection highlight
+- Enforce control enable/disable
+- Stabilize canvas rendering
 - Ensure workspace stability
-- Do not modify sprite data
+- Do not modify data layer

docs/dev/commit_comment.txt

@@ -1 +1 @@
-Align Sprite Editor to unified contract and fix preview rendering mismatch - PR 10.9
+Align Tilemap Studio to unified contract with stable selection, canvas rendering, and workspace behavior - PR 10.10

docs/dev/reports/PR_10_10_tilemap_studio_uat_report.md

@@ -0,0 +1,51 @@
+# PR 10.10 Tilemap Studio UAT Report
+
+## Scope
+- Tool: `tools/Tilemap Studio`
+- Purpose: apply only UAT UI behavior for empty state, tile selection, control state, render stability, and workspace stability.
+- Constraints honored: no tile data/schema changes, no feature additions.
+
+## Changes Implemented
+1. Empty state messaging
+- Added explicit tile-palette empty state text:
+  - `No tiles loaded`
+  - `Import or create tileset`
+- No blank palette container when no selectable tiles exist.
+
+2. First-tile auto-selection
+- Added selection normalization helpers (`getSelectableTiles`, `hasTileSelection`, `ensureFirstTileSelection`).
+- Enforced first valid tile selection during render and workspace snapshot application fallback.
+
+3. Selection highlight
+- Kept and strengthened active swatch highlight styling for clearer visibility.
+
+4. Control enable/disable rules
+- Added `syncTileSelectionControlState()`.
+- Disables tile-edit controls when no valid tile is selected, including tool selector, layer/marker edit controls, and simulation action buttons.
+- Adds disabled visual state to canvas (`aria-disabled`, class state).
+
+5. Canvas stability (no flicker/reset)
+- Canvas width/height are now updated only when dimensions actually change.
+- Added explicit clear before redraw.
+- Reduced hover-triggered redraw churn by rendering on pointer move only when hover cell changes or painting is active.
+
+6. Workspace stability
+- Preserved existing strict snapshot validation and no auto-close/reload behavior.
+- Selection fallback on workspace state apply now uses first valid tile when snapshot selection is absent.
+
+## Acceptance Check
+- Empty state enforced: PASS
+- First tile auto-selected: PASS
+- Selection highlight clear: PASS
+- Controls disabled without selection, enabled with selection: PASS
+- Canvas render stabilized (reduced reset/flicker): PASS
+- Workspace stability preserved (no auto-close/reload additions): PASS
+
+## Files Changed
+- `tools/Tilemap Studio/main.js`
+- `tools/Tilemap Studio/tileMapEditor.css`
+
+## Validation
+- `node --check tools/Tilemap Studio/main.js` PASS
+- `npm run test:launch-smoke:games` PASS (12/12)
+- `npm run test:sample-standalone:data-flow` PASS

docs/dev/reports/REPORT_PR_10_10.md

@@ -0,0 +1,9 @@
+# REPORT_PR_10_10
+
+Tilemap Studio stabilized.
+
+Fixes:
+- Selection consistency
+- Empty state clarity
+- Canvas stability
+- Workspace behavior

docs/dev/reports/launch_smoke_report.md

@@ -1,6 +1,6 @@
 # Launch Smoke Report
 
-Generated: 2026-04-28T14:26:54.354Z
+Generated: 2026-04-28T14:37:54.368Z
 
 Filters: games=true, samples=false, tools=false, sampleRange=all
 

docs/pr/PR_10_10_TILEMAP_STUDIO_UAT/BUILD.md

@@ -0,0 +1,29 @@
+# BUILD_PR_10_10_TILEMAP_STUDIO_UAT
+
+## Behavior
+
+### Empty State
+If no tiles:
+- Show: "No tiles loaded"
+- Show: "Import or create tileset"
+- No blank UI
+
+### Selection
+- First tile auto-selected
+- Highlight selection clearly
+
+### Controls
+- Disabled when no selection
+- Enabled when tile selected
+
+### Canvas
+- Stable render (no flicker)
+- No reset on interaction
+
+### Workspace
+- No auto-close
+- No reload on focus
+
+## Constraints
+- No tile data changes
+- No feature additions

docs/pr/PR_10_10_TILEMAP_STUDIO_UAT/PLAN.md

@@ -0,0 +1,18 @@
+# PLAN_PR_10_10_TILEMAP_STUDIO_UAT
+
+## Purpose
+Align Tilemap Studio behavior with unified UX contract and stabilize tile selection/render flow.
+
+## Scope
+- Enforce layout zones
+- First tile auto-selection
+- Visible selection highlight
+- Enforce control enablement rules
+- Stabilize render (no flicker/reset)
+- No data/schema changes
+
+## Acceptance
+- Tile palette visible or explicit empty state
+- First tile auto-selected
+- Canvas renders consistently
+- Stable in workspace (no reload/reset)

tools/Tilemap Studio/main.js

@@ -69,6 +69,8 @@ const RESERVED_PARALLAX_BLOCK = Object.freeze({
 });
 
 const DEFAULT_TILESET_SWATCH_COLOR = "#64748b";
+const TILE_PALETTE_EMPTY_TITLE = "No tiles loaded";
+const TILE_PALETTE_EMPTY_HINT = "Import or create tileset";
 
 function normalizeSamplePresetPath(pathValue) {
   if (typeof pathValue !== "string") {
@@ -650,7 +652,7 @@ class TileMapEditorApp {
   constructor(documentModel) {
     this.documentModel = documentModel;
     this.selectedLayerId = documentModel.layers[0]?.id || "";
-    this.activeTileId = 1;
+    this.activeTileId = this.findFirstNonEmptyTileId();
     this.activeTool = "paint";
     this.canvasZoom = 1;
     this.hoverCell = null;
@@ -1094,7 +1096,7 @@ class TileMapEditorApp {
     this.documentModel = createInitialDocument({ width, height, tileSize, mapName });
     this.selectedLayerId = this.documentModel.layers[0]?.id || "";
     this.selectedMarkerId = "";
-    this.activeTileId = 1;
+    this.activeTileId = this.findFirstNonEmptyTileId();
     this.tilesetImage = null;
     this.tilesetImageCache = new Map();
     this.clearTransientImageSources();
@@ -1368,6 +1370,52 @@ class TileMapEditorApp {
     return tiles[0]?.id ?? 0;
   }
 
+  getSelectableTiles() {
+    const tileset = Array.isArray(this.documentModel?.tileset) ? this.documentModel.tileset : [];
+    return tileset.filter((tile) => Number.isFinite(Number(tile?.id)) && Number(tile.id) > 0);
+  }
+
+  hasTileSelection() {
+    const selectedTileId = Number.parseInt(this.activeTileId, 10);
+    if (!Number.isFinite(selectedTileId)) {
+      return false;
+    }
+    return this.getSelectableTiles().some((tile) => Number(tile.id) === selectedTileId);
+  }
+
+  ensureFirstTileSelection() {
+    const selectableTiles = this.getSelectableTiles();
+    if (selectableTiles.length <= 0) {
+      this.activeTileId = 0;
+      return false;
+    }
+    if (this.hasTileSelection()) {
+      return false;
+    }
+    this.activeTileId = selectableTiles[0].id;
+    return true;
+  }
+
+  syncTileSelectionControlState() {
+    const hasSelection = this.hasTileSelection();
+    this.refs.activeToolSelect.disabled = !hasSelection;
+    this.refs.addLayerButton.disabled = !hasSelection;
+    this.refs.removeLayerButton.disabled = !hasSelection;
+    this.refs.layerVisibilityToggle.disabled = !hasSelection;
+    this.refs.markerTypeSelect.disabled = !hasSelection;
+    this.refs.markerNameInput.disabled = !hasSelection;
+    this.refs.clearMarkersButton.disabled = !hasSelection;
+    this.refs.mapCanvas.classList.toggle("is-selection-disabled", !hasSelection);
+    this.refs.mapCanvas.setAttribute("aria-disabled", hasSelection ? "false" : "true");
+    if (!hasSelection) {
+      this.refs.simulateButton.disabled = true;
+      this.refs.playSimulationButton.disabled = true;
+      this.refs.pauseSimulationButton.disabled = true;
+      this.refs.restartSimulationButton.disabled = true;
+      this.refs.exitSimulationButton.disabled = true;
+    }
+  }
+
   readTilesetAtlasSettingsFromInputs() {
     const fallback = sanitizeTilesetAtlas(this.documentModel.tilesetAtlas, this.documentModel.map.tileSize);
     return {
@@ -1807,6 +1855,11 @@ class TileMapEditorApp {
       return;
     }
 
+    if (!this.hasTileSelection()) {
+      this.updateStatus(`${TILE_PALETTE_EMPTY_TITLE}. ${TILE_PALETTE_EMPTY_HINT}.`);
+      return;
+    }
+
     if (this.activeTool === "marker") {
       if (event.button === 2) {
         this.removeMarkerAtCell(cell.col, cell.row);
@@ -1826,13 +1879,17 @@ class TileMapEditorApp {
 
   handleCanvasPointerMove(event) {
     const cell = this.getCellFromMouseEvent(event);
+    const hoverChanged = (cell?.col ?? -1) !== (this.hoverCell?.col ?? -1)
+      || (cell?.row ?? -1) !== (this.hoverCell?.row ?? -1);
     this.hoverCell = cell;
 
     if (cell && this.isPointerPainting && (this.activeTool === "paint" || this.activeTool === "erase")) {
       this.applyCellEdit(cell.col, cell.row, this.activeTool);
     }
 
-    this.renderCanvas();
+    if (hoverChanged || this.isPointerPainting) {
+      this.renderCanvas();
+    }
     if (cell) {
       this.refs.canvasMeta.textContent = `Cell ${cell.col}, ${cell.row}`;
     } else {
@@ -1841,9 +1898,12 @@ class TileMapEditorApp {
   }
 
   handleCanvasPointerLeave() {
+    const hadHover = Boolean(this.hoverCell);
     this.hoverCell = null;
     this.isPointerPainting = false;
-    this.renderCanvas();
+    if (hadHover) {
+      this.renderCanvas();
+    }
     this.refs.canvasMeta.textContent = `${this.documentModel.map.width}x${this.documentModel.map.height}`;
   }
 
@@ -1878,9 +1938,14 @@ class TileMapEditorApp {
 
     if (mode === "picker") {
       const sampled = normalizeCellValue(layer.data[row][col]);
-      this.activeTileId = sampled;
-      this.renderTileset();
-      this.updateStatus(`Sampled tile ${sampled} at ${col}, ${row}.`);
+      if (sampled > 0) {
+        this.activeTileId = sampled;
+        this.renderTileset();
+        this.syncTileSelectionControlState();
+        this.updateStatus(`Sampled tile ${sampled} at ${col}, ${row}.`);
+      } else {
+        this.updateStatus("No tile sampled at this cell.");
+      }
       return;
     }
 
@@ -2583,6 +2648,7 @@ class TileMapEditorApp {
   }
 
   renderAll() {
+    this.ensureFirstTileSelection();
     this.renderLayerList();
     this.renderTileset();
     this.renderTilesetMeta();
@@ -2595,6 +2661,7 @@ class TileMapEditorApp {
     this.updateRemediationUI();
     this.updateEditorExperienceUI();
     this.updateDebugVisualizationUI();
+    this.syncTileSelectionControlState();
     this.syncUxContractState();
   }
 
@@ -2655,12 +2722,17 @@ class TileMapEditorApp {
   renderTileset() {
     const container = this.refs.tilePalette;
     container.innerHTML = "";
+    const selectableTiles = this.getSelectableTiles();
+    if (selectableTiles.length <= 0) {
+      container.innerHTML = `<p class="tile-palette-empty"><strong>${TILE_PALETTE_EMPTY_TITLE}</strong><span>${TILE_PALETTE_EMPTY_HINT}</span></p>`;
+      return;
+    }
 
     const fragment = document.createDocumentFragment();
-    this.documentModel.tileset.forEach((tile) => {
+    selectableTiles.forEach((tile) => {
       const button = document.createElement("button");
       button.type = "button";
-      button.className = `tile-swatch${tile.id === this.activeTileId ? " active" : ""}`;
+      button.className = `tile-swatch${Number(tile.id) === Number(this.activeTileId) ? " active" : ""}`;
       button.dataset.tileId = String(tile.id);
       button.title = `${tile.name} (${tile.id})`;
 
@@ -2708,6 +2780,7 @@ class TileMapEditorApp {
       button.addEventListener("click", () => {
         this.activeTileId = tile.id;
         this.renderTileset();
+        this.syncTileSelectionControlState();
         this.updateStatus(`Selected tile ${tile.name} (${tile.id}).`);
       });
 
@@ -2849,9 +2922,16 @@ class TileMapEditorApp {
     const context = this.refs.canvasContext;
     const { width, height, tileSize } = this.documentModel.map;
 
-    canvas.width = width * tileSize;
-    canvas.height = height * tileSize;
+    const nextWidth = width * tileSize;
+    const nextHeight = height * tileSize;
+    if (canvas.width !== nextWidth) {
+      canvas.width = nextWidth;
+    }
+    if (canvas.height !== nextHeight) {
+      canvas.height = nextHeight;
+    }
 
+    context.clearRect(0, 0, canvas.width, canvas.height);
     context.fillStyle = "#0f172a";
     context.fillRect(0, 0, canvas.width, canvas.height);
 
@@ -3268,7 +3348,7 @@ function bootTileMapStudio() {
       ? snapshot.selectedLayerId
       : nextDocument.layers[0]?.id || "";
     this.selectedMarkerId = typeof snapshot?.selectedMarkerId === "string" ? snapshot.selectedMarkerId : "";
-    this.activeTileId = Number.isInteger(snapshot?.activeTileId) ? snapshot.activeTileId : 1;
+    this.activeTileId = Number.isInteger(snapshot?.activeTileId) ? snapshot.activeTileId : this.findFirstNonEmptyTileId();
     this.tilesetImageCache = new Map();
     this.clearTransientImageSources();
     this.resolveAssetRefsFromRegistry();

tools/Tilemap Studio/tileMapEditor.css

@@ -192,6 +192,11 @@ select {
   display: block;
 }
 
+#mapCanvas.is-selection-disabled {
+  opacity: 0.72;
+  pointer-events: none;
+}
+
 .status-text {
   margin-top: 8px;
   font-size: 12px;
@@ -205,6 +210,19 @@ select {
   margin-top: 8px;
 }
 
+.tile-palette-empty {
+  margin: 0;
+  border: 1px dashed var(--editor-border);
+  border-radius: 8px;
+  padding: 10px;
+  color: var(--editor-muted);
+}
+
+.tile-palette-empty strong,
+.tile-palette-empty span {
+  display: block;
+}
+
 .tile-swatch {
   display: flex;
   flex-direction: column;
@@ -234,7 +252,7 @@ select {
 
 .tile-swatch.active {
   border-color: var(--editor-accent);
-  box-shadow: 0 0 0 1px color-mix(in srgb, var(--editor-accent) 35%, transparent) inset;
+  box-shadow: 0 0 0 1px color-mix(in srgb, var(--editor-accent) 35%, transparent) inset, 0 0 0 1px var(--editor-accent);
 }
 
 .tileset-config-grid {