Polish tools platform surface with shared shell, registry-driven active tools landing page, and normalized active-tool UX while preserving legacy Sprite Editor خارج the first-class surface.

Author: ToolboxAid

docs/dev/CODEX_COMMANDS.md

@@ -2,45 +2,35 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Create BUILD_PR_TOOLS_REGISTRY_AND_SPRITE_RENAME as a docs-aligned implementation PR.
+Create BUILD_PR_VECTOR_PLATFORM_SURFACE_POLISH as a surgical tools-surface implementation PR.
 
-REPO RULES:
-- Treat tools/ as a first-class product surface.
-- Keep this PR surgical and limited to tool naming, tool registry, generated navigation, and validation.
-- Do not delete preserved legacy content unless absolutely required and explicitly approved.
-- Prefer one canonical source of truth for active tool metadata.
-- Preserve existing behavior except where required for the canonical Sprite Editor path and tool-surface cleanup.
+OBJECTIVE:
+Make the `tools/` folder first-class and visually unified by adding a shared platform shell and registry-driven active tools surface for:
+- Vector Map Editor
+- Vector Asset Studio
+- Tile Map Editor
+- Parallax Editor
 
-TASKS:
-1. Standardize the active sprite tool at tools/Sprite Editor.
-2. Update active references, labels, titles, links, and path usage to Sprite Editor.
-3. Introduce a single source of truth registry for active tools.
-4. Ensure the active tools list/navigation renders from that registry rather than duplicated hardcoded names.
-5. Mark only these as active first-class tools:
-   - Vector Map Editor
-   - Vector Asset Studio
-   - Tile Map Editor
-   - Parallax Editor
-   - Sprite Editor
-6. Ensure legacy-preserved tools do not appear in the active tools list.
-7. Add a lightweight validation check/script that detects:
-   - missing active tool folders
-   - stale sprite-editor rename references
-   - legacy tools appearing in active navigation
-   - disallowed active naming suffixes like V2/V3/new/final/copy
-8. Validate all active tool loading paths after the rename.
+PRESERVE:
+- legacy Sprite Editor under preserved pathing such as `tools/SpritEditor_old_keep/`
+- existing unique editor workspaces per tool
+- current repo boundaries; do not modify engine/game runtime code
 
-OUTPUTS:
-- Repo changes only for this PR scope
-- docs/pr/BUILD_PR_TOOLS_REGISTRY_AND_SPRITE_RENAME.md retained
-- docs/dev/commit_comment.txt updated
-- package final delta zip to:
-  <project folder>/tmp/BUILD_PR_TOOLS_REGISTRY_AND_SPRITE_RENAME_delta.zip
+IMPLEMENT:
+1. Add/update a first-class tools landing surface.
+2. Generate active tool entries from the canonical tool registry.
+3. Add a lightweight shared platform CSS/JS layer for header/nav/status/workspace chrome.
+4. Apply the shared shell to all active tools.
+5. Normalize visible labels/actions across active tools.
+6. Exclude legacy Sprite Editor from active tools surface.
+7. Validate all renamed paths and remove stale references.
 
-COMMIT COMMENT:
-Unify active tools under a first-class tools registry, standardize Sprite Editor at tools/Sprite Editor, generate active tool navigation from a single source of truth, and add validation to prevent naming/path drift.
+GUARDRAILS:
+- no destructive deletes
+- no framework migration
+- no gameplay/runtime engine changes
+- no ad hoc duplicated tool menus in multiple files
+- keep changes small, readable, and reversible
 
-NEXT COMMAND:
-MODEL: GPT-5.4
-REASONING: high
-COMMAND: Create BUILD_PR_VECTOR_PLATFORM_SURFACE_POLISH to standardize tool landing UX, descriptions, icons/labels, and showcase ordering across the active tools registry without changing engine behavior.
+OUTPUT:
+<project folder>/tmp/BUILD_PR_VECTOR_PLATFORM_SURFACE_POLISH.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-Unify active tools under a first-class tools registry, standardize Sprite Editor at tools/Sprite Editor, generate active tool navigation from a single source of truth, and add validation to prevent naming/path drift.
+Polish tools platform surface with a shared shell, registry-driven active-tool navigation, and unified first-class labels while preserving Sprite Editor outside the active surface.

docs/dev/reports/change_summary.txt

@@ -1,26 +1,17 @@
-BUILD_PR_TOOLS_REGISTRY_AND_SPRITE_RENAME
------------------------------------------
+BUILD PR bundle prepared for vector platform surface polish.
 
-Implemented changes
-- standardized the canonical active sprite tool folder at `tools/Sprite Editor/`
-- updated the sprite tool title and heading to the canonical `Sprite Editor` name
-- introduced `tools/toolRegistry.js` as the single source of truth for active tool metadata
-- introduced `tools/renderToolsIndex.js` so the tools hub renders the active tools list from the registry
-- updated `tools/index.html` to use generated active tool cards instead of hardcoded tool names
-- added `scripts/validate-active-tools-surface.mjs` to detect folder/path/name drift
+Planned implementation summary:
+- establish `tools/` as a first-class product surface
+- add a shared platform shell for active tools
+- drive active tool menus/listings from one canonical registry
+- normalize naming, labels, and common actions across active tools
+- preserve legacy Sprite Editor outside the active tools surface
+- validate rename/path integrity and remove stale references
 
-Approved visible active tools
-- `Vector Map Editor`
-- `Vector Asset Studio`
-- `Tile Map Editor`
-- `Parallax Editor`
-- `Sprite Editor`
-
-Legacy handling
-- `tools/SpriteEditor_old_keep/` remains preserved on disk
-- legacy tools are excluded from the active tools list by registry metadata and validation
-
-Validation
-- active tool entry paths were checked after the rename
-- stale sprite-editor rename references are checked in canonical hub/build-report surfaces
-- disallowed active naming suffixes are checked by validation script
+Included bundle artifacts:
+- PR spec
+- Codex command
+- commit comment
+- change summary
+- validation checklist
+- file tree

docs/dev/reports/file_tree.txt

@@ -1,18 +1,11 @@
-tools/
-  index.html
-  renderToolsIndex.js
-  toolRegistry.js
-  Sprite Editor/
-    index.html
-    README.md
-scripts/
-  validate-active-tools-surface.mjs
-docs/
-  pr/
-    BUILD_PR_TOOLS_REGISTRY_AND_SPRITE_RENAME.md
-  dev/
-    commit_comment.txt
-    reports/
-      change_summary.txt
-      file_tree.txt
-      validation_checklist.txt
+BUILD_PR_VECTOR_PLATFORM_SURFACE_POLISH/
+  docs/
+    pr/
+      BUILD_PR_VECTOR_PLATFORM_SURFACE_POLISH.md
+    dev/
+      codex_commands.md
+      commit_comment.txt
+      reports/
+        change_summary.txt
+        validation_checklist.txt
+        file_tree.txt

docs/dev/reports/validation_checklist.txt

@@ -1,13 +1,15 @@
-[x] canonical sprite tool folder is tools/Sprite Editor
-[x] no canonical stale sprite-editor rename references remain in the validated active tool surface
-[x] active tools registry exists and is the single source of truth
-[x] generated active tools list comes from registry
-[x] active tools list contains only approved first-class tools
-[x] Vector Map Editor listed
-[x] Vector Asset Studio listed
-[x] Tile Map Editor listed
-[x] Parallax Editor listed
-[x] Sprite Editor listed
-[x] legacy-preserved tools excluded from active tools list
-[x] validation detects stale references and naming drift
-[x] active tool paths load correctly after rename
+[ ] Tools landing page exists and is clearly first-class
+[ ] Active tools list is generated from canonical registry
+[ ] Only approved active tools appear on landing page
+[ ] Legacy Sprite Editor does not appear in active tools menu
+[ ] Vector Map Editor uses shared platform shell
+[ ] Vector Asset Studio uses shared platform shell
+[ ] Tile Map Editor uses shared platform shell
+[ ] Parallax Editor uses shared platform shell
+[ ] Current tool title matches canonical naming in every active tool
+[ ] Home/back-to-tools affordance works in every active tool
+[ ] Common actions use normalized wording
+[ ] No visible references to `Sprite Editor V3`
+[ ] No broken asset/script/style paths introduced
+[ ] No engine/game runtime files modified
+[ ] Legacy preserved folder remains intact

docs/pr/BUILD_PR_VECTOR_PLATFORM_SURFACE_POLISH.md

@@ -0,0 +1,83 @@
+# BUILD_PR_VECTOR_PLATFORM_SURFACE_POLISH
+
+## Purpose
+Polish the `tools/` product surface with one shared shell layer and a registry-driven active tools landing experience for the approved first-class tool set only.
+
+## Scope
+In scope:
+- shared platform shell for active tools
+- registry-driven active tool landing and navigation
+- consistent first-class labels for the active tools surface
+- active path cleanup and validation
+
+Out of scope:
+- gameplay or engine runtime changes
+- destructive folder deletes
+- framework migration
+- broad refactors outside tool-surface polish
+- reviving legacy Sprite Editor as a first-class tool
+
+## First-Class Active Tools
+- Vector Map Editor
+- Vector Asset Studio
+- Tile Map Editor
+- Parallax Editor
+
+## Preserved Sprite Paths
+- `tools/Sprite Editor/` remains on disk but is intentionally excluded from the first-class active tools surface for this PR
+- `tools/SpriteEditor_old_keep/` remains preserved on disk as legacy content
+- no preserved sprite path is rendered in the active landing page or shared shell navigation
+
+## Modules Created Or Changed
+- `tools/toolRegistry.js`
+- `tools/renderToolsIndex.js`
+- `tools/index.html`
+- `tools/shared/platformShell.css`
+- `tools/shared/platformShell.js`
+- `tools/Vector Asset Studio/index.html`
+- `tools/Tilemap Studio/index.html`
+- `tools/Parallax Scene Studio/index.html`
+- `tools/Vector Map Editor/index.html`
+- `scripts/validate-active-tools-surface.mjs`
+- `docs/pr/BUILD_PR_VECTOR_PLATFORM_SURFACE_POLISH.md`
+- `docs/dev/commit_comment.txt`
+
+## Public Surface Boundaries
+- `tools/toolRegistry.js` is the single source of truth for active-tool metadata
+- `tools/renderToolsIndex.js` renders the landing-page cards from the registry
+- `tools/shared/platformShell.js` renders shared header, nav, and status chrome from the registry
+- `tools/shared/platformShell.css` provides shared shell framing without replacing tool-specific workspace CSS
+- existing tool workspaces remain mounted inside each tool's current editor shell
+
+## Implementation Summary
+- narrowed the first-class tools surface to the four requested tools only
+- added a shared platform shell with a consistent header, nav, and status band
+- applied the shared shell to the landing page and all four active tool pages
+- normalized the visible first-class labels to `Tile Map Editor` and `Parallax Editor` through the shared registry surface
+- excluded preserved sprite tooling from the active landing page and shared nav
+- kept the underlying tool folders and editor workspaces intact
+
+## Validation Performed
+- `node --check tools/toolRegistry.js`
+- `node --check tools/renderToolsIndex.js`
+- `node --check tools/shared/platformShell.js`
+- `node --check scripts/validate-active-tools-surface.mjs`
+- `node --check tools/Vector Asset Studio/main.js`
+- `node --check tools/Tilemap Studio/main.js`
+- `node --check tools/Parallax Scene Studio/main.js`
+- `node --check tools/Vector Map Editor/main.js`
+- `node scripts/validate-active-tools-surface.mjs`
+
+## Validation Summary
+- the landing page active tools list is registry-driven
+- only the approved four tools appear in the first-class active surface
+- preserved sprite tooling does not appear in active navigation
+- shared shell chrome is available on the landing page and each active tool page
+- active tool folders and entrypoints resolve cleanly
+- stale deprecated sprite-rename references are rejected by the validation script
+- disallowed active naming suffixes remain blocked for first-class tools
+
+## Follow-Up Recommendations
+- keep future landing-page or active-nav changes routed through the registry instead of hardcoded page lists
+- if canonical folder names change later, update the registry and validator in the same PR
+- keep future surface polish additive through the shared shell layer

scripts/validate-active-tools-surface.mjs

@@ -2,8 +2,10 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import {
+  ACTIVE_TOOL_SURFACE_IDS,
   TOOL_NAME_SUFFIX_PATTERN,
   getToolRegistry,
+  getToolById,
   getVisibleActiveToolRegistry
 } from "../tools/toolRegistry.js";
 
@@ -15,17 +17,15 @@ const REQUIRED_ACTIVE_TOOL_NAMES = [
   "Vector Map Editor",
   "Vector Asset Studio",
   "Tile Map Editor",
-  "Parallax Editor",
-  "Sprite Editor"
+  "Parallax Editor"
 ];
 
 const SCAN_TARGETS = [
   "tools/index.html",
   "tools/renderToolsIndex.js",
-  "docs/pr/BUILD_PR_TOOLS_REGISTRY_AND_SPRITE_RENAME.md",
-  "docs/dev/reports/validation_checklist.txt",
-  "docs/dev/reports/change_summary.txt",
-  "docs/dev/reports/file_tree.txt",
+  "tools/shared/platformShell.js",
+  "tools/shared/platformShell.css",
+  "docs/pr/BUILD_PR_VECTOR_PLATFORM_SURFACE_POLISH.md",
   "docs/dev/commit_comment.txt"
 ];
 
@@ -52,11 +52,16 @@ async function main() {
   const toolRegistry = getToolRegistry();
   const visibleActiveTools = getVisibleActiveToolRegistry();
   const activeNames = visibleActiveTools.map((tool) => tool.displayName);
+  const activeIds = visibleActiveTools.map((tool) => tool.id);
 
   if (JSON.stringify(activeNames) !== JSON.stringify(REQUIRED_ACTIVE_TOOL_NAMES)) {
     issues.push(`Active tool names do not match the approved list. Found: ${activeNames.join(", ")}`);
   }
 
+  if (JSON.stringify(activeIds) !== JSON.stringify(ACTIVE_TOOL_SURFACE_IDS)) {
+    issues.push(`Active tool ids do not match the approved registry surface. Found: ${activeIds.join(", ")}`);
+  }
+
   for (const tool of visibleActiveTools) {
     const folderPath = path.join(repoRoot, "tools", tool.folderName);
     const entryPointPath = path.join(repoRoot, "tools", tool.entryPoint);
@@ -76,6 +81,11 @@ async function main() {
     issues.push(`Legacy tools appear in active navigation: ${visibleLegacyTools.map((tool) => tool.displayName).join(", ")}`);
   }
 
+  const preservedSpriteTool = getToolById("sprite-editor");
+  if (preservedSpriteTool?.visibleInToolsList === true || preservedSpriteTool?.status === "active") {
+    issues.push("Sprite Editor is still marked as a first-class active tool.");
+  }
+
   for (const target of SCAN_TARGETS) {
     const text = await readText(target);
     if (/Sprite Editor V3|tools\/Sprite Editor V3|tools\\Sprite Editor V3/.test(text)) {
@@ -85,7 +95,7 @@ async function main() {
 
   for (const target of NAVIGATION_SURFACE_TARGETS) {
     const text = await readText(target);
-    if (/SpriteEditor_old_keep/.test(text)) {
+    if (/SpriteEditor_old_keep|Sprite Editor Legacy|Sprite Editor/.test(text)) {
       issues.push(`Legacy tool appears in active navigation/report surface: ${target}`);
     }
   }

tools/Parallax Scene Studio/index.html

@@ -9,11 +9,13 @@
 <head>
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Parallax Scene Studio</title>
+  <title>Tools Platform</title>
   <link rel="stylesheet" href="../../engine/ui/hubCommon.css" />
+  <link rel="stylesheet" href="../shared/platformShell.css" />
   <link rel="stylesheet" href="./parallaxEditor.css" />
 </head>
-<body class="parallax-editor-page">
+<body class="parallax-editor-page" data-tool-id="parallax-editor" data-tools-platform-page="tool">
+  <div data-tools-platform-header></div>
   <div class="app-shell">
     <header class="toolbar">
       <div class="toolbar-group">
@@ -225,6 +227,8 @@ <h3>Remediation</h3>
     </div>
   </div>
 
+  <div data-tools-platform-status></div>
+  <script type="module" src="../shared/platformShell.js"></script>
   <script type="module" src="./main.js"></script>
 </body>
 </html>

tools/Tilemap Studio/index.html

@@ -9,11 +9,13 @@
 <head>
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Tilemap Studio</title>
+  <title>Tools Platform</title>
   <link rel="stylesheet" href="../../engine/ui/hubCommon.css" />
+  <link rel="stylesheet" href="../shared/platformShell.css" />
   <link rel="stylesheet" href="./tileMapEditor.css" />
 </head>
-<body class="tile-map-editor-page">
+<body class="tile-map-editor-page" data-tool-id="tile-map-editor" data-tools-platform-page="tool">
+  <div data-tools-platform-header></div>
   <div class="app-shell" id="appShell">
     <header class="toolbar">
       <div class="toolbar-group">
@@ -203,6 +205,8 @@ <h3>Remediation</h3>
     </div>
   </div>
 
+  <div data-tools-platform-status></div>
+  <script type="module" src="../shared/platformShell.js"></script>
   <script type="module" src="./main.js"></script>
 </body>
 </html>