Skip to content

Commit 5e9ea48

Browse files
ToolboxAidToolboxAid
committed
Unify active tools under shared engine theme and complete final platform surface integration.
1 parent dec9f74 commit 5e9ea48

11 files changed

Lines changed: 290 additions & 127 deletions

‎docs/dev/CODEX_COMMANDS.md‎

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

44
COMMAND:
5-
Create BUILD_PR_VECTOR_PLATFORM_SURFACE_POLISH as a surgical tools-surface implementation PR.
5+
Create BUILD_PR_ENGINE_THEME_FINAL_PLATFORM_INTEGRATION as a single combined build PR.
66

7-
OBJECTIVE:
8-
Make the `tools/` folder first-class and visually unified by adding a shared platform shell and registry-driven active tools surface for:
9-
- Vector Map Editor
10-
- Vector Asset Studio
11-
- Tile Map Editor
12-
- Parallax Editor
7+
GOAL:
8+
Finish the active tools platform in the fewest remaining steps by making all first-class tools use the engine theme and closing remaining platform-surface integration gaps.
139

14-
PRESERVE:
15-
- legacy Sprite Editor under preserved pathing such as `tools/SpritEditor_old_keep/`
16-
- existing unique editor workspaces per tool
17-
- current repo boundaries; do not modify engine/game runtime code
10+
DO:
11+
1. Identify the existing engine theme source of truth
12+
2. Normalize/extract a reusable shared theme contract only if needed
13+
3. Apply the engine theme to all active tools under tools/
14+
- Vector Map Editor
15+
- Vector Asset Studio
16+
- Tile Map Editor
17+
- Parallax Editor
18+
4. Unify shared shell/surface elements across active tools
19+
5. Ensure active tools surface/index/navigation reflects only active tools
20+
6. Preserve but exclude tools/SpritEditor_old_keep from active tool listings
21+
7. Fix broken paths/imports/assets caused by the consolidation if encountered
22+
8. Validate active tool loading and visual consistency
1823

19-
IMPLEMENT:
20-
1. Add/update a first-class tools landing surface.
21-
2. Generate active tool entries from the canonical tool registry.
22-
3. Add a lightweight shared platform CSS/JS layer for header/nav/status/workspace chrome.
23-
4. Apply the shared shell to all active tools.
24-
5. Normalize visible labels/actions across active tools.
25-
6. Exclude legacy Sprite Editor from active tools surface.
26-
7. Validate all renamed paths and remove stale references.
27-
28-
GUARDRAILS:
29-
- no destructive deletes
30-
- no framework migration
31-
- no gameplay/runtime engine changes
32-
- no ad hoc duplicated tool menus in multiple files
33-
- keep changes small, readable, and reversible
24+
DO NOT:
25+
- delete legacy Sprite content
26+
- invent a second theme system
27+
- perform unrelated refactors
28+
- split into multiple PRs unless a true blocker is discovered
3429

3530
OUTPUT:
36-
<project folder>/tmp/BUILD_PR_VECTOR_PLATFORM_SURFACE_POLISH.zip
31+
<project folder>/tmp/BUILD_PR_ENGINE_THEME_FINAL_PLATFORM_INTEGRATION.zip

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Polish tools platform surface with a shared shell, registry-driven active-tool navigation, and unified first-class labels while preserving Sprite Editor outside the active surface.
1+
Complete final active-tools platform integration by rebasing the shared shell onto the engine theme, preserving registry-driven navigation, and excluding preserved sprite tooling from the first-class surface.

‎docs/dev/reports/change_summary.txt‎

Lines changed: 14 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,16 @@
1-
BUILD PR bundle prepared for vector platform surface polish.
1+
BUILD_PR_ENGINE_THEME_FINAL_PLATFORM_INTEGRATION
22

3-
Planned implementation summary:
4-
- establish `tools/` as a first-class product surface
5-
- add a shared platform shell for active tools
6-
- drive active tool menus/listings from one canonical registry
7-
- normalize naming, labels, and common actions across active tools
8-
- preserve legacy Sprite Editor outside the active tools surface
9-
- validate rename/path integrity and remove stale references
3+
Summary:
4+
- makes engine theme mandatory for all active first-class tools
5+
- combines remaining theme/surface integration into one build PR
6+
- preserves legacy Sprite editor while excluding it from active tool surface
7+
- aims to finish platform polish in the fewest possible remaining steps
108

11-
Included bundle artifacts:
12-
- PR spec
13-
- Codex command
14-
- commit comment
15-
- change summary
16-
- validation checklist
17-
- file tree
9+
Active tools in scope:
10+
- tools/Vector Map Editor/
11+
- tools/Vector Asset Studio/
12+
- tools/Tile Map Editor/
13+
- tools/Parallax Editor/
14+
15+
Legacy preserved:
16+
- tools/SpritEditor_old_keep/

‎docs/dev/reports/file_tree.txt‎

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
1-
BUILD_PR_VECTOR_PLATFORM_SURFACE_POLISH/
2-
docs/
3-
pr/
4-
BUILD_PR_VECTOR_PLATFORM_SURFACE_POLISH.md
5-
dev/
6-
codex_commands.md
7-
commit_comment.txt
8-
reports/
9-
change_summary.txt
10-
validation_checklist.txt
11-
file_tree.txt
1+
docs/
2+
pr/
3+
BUILD_PR_ENGINE_THEME_FINAL_PLATFORM_INTEGRATION.md
4+
dev/
5+
codex_commands.md
6+
commit_comment.txt
7+
reports/
8+
change_summary.txt
9+
validation_checklist.txt
10+
file_tree.txt

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 14 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,14 @@
1-
[ ] Tools landing page exists and is clearly first-class
2-
[ ] Active tools list is generated from canonical registry
3-
[ ] Only approved active tools appear on landing page
4-
[ ] Legacy Sprite Editor does not appear in active tools menu
5-
[ ] Vector Map Editor uses shared platform shell
6-
[ ] Vector Asset Studio uses shared platform shell
7-
[ ] Tile Map Editor uses shared platform shell
8-
[ ] Parallax Editor uses shared platform shell
9-
[ ] Current tool title matches canonical naming in every active tool
10-
[ ] Home/back-to-tools affordance works in every active tool
11-
[ ] Common actions use normalized wording
12-
[ ] No visible references to `Sprite Editor V3`
13-
[ ] No broken asset/script/style paths introduced
14-
[ ] No engine/game runtime files modified
15-
[ ] Legacy preserved folder remains intact
1+
BUILD_PR_ENGINE_THEME_FINAL_PLATFORM_INTEGRATION Validation Checklist
2+
3+
[ ] Engine theme source of truth identified
4+
[ ] Shared theme contract reusable by active tools
5+
[ ] Vector Map Editor uses engine theme
6+
[ ] Vector Asset Studio uses engine theme
7+
[ ] Tile Map Editor uses engine theme
8+
[ ] Parallax Editor uses engine theme
9+
[ ] Shared shell/surface behavior consistent across active tools
10+
[ ] Active tool list excludes SpritEditor_old_keep
11+
[ ] No stale deprecated tool-name references remain on active surface
12+
[ ] No broken imports/paths/assets introduced by theme consolidation
13+
[ ] Active tools load without obvious console/runtime errors
14+
[ ] Final visual result reads as one coherent platform

‎docs/pr/BUILD_PR_ENGINE_THEME_FINAL_PLATFORM_INTEGRATION.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# BUILD_PR_ENGINE_THEME_FINAL_PLATFORM_INTEGRATION
2+
3+
## Purpose
4+
Finish the active tools platform by making the engine theme the single visual source of truth for the first-class tools surface and by closing the remaining shared-shell integration gaps in one combined build PR.
5+
6+
## Engine Theme Source Of Truth
7+
- `engine/ui/hubCommon.css` is the existing engine theme source of truth
8+
- no second theme system was introduced
9+
- no additional theme extraction layer was required beyond consuming the existing engine variables from the shared tools shell
10+
11+
## First-Class Active Tools
12+
- `tools/Vector Map Editor/`
13+
- `tools/Vector Asset Studio/`
14+
- `tools/Tilemap Studio/`
15+
- `tools/Parallax Scene Studio/`
16+
17+
## Preserved But Excluded
18+
- `tools/SpriteEditor_old_keep/` remains preserved on disk
19+
- `tools/Sprite Editor/` remains on disk but is not promoted in the active tools landing page or shared navigation
20+
- preserved sprite paths are excluded from the registry-driven active surface
21+
22+
## Scope Implemented
23+
- rebased the shared tools shell onto the engine theme tokens from `hubCommon.css`
24+
- kept the active tools landing page and active-tool navigation registry-driven
25+
- kept the four active tool workspaces intact while standardizing the shell, header, nav, and status chrome around them
26+
- added validation for engine-theme stylesheet presence and shared-shell presence on active tool pages
27+
- kept path fixes and repo changes limited to the active tools platform surface
28+
29+
## Modules Created Or Changed
30+
- `tools/shared/platformShell.css`
31+
- `tools/shared/platformShell.js`
32+
- `tools/index.html`
33+
- `tools/renderToolsIndex.js`
34+
- `scripts/validate-active-tools-surface.mjs`
35+
- `docs/pr/BUILD_PR_ENGINE_THEME_FINAL_PLATFORM_INTEGRATION.md`
36+
- `docs/dev/COMMIT_COMMENT.txt`
37+
38+
## Public Surface Boundaries
39+
- `engine/ui/hubCommon.css` supplies the theme variables and shared visual tokens
40+
- `tools/shared/platformShell.css` consumes those tokens for platform chrome only
41+
- `tools/shared/platformShell.js` renders the shared shell from the canonical tool registry
42+
- `tools/toolRegistry.js` remains the source of truth for active-tool visibility and navigation
43+
- tool-specific editor logic and engine/game runtime code were not modified for this PR
44+
45+
## Implementation Summary
46+
- converted the shared shell from a hardcoded standalone palette to the engine theme variables already defined in `hubCommon.css`
47+
- kept the landing page and the four first-class tools visually aligned through the same shared shell
48+
- made the landing surface explicitly communicate that it is engine-themed and registry-driven
49+
- preserved the active tool list as the approved four-tool surface only
50+
- kept preserved sprite content excluded from the first-class tools platform
51+
52+
## Validation Performed
53+
- `node --check tools/toolRegistry.js`
54+
- `node --check tools/renderToolsIndex.js`
55+
- `node --check tools/shared/platformShell.js`
56+
- `node --check scripts/validate-active-tools-surface.mjs`
57+
- `node --check tools/Vector Asset Studio/main.js`
58+
- `node --check tools/Tilemap Studio/main.js`
59+
- `node --check tools/Parallax Scene Studio/main.js`
60+
- `node --check tools/Vector Map Editor/main.js`
61+
- `node scripts/validate-active-tools-surface.mjs`
62+
63+
## Validation Summary
64+
- active tool pages still load the engine theme stylesheet from `engine/ui/hubCommon.css`
65+
- active tool pages still load the shared shell stylesheet and module
66+
- the landing page loads the engine theme and shared shell
67+
- only the approved four tools appear in the active registry-driven surface
68+
- preserved sprite tooling does not appear in active landing or navigation output
69+
- stale deprecated sprite-rename references remain blocked by the validator
70+
71+
## Follow-Up Recommendations
72+
- keep future first-class tool visual changes routed through `hubCommon.css` tokens and `tools/shared/platformShell.css`
73+
- keep future active-tool additions gated through `tools/toolRegistry.js` and the same validator
74+
- avoid reintroducing bespoke shell palettes on per-tool pages

‎scripts/validate-active-tools-surface.mjs‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ const SCAN_TARGETS = [
2525
"tools/renderToolsIndex.js",
2626
"tools/shared/platformShell.js",
2727
"tools/shared/platformShell.css",
28-
"docs/pr/BUILD_PR_VECTOR_PLATFORM_SURFACE_POLISH.md",
28+
"docs/pr/BUILD_PR_ENGINE_THEME_FINAL_PLATFORM_INTEGRATION.md",
2929
"docs/dev/commit_comment.txt"
3030
];
3131

@@ -34,6 +34,13 @@ const NAVIGATION_SURFACE_TARGETS = [
3434
"tools/renderToolsIndex.js"
3535
];
3636

37+
const ACTIVE_TOOL_ENTRYPOINTS = [
38+
"tools/Vector Asset Studio/index.html",
39+
"tools/Tilemap Studio/index.html",
40+
"tools/Parallax Scene Studio/index.html",
41+
"tools/Vector Map Editor/index.html"
42+
];
43+
3744
async function pathExists(targetPath) {
3845
try {
3946
await fs.access(targetPath);
@@ -100,6 +107,30 @@ async function main() {
100107
}
101108
}
102109

110+
for (const target of ACTIVE_TOOL_ENTRYPOINTS) {
111+
const text = await readText(target);
112+
if (!text.includes("../../engine/ui/hubCommon.css")) {
113+
issues.push(`Engine theme stylesheet missing from active tool page: ${target}`);
114+
}
115+
if (!text.includes("../shared/platformShell.css")) {
116+
issues.push(`Shared platform shell stylesheet missing from active tool page: ${target}`);
117+
}
118+
if (!text.includes("../shared/platformShell.js")) {
119+
issues.push(`Shared platform shell module missing from active tool page: ${target}`);
120+
}
121+
}
122+
123+
const toolsLandingPage = await readText("tools/index.html");
124+
if (!toolsLandingPage.includes("../engine/ui/hubCommon.css")) {
125+
issues.push("Engine theme stylesheet missing from tools landing page.");
126+
}
127+
if (!toolsLandingPage.includes("./shared/platformShell.css")) {
128+
issues.push("Shared platform shell stylesheet missing from tools landing page.");
129+
}
130+
if (!toolsLandingPage.includes("./shared/platformShell.js")) {
131+
issues.push("Shared platform shell module missing from tools landing page.");
132+
}
133+
103134
if (issues.length > 0) {
104135
console.error("ACTIVE_TOOLS_SURFACE_INVALID");
105136
issues.forEach((issue) => console.error(`- ${issue}`));

‎tools/index.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@
2323

2424
<section class="hero">
2525
<h1>ToolboxAid - Active Tools</h1>
26-
<p class="subtitle">Registry-driven tooling surface for vector maps, vector assets, tile maps, and parallax scenes. Preserved legacy editors stay on disk without appearing in the first-class navigation.</p>
26+
<p class="subtitle">Registry-driven tooling surface for vector maps, vector assets, tile maps, and parallax scenes, all framed by the shared engine theme from <code>engine/ui/hubCommon.css</code>. Preserved legacy editors stay on disk without appearing in the first-class navigation.</p>
2727
</section>
2828

2929
<section>

‎tools/renderToolsIndex.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ function renderToolCard(tool) {
1616
<p>${escapeHtml(tool.description)}</p>
1717
<div class="meta">
1818
<span class="pill live">Active Tool</span>
19-
<span class="pill planned">Registry Driven</span>
19+
<span class="pill planned">Engine Theme</span>
2020
</div>
2121
</div>
2222
`;

0 commit comments

Comments
 (0)