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

DavidQ · DavidQ · commit 64a807d5e56c · 2026-05-01T14:29:31.000-04:00
diff --git a/docs/dev/codex_commands.md b/docs/dev/codex_commands.md
@@ -1,84 +1,94 @@
-# Codex Commands — PR_11_197B
+MODEL: gpt-5.3-codex
+REASONING: medium
 
-Model: GPT-5.4-codex
-Reasoning: high
+# PR_11_198 — Tilemap Studio V2 Completion + Validation
 
 ## Execute
-
-Use this PR as a Codex implementation task. Do not ask questions. Make the smallest scoped valid change.
-
-### Required Task
-Complete Asset Browser V2 as the testable implementation target and bundle it with V2 validation hardening.
-
-### Scope Lock
-Only edit files required for:
-- `tools/asset-browser-v2/index.html`
-- `tools/asset-browser-v2/index.js`
-- narrowly scoped V2 validation/test files if needed
-- docs/dev/reports evidence
-- docs/dev/roadmaps/MASTER_ROADMAP_ENGINE.md status-only marker change if execution-backed
-
-Do not edit schemas, samples, games, Workspace Manager v1, platformShell, or `tools/shared/*`.
-
-### Implementation Rules
-- Re-engineer the tool. Do not copy/paste legacy Asset Browser code.
-- `index.html` owns static shell, CSS links, header mount, layout, and DOM nodes.
-- `index.js` owns behavior only.
-- Use `data-tool-id="asset-browser-v2"`.
-- Header mount must be `<div id="shared-theme-header"></div>`.
-- Use existing `src/engine/theme` and existing accordion styling where applicable.
-- Use two menu areas only if needed: `menuTool` and `menuWorkspace`.
-- Read session data only, using the established V2 hostContextId/session pattern.
-- Do not fetch, guess, synthesize, default, or fallback data.
-- Empty state and invalid state must be explicit and actionable.
-- No helper classes. Single class only.
-- No alias/pass-through variables.
-- No abstraction layers.
-
-### Banned Patterns
-Reject your own diff if it includes:
-- `document.body.innerHTML` for page construction
-- `document.head.insertAdjacentHTML` for CSS/style injection
-- dynamic header script injection from JS
-- `platformShell`
-- `assetUsageIntegration`
-- `tools/shared/`
-- Workspace Manager v1 wiring
-- fallback/default/sample data
-- copied legacy code blocks
-
-### Validation Commands
+Implement the smallest valid testable change for Tilemap Studio V2.
+
+## Hard Boundaries
+- Codex writes implementation code.
+- Do not change schemas.
+- Do not change samples.
+- Do not change games.
+- Do not touch Workspace Manager v1.
+- Do not patch legacy tools.
+- Do not use platformShell.
+- Do not use tools/shared except the explicitly required theme/header mount path already used by the repo theme system.
+- Do not copy old tool code. Re-engineer the V2 tool.
+
+## Required Files To Inspect/Edit
+- tools/tilemap-studio-v2/index.html
+- tools/tilemap-studio-v2/index.js
+
+If either file does not exist, create only the missing file required for this tool.
+
+## Implementation Rules
+1. `tools/tilemap-studio-v2/index.html` must own the static shell:
+   - include theme CSS
+   - include `<div id="shared-theme-header"></div>`
+   - include static page shell/root container
+   - include static menuTool section
+   - include static menuWorkspace section
+   - include `../../src/engine/theme/mount-shared-header.js`
+   - include `./index.js`
+
+2. `tools/tilemap-studio-v2/index.js` must be behavior-only:
+   - single class
+   - no helper classes
+   - no alias/pass-through variables
+   - no full-page `innerHTML` construction
+   - no CSS injection
+   - no dynamic header injection
+   - read session only
+   - update existing DOM nodes only
+   - handle missing, invalid, and valid session states
+
+3. Enforce naming:
+   - visible name: `Tilemap Studio V2`
+   - `document.title`: `Tilemap Studio V2`
+   - `data-tool-id`: `tilemap-studio-v2`
+
+4. Session rules:
+   - no fallback data
+   - no defaults
+   - no fetch
+   - no guessed payloads
+   - no hidden samples
+
+## Validation Commands
 Run targeted validation only:
 
-1. Syntax checks for changed JS files.
-2. Static checks for V2 shell compliance:
-   - Asset Browser V2 `index.html` includes `shared-theme-header`.
-   - Asset Browser V2 `index.js` does not include `document.body.innerHTML`.
-   - Asset Browser V2 `index.js` does not include `document.head.insertAdjacentHTML`.
-   - Asset Browser V2 references `asset-browser-v2`.
-3. Manual/UAT or lightweight browser validation evidence for:
-   - direct open empty state
-   - invalid session state
-   - valid session state render
-   - shared header visible
+```powershell
+node --check tools/tilemap-studio-v2/index.js
+```
 
-Do not run full samples smoke unless a broad shared sample loader/framework file is changed. If skipped, document why.
+Manual validation:
+- Open `tools/tilemap-studio-v2/index.html`.
+- Confirm shared header renders in `#shared-theme-header`.
+- Confirm missing session shows clear actionable state.
+- Confirm valid session renders tilemap content.
+- Confirm browser console has no errors.
 
-### Evidence
-Write results to:
+## Evidence Report
+Create or update:
 
-`docs/dev/reports/PR_11_197B_v2_asset_browser_validation.md`
+```text
+docs/dev/reports/PR_11_198_report.md
+```
 
-Include:
+Report must include:
 - files changed
 - validation commands run
 - pass/fail results
-- full samples smoke skipped/running decision and reason
-- screenshots/log snippets if available
+- manual test notes
+- statement that full samples smoke was skipped and why
 
-### Final Artifact
-Create final ZIP at:
+## Local ZIP Output
+After validation, Codex must create:
 
-`tmp/PR_11_197B.zip`
+```text
+<project folder>/tmp/PR_11_198.zip
+```
 
-The ZIP must preserve repo-relative structure and include implementation changes and evidence.
+The ZIP must preserve repo-relative structure and include the final changed files plus docs/dev evidence.
diff --git a/docs/dev/commit_comment.txt b/docs/dev/commit_comment.txt
@@ -1 +1 @@
-Complete Asset Browser V2 and harden V2 validation with targeted evidence - PR 11.197B
+Complete Tilemap Studio V2 with HTML-first shell and session-only behavior - PR 11.198
diff --git a/docs/dev/reports/PR_11_198_report.md b/docs/dev/reports/PR_11_198_report.md
@@ -0,0 +1,21 @@
+# PR_11_198 Report
+
+## Files Changed
+- `tools/tilemap-studio-v2/index.js`
+- `docs/dev/reports/PR_11_198_report.md`
+
+## Validation Commands Run
+- `node --check tools/tilemap-studio-v2/index.js`
+
+## Validation Results
+- `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).
+
+## 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.
diff --git a/docs/pr/PR_11_198_TILEMAP_STUDIO_V2_COMPLETION.md b/docs/pr/PR_11_198_TILEMAP_STUDIO_V2_COMPLETION.md
@@ -0,0 +1,52 @@
+# PR_11_198 — Tilemap Studio V2 Completion + Validation
+
+## Purpose
+Complete Tilemap Studio V2 as a testable V2 re-engineered tool while enforcing HTML-first shell, session-only runtime behavior, and shared-theme header compliance.
+
+## Scope
+- Tilemap Studio V2 only.
+- Codex writes implementation code.
+- ChatGPT bundle supplies PR docs, Codex commands, commit comment, and report requirements only.
+- No schema changes.
+- No sample changes.
+- No game changes.
+- No Workspace Manager v1 work.
+- No legacy tool patching.
+- No platformShell or tools/shared coupling.
+
+## Required Architecture
+- `tools/tilemap-studio-v2/index.html` owns the static shell.
+- `tools/tilemap-studio-v2/index.js` owns behavior only.
+- Tool reads session-backed data only.
+- Tool does not fetch, guess, default, or fallback.
+- Tool name and visible title must end with `V2`.
+- Header must mount through `<div id="shared-theme-header"></div>`.
+
+## HTML-First Requirements
+`index.html` must contain:
+- theme CSS links
+- shared header mount
+- static app shell
+- static menuTool area
+- static menuWorkspace area
+- script includes for shared header mount and local `index.js`
+
+`index.js` must not contain:
+- full-page `document.body.innerHTML` construction
+- `document.head.insertAdjacentHTML` stylesheet injection
+- inline `<style>` injection
+- dynamic header script injection
+- legacy imports
+- helper classes
+- alias/pass-through variables
+
+## Testable Completion Criteria
+- Tilemap Studio V2 loads standalone.
+- Missing session shows a clear actionable empty/error state.
+- Valid session renders tilemap content.
+- Header renders from shared theme mount.
+- Browser console has no errors during load.
+- `node --check tools/tilemap-studio-v2/index.js` passes.
+
+## Full Samples Smoke Test Decision
+Do not run full samples smoke by default. This PR is scoped to one V2 tool. Run targeted syntax and manual Tilemap Studio V2 checks only unless Codex changes shared loaders/frameworks.
diff --git a/tools/tilemap-studio-v2/index.js b/tools/tilemap-studio-v2/index.js
@@ -1,34 +1,37 @@
 class TilemapStudioV2 {
   constructor() {
-    console.log("[TILEMAP_V2_ENTRY]");
-    this.start();
-  }
-
-  start() {
     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.renderEmpty("No hostContextId was provided. Open Tilemap Studio V2 with a valid Tool V2 session URL.");
+        this.renderMissing("No hostContextId was provided. Re-open Tilemap Studio V2 from a valid Tool V2 session link.");
         return;
       }
-      if (!window.sessionStorage.getItem(`toolboxaid.toolHost.context.${new URL(window.location.href).searchParams.get("hostContextId")}`)) {
-        this.renderEmpty("No session context was found for the provided hostContextId.");
+      if (
+        !window.sessionStorage.getItem(
+          `toolboxaid.toolHost.context.${new URL(window.location.href).searchParams.get("hostContextId")}`
+        )
+      ) {
+        this.renderMissing("No session context was found for the provided hostContextId.");
         return;
       }
-      this.loadContract(JSON.parse(window.sessionStorage.getItem(`toolboxaid.toolHost.context.${new URL(window.location.href).searchParams.get("hostContextId")}`)));
+      this.loadContract(
+        JSON.parse(
+          window.sessionStorage.getItem(
+            `toolboxaid.toolHost.context.${new URL(window.location.href).searchParams.get("hostContextId")}`
+          )
+        )
+      );
     } catch (error) {
       this.renderError(`Unable to read Tilemap Studio V2 session context: ${error instanceof Error ? error.message : "unknown error"}`);
     }
   }
 
   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;
@@ -62,7 +65,7 @@ class TilemapStudioV2 {
       return;
     }
     if (tileMapDocument.layers.length === 0) {
-      this.renderEmpty("Tilemap Studio V2 loaded a valid tilemap document with zero layers.");
+      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))) {
@@ -75,19 +78,42 @@ 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("tilemapV2LayerList").innerHTML = tileMapDocument.layers.map((entry) => `<li><strong>${this.escapeHtml(entry.name.trim())}</strong><br>${this.escapeHtml(entry.kind.trim())} - ${entry.data.length} row${entry.data.length === 1 ? "" : "s"}</li>`).join("");
-    document.getElementById("tilemapV2Preview").innerHTML = `<pre>${this.escapeHtml(JSON.stringify({ map: tileMapDocument.map, layers: tileMapDocument.layers.map((entry) => ({ name: entry.name, kind: entry.kind, rows: entry.data.length })) }, null, 2))}</pre>`;
+    document.getElementById("tilemapV2LayerList").replaceChildren();
+    tileMapDocument.layers.forEach((entry) => {
+      const layerItem = document.createElement("li");
+      const layerName = document.createElement("strong");
+      const layerKind = document.createElement("div");
+      layerName.textContent = entry.name.trim();
+      layerKind.textContent = `${entry.kind.trim()} - ${entry.data.length} row${entry.data.length === 1 ? "" : "s"}`;
+      layerItem.append(layerName, layerKind);
+      document.getElementById("tilemapV2LayerList").appendChild(layerItem);
+    });
+    document.getElementById("tilemapV2Preview").replaceChildren();
+    const tilemapPreview = document.createElement("pre");
+    tilemapPreview.textContent = JSON.stringify(
+      {
+        map: tileMapDocument.map,
+        layers: tileMapDocument.layers.map((entry) => ({
+          name: entry.name,
+          kind: entry.kind,
+          rows: entry.data.length
+        }))
+      },
+      null,
+      2
+    );
+    document.getElementById("tilemapV2Preview").appendChild(tilemapPreview);
   }
 
-  renderEmpty(message) {
+  renderMissing(message) {
     document.getElementById("tilemapV2SessionReadout").textContent = "Session: missing";
     document.getElementById("tilemapV2ContractReadout").textContent = "payloadJson.tileMapDocument not loaded";
     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("tilemapV2LayerList").innerHTML = "";
-    document.getElementById("tilemapV2Preview").innerHTML = "";
+    document.getElementById("tilemapV2LayerList").replaceChildren();
+    document.getElementById("tilemapV2Preview").replaceChildren();
   }
 
   renderError(message) {
@@ -97,12 +123,8 @@ class TilemapStudioV2 {
     document.getElementById("tilemapV2Name").textContent = "Tilemap Studio V2 error";
     document.getElementById("tilemapV2Count").textContent = "0 layers";
     document.getElementById("tilemapV2State").textContent = message;
-    document.getElementById("tilemapV2LayerList").innerHTML = "";
-    document.getElementById("tilemapV2Preview").innerHTML = "";
-  }
-
-  escapeHtml(value) {
-    return String(value).replace(/[&<>"]/g, (character) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", "\"": "&quot;" }[character]));
+    document.getElementById("tilemapV2LayerList").replaceChildren();
+    document.getElementById("tilemapV2Preview").replaceChildren();
   }
 }
 

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Complete Asset Browser V2 and harden V2 validation with targeted evidence - PR 11.197B`
	`1`	`+Complete Tilemap Studio V2 with HTML-first shell and session-only behavior - PR 11.198`