Skip to content

Commit e1c645d

Browse files
author
DavidQ
committed
Stabilize tool UX and remove silent fallback behavior
- Fix Vector Map Editor startup/selection behavior - Restore reliable paint/fill and stroke control behavior - Improve State Inspector JSON empty/error handling - Replace silent fallback data with actionable messages - Tighten fullscreen header sizing and add data-tool-id for diagnostics
1 parent 75279b7 commit e1c645d

9 files changed

Lines changed: 637 additions & 172 deletions

File tree

‎docs/dev/codex_commands.md‎

Lines changed: 51 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,60 @@
11
MODEL: GPT-5.3-codex
22
REASONING: low
33

4-
Apply tool header standardization:
4+
PR purpose:
5+
Stabilize existing tools only. Do not add new features.
56

6-
- Replace all fullscreen tool headers with:
7+
Priority:
8+
1. Fix Vector Map Editor default selection behavior first.
9+
2. Fix paint/fill and stroke controls.
10+
3. Improve State Inspector JSON usability.
11+
4. Remove silent fallback data.
12+
5. Apply header polish follow-up.
13+
14+
Hard rules:
15+
- Do not use silent fallback data.
16+
- Do not auto-load hidden/default sample assets.
17+
- Do not add safe fallback behavior that hides missing tool configuration.
18+
- If required data or configuration is missing, show an actionable error message.
19+
- Do not modify start_of_day folders.
20+
- Do not modify sample games or unrelated engine runtime files.
21+
22+
Header follow-up:
23+
- Keep fullscreen header single-line format:
724
<Tool Name> — <Short Description>
25+
- If tool.name or tool.shortDescription is missing, show an actionable configuration error.
26+
- Add hard max-width / nowrap / overflow hidden / text-overflow ellipsis.
27+
- Lock font size and line height.
28+
- Add data-tool-id to header DOM.
29+
30+
Vector Map Editor:
31+
- Make initial selection/mode explicit and visible.
32+
- Do not silently select an object.
33+
- Do not silently load default/sample data.
34+
- Show empty state when no map/manifest is loaded.
35+
- Confirm selection clears correctly.
836

9-
- Remove:
10-
- intro paragraphs
11-
- multi-line headers
37+
Paint / stroke:
38+
- Ensure fill/paint controls update selected editable objects.
39+
- Ensure stroke controls update selected editable objects.
40+
- Disable controls only when there is no valid selection.
41+
- Disabled controls must explain why.
1242

13-
- Ensure:
14-
- truncation with ellipsis if needed
15-
- tooltip shows full text
43+
State Inspector:
44+
- Format valid JSON.
45+
- Show clear parse errors for invalid JSON.
46+
- Show safe empty state for missing/empty state.
47+
- Do not inject sample state.
1648

17-
- Bind UI to:
18-
tool.name
19-
tool.shortDescription
49+
Validation:
50+
- Run node --check on changed JavaScript files.
51+
- Manually verify the four target tools:
52+
- Vector Map Editor
53+
- Vector Asset Studio
54+
- Sprite Editor
55+
- State Inspector
2056

21-
Target tools:
22-
- Vector Map Editor
23-
- Vector Asset Studio
24-
- Sprite Editor
25-
- State Inspector
57+
Report:
58+
- List changed files.
59+
- List validation commands/results.
60+
- Note any remaining issues without masking them.

‎docs/dev/commit_comment.txt‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
1-
Standardize fullscreen tool headers to single-line format
1+
Stabilize tool UX and remove silent fallback behavior
22

3-
- Enforces: <Tool Name> — <Short Description>
4-
- Removes multi-line headers and intro blocks
5-
- Improves workspace density and UX consistency
3+
- Fix Vector Map Editor startup/selection behavior
4+
- Restore reliable paint/fill and stroke control behavior
5+
- Improve State Inspector JSON empty/error handling
6+
- Replace silent fallback data with actionable messages
7+
- Tighten fullscreen header sizing and add data-tool-id for diagnostics

‎docs/dev/pr_tool_stabilization.md‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
# PR — Tool Stabilization
2+
3+
## Purpose
4+
5+
Stabilize the tool workspace so layout, asset, and inspection tools are reliable before building King of the Iceberg screens or gameplay maps.
6+
7+
This PR is stabilization only. Do not add new features.
8+
9+
---
10+
11+
## Priority Order
12+
13+
1. Vector Map Editor default selection issue
14+
2. Paint / stroke not working
15+
3. State Inspector JSON usability
16+
4. Remove silent fallback data
17+
5. Header polish follow-up from prior PR
18+
19+
---
20+
21+
## Scope
22+
23+
Target tools and shared code only:
24+
25+
- Vector Map Editor
26+
- Vector Asset Studio
27+
- Sprite Editor
28+
- State Inspector
29+
- Shared platform shell / registry code used by those tools
30+
31+
Do not modify sample games, runtime game engine files, or start_of_day folders.
32+
33+
---
34+
35+
## 1. Vector Map Editor Default Selection
36+
37+
### Problem
38+
39+
The Vector Map Editor should open in a predictable state and should not silently select the wrong tool, object, or default sample.
40+
41+
### Required Behavior
42+
43+
- On load, the active selection state must be explicit.
44+
- If no map, object, or manifest is loaded, show an empty-state message.
45+
- Do not silently load hidden/default sample assets.
46+
- Do not silently select an object that the user did not choose.
47+
- If a default editor mode is needed, use a visible neutral mode such as Select/Pan.
48+
- The UI must clearly show the active tool/mode.
49+
50+
### Validation
51+
52+
- Open Vector Map Editor fresh.
53+
- Confirm active mode is visible.
54+
- Confirm no hidden/default asset loads.
55+
- Confirm user can intentionally select map objects.
56+
- Confirm selection state clears correctly when no object is selected.
57+
58+
---
59+
60+
## 2. Paint / Stroke Not Working
61+
62+
### Problem
63+
64+
Paint and stroke controls must work consistently in the relevant asset/vector tools.
65+
66+
### Required Behavior
67+
68+
- Paint/fill controls must update the selected asset/object.
69+
- Stroke controls must update the selected asset/object.
70+
- Disabled controls must explain why they are disabled.
71+
- Controls must not appear editable when no valid target is selected.
72+
- Errors must be visible and actionable.
73+
74+
### Validation
75+
76+
- Select an editable object.
77+
- Change fill/paint value.
78+
- Confirm visual update.
79+
- Change stroke value.
80+
- Confirm visual update.
81+
- Deselect object.
82+
- Confirm controls disable with a useful message.
83+
84+
---
85+
86+
## 3. State Inspector JSON Usability
87+
88+
### Problem
89+
90+
The State Inspector must make JSON state easy to inspect and troubleshoot.
91+
92+
### Required Behavior
93+
94+
- JSON must be formatted/readable.
95+
- Invalid JSON must show a clear parse error.
96+
- Empty or missing state must show a safe empty state.
97+
- Do not inject fake/sample state.
98+
- Error messages must include enough information to help the user fix the input.
99+
100+
### Validation
101+
102+
- Load valid JSON and confirm formatted display.
103+
- Load invalid JSON and confirm clear parse error.
104+
- Load empty state and confirm empty-state message.
105+
- Confirm no silent fallback/sample data appears.
106+
107+
---
108+
109+
## 4. Remove Silent Fallback Data
110+
111+
### Rule
112+
113+
Silent fallback data is not allowed.
114+
115+
If required data is missing, invalid, or unavailable, the tool must show actionable information instead of inventing or loading hidden fallback content.
116+
117+
### Required Error Pattern
118+
119+
Use clear messages that identify:
120+
121+
- What is missing or invalid
122+
- Which tool/component detected it
123+
- What the user can do next
124+
- Any expected file/input shape, if known
125+
126+
### Examples
127+
128+
Good:
129+
130+
```txt
131+
Vector Map Editor cannot load a map because no map manifest was provided. Choose or create a map manifest to continue.
132+
```
133+
134+
Bad:
135+
136+
```txt
137+
Loaded default sample map.
138+
```
139+
140+
Good:
141+
142+
```txt
143+
State Inspector could not parse JSON at line 12: unexpected token. Fix the JSON and reload.
144+
```
145+
146+
Bad:
147+
148+
```txt
149+
Using empty sample state.
150+
```
151+
152+
---
153+
154+
## 5. Header Polish Follow-Up
155+
156+
From the prior header standardization PR, apply these refinements.
157+
158+
### Required Behavior
159+
160+
- Do NOT add a safe fallback that hides missing `shortDescription`.
161+
- If `tool.name` or `tool.shortDescription` is missing, show an actionable configuration error.
162+
- Apply hard max-width styling to prevent overflow.
163+
- Lock font size and line height for header consistency.
164+
- Add `data-tool-id` to the rendered header host/title for debugging and tests.
165+
166+
### CSS Requirements
167+
168+
- Header text remains one line.
169+
- Header text does not wrap.
170+
- Header text truncates with ellipsis.
171+
- Header text uses locked font size and line height.
172+
173+
### Validation
174+
175+
- Temporarily remove `shortDescription` from one target tool and confirm a useful configuration error appears.
176+
- Restore config.
177+
- Confirm single-line header still truncates cleanly.
178+
- Confirm `data-tool-id` exists in DOM.
179+
180+
---
181+
182+
## Acceptance Criteria
183+
184+
- No silent fallback data remains in the touched tools.
185+
- Missing/invalid input produces actionable messages.
186+
- Vector Map Editor opens in a clear, explicit state.
187+
- Paint/fill and stroke controls work for valid selected objects.
188+
- State Inspector handles valid, invalid, and empty JSON clearly.
189+
- Fullscreen headers remain compact and single-line.
190+
- Header CSS uses hard max width, locked font size, and locked line height.
191+
- Header DOM includes `data-tool-id`.
192+
- Existing validation commands pass.
193+
194+
---
195+
196+
## Out of Scope
197+
198+
- New tool features
199+
- New game screens
200+
- King of the Iceberg implementation
201+
- Tileset breakout
202+
- Runtime engine refactors
203+
- start_of_day folder changes

0 commit comments

Comments
 (0)