BUILD PR: centralize project-system cloneValue/safeString helpers across exact tools/shared batch.

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,10 +1,11 @@
 MODEL: GPT-5.3-codex
 REASONING: high
 COMMAND:
-Execute docs/pr/BUILD_PR_SHARED_EXTRACTION_46_STRINGIFY_VALUE_INSPECTOR_BATCH.md exactly.
+Execute docs/pr/BUILD_PR_SHARED_EXTRACTION_47_PROJECT_SYSTEM_VALUE_HELPERS_BATCH.md exactly.
 Edit only these files:
-- tools/dev/shared/stringifyValueUtils.js (new file)
-- src/engine/debug/inspectors/viewModels/stateDiffInspectorViewModel.js
-- tools/dev/commandPacks/inspectorCommandPack.js
+- tools/shared/projectSystemValueUtils.js (new file)
+- tools/shared/projectManifestContract.js
+- tools/shared/projectSystem.js
+- tools/shared/projectSystemAdapters.js
 Do not expand scope.
-Package the delta output to <project folder>/tmp/BUILD_PR_SHARED_EXTRACTION_46_STRINGIFY_VALUE_INSPECTOR_BATCH_delta.zip
+Package the delta output to <project folder>/tmp/BUILD_PR_SHARED_EXTRACTION_47_PROJECT_SYSTEM_VALUE_HELPERS_BATCH_delta.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-BUILD PR: centralize stringifyValue across exact inspector/command-pack batch.
+BUILD PR: centralize project-system cloneValue/safeString helpers across exact tools/shared batch.

docs/dev/NEXT_COMMAND.txt

@@ -1 +1 @@
-Next: continue duplicate-family extraction from the provided duplicate report.
+Next: run BUILD_PR_SHARED_EXTRACTION_48_RUNTIME_ASSET_VALIDATION_BATCH after this batch.

docs/dev/reports/change_summary.txt

@@ -1 +1 @@
-Execution-grade batch for stringifyValue using the exact duplicate-report file list.
+Execution-grade batch for cloneValue/safeString using the exact duplicate-report file list.

docs/pr/BUILD_PR_SHARED_EXTRACTION_47_PROJECT_SYSTEM_VALUE_HELPERS_BATCH.md

@@ -0,0 +1,93 @@
+# BUILD_PR_SHARED_EXTRACTION_47_PROJECT_SYSTEM_VALUE_HELPERS_BATCH
+
+## Purpose
+Centralize duplicated project-system value helpers across the exact tools/shared batch identified in the duplicate report.
+
+## Single PR Purpose
+Normalize ONLY these helpers:
+
+- `cloneValue(value)`
+- `safeString(value, fallback = "")`
+
+## Exact Files Allowed
+
+### New shared file
+1. `tools/shared/projectSystemValueUtils.js`
+
+### Consumer files
+2. `tools/shared/projectManifestContract.js`
+3. `tools/shared/projectSystem.js`
+4. `tools/shared/projectSystemAdapters.js`
+
+Do not edit any other file.
+
+## Source of Truth
+This exact scope comes from the provided duplicate report entries for:
+- `function cloneValue(value)`
+- `function safeString(value, fallback = "")`
+
+Only the 3 listed consumer files are in scope.
+
+## Exact Shared Helper Creation
+Create:
+
+`tools/shared/projectSystemValueUtils.js`
+
+Export exactly:
+- `cloneValue`
+- `safeString`
+
+Implementation rules:
+- use ONE existing local implementation as source-of-truth for each helper
+- do NOT merge logic
+- do NOT generalize behavior
+- preserve signatures exactly:
+  - `cloneValue(value)`
+  - `safeString(value, fallback = "")`
+
+## Exact Consumer Changes
+For each of the 3 listed consumer files:
+
+If the file contains local function definitions matching:
+```js
+function cloneValue(value)
+function safeString(value, fallback = "")
+```
+then:
+- remove the local function definition(s)
+- import the helper(s) from the correct relative path to:
+  - `./projectSystemValueUtils.js`
+- if the file already imports from that module, add the needed helper(s) with the minimum safe edit
+- do not duplicate imports
+- do not touch unrelated helpers
+- do not change logic
+
+If a listed file already imports and uses shared versions, leave it unchanged.
+
+## Relative Import Rule
+Use exactly:
+
+`./projectSystemValueUtils.js`
+
+Do not use aliases.
+Do not change `.js` extension usage.
+
+## Hard Constraints
+- no files outside the 3 listed consumers plus the one new shared file
+- no repo-wide project-system cleanup
+- no behavior changes
+- keep one PR purpose only
+
+## Validation Checklist
+1. Confirm no more than the 4 listed files changed
+2. Confirm `tools/shared/projectSystemValueUtils.js` exists and exports:
+   - `cloneValue`
+   - `safeString`
+3. Confirm local function definitions no longer exist in changed listed consumer files
+4. Confirm changed consumer files import the helpers from `./projectSystemValueUtils.js`
+5. Confirm no unrelated files changed
+6. Confirm no behavior changes were made
+
+## Non-Goals
+- no cleanup outside the 3 listed consumer files
+- no refactor beyond this exact duplicate-removal batch

src/engine/animation/AnimationController.js-

@@ -1,16 +1,10 @@
 import { readSharedAssetHandoff, readSharedPaletteHandoff } from "./assetUsageIntegration.js";
+import { cloneValue } from "./projectSystemValueUtils.js";
 
 export const PROJECT_MANIFEST_SCHEMA = "html-js-gaming.project";
 export const PROJECT_MANIFEST_VERSION = 1;
 export const ACTIVE_PROJECT_STORAGE_KEY = "toolboxaid.projectSystem.activeManifest";
 
-function cloneValue(value) {
-  if (typeof structuredClone === "function") {
-    return structuredClone(value);
-  }
-  return JSON.parse(JSON.stringify(value));
-}
-
 function sanitizeString(value, fallback = "") {
   return typeof value === "string" && value.trim() ? value.trim() : fallback;
 }

tools/shared/projectManifestContract.js

@@ -9,17 +9,7 @@ import {
   validateProjectManifest
 } from "./projectManifestContract.js";
 import { getProjectAdapter } from "./projectSystemAdapters.js";
-
-function cloneValue(value) {
-  if (typeof structuredClone === "function") {
-    return structuredClone(value);
-  }
-  return JSON.parse(JSON.stringify(value));
-}
-
-function safeString(value, fallback = "") {
-  return typeof value === "string" && value.trim() ? value.trim() : fallback;
-}
+import { cloneValue, safeString } from "./projectSystemValueUtils.js";
 
 function readStorage() {
   try {

tools/shared/projectSystem.js

@@ -1,16 +1,6 @@
 import { createAssetRegistry } from "./projectAssetRegistry.js";
 import { createNewProject, ensureProjectShape, serializeProject } from "../Sprite Editor/modules/projectModel.js";
-
-function cloneValue(value) {
-  if (typeof structuredClone === "function") {
-    return structuredClone(value);
-  }
-  return JSON.parse(JSON.stringify(value));
-}
-
-function safeString(value, fallback = "") {
-  return typeof value === "string" && value.trim() ? value.trim() : fallback;
-}
+import { cloneValue, safeString } from "./projectSystemValueUtils.js";
 
 function readToolApi(globalKey) {
   return globalThis[globalKey] && typeof globalThis[globalKey] === "object"

tools/shared/projectSystemAdapters.js

@@ -0,0 +1,10 @@
+export function cloneValue(value) {
+  if (typeof structuredClone === "function") {
+    return structuredClone(value);
+  }
+  return JSON.parse(JSON.stringify(value));
+}
+
+export function safeString(value, fallback = "") {
+  return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}