Close the final remaining Tools lane residue

DavidQ · DavidQ · commit e749f0dcc7af · 2026-04-14T21:30:13.000-04:00
BUILD_PR_LEVEL_09_TOOLS_RESIDUE_ONLY
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -2,49 +2,26 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Create `BUILD_PR_LEVEL_09_TOOLS_NORMALIZATION_AND_REQUIRED_TOOLS_COMBINED_PASS` as one combined Tools-lane PR.
+Create `BUILD_PR_LEVEL_09_TOOLS_RESIDUE_ONLY` as the final residue-only PR for the Tools lane.
 
 Goal:
-Finish as much of the remaining tool normalization and dependency-driven required tool work as truthfully possible in one pass.
-
-Target items to close in this PR if supported:
-
-Existing Tools
-- TileMapEditor normalized
-- ParallaxEditor normalized
-- VectorMapEditor normalized
-- VectorAssetStudio normalized
-
-New Required Tools
-- PhysicsSandboxTool
-- StateInspectorTool
-- ReplayVisualizerTool
-- PerformanceProfilerTool
-- AssetPipelineTool
-- Tile/Model Converter Tool
+Close only the remaining residue left after:
+`BUILD_PR_LEVEL_09_TOOLS_NORMALIZATION_AND_REQUIRED_TOOLS_COMBINED_PASS`
 
 Required work:
-1. Treat the four existing tools as one normalization cluster.
-2. Normalize their shared shell, placement, boundaries, and data-contract consistency.
-3. Treat the required tools as one dependency-driven stabilization cluster.
-4. Close as many partial or open items as truthfully possible without speculative overbuilding.
-5. Reuse existing repo patterns and tool infrastructure instead of creating disconnected one-offs.
-6. Close as many remaining tool items as truthfully possible in this one PR.
-7. If anything remains open:
-   - keep the residue very small
-   - report exact blockers
-   - leave it suitable for one residue-only PR
-
-Roadmap:
-- update status markers only
-- do NOT rewrite roadmap text
+1. Inspect the results of the prior combined tools pass.
+2. Identify only the tool items that still remain open.
+3. Make the smallest valid changes needed to close those remaining items.
+4. Do NOT reopen or rework tool items already completed.
+5. Do NOT expand scope beyond the actual residue.
+6. Update roadmap status markers only.
+7. Report whether the Tools lane is now fully complete.
 
 Final packaging step is REQUIRED:
 - package ALL changed files into this exact repo-structured ZIP:
-  `<project folder>/tmp/BUILD_PR_LEVEL_09_TOOLS_NORMALIZATION_AND_REQUIRED_TOOLS_COMBINED_PASS.zip`
+  `<project folder>/tmp/BUILD_PR_LEVEL_09_TOOLS_RESIDUE_ONLY.zip`
 
 Hard rules:
-- combine aggressively to reduce PR count
-- keep the changes coherent
+- residue-only closeout
 - no unrelated repo changes
 - no missing ZIP
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1,2 +1,2 @@
-Combine tool normalization and required-tool stabilization into one low-PR pass
-BUILD_PR_LEVEL_09_TOOLS_NORMALIZATION_AND_REQUIRED_TOOLS_COMBINED_PASS
+Close the final remaining Tools lane residue
+BUILD_PR_LEVEL_09_TOOLS_RESIDUE_ONLY
diff --git a/docs/dev/NEXT_COMMAND.txt b/docs/dev/NEXT_COMMAND.txt
@@ -1 +1 @@
-BUILD_PR_LEVEL_09_TOOLS_RESIDUE_ONLY
+NEXT_PR_TBD
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1,3 +1,3 @@
-- Added a combined PR for the remaining Tools lane
-- Bundles existing-tool normalization with dependency-driven required-tool stabilization
-- Intended to finish most or all of the Tools lane in one pass and leave only tiny residue if needed
+- Added residue-only follow-up PR for the Tools lane
+- Intended to close whatever remains after the combined tools pass
+- Limits work to the smallest valid closeout only
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,14 +1,6 @@
-- TileMapEditor addressed
-- ParallaxEditor addressed
-- VectorMapEditor addressed
-- VectorAssetStudio addressed
-- PhysicsSandboxTool addressed
-- StateInspectorTool addressed
-- ReplayVisualizerTool addressed
-- PerformanceProfilerTool addressed
-- AssetPipelineTool addressed
-- Tile/Model Converter Tool addressed
-- any residue is explicit and minimal
+- only remaining open tool items were touched
+- no already-complete tool items were reopened
 - roadmap updated by status markers only
+- Tools lane is either fully complete or exact blockers are reported
 - output ZIP created at:
-  <project folder>/tmp/BUILD_PR_LEVEL_09_TOOLS_NORMALIZATION_AND_REQUIRED_TOOLS_COMBINED_PASS.zip
+  <project folder>/tmp/BUILD_PR_LEVEL_09_TOOLS_RESIDUE_ONLY.zip
diff --git a/docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md b/docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md
@@ -442,9 +442,9 @@
 - [x] VectorAssetStudio normalized
 
 ### New Required Tools (By Dependency)
-- [ ] 3DMapEditor
-- [ ] 3DAssetViewer
-- [ ] 3DCameraPathEditor
+- [x] 3DMapEditor
+- [x] 3DAssetViewer
+- [x] 3DCameraPathEditor
 - [x] PhysicsSandboxTool
 - [x] StateInspectorTool
 - [x] ReplayVisualizerTool
diff --git a/docs/pr/BUILD_PR_LEVEL_09_TOOLS_RESIDUE_ONLY.md b/docs/pr/BUILD_PR_LEVEL_09_TOOLS_RESIDUE_ONLY.md
@@ -0,0 +1,56 @@
+# BUILD_PR_LEVEL_09_TOOLS_RESIDUE_ONLY
+
+## Purpose
+Close only the remaining residue from `BUILD_PR_LEVEL_09_TOOLS_NORMALIZATION_AND_REQUIRED_TOOLS_COMBINED_PASS` in the Tools lane.
+
+## Residue Identified
+Open required-tool items after the prior combined pass:
+- `3DMapEditor`
+- `3DAssetViewer`
+- `3DCameraPathEditor`
+
+## Implemented Changes
+
+### New first-class tools
+- `tools/3D Map Editor/`
+- `tools/3D Asset Viewer/`
+- `tools/3D Camera Path Editor/`
+
+Each tool includes:
+- `index.html` with shared shell contract (`data-tool-id`, `platformShell.js`)
+- `main.js` with `registerToolBootContract(...)`
+- minimal deterministic baseline behavior (normalize/inspect/edit flows)
+
+### Registry + validation updates
+- Added all three tools to `tools/toolRegistry.js`
+- Extended launch-contract validation:
+  - `tests/tools/ToolEntryLaunchContract.test.mjs`
+- Extended boundary enforcement validation:
+  - `tests/tools/ToolBoundaryEnforcement.test.mjs`
+- Extended required-tools baseline validation:
+  - `tests/tools/RequiredToolsBaseline.test.mjs`
+
+### Roadmap status updates
+- Updated status markers only for:
+  - `3DMapEditor`
+  - `3DAssetViewer`
+  - `3DCameraPathEditor`
+
+No roadmap prose was rewritten.
+
+## Focused Validation
+- `node --check` on touched JS files
+- `tests/tools/ToolBoundaryEnforcement.test.mjs`
+- `tests/tools/ToolEntryLaunchContract.test.mjs`
+- `tests/tools/RequiredToolsBaseline.test.mjs`
+
+## Tools Lane Completion Status
+Required tool residue from the prior combined pass is now closed.
+
+Section 9 still contains separate open strategy/shell-note markers not changed in this residue-only PR:
+- `2D tool stabilization before 3D tool expansion`
+- `3D prerequisite samples before advanced 3D tools`
+- `no standalone showcase-only tool tracks`
+- `tools header accordion...`
+- `tool-shell UI compaction...`
+- `follow-up tool UI cleanup...`
diff --git a/tests/tools/RequiredToolsBaseline.test.mjs b/tests/tools/RequiredToolsBaseline.test.mjs
@@ -12,7 +12,10 @@ const REQUIRED_TOOLS = Object.freeze([
   { id: "replay-visualizer", folder: "Replay Visualizer" },
   { id: "performance-profiler", folder: "Performance Profiler" },
   { id: "asset-pipeline-tool", folder: "Asset Pipeline Tool" },
-  { id: "tile-model-converter", folder: "Tile Model Converter" }
+  { id: "tile-model-converter", folder: "Tile Model Converter" },
+  { id: "3d-map-editor", folder: "3D Map Editor" },
+  { id: "3d-asset-viewer", folder: "3D Asset Viewer" },
+  { id: "3d-camera-path-editor", folder: "3D Camera Path Editor" }
 ]);
 
 export async function run() {
diff --git a/tests/tools/ToolBoundaryEnforcement.test.mjs b/tests/tools/ToolBoundaryEnforcement.test.mjs
@@ -15,7 +15,10 @@ const ACTIVE_TOOL_FOLDERS = Object.freeze([
   "Performance Profiler",
   "Physics Sandbox",
   "Asset Pipeline Tool",
-  "Tile Model Converter"
+  "Tile Model Converter",
+  "3D Map Editor",
+  "3D Asset Viewer",
+  "3D Camera Path Editor"
 ]);
 
 function listScriptFiles(directoryPath) {
diff --git a/tests/tools/ToolEntryLaunchContract.test.mjs b/tests/tools/ToolEntryLaunchContract.test.mjs
@@ -18,7 +18,10 @@ const FIRST_CLASS_TOOL_INDEXES = Object.freeze([
   { toolId: "performance-profiler", indexPath: "../../tools/Performance Profiler/index.html" },
   { toolId: "physics-sandbox", indexPath: "../../tools/Physics Sandbox/index.html" },
   { toolId: "asset-pipeline-tool", indexPath: "../../tools/Asset Pipeline Tool/index.html" },
-  { toolId: "tile-model-converter", indexPath: "../../tools/Tile Model Converter/index.html" }
+  { toolId: "tile-model-converter", indexPath: "../../tools/Tile Model Converter/index.html" },
+  { toolId: "3d-map-editor", indexPath: "../../tools/3D Map Editor/index.html" },
+  { toolId: "3d-asset-viewer", indexPath: "../../tools/3D Asset Viewer/index.html" },
+  { toolId: "3d-camera-path-editor", indexPath: "../../tools/3D Camera Path Editor/index.html" }
 ]);
 
 export async function run() {
diff --git a/tools/3D Asset Viewer/index.html b/tools/3D Asset Viewer/index.html
@@ -0,0 +1,38 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>3D Asset Viewer</title>
+  <link rel="stylesheet" href="../../src/engine/ui/hubCommon.css" />
+  <link rel="stylesheet" href="../shared/platformShell.css" />
+  <link rel="stylesheet" href="../shared/debugInspectorTools.css" />
+</head>
+<body class="tools-platform-tool-page" data-tool-id="3d-asset-viewer" data-tools-platform-page="tool">
+  <div data-tools-platform-header></div>
+  <div class="debug-tool-shell app-shell">
+    <section class="panel debug-tool-panel">
+      <h2>3D Asset Viewer</h2>
+      <p>Inspect baseline 3D asset payload metadata, vertex counts, and computed bounds.</p>
+      <div class="debug-tool-actions">
+        <button type="button" id="inspect3dAssetButton">Inspect Asset</button>
+      </div>
+      <div id="asset3dStatus" class="debug-tool-meta">3D asset viewer ready.</div>
+    </section>
+
+    <section class="debug-tool-grid">
+      <section class="panel debug-tool-panel">
+        <h3>Asset Input</h3>
+        <textarea id="asset3dInput" rows="16"></textarea>
+      </section>
+      <section class="panel debug-tool-panel">
+        <h3>Asset Inspection</h3>
+        <pre id="asset3dOutput" class="debug-tool-readout">Inspect an asset payload to see normalized summary output.</pre>
+      </section>
+    </section>
+  </div>
+  <div data-tools-platform-status></div>
+  <script type="module" src="../shared/platformShell.js"></script>
+  <script type="module" src="./main.js"></script>
+</body>
+</html>
diff --git a/tools/3D Asset Viewer/main.js b/tools/3D Asset Viewer/main.js
@@ -0,0 +1,117 @@
+import { safeParseJson, toPrettyJson } from "../shared/debugInspectorData.js";
+import { registerToolBootContract } from "../shared/toolBootContract.js";
+
+const refs = {
+  inspectButton: document.getElementById("inspect3dAssetButton"),
+  statusText: document.getElementById("asset3dStatus"),
+  input: document.getElementById("asset3dInput"),
+  output: document.getElementById("asset3dOutput")
+};
+
+function setStatus(message) {
+  if (refs.statusText instanceof HTMLElement) {
+    refs.statusText.textContent = message;
+  }
+}
+
+function sanitizeNumber(value) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : 0;
+}
+
+function computeBounds(vertices) {
+  if (!Array.isArray(vertices) || vertices.length === 0) {
+    return null;
+  }
+  let minX = Infinity;
+  let minY = Infinity;
+  let minZ = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  let maxZ = -Infinity;
+
+  vertices.forEach((vertex) => {
+    const x = sanitizeNumber(vertex?.x);
+    const y = sanitizeNumber(vertex?.y);
+    const z = sanitizeNumber(vertex?.z);
+    minX = Math.min(minX, x);
+    minY = Math.min(minY, y);
+    minZ = Math.min(minZ, z);
+    maxX = Math.max(maxX, x);
+    maxY = Math.max(maxY, y);
+    maxZ = Math.max(maxZ, z);
+  });
+
+  return {
+    min: { x: minX, y: minY, z: minZ },
+    max: { x: maxX, y: maxY, z: maxZ },
+    size: { x: maxX - minX, y: maxY - minY, z: maxZ - minZ }
+  };
+}
+
+function buildDefaultPayload() {
+  return {
+    schema: "tools.3d-asset-viewer.asset/1",
+    assetId: "ship-hull",
+    vertices: [
+      { x: -1, y: -0.5, z: -2 },
+      { x: 1, y: -0.5, z: -2 },
+      { x: 0, y: 0.75, z: 2 }
+    ],
+    metadata: {
+      sourceToolId: "vector-asset-studio"
+    }
+  };
+}
+
+function inspectAssetPayload() {
+  if (!(refs.input instanceof HTMLTextAreaElement)) {
+    return;
+  }
+  const parsed = safeParseJson(refs.input.value);
+  if (!parsed || typeof parsed !== "object") {
+    setStatus("Input JSON is invalid. Provide an asset object.");
+    return;
+  }
+
+  const vertices = Array.isArray(parsed.vertices) ? parsed.vertices : [];
+  const bounds = computeBounds(vertices);
+  const report = {
+    schema: "tools.3d-asset-viewer.report/1",
+    assetId: typeof parsed.assetId === "string" && parsed.assetId.trim() ? parsed.assetId.trim() : "asset-3d",
+    vertexCount: vertices.length,
+    bounds,
+    metadata: parsed.metadata && typeof parsed.metadata === "object" ? { ...parsed.metadata } : {}
+  };
+
+  if (refs.output instanceof HTMLElement) {
+    refs.output.textContent = toPrettyJson(report);
+  }
+  setStatus(`Inspection complete. vertices=${report.vertexCount}.`);
+}
+
+function boot3dAssetViewer() {
+  if (refs.inspectButton instanceof HTMLButtonElement) {
+    refs.inspectButton.addEventListener("click", inspectAssetPayload);
+  }
+  if (refs.input instanceof HTMLTextAreaElement && !refs.input.value.trim()) {
+    refs.input.value = toPrettyJson(buildDefaultPayload());
+  }
+  return {
+    inspect: inspectAssetPayload
+  };
+}
+
+registerToolBootContract("3d-asset-viewer", {
+  init: boot3dAssetViewer,
+  destroy() {
+    return true;
+  },
+  getApi() {
+    return {
+      inspect: inspectAssetPayload
+    };
+  }
+});
+
+boot3dAssetViewer();
diff --git a/tools/3D Camera Path Editor/index.html b/tools/3D Camera Path Editor/index.html
@@ -0,0 +1,39 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>3D Camera Path Editor</title>
+  <link rel="stylesheet" href="../../src/engine/ui/hubCommon.css" />
+  <link rel="stylesheet" href="../shared/platformShell.css" />
+  <link rel="stylesheet" href="../shared/debugInspectorTools.css" />
+</head>
+<body class="tools-platform-tool-page" data-tool-id="3d-camera-path-editor" data-tools-platform-page="tool">
+  <div data-tools-platform-header></div>
+  <div class="debug-tool-shell app-shell">
+    <section class="panel debug-tool-panel">
+      <h2>3D Camera Path Editor</h2>
+      <p>Edit camera waypoints and export a normalized deterministic path payload.</p>
+      <div class="debug-tool-actions">
+        <button type="button" id="addCameraPointButton">Add Waypoint</button>
+        <button type="button" id="normalizeCameraPathButton">Normalize Path</button>
+      </div>
+      <div id="cameraPathStatus" class="debug-tool-meta">3D camera path editor ready.</div>
+    </section>
+
+    <section class="debug-tool-grid">
+      <section class="panel debug-tool-panel">
+        <h3>Path Input</h3>
+        <textarea id="cameraPathInput" rows="16"></textarea>
+      </section>
+      <section class="panel debug-tool-panel">
+        <h3>Path Output</h3>
+        <pre id="cameraPathOutput" class="debug-tool-readout">Normalize a path to inspect waypoint output.</pre>
+      </section>
+    </section>
+  </div>
+  <div data-tools-platform-status></div>
+  <script type="module" src="../shared/platformShell.js"></script>
+  <script type="module" src="./main.js"></script>
+</body>
+</html>
diff --git a/tools/3D Camera Path Editor/main.js b/tools/3D Camera Path Editor/main.js
diff --git a/tools/3D Map Editor/index.html b/tools/3D Map Editor/index.html
diff --git a/tools/3D Map Editor/main.js b/tools/3D Map Editor/main.js
diff --git a/tools/toolRegistry.js b/tools/toolRegistry.js

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-BUILD_PR_LEVEL_09_TOOLS_RESIDUE_ONLY`
	`1`	`+NEXT_PR_TBD`