Skip to content

Commit 65df45a

Browse files
author
DavidQ
committed
Complete tool alignment and header real-estate reduction
- audited header real-estate usage across primary tools - reduced wasted header space where feasible - aligned shared cross-tool behaviors where applicable - documented before/after differences and validation evidence - preserved unrelated working-tree changes PR Details - advances `reduce screen real estate used by headers` from [ ] to [x] - advances `align functionality across tools where applicable` from [ ] to [x]
1 parent f331505 commit 65df45a

13 files changed

Lines changed: 456 additions & 88 deletions

‎docs/dev/reports/BUILD_PR_LEVEL_21_4_TOOL_ALIGNMENT_AND_HEADER_REAL_ESTATE_HEADER_REAL_ESTATE_AUDIT.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# BUILD_PR_LEVEL_21_4_TOOL_ALIGNMENT_AND_HEADER_REAL_ESTATE_HEADER_REAL_ESTATE_AUDIT
2+
3+
## Baseline Inputs Used
4+
- `docs/dev/reports/BUILD_PR_LEVEL_21_2_TOOL_TESTING_DOCUMENTATION_AND_REPORT_STANDARDIZATION_TOOL_INVENTORY.md`
5+
- `docs/dev/reports/BUILD_PR_LEVEL_21_3_TOOL_AUTOMATION_AND_TOOL_QUALITY_BASELINE_AUTOMATION_MATRIX.md`
6+
- `docs/dev/reports/tool_known_bugs.md`
7+
- `docs/dev/reports/tool_missing_functionality.md`
8+
9+
## Prioritization Rationale
10+
- Highest-value lane from 21.3: shared cross-tool shell alignment and compacting header chrome.
11+
- Single shared shell (`tools/shared/platformShell.js` + `tools/shared/platformShell.css`) applies to all primary tools and yields the largest bounded reduction in vertical waste without per-tool feature rewrites.
12+
13+
## In-Scope Tool Surfaces
14+
- Asset Browser
15+
- Palette Browser
16+
- Parallax Scene Studio
17+
- Sprite Editor
18+
- Tilemap Studio
19+
- Vector Asset Studio
20+
- Vector Map Editor
21+
- Tool Host
22+
- Additional shared-shell consumers: 3D Asset Viewer, 3D Camera Path Editor, 3D Map Editor, Performance Profiler, Physics Sandbox, Replay Visualizer, State Inspector, Tile Model Converter, Asset Pipeline Tool, Tools Index
23+
24+
## Header Real-Estate Changes (Shared Shell)
25+
| Surface | Before | After | Result |
26+
| --- | --- | --- | --- |
27+
| Header container spacing | host margin `16px auto` | host margin `10px auto` | Reduced top/bottom chrome footprint |
28+
| Header frame padding | `18px 20px` | `12px 14px` | Reduced vertical and horizontal overhead |
29+
| Header mode | always-open details pattern | collapsible accordion with persisted state (`toolboxaid.toolsPlatform.headerExpanded`) | Tool pages default compact; full controls still accessible |
30+
| Header controls row | large-pill minimum heights (`36px` / `34px`) | compact-pill minimum heights (`30px` / `28px`) | Reduced action row height and wrap pressure |
31+
| Header metadata text | larger text (`0.95rem`) | compact text (`0.85rem`) | Less vertical crowding while preserving readability |
32+
| Status bar spacing | `12px 16px` padding | `8px 12px` padding | Lower baseline chrome height |
33+
34+
## Structure Audit (Before -> After)
35+
| Area | Before | After |
36+
| --- | --- | --- |
37+
| Accordion class contract | mixed, tool-specific class leakage (`palette-browser__accordion`) | shared shell-only class contract (`tools-platform-frame__accordion*`) |
38+
| Accordion icon rendering | mojibake glyph in shared shell markup | explicit entity (`▾`) with rotation state class |
39+
| Header summary | less informative compact row | summary includes active title + shell label + compact meta |
40+
| Tool Host label in shared shell | generic fallback labels | explicit `data-tool-title="Tool Host"` consumed by shell |
41+
42+
## Usability Guard
43+
- Controls were not removed; they are compacted and collapsible.
44+
- Full nav/actions/project controls remain in the expanded panel.
45+
- Tools launch smoke confirms no blocking load regressions after compaction/alignment.

‎docs/dev/reports/BUILD_PR_LEVEL_21_4_TOOL_ALIGNMENT_AND_HEADER_REAL_ESTATE_TOOL_ALIGNMENT_MATRIX.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# BUILD_PR_LEVEL_21_4_TOOL_ALIGNMENT_AND_HEADER_REAL_ESTATE_TOOL_ALIGNMENT_MATRIX
2+
3+
## Alignment Capability Matrix
4+
| Capability | Tools Affected | Previous Inconsistency | New Aligned Behavior | Evidence |
5+
| --- | --- | --- | --- | --- |
6+
| Shared compact header behavior | All shared-shell tools (primary set + shared-shell consumers) | Header chrome consumed high vertical space and remained expanded by default in tool pages. | Shared shell now supports compact accordion mode with persisted open/closed state; tool pages default to compact and can expand on demand. | `tools/shared/platformShell.js`, `tools/shared/platformShell.css`, `tests/tools/PlatformShellHeaderAlignment.test.mjs` |
7+
| Shared shell class contract | All shared-shell tools | Shell markup leaked tool-specific accordion classes (`palette-browser__accordion`). | Shell uses only `tools-platform-frame__accordion*` classes, eliminating tool-specific coupling in shared chrome. | `tools/shared/platformShell.js`, `tools/shared/platformShell.css` |
8+
| Shared action availability in non-landing tools | Tool Host + all existing tool-id pages | Shared action links required a tool id, so Tool Host had no aligned shared action row. | Non-landing surfaces now render shared action links with fallback source id (`tool-host`) when a tool id is unavailable. | `tools/shared/platformShell.js` (`renderSharedActionLinks`) |
9+
| Shared shell labeling for Tool Host | Tool Host | Generic fallback shell labels (not explicit tool surface label). | Tool Host now provides `data-tool-title="Tool Host"` and shell consumes it for title/status consistency. | `tools/Tool Host/index.html`, `tools/shared/platformShell.js` |
10+
11+
## Primary Tool Set Coverage
12+
| Tool | Shared Compact Header | Shared Action Row Alignment | Tool Label Alignment |
13+
| --- | --- | --- | --- |
14+
| Asset Browser | Yes | Yes | Via registry tool label |
15+
| Palette Browser | Yes | Yes | Via registry tool label |
16+
| Parallax Scene Studio | Yes | Yes | Via registry tool label |
17+
| Sprite Editor | Yes | Yes | Via registry tool label |
18+
| Tilemap Studio | Yes | Yes | Via registry tool label |
19+
| Vector Asset Studio | Yes | Yes | Via registry tool label |
20+
| Vector Map Editor | Yes | Yes | Via registry tool label |
21+
| Tool Host | Yes | Yes (fallback source id) | Yes (`data-tool-title`) |
22+
23+
## Notes
24+
- This PR intentionally does not claim panel docking/resizing completion.
25+
- This PR intentionally does not claim full repo-wide control placement normalization outside shared shell scope.

‎docs/dev/reports/BUILD_PR_LEVEL_21_4_TOOL_ALIGNMENT_AND_HEADER_REAL_ESTATE_VALIDATION.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# BUILD_PR_LEVEL_21_4_TOOL_ALIGNMENT_AND_HEADER_REAL_ESTATE_VALIDATION
2+
3+
## Commands Run
4+
1. `node --input-type=module -` (targeted tool tests)
5+
- `tests/tools/RequiredToolsBaseline.test.mjs`
6+
- `tests/tools/ToolEntryLaunchContract.test.mjs`
7+
- `tests/tools/ToolsIndexRegistrySmoke.test.mjs`
8+
- `tests/tools/PlatformShellHeaderAlignment.test.mjs`
9+
2. `node ./tests/runtime/LaunchSmokeAllEntries.test.mjs --tools`
10+
3. `git status --short -- docs/dev/start_of_day`
11+
12+
## Results
13+
| Validation | Result | Evidence |
14+
| --- | --- | --- |
15+
| Tool contract/index tests | PASS | all four targeted tests passed |
16+
| Shared header/alignment contract test | PASS | `PASS ./tests/tools/PlatformShellHeaderAlignment.test.mjs` |
17+
| Tools launch smoke | PASS | `PASS=17 FAIL=0 TOTAL=17` |
18+
| No start_of_day modifications | PASS | clean `git status -- docs/dev/start_of_day` |
19+
20+
## Scope Guard Checks
21+
- One PR purpose maintained: shared tool header real-estate reduction + cross-tool shared-shell alignment.
22+
- No unrelated feature expansion performed.
23+
- No roadmap rewrite performed.
24+
25+
## Roadmap Status Decision (Execution-Backed)
26+
Applied:
27+
- `reduce screen real estate used by headers` `[ ] -> [x]`
28+
- `align functionality across tools where applicable` `[ ] -> [x]`
29+
30+
Not applied:
31+
- `normalize tool layout and spacing`
32+
- `improve panel resizing and docking behavior`
33+
- `ensure consistent control placement across tools`
34+
35+
Reason:
36+
- These optional items were not fully completed repo-wide in this PR.

‎docs/dev/reports/change_summary.txt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
1-
This bundle combines the next safe adjacent tools lanes so one execution pass can advance more roadmap items:
2-
automation coverage, known bugs baselining, and missing-functionality baselining.
1+
This bundle combines the next safe tools lanes into one execution pass:
2+
header compaction and shared functionality alignment based on the 21.3 quality baseline.

‎docs/dev/reports/launch_smoke_report.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Launch Smoke Report
22

3-
Generated: 2026-04-18T20:04:42.559Z
3+
Generated: 2026-04-18T20:18:40.966Z
44

55
Filters: games=false, samples=false, tools=true, sampleRange=all
66

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 5 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,8 @@
1-
- [ ] automation added where feasible
2-
- [ ] automation pass executed
3-
- [ ] automation coverage and blockers documented
4-
- [ ] known bugs register created/updated
5-
- [ ] each bug includes severity
6-
- [ ] each bug includes reproduction steps
7-
- [ ] each bug includes owner or resolution path
8-
- [ ] missing functionality matrix created/updated
9-
- [ ] expected vs current behavior documented
10-
- [ ] priorities assigned to gaps
1+
- [ ] header real-estate audit completed
2+
- [ ] in-scope tool headers compacted where feasible
3+
- [ ] before/after differences documented
4+
- [ ] shared cross-tool behaviors aligned where applicable
5+
- [ ] alignment matrix completed
116
- [ ] no start_of_day changes
127
- [ ] unrelated working-tree changes preserved
138
- [ ] roadmap updated only for completed items

‎docs/dev/roadmaps/MASTER_ROADMAP_TOOLS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Track all tool-related improvements, gaps, and future work.
1515
---
1616

1717
## 2. UI / UX Improvements
18-
- [ ] reduce screen real estate used by headers
18+
- [x] reduce screen real estate used by headers
1919
- [ ] normalize tool layout and spacing
2020
- [ ] improve panel resizing and docking behavior
2121
- [ ] ensure consistent control placement across tools
@@ -34,7 +34,7 @@ Track all tool-related improvements, gaps, and future work.
3434
- [x] identify gaps in each tool
3535
- [x] define expected vs current behavior
3636
- [x] prioritize missing features
37-
- [ ] align functionality across tools where applicable
37+
- [x] align functionality across tools where applicable
3838

3939
---
4040

‎docs/pr/BUILD_PR_LEVEL_21_4_TOOL_ALIGNMENT_AND_HEADER_REAL_ESTATE.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# BUILD_PR_LEVEL_21_4_TOOL_ALIGNMENT_AND_HEADER_REAL_ESTATE
2+
3+
## Purpose
4+
Execute the next combined safe tools lane by using the 21.3 tool-quality baseline to drive two adjacent, compatible work streams in one PR:
5+
6+
- reduce real estate used by headers
7+
- align functionality across tools where applicable
8+
9+
This PR should convert the cross-tool gaps and shared UI inconsistencies found in the baseline into a concrete, validated alignment pass.
10+
11+
## Combined roadmap intent
12+
This PR may advance the following items only if fully executed and validated:
13+
14+
### UI / UX Improvements
15+
- `reduce screen real estate used by headers` `[ ] -> [x]`
16+
17+
### Missing Functionality
18+
- `align functionality across tools where applicable` `[ ] -> [x]`
19+
20+
### Optional additional advancement
21+
If this PR also fully completes all remaining UI/UX items through real execution and validation, it may additionally advance:
22+
- `normalize tool layout and spacing` `[ ] -> [x]`
23+
- `improve panel resizing and docking behavior` `[ ] -> [x]`
24+
- `ensure consistent control placement across tools` `[ ] -> [x]`
25+
26+
Do **not** update those optional items unless they are truly completed and validated in this same PR.
27+
28+
## Scope
29+
Included:
30+
- use the 21.3 bug/gap baseline as the source of truth for shared tool inconsistencies
31+
- reduce header height, spacing, and vertical waste across primary tools where feasible
32+
- standardize shared header behavior/patterns across tools
33+
- align common tool capabilities where those capabilities should behave consistently
34+
- normalize obvious shared control placement differences where tied directly to the header/alignment pass
35+
- produce before/after validation evidence
36+
- preserve unrelated working-tree changes
37+
38+
Excluded:
39+
- no speculative new tools
40+
- no unrelated feature expansion
41+
- no broad design rewrite beyond the aligned header/capability pass
42+
- no roadmap rewrites
43+
- no `start_of_day` changes
44+
45+
## Baseline inputs
46+
Use:
47+
- tool UAT inventory from 21.2
48+
- automation / bugs / missing functionality outputs from 21.3
49+
50+
If the 21.3 baseline identifies a subset of tools as highest-value for alignment, prioritize those first and record the prioritization rationale.
51+
52+
## Primary tool set
53+
At minimum evaluate:
54+
- Asset Browser
55+
- Palette Browser
56+
- Parallax Scene Studio
57+
- Sprite Editor
58+
- Tilemap Studio
59+
- Vector Asset Studio
60+
- Vector Map Editor
61+
- Tool Host
62+
63+
Also include additional tools where the shared header/layout system applies cleanly.
64+
65+
## Required outputs
66+
Codex must create/update:
67+
68+
- `docs/dev/reports/BUILD_PR_LEVEL_21_4_TOOL_ALIGNMENT_AND_HEADER_REAL_ESTATE_HEADER_REAL_ESTATE_AUDIT.md`
69+
- `docs/dev/reports/BUILD_PR_LEVEL_21_4_TOOL_ALIGNMENT_AND_HEADER_REAL_ESTATE_TOOL_ALIGNMENT_MATRIX.md`
70+
- `docs/dev/reports/BUILD_PR_LEVEL_21_4_TOOL_ALIGNMENT_AND_HEADER_REAL_ESTATE_VALIDATION.md`
71+
72+
If useful for validation evidence:
73+
- before/after screenshots or report references
74+
- shared pattern notes describing the normalized header/control model
75+
76+
## Header real-estate requirements
77+
For each in-scope tool:
78+
- record current header structure
79+
- reduce unnecessary vertical usage where possible
80+
- preserve usability and discoverability
81+
- avoid hiding critical controls unless replaced with a clearly better compact pattern
82+
83+
Examples of valid changes:
84+
- compact header rows
85+
- accordion/collapsible secondary sections
86+
- reduced padding/margins
87+
- merged redundant labels/containers
88+
- shared toolbar patterns
89+
90+
## Alignment requirements
91+
For each aligned cross-tool capability, document:
92+
- capability name
93+
- tools affected
94+
- previous inconsistency
95+
- new aligned behavior
96+
- validation proof
97+
98+
Examples of likely alignment candidates:
99+
- load/open controls
100+
- save/export controls
101+
- project/sample picker placement
102+
- preview/run controls
103+
- header action grouping
104+
- compact toolbar behavior
105+
106+
## Acceptance
107+
- header real estate is reduced for in-scope tools
108+
- aligned cross-tool behaviors are documented and validated
109+
- before/after differences are explicit
110+
- no unrelated regressions introduced
111+
- unrelated working-tree changes are preserved
112+
- roadmap updates are status-only and execution-backed
113+
114+
## Validation requirements
115+
Validation must confirm:
116+
- header audit completed
117+
- alignment matrix completed
118+
- in-scope tools updated and validated
119+
- no `start_of_day` changes
120+
- unrelated working-tree changes preserved
121+
- roadmap edits limited to items fully completed here
122+
123+
## Roadmap update rules
124+
Only update status markers in:
125+
- `docs/dev/roadmaps/MASTER_ROADMAP_TOOLS.md`
126+
127+
Allowed transitions only if fully executed and validated:
128+
- `reduce screen real estate used by headers` `[ ] -> [x]`
129+
- `align functionality across tools where applicable` `[ ] -> [x]`
130+
131+
Optional additional transitions only if fully completed and validated in this PR:
132+
- `normalize tool layout and spacing` `[ ] -> [x]`
133+
- `improve panel resizing and docking behavior` `[ ] -> [x]`
134+
- `ensure consistent control placement across tools` `[ ] -> [x]`

‎tests/run-tests.mjs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,7 @@ import { run as runRuntimeAssetLookupConsolidation } from './tools/RuntimeAssetL
105105
import { run as runRuntimeAssetValidation } from './tools/RuntimeAssetValidation.test.mjs';
106106
import { run as runToolEntryLaunchContract } from './tools/ToolEntryLaunchContract.test.mjs';
107107
import { run as runToolsIndexRegistrySmoke } from './tools/ToolsIndexRegistrySmoke.test.mjs';
108+
import { run as runPlatformShellHeaderAlignment } from './tools/PlatformShellHeaderAlignment.test.mjs';
108109
import { run as runProjectPackagingSystem } from './tools/ProjectPackagingSystem.test.mjs';
109110
import { run as runRuntimeAssetLoader } from './tools/RuntimeAssetLoader.test.mjs';
110111
import { run as runEditorExperienceLayer } from './tools/EditorExperienceLayer.test.mjs';
@@ -236,6 +237,7 @@ const tests = [
236237
['RuntimeAssetValidation', runRuntimeAssetValidation],
237238
['ToolEntryLaunchContract', runToolEntryLaunchContract],
238239
['ToolsIndexRegistrySmoke', runToolsIndexRegistrySmoke],
240+
['PlatformShellHeaderAlignment', runPlatformShellHeaderAlignment],
239241
['ProjectPackagingSystem', runProjectPackagingSystem],
240242
['RuntimeAssetLoader', runRuntimeAssetLoader],
241243
['EditorExperienceLayer', runEditorExperienceLayer],

‎tests/tools/PlatformShellHeaderAlignment.test.mjs‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
import assert from "node:assert/strict";
2+
import { readFileSync } from "node:fs";
3+
import path from "node:path";
4+
import { fileURLToPath } from "node:url";
5+
6+
const REPO_ROOT = fileURLToPath(new URL("../..", import.meta.url));
7+
8+
export async function run() {
9+
const shellJsPath = path.join(REPO_ROOT, "tools", "shared", "platformShell.js");
10+
const shellCssPath = path.join(REPO_ROOT, "tools", "shared", "platformShell.css");
11+
const toolHostHtmlPath = path.join(REPO_ROOT, "tools", "Tool Host", "index.html");
12+
13+
const shellJs = readFileSync(shellJsPath, "utf8");
14+
const shellCss = readFileSync(shellCssPath, "utf8");
15+
const toolHostHtml = readFileSync(toolHostHtmlPath, "utf8");
16+
17+
assert.match(shellJs, /HEADER_EXPANDED_STORAGE_KEY = "toolboxaid\.toolsPlatform\.headerExpanded"/);
18+
assert.match(shellJs, /HEADER_EXPANDED_FALLBACK_TOOL = "tool-host"/);
19+
assert.match(shellJs, /class="tools-platform-frame__accordion"/);
20+
assert.match(shellJs, /class="tools-platform-frame__accordion-summary"/);
21+
assert.match(shellJs, /renderSharedActionLinks\(currentTool\?\.id \?\? ""\)/);
22+
assert.match(shellJs, /document\.body\.dataset\.toolTitle/);
23+
24+
assert.match(shellCss, /\.tools-platform-frame__accordion-summary/);
25+
assert.match(shellCss, /\.tools-platform-frame__accordion-content/);
26+
assert.match(shellCss, /\.tools-platform-frame__summary-meta/);
27+
assert.match(shellCss, /\.tools-platform-frame__accordion-icon/);
28+
29+
assert.match(toolHostHtml, /data-tool-title="Tool Host"/);
30+
}

0 commit comments

Comments
 (0)