BUILD PR: centralize cloneJson across exact tools/dev + tools/shared batch.

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1 +1,36 @@
-Execute BUILD_PR_SHARED_EXTRACTION_33_NETWORK_DEBUG_HELPERS_BATCH.md exactly.
+MODEL: GPT-5.3-codex
+REASONING: high
+COMMAND:
+Execute docs/pr/BUILD_PR_SHARED_EXTRACTION_31_CLONE_JSON_BATCH_RETRY.md exactly.
+Edit only these files:
+- src/shared/utils/jsonUtils.js (new file)
+- tools/dev/devConsoleIntegration.js
+- tools/dev/advanced/debugMacroRegistry.js
+- tools/dev/advanced/debugPanelGroupRegistry.js
+- tools/dev/inspectors/inspectorStore.js
+- tools/dev/plugins/debugPluginSystem.js
+- tools/dev/presets/debugPresetApplier.js
+- tools/dev/presets/debugPresetRegistry.js
+- tools/shared/assetMarketplace.js
+- tools/shared/asteroidsPlatformDemo.js
+- tools/shared/cloudRuntime.js
+- tools/shared/collaborationSystem.js
+- tools/shared/contractVersioning.js
+- tools/shared/devConsoleDebugOverlay.js
+- tools/shared/hotReloadSystem.js
+- tools/shared/multiTargetExport.js
+- tools/shared/performanceBenchmarks.js
+- tools/shared/platformValidationSuite.js
+- tools/shared/pluginArchitecture.js
+- tools/shared/renderPipelineContract.js
+- tools/shared/runtimeAssetLoader.js
+- tools/shared/runtimeSceneLoaderHotReload.js
+- tools/shared/runtimeStreaming.js
+- tools/shared/vectorAssetSystem.js
+- tools/shared/vectorGeometryRuntime.js
+- tools/shared/vectorNativeTemplate.js
+- tools/shared/vectorTemplateSampleGame.js
+- tools/shared/vector/vectorAssetContract.js
+- tools/shared/vector/vectorRenderPrep.js
+Do not expand scope.
+Package the delta output to <project folder>/tmp/BUILD_PR_SHARED_EXTRACTION_31_CLONE_JSON_BATCH_RETRY_delta.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-centralize network debug helpers
+BUILD PR: centralize cloneJson across exact tools/dev + tools/shared batch.

docs/dev/NEXT_COMMAND.txt

@@ -1 +1 @@
-Next: state system alignment
+Next: run BUILD_PR_SHARED_EXTRACTION_32_IS_OBJECT_BATCH_RETRY after this batch.

docs/dev/reports/change_summary.txt

@@ -1 +1 @@
-network debug helpers centralized
+Replaced the blocked cloneJson BUILD with an execution-grade retry using the exact target file list from the duplicate report.

docs/dev/reports/validation_checklist.txt

@@ -1 +1 @@
-validate per PR
+Exact file list present; no guessing; one PR purpose only.

docs/pr/BUILD_PR_SHARED_EXTRACTION_31_CLONE_JSON_BATCH_RETRY.md

@@ -0,0 +1,116 @@
+# BUILD_PR_SHARED_EXTRACTION_31_CLONE_JSON_BATCH_RETRY
+
+## Purpose
+Centralize duplicated `cloneJson(value)` implementations across the exact tools/dev + tools/shared batch identified in the duplicate report, without guessing scope.
+
+## Single PR Purpose
+Normalize ONLY this helper:
+
+- `cloneJson(value)`
+
+## Exact Files Allowed
+
+### New shared file
+1. `src/shared/utils/jsonUtils.js`
+
+### Consumer files
+2. `tools/dev/devConsoleIntegration.js`
+3. `tools/dev/advanced/debugMacroRegistry.js`
+4. `tools/dev/advanced/debugPanelGroupRegistry.js`
+5. `tools/dev/inspectors/inspectorStore.js`
+6. `tools/dev/plugins/debugPluginSystem.js`
+7. `tools/dev/presets/debugPresetApplier.js`
+8. `tools/dev/presets/debugPresetRegistry.js`
+9. `tools/shared/assetMarketplace.js`
+10. `tools/shared/asteroidsPlatformDemo.js`
+11. `tools/shared/cloudRuntime.js`
+12. `tools/shared/collaborationSystem.js`
+13. `tools/shared/contractVersioning.js`
+14. `tools/shared/devConsoleDebugOverlay.js`
+15. `tools/shared/hotReloadSystem.js`
+16. `tools/shared/multiTargetExport.js`
+17. `tools/shared/performanceBenchmarks.js`
+18. `tools/shared/platformValidationSuite.js`
+19. `tools/shared/pluginArchitecture.js`
+20. `tools/shared/renderPipelineContract.js`
+21. `tools/shared/runtimeAssetLoader.js`
+22. `tools/shared/runtimeSceneLoaderHotReload.js`
+23. `tools/shared/runtimeStreaming.js`
+24. `tools/shared/vectorAssetSystem.js`
+25. `tools/shared/vectorGeometryRuntime.js`
+26. `tools/shared/vectorNativeTemplate.js`
+27. `tools/shared/vectorTemplateSampleGame.js`
+28. `tools/shared/vector/vectorAssetContract.js`
+29. `tools/shared/vector/vectorRenderPrep.js`
+
+Do not edit any other file.
+
+## Source of Truth
+This exact file list comes from the provided duplicate report entry for:
+
+`function cloneJson(value)`
+
+No other clone/copy helpers are in scope.
+
+## Exact Shared Helper Creation
+Create:
+
+`src/shared/utils/jsonUtils.js`
+
+Export exactly one helper:
+
+```js
+export function cloneJson(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+```
+
+Use the existing local implementation contract already present in the batch. Do not change behavior.
+
+## Exact Consumer Changes
+For each of the 28 listed consumer files:
+
+If the file contains a local function definition matching:
+```js
+function cloneJson(value)
+```
+then:
+- remove the local `cloneJson(value)` function definition
+- import `cloneJson` from the correct relative path to:
+  - `src/shared/utils/jsonUtils.js`
+- if the file already imports from that module, add `cloneJson` 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 `cloneJson`, leave it unchanged.
+
+## Relative Import Rule
+Use the correct relative path from each consumer file to:
+
+`src/shared/utils/jsonUtils.js`
+
+Do not use aliases.
+Do not change `.js` extension usage.
+
+## Hard Constraints
+- no engine changes
+- no game files
+- no sample files
+- no repo-wide clone/deep-clone cleanup
+- no behavior changes
+- keep one PR purpose only
+
+## Validation Checklist
+1. Confirm no more than the 29 listed files changed
+2. Confirm `src/shared/utils/jsonUtils.js` exists and exports only `cloneJson`
+3. Confirm local `function cloneJson(value)` definitions no longer exist in changed listed consumer files
+4. Confirm changed consumer files import `cloneJson` from the correct relative path to `src/shared/utils/jsonUtils.js`
+5. Confirm no engine, game, or sample files changed
+6. Confirm no behavior changes were made
+
+## Non-Goals
+- no cleanup of `clone(value)`
+- no cleanup of `cloneDeep(value)`
+- no cleanup outside the 28 listed consumer files
+- no refactor beyond this exact duplicate-removal batch

src/shared/utils/jsonUtils.js

@@ -0,0 +1,3 @@
+export function cloneJson(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}

tools/dev/advanced/debugMacroRegistry.js

@@ -6,6 +6,7 @@ debugMacroRegistry.js
 */
 
 import { sanitizeText } from "../../../src/engine/debug/inspectors/shared/inspectorUtils.js";
+import { cloneJson } from "../../../src/shared/utils/jsonUtils.js";
 
 function asStepArray(value) {
   if (!Array.isArray(value)) {
@@ -16,13 +17,6 @@ function asStepArray(value) {
     .filter(Boolean);
 }
 
-function cloneJson(value) {
-  if (typeof structuredClone === "function") {
-    return structuredClone(value);
-  }
-  return JSON.parse(JSON.stringify(value));
-}
-
 function normalizeMacroDescriptor(descriptor = {}) {
   const macroId = sanitizeText(descriptor.macroId);
   const title = sanitizeText(descriptor.title) || macroId;

tools/dev/advanced/debugPanelGroupRegistry.js

@@ -6,6 +6,7 @@ debugPanelGroupRegistry.js
 */
 
 import { sanitizeText } from "../../../src/engine/debug/inspectors/shared/inspectorUtils.js";
+import { cloneJson } from "../../../src/shared/utils/jsonUtils.js";
 
 function asStringArray(value) {
   if (!Array.isArray(value)) {
@@ -21,13 +22,6 @@ function asStringArray(value) {
   return Array.from(unique.values());
 }
 
-function cloneJson(value) {
-  if (typeof structuredClone === "function") {
-    return structuredClone(value);
-  }
-  return JSON.parse(JSON.stringify(value));
-}
-
 function normalizeGroupDescriptor(descriptor = {}) {
   const groupId = sanitizeText(descriptor.groupId);
   const title = sanitizeText(descriptor.title) || groupId;

tools/dev/devConsoleIntegration.js

@@ -22,6 +22,8 @@ import { createToggleCommandPack } from "./commandPacks/toggleCommandPack.js";
 import { createValidationCommandPack } from "./commandPacks/validationCommandPack.js";
 import { createInspectorStore } from "./inspectors/inspectorStore.js";
 import { createDebugPluginRegistry } from "./plugins/debugPluginSystem.js";
+import { cloneJson } from "../../src/shared/utils/jsonUtils.js";
+
 import {
   createDiagnosticsCollector,
   createDevConsoleDebugOverlayRuntime
@@ -58,13 +60,6 @@ const DEFAULT_PLUGIN_CAPABILITIES = Object.freeze([
 import { sanitizeText } from "../../src/engine/debug/inspectors/shared/inspectorUtils.js";
 import { isObject } from "../../src/shared/utils/objectUtils.js";
 
-function cloneJson(value) {
-  if (typeof structuredClone === "function") {
-    return structuredClone(value);
-  }
-  return JSON.parse(JSON.stringify(value));
-}
-
 function toContextSection(context, field) {
   return isObject(context?.[field]) ? context[field] : {};
 }