docs: add BUILD_PR bundle for conservative tools/shared extraction phase 1

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,29 +2,29 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Create BUILD_PR_TOOLS_THEME_REUSE_BASELINE as a docs-to-code follow-up to PLAN_PR_TOOLS_SHARED_NORMALIZATION.
+Create BUILD_PR_TOOLS_SHARED_EXTRACTION_PHASE_1 as a conservative exact-cluster implementation.
 
 Scope:
-- prioritize reuse of existing engine theme/UI assets before adding or expanding any new tool-local CSS
-- target active tools only:
-  - tools/Asset Browser
-  - tools/Palette Browser
-  - tools/Parallax Scene Studio
-  - tools/Sprite Editor
-  - tools/Tilemap Studio
-  - tools/Vector Asset Studio
-  - tools/Vector Map Editor
+- 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
+- no editor-state extraction
+- no render-pipeline rewrites
+- no tool-host work
 - preserve tools/SpriteEditor_old_keep
-- keep scope tight to shell/theme/layout normalization and import alignment only
-- do not refactor tool-specific behavior
-- do not rewrite roadmap wording
-- do not touch start_of_day directories
+- keep changed-file count minimal
+- stop and report if helper semantics diverge too much
 
 Validation:
-- each touched tool loads
-- no console regressions
-- no shell/theme visual collapse
+- npm run test:launch-smoke -- --tools
 - report exact files changed
+- report extracted vs normalized helpers
+- report helpers intentionally left local and why
 
 Output:
 - package repo-structured delta ZIP under <project folder>/tmp/

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-docs: add PLAN_PR for tools/shared normalization with engine-theme-first reuse priority
+docs: add BUILD_PR bundle for conservative tools/shared extraction phase 1

docs/dev/reports/BUILD_PR_TOOLS_SHARED_EXTRACTION_PHASE_1_changes.md

@@ -0,0 +1,55 @@
+# BUILD_PR_TOOLS_SHARED_EXTRACTION_PHASE_1 - Changes Report
+
+Date: 2026-04-11
+
+## Exact Files Changed
+- docs/pr/BUILD_PR_TOOLS_SHARED_EXTRACTION_PHASE_1.md
+- tools/shared/projectManifestContract.js
+- tools/shared/runtimeAssetLoader.js
+- tools/shared/runtimeAssetValidationUtils.js
+- tools/shared/runtimeStreaming.js
+- tools/shared/runtimeAssetSharedUtils.js
+- tools/shared/vector/vectorAssetBridge.js
+- tools/shared/vector/vectorAssetContract.js
+- tools/shared/vector/vectorRenderPrep.js
+- tools/shared/vector/vectorSafeValueUtils.js
+
+## Extracted vs Normalized Helpers
+
+Extracted (new shared helpers):
+- `tools/shared/runtimeAssetSharedUtils.js`
+  - `sanitizeRuntimeText(value, fallback)`
+  - `createRuntimeReport(level, code, message)`
+- `tools/shared/vector/vectorSafeValueUtils.js`
+  - `sanitizeVectorText(value, fallback)`
+
+Normalized (existing files now reuse extracted helpers):
+- `tools/shared/runtimeAssetLoader.js`
+  - replaced local report/text helpers with `runtimeAssetSharedUtils`
+- `tools/shared/runtimeStreaming.js`
+  - replaced local report/text helpers with `runtimeAssetSharedUtils`
+- `tools/shared/runtimeAssetValidationUtils.js`
+  - normalized runtime text sanitization via `runtimeAssetSharedUtils`
+- `tools/shared/projectManifestContract.js`
+  - normalized string sanitization to existing `safeString` from `projectSystemValueUtils`
+- `tools/shared/vector/vectorAssetBridge.js`
+  - normalized local string sanitization to `sanitizeVectorText`
+- `tools/shared/vector/vectorAssetContract.js`
+  - normalized local string sanitization to `sanitizeVectorText`
+- `tools/shared/vector/vectorRenderPrep.js`
+  - normalized local string sanitization to `sanitizeVectorText`
+
+## Helpers Intentionally Left Local
+- `sanitizeText/createReport` in:
+  - `tools/shared/hotReloadSystem.js`
+  - `tools/shared/platformValidationSuite.js`
+  - `tools/shared/vectorAssetSystem.js`
+
+Why left local:
+- These modules are orchestration/reporting surfaces with domain-specific report vocabulary and aggregation behavior.
+- Pulling them into this lane would expand beyond the requested exact-cluster (runtime loader/validation + vector-safe helper normalization) and increase risk/scope.
+
+- Local helper clusters in tool app files (for example, sample-path/readout helpers in Parallax/Tilemap/Vector Asset Studio) were intentionally left unchanged.
+
+Why left local:
+- Out of requested scope for this PR (would trend into editor-state extraction or broader refactor lanes).

docs/dev/reports/BUILD_PR_TOOLS_SHARED_EXTRACTION_PHASE_1_validation.md

@@ -0,0 +1,33 @@
+# BUILD_PR_TOOLS_SHARED_EXTRACTION_PHASE_1 - Validation Report
+
+Date: 2026-04-11
+Branch: main
+
+## Command Validation
+Executed:
+- `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
+
+Generated by test command:
+- `docs/dev/reports/launch_smoke_report.md`
+
+## Scope Safety Checks
+- `tools/SpriteEditor_old_keep` modified: NO
+- start_of_day directories modified: NO
+- style/theme files touched in this BUILD lane: NO
+
+## Semantic Divergence Gate
+- Runtime helper normalization limited to exact duplicate semantics (`sanitize text` + `create report` helper shape).
+- Project system normalization limited to aliasing existing `safeString` helper.
+- Vector helper normalization limited to existing string sanitization helper replacement in `tools/shared/vector/*`.
+- No behavior rewrites in editor state, render pipelines, or tool host.

docs/dev/reports/BUILD_PR_TOOLS_SHARED_EXTRACTION_PHASE_1_validation_checklist.txt

@@ -0,0 +1,14 @@
+VALIDATION CHECKLIST — BUILD_PR_TOOLS_SHARED_EXTRACTION_PHASE_1
+
+Required:
+- [ ] touched tools still load
+- [ ] no new console errors
+- [ ] npm run test:launch-smoke -- --tools executed
+- [ ] no shell/theme regressions introduced by this PR
+- [ ] changed-file count stayed minimal
+- [ ] SpriteEditor_old_keep untouched
+- [ ] report exact extracted/normalized helpers
+- [ ] report helpers intentionally left local
+
+Nice to have:
+- [ ] note any helper families that clearly belong in phase 2