docs: add BUILD_PR project-level tool integration bundle

DavidQ · DavidQ · commit 1cfc4cbf6754 · 2026-04-11T20:05:26.000-04:00
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -2,16 +2,16 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Create BUILD_PR_TOOL_HOST_STATE_HANDOFF
+Create BUILD_PR_PROJECT_TOOL_INTEGRATION
 
 Scope:
-- add shared context for tools
-- allow optional state passing
-- minimal changes
+- unify project model across tools
+- normalize asset references
+- minimal adapters
 
 Validation:
 - npm run test:launch-smoke -- --tools
-- verify state handoff works
+- verify project works across tools
 
 Output:
-<project>/tmp/BUILD_PR_TOOL_HOST_STATE_HANDOFF_delta.zip
+<project>/tmp/BUILD_PR_PROJECT_TOOL_INTEGRATION_delta.zip
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1 +1 @@
-docs: add BUILD_PR tool host state handoff bundle
+docs: add BUILD_PR project-level tool integration bundle
diff --git a/docs/dev/reports/BUILD_PR_PROJECT_TOOL_INTEGRATION_report.md b/docs/dev/reports/BUILD_PR_PROJECT_TOOL_INTEGRATION_report.md
@@ -0,0 +1,39 @@
+# BUILD_PR_PROJECT_TOOL_INTEGRATION Report
+
+## Scope Outcome
+- Unified project-level tool integration model in shared project manifest flow.
+- Normalized cross-tool asset references into one aggregated integration block.
+- Kept changes adapter-focused and minimal in `tools/shared` only.
+
+## Implementation Summary
+- Added shared integration helper:
+  - `tools/shared/projectToolIntegration.js`
+  - Normalizes tool states for manifest persistence.
+  - Extracts tool asset references into a normalized structure.
+  - Builds `toolIntegration` block with per-tool and aggregate asset references.
+- Updated manifest contract:
+  - `tools/shared/projectManifestContract.js`
+  - Sanitizes persisted tool states with integration helper.
+  - Always creates/migrates `toolIntegration` from `tools` block.
+  - Validates presence of `toolIntegration`.
+- Updated project system controller:
+  - `tools/shared/projectSystem.js`
+  - Normalizes captured/default/opened tool states before persistence.
+  - Unwraps compatible state shape before adapter apply.
+  - Rebuilds `toolIntegration` during project lifecycle transitions.
+
+## Validation
+- `npm run test:launch-smoke -- --tools`
+  - PASS (`9/9` tools)
+- Cross-tool project integration verification (module-level check):
+  - Built mixed-tool manifest payload (tilemap/parallax/sprite/palette/asset browser).
+  - Confirmed normalized per-tool refs in persisted tool states.
+  - Confirmed aggregated `toolIntegration.assetReferences` includes normalized IDs across tools.
+  - Result: PASS.
+
+## Files Changed
+- `tools/shared/projectToolIntegration.js`
+- `tools/shared/projectManifestContract.js`
+- `tools/shared/projectSystem.js`
+- `docs/dev/reports/launch_smoke_report.md`
+- `docs/dev/reports/BUILD_PR_PROJECT_TOOL_INTEGRATION_report.md`
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:53:57.877Z
+Generated: 2026-04-12T00:01:45.164Z
 
 Filters: games=false, samples=false, tools=true, sampleRange=all
 
diff --git a/docs/dev/reports/project_tool_integration_targets.txt b/docs/dev/reports/project_tool_integration_targets.txt
@@ -0,0 +1,5 @@
+PROJECT TOOL INTEGRATION TARGETS
+
+- shared project schema
+- asset reference normalization
+- cross-tool project loading
diff --git a/docs/pr/BUILD_PR_PROJECT_TOOL_INTEGRATION.md b/docs/pr/BUILD_PR_PROJECT_TOOL_INTEGRATION.md
@@ -0,0 +1,29 @@
+# BUILD_PR_PROJECT_TOOL_INTEGRATION
+
+## Purpose
+Unify project-level data across tools so assets, maps, and scenes can be shared consistently.
+
+## Goals
+- single project model
+- shared asset references
+- cross-tool compatibility
+
+## Scope
+- project schema normalization
+- asset reference alignment
+- adapter layer for tools
+
+## Out of Scope
+- tool UI redesign
+- rendering changes
+- deep editor refactors
+
+## Strategy
+- leverage tools/shared/projectSystem
+- align asset paths and IDs
+- minimal adapters per tool
+
+## Validation
+- npm run test:launch-smoke -- --tools
+- open project across multiple tools
+- no console errors
diff --git a/tools/shared/projectManifestContract.js b/tools/shared/projectManifestContract.js
@@ -1,5 +1,11 @@
 import { readSharedAssetHandoff, readSharedPaletteHandoff } from "./assetUsageIntegration.js";
 import { cloneValue, safeString } from "./projectSystemValueUtils.js";
+import {
+  buildProjectToolIntegration,
+  PROJECT_TOOL_INTEGRATION_SCHEMA,
+  PROJECT_TOOL_INTEGRATION_VERSION,
+  normalizeToolStateForProjectManifest
+} from "./projectToolIntegration.js";
 
 export const PROJECT_MANIFEST_SCHEMA = "html-js-gaming.project";
 export const PROJECT_MANIFEST_VERSION = 1;
@@ -39,7 +45,7 @@ function sanitizeToolsBlock(rawTools) {
     if (typeof toolId !== "string" || !toolId.trim() || !value || typeof value !== "object") {
       return;
     }
-    tools[toolId.trim()] = cloneValue(value);
+    tools[toolId.trim()] = normalizeToolStateForProjectManifest(toolId.trim(), value);
   });
   return tools;
 }
@@ -88,6 +94,7 @@ export function normalizeProjectFileName(projectName) {
 export function createEmptyProjectManifest(options = {}) {
   const now = new Date().toISOString();
   const toolId = sanitizeString(options.toolId, "");
+  const tools = sanitizeToolsBlock(options.tools);
   const name = sanitizeString(options.name, "Untitled Project");
   const manifest = {
     schema: PROJECT_MANIFEST_SCHEMA,
@@ -103,7 +110,8 @@ export function createEmptyProjectManifest(options = {}) {
       palette: sanitizeSharedReference(options.sharedReferences?.palette || readSharedPaletteHandoff())
     },
     sharedLibrary: sanitizeSharedLibrary(options.sharedLibrary),
-    tools: sanitizeToolsBlock(options.tools),
+    tools,
+    toolIntegration: buildProjectToolIntegration(tools),
     workspace: {
       lastOpenTool: toolId,
       notes: sanitizeString(options.workspace?.notes, "")
@@ -149,6 +157,12 @@ export function migrateProjectManifest(rawManifest) {
     migrated.migration.applied.push("forward-version-opened-as-compatible");
   }
 
+  if (!rawManifest.toolIntegration || typeof rawManifest.toolIntegration !== "object") {
+    migrated.migration.applied.push("project-tool-integration-created");
+  }
+
+  migrated.toolIntegration = buildProjectToolIntegration(migrated.tools);
+
   return migrated;
 }
 
@@ -177,6 +191,17 @@ export function validateProjectManifest(rawManifest) {
     issues.push("Project manifest tools block is required.");
   }
 
+  if (!manifest.toolIntegration || typeof manifest.toolIntegration !== "object") {
+    issues.push("Project manifest toolIntegration block is required.");
+  } else {
+    if (manifest.toolIntegration.schema !== PROJECT_TOOL_INTEGRATION_SCHEMA) {
+      warnings.push(`Project toolIntegration schema expected ${PROJECT_TOOL_INTEGRATION_SCHEMA} but received ${manifest.toolIntegration.schema || "unknown"}.`);
+    }
+    if (manifest.toolIntegration.version !== PROJECT_TOOL_INTEGRATION_VERSION) {
+      warnings.push(`Project toolIntegration version expected ${PROJECT_TOOL_INTEGRATION_VERSION} but received ${manifest.toolIntegration.version || "unknown"}.`);
+    }
+  }
+
   if (manifest.sharedReferences.asset && !manifest.sharedReferences.asset.id && !manifest.sharedReferences.asset.sourcePath) {
     warnings.push("Shared asset reference is present but does not include an id or source path.");
   }
diff --git a/tools/shared/projectSystem.js b/tools/shared/projectSystem.js
@@ -10,6 +10,11 @@ import {
 } from "./projectManifestContract.js";
 import { getProjectAdapter } from "./projectSystemAdapters.js";
 import { cloneValue, safeString } from "./projectSystemValueUtils.js";
+import {
+  buildProjectToolIntegration,
+  normalizeToolStateForProjectManifest,
+  unwrapToolStateForAdapter
+} from "./projectToolIntegration.js";
 
 function readStorage() {
   try {
@@ -87,15 +92,23 @@ export function createProjectSystemController(options = {}) {
     currentManifest.workspace.lastOpenTool = toolId;
     currentManifest.updatedAt = new Date().toISOString();
     currentManifest.sharedReferences = captureSharedReferenceSnapshot();
+    currentManifest.tools = currentManifest.tools && typeof currentManifest.tools === "object"
+      ? currentManifest.tools
+      : {};
 
     if (toolAdapter.ready) {
-      currentManifest.tools[toolId] = toolAdapter.captureState();
+      currentManifest.tools[toolId] = normalizeToolStateForProjectManifest(
+        toolId,
+        toolAdapter.captureState()
+      );
       const adapterName = safeString(toolAdapter.getProjectName?.(), "");
       if (adapterName) {
         currentManifest.name = adapterName;
       }
     }
 
+    currentManifest.toolIntegration = buildProjectToolIntegration(currentManifest.tools);
+
     return migrateProjectManifest(currentManifest);
   }
 
@@ -156,7 +169,7 @@ export function createProjectSystemController(options = {}) {
     const manifest = ensureProjectManifest();
     const toolState = manifest.tools?.[toolId];
     if (toolState) {
-      toolAdapter.applyState(cloneValue(toolState));
+      toolAdapter.applyState(cloneValue(unwrapToolStateForAdapter(toolId, toolState)));
       onStatus(buildStatusSummary(validateProjectManifest(manifest)));
     }
     state.appliedInitialState = true;
@@ -172,8 +185,10 @@ export function createProjectSystemController(options = {}) {
       toolId
     });
     if (toolAdapter.ready) {
-      nextManifest.tools[toolId] = toolAdapter.createDefaultState(nextName);
-      toolAdapter.applyState(cloneValue(nextManifest.tools[toolId]));
+      const defaultState = normalizeToolStateForProjectManifest(toolId, toolAdapter.createDefaultState(nextName));
+      nextManifest.tools[toolId] = defaultState;
+      nextManifest.toolIntegration = buildProjectToolIntegration(nextManifest.tools);
+      toolAdapter.applyState(cloneValue(unwrapToolStateForAdapter(toolId, defaultState)));
     }
     state.manifest = nextManifest;
     state.appliedInitialState = true;
@@ -192,9 +207,12 @@ export function createProjectSystemController(options = {}) {
     state.manifest = nextManifest;
     const toolAdapter = adapter();
     if (toolAdapter.ready) {
-      const nextToolState = nextManifest.tools?.[toolId] || toolAdapter.createDefaultState(nextManifest.name);
-      toolAdapter.applyState(cloneValue(nextToolState));
+      const nextToolState = nextManifest.tools?.[toolId]
+        ? normalizeToolStateForProjectManifest(toolId, nextManifest.tools[toolId])
+        : normalizeToolStateForProjectManifest(toolId, toolAdapter.createDefaultState(nextManifest.name));
+      toolAdapter.applyState(cloneValue(unwrapToolStateForAdapter(toolId, nextToolState)));
       nextManifest.tools[toolId] = cloneValue(nextToolState);
+      nextManifest.toolIntegration = buildProjectToolIntegration(nextManifest.tools);
     }
     state.appliedInitialState = true;
     markSaved("open-project");
@@ -224,8 +242,10 @@ export function createProjectSystemController(options = {}) {
       toolId
     });
     if (toolAdapter.ready) {
-      nextManifest.tools[toolId] = toolAdapter.createDefaultState(fallbackName);
-      toolAdapter.applyState(cloneValue(nextManifest.tools[toolId]));
+      const defaultState = normalizeToolStateForProjectManifest(toolId, toolAdapter.createDefaultState(fallbackName));
+      nextManifest.tools[toolId] = defaultState;
+      nextManifest.toolIntegration = buildProjectToolIntegration(nextManifest.tools);
+      toolAdapter.applyState(cloneValue(unwrapToolStateForAdapter(toolId, defaultState)));
     }
     state.manifest = nextManifest;
     state.appliedInitialState = true;
diff --git a/tools/shared/projectToolIntegration.js b/tools/shared/projectToolIntegration.js

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-docs: add BUILD_PR tool host state handoff bundle`
	`1`	`+docs: add BUILD_PR project-level tool integration bundle`