docs: add PLAN_PR for tools/shared normalization with engine-theme-first reuse priority

Author: DavidQ

.gitignore

@@ -10,5 +10,3 @@
 # Ignore the docs directory
 /*.zip
 /tmp/*
-/node_modules/
-.tmp*

docs/dev/CODEX_COMMANDS.md

@@ -2,48 +2,30 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Execute BUILD_PR_SAMPLES_INDEX_FIXES_AND_TARGETED_PREVIEW_RETRY with the following exact scope only:
+Create BUILD_PR_TOOLS_THEME_REUSE_BASELINE as a docs-to-code follow-up to PLAN_PR_TOOLS_SHARED_NORMALIZATION.
 
-1. Edit `samples/index.html`
-   - remove header reference `(xxyy - xxzz)`
-   - update phase dropdown labels to exactly `Phase xx - <phase name>`
-   - no other layout or metadata/tag changes
+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
+- 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
 
-2. Fix Sample 1303 (`samples/phase13/1303/*` and only sample-local supporting files if required)
-   - asteroid velocity is exploding to extreme values
-   - add a reasonable asteroid max-speed cap/clamp locally in the sample
-   - preserve normal Asteroids-style feel
-   - no engine/core changes
-   - do not touch Samples 1316, 1317, 1318
+Validation:
+- each touched tool loads
+- no console regressions
+- no shell/theme visual collapse
+- report exact files changed
 
-3. Retry preview SVG generation only for this exact list:
-   0102,0107,0110,0116,0117,0119,
-   0206,0212,0218,0220,0221,0223,
-   0305,0306,0307,0308,0311,0318,0320,0322,0324,
-   0407,0409,0412,
-   0508,
-   0601,0603,0605,0607,0608,0612,
-   0707,0709,0712,
-   0801,0808,
-   0904,
-   1101,1102,1103,
-   1201,1202,1203,1206,1207,
-   1301,1302,1303,1305,1306,1307,1308,1309,1311,1313,1314,1315,
-   1401,1404,1410,1418,
-   1503,1506
-
-   Retry logic:
-   - inspect current generated preview SVG for each listed sample
-   - regenerate only if the SVG currently contains the literal text `Capture timeout`
-   - do not retry any samples outside this list
-   - do not use previous failed-detection logic
-   - allow runtime to settle before capture with adaptive wait and a minimum of ~3 seconds
-   - do not touch 1316, 1317, 1318
-
-4. Validate and package
-   - report exact files changed
-   - confirm no engine files changed
-   - report which listed samples were retried vs skipped
-   - confirm no non-listed samples were touched
-   - package repo-structured delta ZIP to:
-     `<project folder>/tmp/BUILD_PR_SAMPLES_INDEX_FIXES_AND_TARGETED_PREVIEW_RETRY_delta.zip`
+Output:
+- package repo-structured delta ZIP under <project folder>/tmp/
+- use docs/dev/reports for validation/report files

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-BUILD_PR_SAMPLES_INDEX_FIXES_AND_TARGETED_PREVIEW_RETRY: narrow samples-system BUILD for index label cleanup, Sample 1303 local asteroid speed cap, and targeted preview SVG retry only where current SVG contains "Capture timeout".
+docs: add PLAN_PR for tools/shared normalization with engine-theme-first reuse priority

docs/dev/reports/BUILD_PR_TOOLS_THEME_REUSE_BASELINE_changes.md

@@ -0,0 +1,26 @@
+# BUILD_PR_TOOLS_THEME_REUSE_BASELINE - Changes Report
+
+Date: 2026-04-11
+
+## Files Changed
+- docs/pr/BUILD_PR_TOOLS_THEME_REUSE_BASELINE.md
+- tools/Asset Browser/assetBrowser.css
+- tools/Palette Browser/paletteBrowser.css
+- tools/Parallax Scene Studio/parallaxEditor.css
+- tools/Sprite Editor/spriteEditor.css
+- tools/Tilemap Studio/tileMapEditor.css
+- tools/Vector Asset Studio/svgBackgroundEditor.css
+- tools/Vector Map Editor/vectorMapEditor.css
+
+## Implementation Summary
+- Added BUILD doc with exact target files, validation expectations, failure conditions, and exact ZIP output path.
+- Replaced tool-local hardcoded shell/theme colors with shared tokens already provided by engine/theme shell layers:
+  - `--panel`, `--panel2`, `--line`, `--text`, `--muted`, `--accent`, `--surface-inline`, `--surface-code`
+- Removed redundant local root theme blocks (`:root`) from targeted tool CSS files.
+- Kept tool-specific layout and interaction styling intact (workspace grids, panel blocks, selection/preview-specific classes).
+- Did not modify tool JavaScript behavior.
+
+## Explicit Non-Changes
+- No edits in `tools/SpriteEditor_old_keep/`.
+- No edits in `docs/dev/start_of_day/`.
+- No roadmap wording changes.

docs/dev/reports/BUILD_PR_TOOLS_THEME_REUSE_BASELINE_validation.md

@@ -0,0 +1,57 @@
+# BUILD_PR_TOOLS_THEME_REUSE_BASELINE - Validation Report
+
+Date: 2026-04-11
+Branch: main
+
+## Scope Checks
+- PASS: start_of_day directories unchanged (`git status --short -- docs/dev/start_of_day`)
+- PASS: `tools/SpriteEditor_old_keep` unchanged (`git status --short -- tools/SpriteEditor_old_keep`)
+- PASS: active tool targets limited to seven tool CSS files
+
+## Static Contract Validation
+Command: Node import contract check on target tool `index.html` files.
+
+Result:
+- PASS tools/Asset Browser/index.html
+- PASS tools/Palette Browser/index.html
+- PASS tools/Parallax Scene Studio/index.html
+- PASS tools/Sprite Editor/index.html
+- PASS tools/Tilemap Studio/index.html
+- PASS tools/Vector Asset Studio/index.html
+- PASS tools/Vector Map Editor/index.html
+
+Verified required shared assets are referenced in each file:
+- `../../src/engine/ui/hubCommon.css`
+- `../shared/platformShell.css`
+- `../shared/platformShell.js`
+
+## Static Layout Selector Validation
+Command: Node selector-presence check for key layout selectors in each touched CSS file.
+
+Result:
+- PASS tools/Asset Browser/assetBrowser.css
+- PASS tools/Palette Browser/paletteBrowser.css
+- PASS tools/Parallax Scene Studio/parallaxEditor.css
+- PASS tools/Sprite Editor/spriteEditor.css
+- PASS tools/Tilemap Studio/tileMapEditor.css
+- PASS tools/Vector Asset Studio/svgBackgroundEditor.css
+- PASS tools/Vector Map Editor/vectorMapEditor.css
+
+## Static Reference Existence Validation
+Command: Node link/src existence check for local `link[href]` and `script[src]` references in each target tool `index.html`.
+
+Result:
+- PASS tools/Asset Browser/index.html
+- PASS tools/Palette Browser/index.html
+- PASS tools/Parallax Scene Studio/index.html
+- PASS tools/Sprite Editor/index.html
+- PASS tools/Tilemap Studio/index.html
+- PASS tools/Vector Asset Studio/index.html
+- PASS tools/Vector Map Editor/index.html
+
+## Runtime Smoke Validation
+- Browser runtime smoke tests were NOT executed in this environment (no Playwright/Puppeteer installed).
+- Manual validation remains required for:
+  - no console regressions
+  - no shell/theme visual collapse
+  - per-tool load confirmation in browser

docs/dev/reports/boundary_rules.md

@@ -0,0 +1,31 @@
+# Tools Shared Boundary Rules
+
+## Reuse Order
+1. `src/engine/theme/*`
+2. `src/engine/ui/*`
+3. `tools/shared/platformShell.css`
+4. tool-local CSS only for tool-specific concerns
+
+## Allowed In `tools/shared`
+- shell chrome
+- common UI primitives
+- common IO
+- common preview helpers
+- vector helpers
+- project manifest / registry / validation helpers
+- shared panel/inspector utilities
+
+## Forbidden In `tools/shared`
+- speculative abstractions without reuse proof
+- tool-specific editor state
+- tool-specific workflows
+- unique tool rendering logic
+- unique tool command sets
+- broad legacy carryover
+
+## BUILD Discipline For Follow-up PRs
+- exact-cluster only
+- one purpose only
+- preserve `SpriteEditor_old_keep`
+- no engine-core broadening
+- no opportunistic CSS rewrites outside named scope

docs/dev/reports/duplication_candidates.txt

@@ -0,0 +1,28 @@
+DUPLICATION / NORMALIZATION CANDIDATES
+
+Priority 1 — Theme / shell / layout reuse
+- generic layout rules duplicated across tool-local CSS
+- panel chrome / shell styling candidates should prefer:
+  - src/engine/theme/*
+  - src/engine/ui/baseLayout.css
+  - src/engine/ui/hubCommon.css
+  - tools/shared/platformShell.css only after engine reuse review
+
+Priority 2 — Shared JS extraction candidates
+- platform shell bootstrap usage
+- preview-generation helpers
+- vector utility overlap
+- project manifest / registry helpers
+- validation helpers
+
+Priority 3 — Tool-local residuals to preserve
+- Sprite Editor pixel-grid/editor specifics
+- Tilemap Studio tile-palette/map specifics
+- Vector Map Editor authoring specifics
+- Vector Asset Studio SVG-specific workflows
+- Parallax Scene Studio layer/timeline/editor specifics
+
+Do not treat the following as immediate extraction candidates:
+- tool-exclusive render pipelines
+- unique editor interaction models
+- legacy/old_keep surfaces

docs/dev/reports/tools_shared_inventory.txt

@@ -0,0 +1,30 @@
+TOOLS/SHARED NORMALIZATION INVENTORY
+
+Active tools discovered:
+- tools/Asset Browser
+- tools/Palette Browser
+- tools/Parallax Scene Studio
+- tools/Sprite Editor
+- tools/SpriteEditor_old_keep
+- tools/Tilemap Studio
+- tools/Vector Asset Studio
+- tools/Vector Map Editor
+
+Existing shared tooling layer:
+- tools/shared/platformShell.js
+- tools/shared/platformShell.css
+- tools/shared/vector/vectorAssetBridge.js
+- tools/shared/vector/vectorAssetContract.js
+- tools/shared/vector/vectorGeometryMath.js
+- tools/shared/vector/vectorRenderPrep.js
+- tools/shared/projectSystem.js
+- tools/shared/projectSystemAdapters.js
+- tools/shared/projectSystemValueUtils.js
+- tools/shared/runtimeAssetLoader.js
+- tools/shared/runtimeAssetValidationUtils.js
+- tools/shared/renderPipelineContract.js
+- tools/shared/vectorAssetSystem.js
+
+Observation:
+- The repo already has a meaningful `tools/shared` surface.
+- The next lane should normalize and constrain it rather than inventing a new shared layer from scratch.

docs/pr/BUILD_PR_TOOLS_THEME_REUSE_BASELINE.md

@@ -0,0 +1,59 @@
+# BUILD_PR_TOOLS_THEME_REUSE_BASELINE
+
+## PR Purpose
+Apply a minimal tools theme reuse baseline as a docs-to-code follow-up to `PLAN_PR_TOOLS_SHARED_NORMALIZATION`, limited to shell/theme/layout normalization and stylesheet token alignment for active tools.
+
+## Scope Guardrails
+- Prioritize reuse of existing engine UI/theme assets (`src/engine/ui/hubCommon.css`, `tools/shared/platformShell.css`) before any expansion of tool-local CSS.
+- Touch 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/`
+- Keep `tools/SpriteEditor_old_keep/` unchanged.
+- Do not refactor tool-specific behavior.
+- Do not rewrite roadmap wording.
+- Do not touch `docs/dev/start_of_day/*`.
+
+## Exact Target Files
+- `tools/Asset Browser/assetBrowser.css`
+- `tools/Palette Browser/paletteBrowser.css`
+- `tools/Parallax Scene Studio/parallaxEditor.css`
+- `tools/Sprite Editor/spriteEditor.css`
+- `tools/Tilemap Studio/tileMapEditor.css`
+- `tools/Vector Asset Studio/svgBackgroundEditor.css`
+- `tools/Vector Map Editor/vectorMapEditor.css`
+
+## Execution Rules
+- Normalize shared shell/theme selectors to use existing shared tokens:
+  - `--panel`, `--panel2`, `--line`, `--text`, `--muted`, `--accent`, `--surface-inline`, `--surface-code`
+- Keep layout structure intact (grid/flex sizing, section ordering, tool-specific panel structure).
+- No JavaScript behavior edits.
+
+## Validation
+1. Contract check (static):
+   - each touched tool `index.html` includes:
+     - `../../src/engine/ui/hubCommon.css`
+     - `../shared/platformShell.css`
+     - `../shared/platformShell.js`
+2. Style check (static):
+   - touched CSS files no longer introduce new root-level palette systems that duplicate shell tokens
+   - touched CSS files keep layout selectors for workspace/shell intact
+3. Runtime smoke requirement:
+   - each touched tool loads in browser with no console errors
+   - no shell/theme visual collapse
+
+## Failure Conditions
+Stop and report if:
+- scope expands beyond the exact files listed above
+- `tools/SpriteEditor_old_keep/` requires edits
+- start_of_day directories require edits
+- a touched tool cannot load after theme normalization
+
+## Required Output
+- Validation report files under `docs/dev/reports/`
+- Repo-structured delta ZIP at exact path:
+  - `tmp/BUILD_PR_TOOLS_THEME_REUSE_BASELINE_delta.zip`