Skip to content

Commit 150fe5a

Browse files
author
DavidQ
committed
docs: add PLAN_PR for tools/shared normalization with engine-theme-first reuse priority
1 parent 100255e commit 150fe5a

17 files changed

Lines changed: 620 additions & 256 deletions

.gitignore

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,5 +10,3 @@
1010
# Ignore the docs directory
1111
/*.zip
1212
/tmp/*
13-
/node_modules/
14-
.tmp*

docs/dev/CODEX_COMMANDS.md

Lines changed: 24 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -2,48 +2,30 @@ MODEL: GPT-5.4
22
REASONING: high
33

44
COMMAND:
5-
Execute BUILD_PR_SAMPLES_INDEX_FIXES_AND_TARGETED_PREVIEW_RETRY with the following exact scope only:
5+
Create BUILD_PR_TOOLS_THEME_REUSE_BASELINE as a docs-to-code follow-up to PLAN_PR_TOOLS_SHARED_NORMALIZATION.
66

7-
1. Edit `samples/index.html`
8-
- remove header reference `(xxyy - xxzz)`
9-
- update phase dropdown labels to exactly `Phase xx - <phase name>`
10-
- no other layout or metadata/tag changes
7+
Scope:
8+
- prioritize reuse of existing engine theme/UI assets before adding or expanding any new tool-local CSS
9+
- target active tools only:
10+
- tools/Asset Browser
11+
- tools/Palette Browser
12+
- tools/Parallax Scene Studio
13+
- tools/Sprite Editor
14+
- tools/Tilemap Studio
15+
- tools/Vector Asset Studio
16+
- tools/Vector Map Editor
17+
- preserve tools/SpriteEditor_old_keep
18+
- keep scope tight to shell/theme/layout normalization and import alignment only
19+
- do not refactor tool-specific behavior
20+
- do not rewrite roadmap wording
21+
- do not touch start_of_day directories
1122

12-
2. Fix Sample 1303 (`samples/phase13/1303/*` and only sample-local supporting files if required)
13-
- asteroid velocity is exploding to extreme values
14-
- add a reasonable asteroid max-speed cap/clamp locally in the sample
15-
- preserve normal Asteroids-style feel
16-
- no engine/core changes
17-
- do not touch Samples 1316, 1317, 1318
23+
Validation:
24+
- each touched tool loads
25+
- no console regressions
26+
- no shell/theme visual collapse
27+
- report exact files changed
1828

19-
3. Retry preview SVG generation only for this exact list:
20-
0102,0107,0110,0116,0117,0119,
21-
0206,0212,0218,0220,0221,0223,
22-
0305,0306,0307,0308,0311,0318,0320,0322,0324,
23-
0407,0409,0412,
24-
0508,
25-
0601,0603,0605,0607,0608,0612,
26-
0707,0709,0712,
27-
0801,0808,
28-
0904,
29-
1101,1102,1103,
30-
1201,1202,1203,1206,1207,
31-
1301,1302,1303,1305,1306,1307,1308,1309,1311,1313,1314,1315,
32-
1401,1404,1410,1418,
33-
1503,1506
34-
35-
Retry logic:
36-
- inspect current generated preview SVG for each listed sample
37-
- regenerate only if the SVG currently contains the literal text `Capture timeout`
38-
- do not retry any samples outside this list
39-
- do not use previous failed-detection logic
40-
- allow runtime to settle before capture with adaptive wait and a minimum of ~3 seconds
41-
- do not touch 1316, 1317, 1318
42-
43-
4. Validate and package
44-
- report exact files changed
45-
- confirm no engine files changed
46-
- report which listed samples were retried vs skipped
47-
- confirm no non-listed samples were touched
48-
- package repo-structured delta ZIP to:
49-
`<project folder>/tmp/BUILD_PR_SAMPLES_INDEX_FIXES_AND_TARGETED_PREVIEW_RETRY_delta.zip`
29+
Output:
30+
- package repo-structured delta ZIP under <project folder>/tmp/
31+
- use docs/dev/reports for validation/report files

docs/dev/COMMIT_COMMENT.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +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".
1+
docs: add PLAN_PR for tools/shared normalization with engine-theme-first reuse priority
Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# BUILD_PR_TOOLS_THEME_REUSE_BASELINE - Changes Report
2+
3+
Date: 2026-04-11
4+
5+
## Files Changed
6+
- docs/pr/BUILD_PR_TOOLS_THEME_REUSE_BASELINE.md
7+
- tools/Asset Browser/assetBrowser.css
8+
- tools/Palette Browser/paletteBrowser.css
9+
- tools/Parallax Scene Studio/parallaxEditor.css
10+
- tools/Sprite Editor/spriteEditor.css
11+
- tools/Tilemap Studio/tileMapEditor.css
12+
- tools/Vector Asset Studio/svgBackgroundEditor.css
13+
- tools/Vector Map Editor/vectorMapEditor.css
14+
15+
## Implementation Summary
16+
- Added BUILD doc with exact target files, validation expectations, failure conditions, and exact ZIP output path.
17+
- Replaced tool-local hardcoded shell/theme colors with shared tokens already provided by engine/theme shell layers:
18+
- `--panel`, `--panel2`, `--line`, `--text`, `--muted`, `--accent`, `--surface-inline`, `--surface-code`
19+
- Removed redundant local root theme blocks (`:root`) from targeted tool CSS files.
20+
- Kept tool-specific layout and interaction styling intact (workspace grids, panel blocks, selection/preview-specific classes).
21+
- Did not modify tool JavaScript behavior.
22+
23+
## Explicit Non-Changes
24+
- No edits in `tools/SpriteEditor_old_keep/`.
25+
- No edits in `docs/dev/start_of_day/`.
26+
- No roadmap wording changes.
Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# BUILD_PR_TOOLS_THEME_REUSE_BASELINE - Validation Report
2+
3+
Date: 2026-04-11
4+
Branch: main
5+
6+
## Scope Checks
7+
- PASS: start_of_day directories unchanged (`git status --short -- docs/dev/start_of_day`)
8+
- PASS: `tools/SpriteEditor_old_keep` unchanged (`git status --short -- tools/SpriteEditor_old_keep`)
9+
- PASS: active tool targets limited to seven tool CSS files
10+
11+
## Static Contract Validation
12+
Command: Node import contract check on target tool `index.html` files.
13+
14+
Result:
15+
- PASS tools/Asset Browser/index.html
16+
- PASS tools/Palette Browser/index.html
17+
- PASS tools/Parallax Scene Studio/index.html
18+
- PASS tools/Sprite Editor/index.html
19+
- PASS tools/Tilemap Studio/index.html
20+
- PASS tools/Vector Asset Studio/index.html
21+
- PASS tools/Vector Map Editor/index.html
22+
23+
Verified required shared assets are referenced in each file:
24+
- `../../src/engine/ui/hubCommon.css`
25+
- `../shared/platformShell.css`
26+
- `../shared/platformShell.js`
27+
28+
## Static Layout Selector Validation
29+
Command: Node selector-presence check for key layout selectors in each touched CSS file.
30+
31+
Result:
32+
- PASS tools/Asset Browser/assetBrowser.css
33+
- PASS tools/Palette Browser/paletteBrowser.css
34+
- PASS tools/Parallax Scene Studio/parallaxEditor.css
35+
- PASS tools/Sprite Editor/spriteEditor.css
36+
- PASS tools/Tilemap Studio/tileMapEditor.css
37+
- PASS tools/Vector Asset Studio/svgBackgroundEditor.css
38+
- PASS tools/Vector Map Editor/vectorMapEditor.css
39+
40+
## Static Reference Existence Validation
41+
Command: Node link/src existence check for local `link[href]` and `script[src]` references in each target tool `index.html`.
42+
43+
Result:
44+
- PASS tools/Asset Browser/index.html
45+
- PASS tools/Palette Browser/index.html
46+
- PASS tools/Parallax Scene Studio/index.html
47+
- PASS tools/Sprite Editor/index.html
48+
- PASS tools/Tilemap Studio/index.html
49+
- PASS tools/Vector Asset Studio/index.html
50+
- PASS tools/Vector Map Editor/index.html
51+
52+
## Runtime Smoke Validation
53+
- Browser runtime smoke tests were NOT executed in this environment (no Playwright/Puppeteer installed).
54+
- Manual validation remains required for:
55+
- no console regressions
56+
- no shell/theme visual collapse
57+
- per-tool load confirmation in browser

docs/dev/reports/boundary_rules.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Tools Shared Boundary Rules
2+
3+
## Reuse Order
4+
1. `src/engine/theme/*`
5+
2. `src/engine/ui/*`
6+
3. `tools/shared/platformShell.css`
7+
4. tool-local CSS only for tool-specific concerns
8+
9+
## Allowed In `tools/shared`
10+
- shell chrome
11+
- common UI primitives
12+
- common IO
13+
- common preview helpers
14+
- vector helpers
15+
- project manifest / registry / validation helpers
16+
- shared panel/inspector utilities
17+
18+
## Forbidden In `tools/shared`
19+
- speculative abstractions without reuse proof
20+
- tool-specific editor state
21+
- tool-specific workflows
22+
- unique tool rendering logic
23+
- unique tool command sets
24+
- broad legacy carryover
25+
26+
## BUILD Discipline For Follow-up PRs
27+
- exact-cluster only
28+
- one purpose only
29+
- preserve `SpriteEditor_old_keep`
30+
- no engine-core broadening
31+
- no opportunistic CSS rewrites outside named scope
Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
DUPLICATION / NORMALIZATION CANDIDATES
2+
3+
Priority 1 — Theme / shell / layout reuse
4+
- generic layout rules duplicated across tool-local CSS
5+
- panel chrome / shell styling candidates should prefer:
6+
- src/engine/theme/*
7+
- src/engine/ui/baseLayout.css
8+
- src/engine/ui/hubCommon.css
9+
- tools/shared/platformShell.css only after engine reuse review
10+
11+
Priority 2 — Shared JS extraction candidates
12+
- platform shell bootstrap usage
13+
- preview-generation helpers
14+
- vector utility overlap
15+
- project manifest / registry helpers
16+
- validation helpers
17+
18+
Priority 3 — Tool-local residuals to preserve
19+
- Sprite Editor pixel-grid/editor specifics
20+
- Tilemap Studio tile-palette/map specifics
21+
- Vector Map Editor authoring specifics
22+
- Vector Asset Studio SVG-specific workflows
23+
- Parallax Scene Studio layer/timeline/editor specifics
24+
25+
Do not treat the following as immediate extraction candidates:
26+
- tool-exclusive render pipelines
27+
- unique editor interaction models
28+
- legacy/old_keep surfaces
Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
TOOLS/SHARED NORMALIZATION INVENTORY
2+
3+
Active tools discovered:
4+
- tools/Asset Browser
5+
- tools/Palette Browser
6+
- tools/Parallax Scene Studio
7+
- tools/Sprite Editor
8+
- tools/SpriteEditor_old_keep
9+
- tools/Tilemap Studio
10+
- tools/Vector Asset Studio
11+
- tools/Vector Map Editor
12+
13+
Existing shared tooling layer:
14+
- tools/shared/platformShell.js
15+
- tools/shared/platformShell.css
16+
- tools/shared/vector/vectorAssetBridge.js
17+
- tools/shared/vector/vectorAssetContract.js
18+
- tools/shared/vector/vectorGeometryMath.js
19+
- tools/shared/vector/vectorRenderPrep.js
20+
- tools/shared/projectSystem.js
21+
- tools/shared/projectSystemAdapters.js
22+
- tools/shared/projectSystemValueUtils.js
23+
- tools/shared/runtimeAssetLoader.js
24+
- tools/shared/runtimeAssetValidationUtils.js
25+
- tools/shared/renderPipelineContract.js
26+
- tools/shared/vectorAssetSystem.js
27+
28+
Observation:
29+
- The repo already has a meaningful `tools/shared` surface.
30+
- The next lane should normalize and constrain it rather than inventing a new shared layer from scratch.
Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# BUILD_PR_TOOLS_THEME_REUSE_BASELINE
2+
3+
## PR Purpose
4+
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.
5+
6+
## Scope Guardrails
7+
- Prioritize reuse of existing engine UI/theme assets (`src/engine/ui/hubCommon.css`, `tools/shared/platformShell.css`) before any expansion of tool-local CSS.
8+
- Touch active tools only:
9+
- `tools/Asset Browser/`
10+
- `tools/Palette Browser/`
11+
- `tools/Parallax Scene Studio/`
12+
- `tools/Sprite Editor/`
13+
- `tools/Tilemap Studio/`
14+
- `tools/Vector Asset Studio/`
15+
- `tools/Vector Map Editor/`
16+
- Keep `tools/SpriteEditor_old_keep/` unchanged.
17+
- Do not refactor tool-specific behavior.
18+
- Do not rewrite roadmap wording.
19+
- Do not touch `docs/dev/start_of_day/*`.
20+
21+
## Exact Target Files
22+
- `tools/Asset Browser/assetBrowser.css`
23+
- `tools/Palette Browser/paletteBrowser.css`
24+
- `tools/Parallax Scene Studio/parallaxEditor.css`
25+
- `tools/Sprite Editor/spriteEditor.css`
26+
- `tools/Tilemap Studio/tileMapEditor.css`
27+
- `tools/Vector Asset Studio/svgBackgroundEditor.css`
28+
- `tools/Vector Map Editor/vectorMapEditor.css`
29+
30+
## Execution Rules
31+
- Normalize shared shell/theme selectors to use existing shared tokens:
32+
- `--panel`, `--panel2`, `--line`, `--text`, `--muted`, `--accent`, `--surface-inline`, `--surface-code`
33+
- Keep layout structure intact (grid/flex sizing, section ordering, tool-specific panel structure).
34+
- No JavaScript behavior edits.
35+
36+
## Validation
37+
1. Contract check (static):
38+
- each touched tool `index.html` includes:
39+
- `../../src/engine/ui/hubCommon.css`
40+
- `../shared/platformShell.css`
41+
- `../shared/platformShell.js`
42+
2. Style check (static):
43+
- touched CSS files no longer introduce new root-level palette systems that duplicate shell tokens
44+
- touched CSS files keep layout selectors for workspace/shell intact
45+
3. Runtime smoke requirement:
46+
- each touched tool loads in browser with no console errors
47+
- no shell/theme visual collapse
48+
49+
## Failure Conditions
50+
Stop and report if:
51+
- scope expands beyond the exact files listed above
52+
- `tools/SpriteEditor_old_keep/` requires edits
53+
- start_of_day directories require edits
54+
- a touched tool cannot load after theme normalization
55+
56+
## Required Output
57+
- Validation report files under `docs/dev/reports/`
58+
- Repo-structured delta ZIP at exact path:
59+
- `tmp/BUILD_PR_TOOLS_THEME_REUSE_BASELINE_delta.zip`

0 commit comments

Comments
 (0)