docs: add BUILD_PR phase 2 shared extraction bundle

DavidQ · DavidQ · commit 827e543f985e · 2026-04-11T19:19:38.000-04:00
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -2,30 +2,19 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Create BUILD_PR_TOOLS_SHARED_EXTRACTION_PHASE_1 as a conservative exact-cluster implementation.
+Create BUILD_PR_TOOLS_SHARED_EXTRACTION_PHASE_2
 
 Scope:
-- active tools only
-- reuse existing tools/shared modules first
-- target only:
-  - project system helper normalization
-  - runtime asset loader helper normalization
-  - runtime asset validation helper normalization
-  - safe vector helper normalization already represented in tools/shared/vector/*
-- no style/theme work in this PR
+- extract shared event + command helpers
+- extract safe UI utilities
+- reuse tools/shared first
+- minimal changes
+- no theme work
 - no editor-state extraction
-- no render-pipeline rewrites
-- no tool-host work
-- preserve tools/SpriteEditor_old_keep
-- keep changed-file count minimal
-- stop and report if helper semantics diverge too much
 
 Validation:
 - npm run test:launch-smoke -- --tools
-- report exact files changed
-- report extracted vs normalized helpers
-- report helpers intentionally left local and why
+- report files changed
 
 Output:
-- package repo-structured delta ZIP under <project folder>/tmp/
-- use docs/dev/reports for validation/report files
+<project>/tmp/BUILD_PR_TOOLS_SHARED_EXTRACTION_PHASE_2_delta.zip
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1 +1 @@
-docs: add BUILD_PR bundle for conservative tools/shared extraction phase 1
+docs: add BUILD_PR phase 2 shared extraction bundle
diff --git a/docs/dev/reports/BUILD_PR_TOOLS_SHARED_EXTRACTION_PHASE_2_changes.md b/docs/dev/reports/BUILD_PR_TOOLS_SHARED_EXTRACTION_PHASE_2_changes.md
@@ -0,0 +1,30 @@
+# BUILD_PR_TOOLS_SHARED_EXTRACTION_PHASE_2 - Changes Report
+
+Date: 2026-04-11
+
+## Files Changed
+- docs/pr/BUILD_PR_TOOLS_SHARED_EXTRACTION_PHASE_2.md
+- tools/shared/eventCommandUtils.js
+- tools/shared/uiSafeUtils.js
+- tools/shared/platformShell.js
+- docs/dev/reports/BUILD_PR_TOOLS_SHARED_EXTRACTION_PHASE_2_validation.md
+- docs/dev/reports/BUILD_PR_TOOLS_SHARED_EXTRACTION_PHASE_2_changes.md
+- docs/dev/reports/launch_smoke_report.md
+
+## Extraction Summary
+- Added shared event/command helper module:
+  - `sanitizeCommand`
+  - `createCommandDispatcher`
+  - `bindEventHandlers`
+- Added shared safe UI helper module:
+  - `queryFirst`
+  - `queryAll`
+  - `readDataAttribute`
+  - `asHtmlInput`
+  - `setTextContent`
+- Normalized `tools/shared/platformShell.js` to use new shared helpers with equivalent behavior.
+
+## Scope Compliance
+- No theme/style changes.
+- No editor-state extraction.
+- Minimal file count and behavior-preserving refactor.
diff --git a/docs/dev/reports/BUILD_PR_TOOLS_SHARED_EXTRACTION_PHASE_2_validation.md b/docs/dev/reports/BUILD_PR_TOOLS_SHARED_EXTRACTION_PHASE_2_validation.md
@@ -0,0 +1,22 @@
+# BUILD_PR_TOOLS_SHARED_EXTRACTION_PHASE_2 - Validation Report
+
+Date: 2026-04-11
+Branch: main
+
+## Command
+- `npm run test:launch-smoke -- --tools`
+
+## Result
+- PASS Asset Browser
+- PASS Palette Browser
+- PASS Parallax Scene Studio
+- PASS Sprite Editor
+- PASS SpriteEditor_old_keep
+- PASS Tilemap Studio
+- PASS Vector Asset Studio
+- PASS Vector Map Editor
+- Summary: PASS=8 FAIL=0 TOTAL=8
+
+## Notes
+- Launch smoke report refreshed at `docs/dev/reports/launch_smoke_report.md`.
+- Scope remained limited to shared event/command and UI utility extraction in `tools/shared`.
diff --git a/docs/dev/reports/boot_contract_targets.txt b/docs/dev/reports/boot_contract_targets.txt
@@ -0,0 +1,10 @@
+BOOT CONTRACT TARGETS
+
+- init(container, config)
+- destroy()
+
+Optional:
+- loadProject()
+- saveProject()
+
+Ensure consistent signature across tools
diff --git a/docs/dev/reports/launch_smoke_report.md b/docs/dev/reports/launch_smoke_report.md
@@ -1,6 +1,6 @@
 # Launch Smoke Report
 
-Generated: 2026-04-11T23:13:05.760Z
+Generated: 2026-04-11T23:18:02.796Z
 
 Filters: games=false, samples=false, tools=true, sampleRange=all
 
diff --git a/docs/dev/reports/tools_shared_phase2_targets.txt b/docs/dev/reports/tools_shared_phase2_targets.txt
@@ -0,0 +1,9 @@
+PHASE 2 TARGETS
+
+1. event helpers
+2. command helpers
+3. lightweight UI utilities
+
+Only extract if:
+- used in multiple tools
+- no editor-specific coupling
diff --git a/docs/pr/BUILD_PR_TOOLS_BOOT_CONTRACT_NORMALIZATION.md b/docs/pr/BUILD_PR_TOOLS_BOOT_CONTRACT_NORMALIZATION.md
@@ -0,0 +1,23 @@
+# BUILD_PR_TOOLS_BOOT_CONTRACT_NORMALIZATION
+
+## Purpose
+Standardize how tools boot, initialize, and expose capabilities so they can be hosted consistently.
+
+## Goals
+- consistent init signature
+- predictable lifecycle hooks
+- no UI/theme changes
+
+## Scope
+- tool entry points
+- init/bootstrap logic
+- lightweight adapters
+
+## Out of Scope
+- rendering logic
+- editor state
+- styling
+
+## Validation
+- npm run test:launch-smoke -- --tools
+- all tools still launch
diff --git a/docs/pr/BUILD_PR_TOOLS_SHARED_EXTRACTION_PHASE_2.md b/docs/pr/BUILD_PR_TOOLS_SHARED_EXTRACTION_PHASE_2.md
@@ -0,0 +1,25 @@
+# BUILD_PR_TOOLS_SHARED_EXTRACTION_PHASE_2
+
+## PR Purpose
+Extract and normalize shared event/command helpers plus safe UI utilities with minimal changes and reuse of `tools/shared` first.
+
+## Scope
+- Extract shared event + command helpers.
+- Extract safe UI utilities.
+- Reuse `tools/shared/*` before introducing new local helpers.
+- Minimal changes only.
+- No theme work.
+- No editor-state extraction.
+
+## Exact Target Files
+- `tools/shared/platformShell.js`
+- `tools/shared/eventCommandUtils.js`
+- `tools/shared/uiSafeUtils.js`
+
+## Validation
+- Run: `npm run test:launch-smoke -- --tools`
+- Report files changed.
+
+## Required Output
+- ZIP: `tmp/BUILD_PR_TOOLS_SHARED_EXTRACTION_PHASE_2_delta.zip`
+- Reports under `docs/dev/reports/`
diff --git a/tools/shared/eventCommandUtils.js b/tools/shared/eventCommandUtils.js
@@ -0,0 +1,35 @@
+import { trimSafe } from "../../src/shared/utils/stringUtils.js";
+
+export function sanitizeCommand(value, fallback = "") {
+  const command = trimSafe(value);
+  return command || fallback;
+}
+
+export function createCommandDispatcher(handlers = {}, options = {}) {
+  const commandHandlers = handlers && typeof handlers === "object" ? handlers : {};
+  const onUnknownCommand = typeof options.onUnknownCommand === "function"
+    ? options.onUnknownCommand
+    : null;
+
+  return async function dispatchCommand(command, ...args) {
+    const normalized = sanitizeCommand(command);
+    const handler = normalized ? commandHandlers[normalized] : null;
+    if (typeof handler !== "function") {
+      if (onUnknownCommand) {
+        onUnknownCommand(normalized, ...args);
+      }
+      return false;
+    }
+    await handler(...args);
+    return true;
+  };
+}
+
+export function bindEventHandlers(elements, eventName, handler) {
+  const list = Array.isArray(elements) ? elements : [elements];
+  list.forEach((element) => {
+    if (element && typeof element.addEventListener === "function") {
+      element.addEventListener(eventName, handler);
+    }
+  });
+}
diff --git a/tools/shared/platformShell.js b/tools/shared/platformShell.js
@@ -5,6 +5,8 @@ import {
   readSharedPaletteHandoff
 } from "./assetUsageIntegration.js";
 import { createProjectSystemController } from "./projectSystem.js";
+import { bindEventHandlers, createCommandDispatcher } from "./eventCommandUtils.js";
+import { asHtmlInput, queryAll, queryFirst, readDataAttribute, setTextContent } from "./uiSafeUtils.js";
 import { escapeHtml } from "../../src/shared/string/stringUtil.js";
 
 let projectController = null;
@@ -176,50 +178,46 @@ function bindProjectShellEvents(currentTool) {
     return;
   }
 
-  document.querySelectorAll("[data-project-action]").forEach((button) => {
-    button.addEventListener("click", async () => {
-      const action = button.getAttribute("data-project-action");
+  const actionButtons = queryAll("[data-project-action]");
+  const openInputElement = asHtmlInput(queryFirst("[data-project-open-input]"));
 
-      if (action === "new") {
-        if (!projectController.shouldConfirmDiscard("Discard unsaved project changes and create a new project?")) {
-          return;
-        }
-        await projectController.handleNewProject();
-        return;
-      }
-
-      if (action === "open") {
-        if (!projectController.shouldConfirmDiscard("Discard unsaved project changes and open another project?")) {
-          return;
-        }
-        document.querySelector("[data-project-open-input]")?.click();
+  const dispatchProjectAction = createCommandDispatcher({
+    async new() {
+      if (!projectController.shouldConfirmDiscard("Discard unsaved project changes and create a new project?")) {
         return;
       }
-
-      if (action === "save") {
-        projectController.handleSaveProject();
+      await projectController.handleNewProject();
+    },
+    async open() {
+      if (!projectController.shouldConfirmDiscard("Discard unsaved project changes and open another project?")) {
         return;
       }
-
-      if (action === "save-as") {
-        projectController.handleSaveProjectAs();
+      openInputElement?.click();
+    },
+    async save() {
+      projectController.handleSaveProject();
+    },
+    async "save-as"() {
+      projectController.handleSaveProjectAs();
+    },
+    async close() {
+      if (!projectController.shouldConfirmDiscard("Close the active project and clear unsaved changes?")) {
         return;
       }
+      projectController.handleCloseProject();
+    }
+  });
 
-      if (action === "close") {
-        if (!projectController.shouldConfirmDiscard("Close the active project and clear unsaved changes?")) {
-          return;
-        }
-        projectController.handleCloseProject();
-      }
-    });
+  bindEventHandlers(actionButtons, "click", async (event) => {
+    const button = event.currentTarget instanceof Element ? event.currentTarget : null;
+    const action = readDataAttribute(button, "data-project-action");
+    await dispatchProjectAction(action);
   });
 
-  const openInput = document.querySelector("[data-project-open-input]");
-  if (openInput instanceof HTMLInputElement) {
-    openInput.addEventListener("change", async () => {
-      const file = openInput.files?.[0];
-      openInput.value = "";
+  if (openInputElement) {
+    bindEventHandlers(openInputElement, "change", async () => {
+      const file = openInputElement.files?.[0];
+      openInputElement.value = "";
       if (!file) {
         return;
       }
@@ -232,19 +230,17 @@ function bindProjectShellEvents(currentTool) {
     });
   }
 
-  document.querySelectorAll(".tools-platform-frame__nav-link").forEach((link) => {
-    link.addEventListener("click", (event) => {
+  bindEventHandlers(queryAll(".tools-platform-frame__nav-link"), "click", (event) => {
       if (projectController.shouldConfirmDiscard("You have unsaved project changes. Continue to another tool?")) {
         return;
       }
       event.preventDefault();
-    });
   });
 }
 
 function renderShell(currentTool) {
-  const headerHost = document.querySelector("[data-tools-platform-header]");
-  const statusHost = document.querySelector("[data-tools-platform-status]");
+  const headerHost = queryFirst("[data-tools-platform-header]");
+  const statusHost = queryFirst("[data-tools-platform-status]");
 
   // Preserve accordion open state (default to open on first load)
   const accordion = headerHost?.querySelector(".accordion");
@@ -282,13 +278,13 @@ function initPlatformShell() {
         renderShell(currentTool);
       },
       onStatus(message) {
-        const statusHost = document.querySelector("[data-tools-platform-status]");
+        const statusHost = queryFirst("[data-tools-platform-status]");
         if (!(statusHost instanceof HTMLElement)) {
           return;
         }
-        const spans = statusHost.querySelectorAll("span");
+        const spans = queryAll("span", statusHost);
         if (spans[0]) {
-          spans[0].textContent = message;
+          setTextContent(spans[0], message);
         }
       }
     });
diff --git a/tools/shared/uiSafeUtils.js b/tools/shared/uiSafeUtils.js
@@ -0,0 +1,37 @@
+import { trimSafe } from "../../src/shared/utils/stringUtils.js";
+
+export function queryFirst(selector, root = document) {
+  if (!root || typeof root.querySelector !== "function") {
+    return null;
+  }
+  return root.querySelector(selector);
+}
+
+export function queryAll(selector, root = document) {
+  if (!root || typeof root.querySelectorAll !== "function") {
+    return [];
+  }
+  return Array.from(root.querySelectorAll(selector));
+}
+
+export function readDataAttribute(element, attributeName, fallback = "") {
+  if (!(element instanceof Element)) {
+    return fallback;
+  }
+  const key = trimSafe(attributeName);
+  if (!key) {
+    return fallback;
+  }
+  const value = trimSafe(element.getAttribute(key));
+  return value || fallback;
+}
+
+export function asHtmlInput(element) {
+  return element instanceof HTMLInputElement ? element : null;
+}
+
+export function setTextContent(element, value) {
+  if (element && "textContent" in element) {
+    element.textContent = typeof value === "string" ? value : String(value ?? "");
+  }
+}

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-docs: add BUILD_PR bundle for conservative tools/shared extraction phase 1`
	`1`	`+docs: add BUILD_PR phase 2 shared extraction bundle`