centralize string normalization helpers

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,6 +1,6 @@
 MODEL: GPT-5.3-codex
 REASONING: high
 COMMAND:
-Execute docs/pr/BUILD_PR_SHARED_EXTRACTION_36_ARRAY_UTILS_ENSURE_ARRAY_BATCH.md exactly.
+Execute docs/pr/BUILD_PR_SHARED_EXTRACTION_37_STRING_UTILS_TRIM_NORMALIZE_BATCH.md exactly.
 Edit only listed files.
-Package to <project folder>/tmp/BUILD_PR_SHARED_EXTRACTION_36_ARRAY_UTILS_ENSURE_ARRAY_BATCH_delta.zip
+Package to <project folder>/tmp/BUILD_PR_SHARED_EXTRACTION_37_STRING_UTILS_TRIM_NORMALIZE_BATCH_delta.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-centralize ensureArray helper
+centralize string normalization helpers

docs/dev/NEXT_COMMAND.txt

@@ -1 +1 @@
-Next: string utils batch
+Next: id utils batch

docs/dev/reports/change_summary.txt

@@ -1 +1 @@
-ensureArray centralized
+string utils centralized

docs/pr/BUILD_PR_SHARED_EXTRACTION_37_STRING_UTILS_TRIM_NORMALIZE_BATCH.md

@@ -0,0 +1,33 @@
+# BUILD_PR_SHARED_EXTRACTION_37_STRING_UTILS_TRIM_NORMALIZE_BATCH
+
+## Purpose
+Centralize duplicated string normalization helpers across tools/debug domains.
+
+## Single PR Purpose
+Normalize ONLY:
+
+- normalizeString(value)
+- trimSafe(value)
+
+## Exact Files Allowed
+
+### Shared
+1. src/shared/utils/stringUtils.js
+
+### Consumers (from dupes report)
+2. tools/dev/devConsoleIntegration.js
+3. tools/dev/commandPacks/packUtils.js
+4. tools/dev/presets/debugPresetRegistry.js
+5. tools/shared/runtimeAssetLoader.js
+6. tools/shared/vectorTemplateSampleGame.js
+
+## Rules
+- remove local implementations
+- import from shared
+- no behavior change
+- no scope expansion
+
+## Validation
+- helper exists once
+- imports correct
+- no local duplicates remain

src/shared/utils/stringUtils.js

@@ -0,0 +1,7 @@
+export function trimSafe(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+export function normalizeString(value) {
+  return trimSafe(value);
+}

tools/shared/runtimeAssetLoader.js

@@ -4,16 +4,13 @@ import ImageAssetLoader from "../../engine/assets/ImageAssetLoader.js";
 import { prepareVectorGeometryRuntimeAsset } from "./vectorGeometryRuntime.js";
 import { ensureArray } from "../../src/shared/utils/arrayUtils.js";
 import { cloneJson } from "../../src/shared/utils/jsonUtils.js";
-
-function sanitizeText(value) {
-  return typeof value === "string" ? value.trim() : "";
-}
+import { trimSafe } from "../../src/shared/utils/stringUtils.js";
 
 function createReport(level, code, message) {
   return {
-    level: sanitizeText(level) || "info",
-    code: sanitizeText(code),
-    message: sanitizeText(message)
+    level: trimSafe(level) || "info",
+    code: trimSafe(code),
+    message: trimSafe(message)
   };
 }
 
@@ -36,7 +33,7 @@ function validatePackageManifest(manifest) {
   if (!Number.isFinite(pkg.version)) {
     throw new Error("Invalid packaged input: package.version must be numeric.");
   }
-  if (!sanitizeText(pkg.projectId)) {
+  if (!trimSafe(pkg.projectId)) {
     throw new Error("Invalid packaged input: package.projectId is required.");
   }
   if (!Array.isArray(pkg.assets) || pkg.assets.length === 0) {
@@ -51,8 +48,8 @@ function validatePackageManifest(manifest) {
 
   const seenIds = new Set();
   pkg.assets.forEach((asset, index) => {
-    const id = sanitizeText(asset?.id);
-    const type = sanitizeText(asset?.type);
+    const id = trimSafe(asset?.id);
+    const type = trimSafe(asset?.type);
     if (!id) {
       throw new Error(`Invalid packaged input: asset at index ${index} is missing id.`);
     }
@@ -66,16 +63,16 @@ function validatePackageManifest(manifest) {
   });
 
   pkg.roots.forEach((root, index) => {
-    const id = sanitizeText(root?.id);
+    const id = trimSafe(root?.id);
     if (!id || !seenIds.has(id)) {
       throw new Error(`Invalid packaged input: startup root at index ${index} does not resolve to a packaged asset.`);
     }
   });
 
   pkg.dependencies.forEach((dependency, index) => {
-    const from = sanitizeText(dependency?.from);
-    const to = sanitizeText(dependency?.to);
-    const type = sanitizeText(dependency?.type);
+    const from = trimSafe(dependency?.from);
+    const to = trimSafe(dependency?.to);
+    const type = trimSafe(dependency?.type);
     if (!from || !to || !type) {
       throw new Error(`Invalid packaged input: dependency at index ${index} is incomplete.`);
     }
@@ -88,12 +85,12 @@ function validatePackageManifest(manifest) {
 }
 
 function createRegistryDefinition(asset, source) {
-  const type = sanitizeText(asset?.type);
+  const type = trimSafe(asset?.type);
   const sourceType = type === "image" ? "image" : "data";
   return {
-    id: sanitizeText(asset?.id),
+    id: trimSafe(asset?.id),
     type: sourceType,
-    path: sanitizeText(asset?.path),
+    path: trimSafe(asset?.path),
     source
   };
 }
@@ -102,7 +99,7 @@ function toBootstrapData(packageManifest, loadedAssets) {
   const pkg = packageManifest.package;
   return {
     projectId: pkg.projectId,
-    startupAssetIds: pkg.roots.map((root) => sanitizeText(root.id)),
+    startupAssetIds: pkg.roots.map((root) => trimSafe(root.id)),
     assetTable: loadedAssets.reduce((accumulator, entry) => {
       accumulator[entry.id] = entry.asset;
       return accumulator;
@@ -112,12 +109,12 @@ function toBootstrapData(packageManifest, loadedAssets) {
 }
 
 function finalizeLoadedAsset(asset, loadedAsset) {
-  if (sanitizeText(asset?.type) !== "vector") {
+  if (trimSafe(asset?.type) !== "vector") {
     return loadedAsset;
   }
   return prepareVectorGeometryRuntimeAsset(loadedAsset, {
-    sourcePath: sanitizeText(asset?.path),
-    assetId: sanitizeText(asset?.id)
+    sourcePath: trimSafe(asset?.path),
+    assetId: trimSafe(asset?.id)
   });
 }
 
@@ -169,7 +166,7 @@ export async function loadPackagedProjectRuntime(options = {}) {
 
   for (let index = 0; index < pkg.assets.length; index += 1) {
     const asset = pkg.assets[index];
-    const assetId = sanitizeText(asset?.id);
+    const assetId = trimSafe(asset?.id);
     const resolvedSource = assetProvider(asset, manifest);
     if (resolvedSource === undefined || resolvedSource === null || resolvedSource === "") {
       reports.push(createReport("error", "MISSING_PACKAGED_ASSET", `Required packaged asset ${assetId} could not be resolved from package input.`));
@@ -189,7 +186,7 @@ export async function loadPackagedProjectRuntime(options = {}) {
       };
     }
     const finalizedAsset = finalizeLoadedAsset(asset, result.asset);
-    if (sanitizeText(asset?.type) === "vector") {
+    if (trimSafe(asset?.type) === "vector") {
       reports.push(createReport("info", "VECTOR_RUNTIME_READY", `Prepared vector geometry runtime data for ${assetId}.`));
     }
     loadedAssets.push({

tools/shared/vectorTemplateSampleGame.js

@@ -9,21 +9,18 @@ import { buildDebugVisualizationLayer, summarizeDebugVisualizationLayer } from "
 import { buildPerformanceProfiler, summarizePerformanceProfiler } from "./performanceProfiler.js";
 import { createVectorNativeTemplateDefinition } from "./vectorNativeTemplate.js";
 import { cloneJson } from "../../src/shared/utils/jsonUtils.js";
-
-function sanitizeText(value) {
-  return typeof value === "string" ? value.trim() : "";
-}
+import { normalizeString } from "../../src/shared/utils/stringUtils.js";
 
 function createReport(level, code, message) {
   return {
-    level: sanitizeText(level) || "info",
-    code: sanitizeText(code),
-    message: sanitizeText(message)
+    level: normalizeString(level) || "info",
+    code: normalizeString(code),
+    message: normalizeString(message)
   };
 }
 
 function remapPath(pathValue) {
-  return sanitizeText(pathValue).replace("templates/vector-native-arcade/", "games/vector-arcade-sample/");
+  return normalizeString(pathValue).replace("templates/vector-native-arcade/", "games/vector-arcade-sample/");
 }
 
 function remapRegistry(registry) {
@@ -84,24 +81,24 @@ function buildImageSource(asset) {
     image: {
       width: 960,
       height: 720,
-      src: sanitizeText(asset?.path)
+      src: normalizeString(asset?.path)
     },
     status: "provided-loaded"
   };
 }
 
 function createResolvePackagedAsset(assetSources) {
   return (asset) => {
-    const assetId = sanitizeText(asset?.id);
-    if (sanitizeText(asset?.type) === "image") {
+    const assetId = normalizeString(asset?.id);
+    if (normalizeString(asset?.type) === "image") {
       return buildImageSource(asset);
     }
     return assetSources[assetId] ? cloneJson(assetSources[assetId]) : null;
   };
 }
 
 export function summarizeVectorTemplateSampleGame(result) {
-  const status = sanitizeText(result?.sampleGame?.status);
+  const status = normalizeString(result?.sampleGame?.status);
   if (status !== "ready") {
     return "Vector template sample game unavailable.";
   }
@@ -172,7 +169,7 @@ export async function buildVectorTemplateSampleGame(options = {}) {
   });
 
   const packageAssetIds = Array.isArray(packageResult.manifest?.package?.assets)
-    ? packageResult.manifest.package.assets.map((asset) => sanitizeText(asset?.id))
+    ? packageResult.manifest.package.assets.map((asset) => normalizeString(asset?.id))
     : [];
   const hasSpriteRuntimeDependency = packageAssetIds.some((id) => id.startsWith("sprite."));