Skip to content

Commit 0bbc34f

Browse files
author
DavidQ
committed
docs: plan advanced UX layer for promoted debug surfaces
1 parent 057da6f commit 0bbc34f

9 files changed

Lines changed: 296 additions & 45 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,17 @@ MODEL: GPT-5.4-codex
22
REASONING: high
33

44
COMMAND:
5-
Create BUILD_PR_DEBUG_SURFACES_PRESETS
5+
Create PLAN_PR_DEBUG_SURFACES_ADVANCED_UX
66

77
Requirements:
88
- Follow PLAN_PR -> BUILD_PR -> APPLY_PR
99
- Docs-first only
1010
- One PR per purpose
11-
- Build the first reusable presets system for promoted debug surfaces
12-
- Define authoritative target structure, shared preset inventory, preset commands, precedence rules with persistence, adoption modes, validation goals, and rollback strategy
11+
- Plan a reusable advanced UX layer for promoted debug surfaces
12+
- Define panel group infrastructure, quick toggles, macro registry/executor, optional shortcut helpers, command surfaces, naming conventions, and target structure
1313
- Keep the first version small and opt-in
14-
- Focus only on panel visibility and optional ordering
15-
- Exclude layout editors, docking systems, role permissions, 3D-specific, network-specific, and project-specific preset implementations from the shared layer
16-
- Use DebugPresetRegistry, DebugPresetApplier, registerStandardDebugPresets(), and registerPresetCommands()
14+
- Ensure macros compose only public APIs and approved commands/actions
15+
- Exclude layout editors, docking systems, 3D-specific, network-specific, and project-specific workflow implementations from the shared layer
1716
- Write outputs under docs/pr and docs/dev/reports
1817
- Put codex command and commit comment under docs/dev
19-
- Package to <project folder>/tmp/BUILD_PR_DEBUG_SURFACES_PRESETS_delta.zip
18+
- Package to <project folder>/tmp/PLAN_PR_DEBUG_SURFACES_ADVANCED_UX_delta.zip

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
docs: build reusable debug surfaces presets bundle with authoritative registry/applier and preset command contracts
1+
docs: plan advanced UX layer for debug surfaces with public-API-only macro composition and opt-in groups/toggles/shortcuts

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
11
Next:
2-
APPLY_PR_DEBUG_SURFACES_PRESETS
2+
BUILD_PR_DEBUG_SURFACES_ADVANCED_UX

‎docs/dev/reports/change_summary.txt‎

Lines changed: 16 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,29 @@
1-
BUILD_PR_DEBUG_SURFACES_PRESETS change summary
1+
PLAN_PR_DEBUG_SURFACES_ADVANCED_UX change summary
22

33
Summary
4-
- Produced docs-only BUILD bundle for the first reusable debug surfaces presets system.
5-
- Defined authoritative structure, inventory, commands, precedence, adoption modes, validation goals, and rollback strategy.
4+
- Refined docs-only plan bundle for advanced debug surfaces UX.
5+
- Kept one PR purpose: advanced UX planning only.
66
- Kept v1 small and opt-in.
77

8-
Key inclusions
9-
- required components: `DebugPresetRegistry`, `DebugPresetApplier`, `registerStandardDebugPresets()`, `registerPresetCommands()`
10-
- shared preset inventory: minimal/gameplay/rendering/systems/qa
11-
- shared preset commands: help/list/current/apply/reset
12-
- precedence with persistence formally defined
8+
Plan now defines
9+
- panel group infrastructure
10+
- quick toggles
11+
- macro registry/executor with hard public-API composition rules
12+
- optional shortcut helpers
13+
- command surfaces
14+
- naming conventions
15+
- target structure
1316

1417
Scope controls preserved
15-
- visibility and optional ordering only
16-
- excluded: layout editors, docking systems, role permissions, 3D-specific, network-specific, and project-specific shared implementations
18+
- excludes layout editors, docking systems, 3D-specific, network-specific, and project-specific shared workflow implementations
1719

1820
Outputs
19-
- docs/pr/PLAN_PR_DEBUG_SURFACES_PRESETS.md
20-
- docs/pr/BUILD_PR_DEBUG_SURFACES_PRESETS.md
21-
- docs/pr/APPLY_PR_DEBUG_SURFACES_PRESETS.md
21+
- docs/pr/PLAN_PR_DEBUG_SURFACES_ADVANCED_UX.md
2222
- docs/dev/codex_commands.md
2323
- docs/dev/commit_comment.txt
2424
- docs/dev/reports/change_summary.txt
2525
- docs/dev/reports/validation_checklist.txt
2626
- docs/dev/reports/file_tree.txt
27+
28+
Next recommended command
29+
- BUILD_PR_DEBUG_SURFACES_ADVANCED_UX

‎docs/dev/reports/file_tree.txt‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,7 @@
11
HTML-JavaScript-Gaming/
22
|-- docs/
33
| |-- pr/
4-
| | |-- PLAN_PR_DEBUG_SURFACES_PRESETS.md
5-
| | |-- BUILD_PR_DEBUG_SURFACES_PRESETS.md
6-
| | `-- APPLY_PR_DEBUG_SURFACES_PRESETS.md
4+
| | `-- PLAN_PR_DEBUG_SURFACES_ADVANCED_UX.md
75
| `-- dev/
86
| |-- codex_commands.md
97
| |-- commit_comment.txt
@@ -12,4 +10,4 @@ HTML-JavaScript-Gaming/
1210
| |-- validation_checklist.txt
1311
| `-- file_tree.txt
1412
`-- tmp/
15-
`-- BUILD_PR_DEBUG_SURFACES_PRESETS_delta.zip
13+
`-- PLAN_PR_DEBUG_SURFACES_ADVANCED_UX_delta.zip

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 17 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,31 @@
1-
BUILD_PR_DEBUG_SURFACES_PRESETS validation checklist
1+
PLAN_PR_DEBUG_SURFACES_ADVANCED_UX validation checklist
22

33
Workflow
4-
- [done] PLAN_PR -> BUILD_PR -> APPLY_PR structure preserved
4+
- [done] PLAN_PR -> BUILD_PR -> APPLY_PR structure referenced
55
- [done] Docs-first only
66
- [done] One PR per purpose
77

8-
Build Content
9-
- [done] Authoritative target structure defined
10-
- [done] Shared preset inventory defined
11-
- [done] Shared preset commands defined
12-
- [done] Precedence with persistence defined
13-
- [done] Adoption modes defined
14-
- [done] Validation goals defined
15-
- [done] Rollback strategy defined
16-
- [done] Required components explicitly included
8+
Plan Content
9+
- [done] Panel group infrastructure defined
10+
- [done] Quick toggles defined
11+
- [done] Macro registry/executor defined
12+
- [done] Optional shortcut helpers defined
13+
- [done] Command surfaces defined
14+
- [done] Naming conventions defined
15+
- [done] Target structure defined
16+
- [done] Macros constrained to public APIs and approved commands/actions
1717

1818
Scope Controls
1919
- [done] v1 remains small and opt-in
20-
- [done] Scope limited to panel visibility and optional ordering
21-
- [done] layout editors excluded
22-
- [done] docking systems excluded
23-
- [done] role permissions excluded
20+
- [done] layout editor scope excluded
21+
- [done] docking system scope excluded
2422
- [done] 3D-specific scope excluded
2523
- [done] network-specific scope excluded
26-
- [done] project-specific shared implementations excluded
24+
- [done] project-specific shared workflow implementations excluded
2725

2826
Outputs
29-
- [done] Docs under docs/pr
30-
- [done] Reports under docs/dev/reports
27+
- [done] Plan doc under docs/pr
3128
- [done] Codex command under docs/dev
3229
- [done] Commit comment under docs/dev
33-
- [done] Delta zip generated at <project folder>/tmp/BUILD_PR_DEBUG_SURFACES_PRESETS_delta.zip
30+
- [done] Reports under docs/dev/reports
31+
- [done] Delta zip generated at <project folder>/tmp/PLAN_PR_DEBUG_SURFACES_ADVANCED_UX_delta.zip

‎docs/pr/APPLY_PR_DEBUG_SURFACES_ADVANCED_UX.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# APPLY_PR_DEBUG_SURFACES_ADVANCED_UX
2+
3+
## Purpose
4+
5+
Apply the approved advanced UX plan by creating the first reusable panel groups, quick toggles, macros, and optional shortcut helpers for the promoted debug surfaces platform.
6+
7+
## Apply Scope
8+
9+
### Create Shared Group Infrastructure
10+
- panel group registry
11+
- shared panel group registrations
12+
- group commands
13+
14+
### Create Shared Macro Infrastructure
15+
- macro registry
16+
- macro executor
17+
- shared macro registrations
18+
- macro commands
19+
20+
### Create Shared Toggle Helpers
21+
- quick toggle commands
22+
23+
### Create Optional Shortcut Helpers
24+
- optional debug shortcut registration
25+
26+
### Keep Local
27+
- project-specific macros
28+
- project-specific shortcuts
29+
- scene-specific workflow helpers
30+
- tool-specific workflow helpers
31+
32+
## Apply Rules
33+
34+
- keep adoption opt-in
35+
- preserve public API boundaries
36+
- macros compose approved public commands/actions only
37+
- shortcut registration remains optional and debug-only
38+
- validate through sample and tool integrations

‎docs/pr/BUILD_PR_DEBUG_SURFACES_ADVANCED_UX.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# BUILD_PR_DEBUG_SURFACES_ADVANCED_UX
2+
3+
## Purpose
4+
5+
Turn the advanced UX plan into a docs-only build bundle for Codex.
6+
7+
## Build Scope
8+
9+
Define:
10+
11+
- panel group infrastructure
12+
- quick toggle command set
13+
- macro registry/execution model
14+
- optional shortcut registration
15+
- shared advanced UX inventory
16+
- adoption patterns
17+
- validation rules
18+
19+
## Required Deliverables
20+
21+
- authoritative target tree
22+
- group inventory
23+
- macro inventory
24+
- toggle inventory
25+
- command inventory
26+
- adoption models
27+
- validation checklist
28+
- rollback notes
29+
- codex command
30+
- commit comment
31+
- next command
32+
33+
## Build Rules
34+
35+
- one PR purpose only
36+
- docs-first only
37+
- keep the initial advanced UX layer small
38+
- macros compose public APIs only
39+
- shortcuts remain optional
40+
- no layout systems
41+
- no 3D/network-specific workflow logic

‎docs/pr/PLAN_PR_DEBUG_SURFACES_ADVANCED_UX.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
# PLAN_PR_DEBUG_SURFACES_ADVANCED_UX
2+
3+
## Objective
4+
Plan a reusable advanced UX layer for promoted debug surfaces that improves operator speed while remaining small, opt-in, and boundary-safe.
5+
6+
## Workflow
7+
PLAN_PR -> BUILD_PR -> APPLY_PR
8+
9+
## PR Purpose
10+
One PR purpose only: advanced UX planning for debug surfaces.
11+
12+
## Scope
13+
In scope:
14+
- panel group infrastructure
15+
- quick toggles
16+
- macro registry + macro executor
17+
- optional shortcut helpers
18+
- command surfaces
19+
- naming conventions
20+
- target structure
21+
22+
Out of scope:
23+
- implementation in this PR
24+
- layout editors
25+
- docking systems
26+
- 3D-specific UX
27+
- network-specific UX
28+
- project-specific workflow implementations in shared layer
29+
30+
## Design Constraints
31+
- docs-first only
32+
- keep v1 small and opt-in
33+
- preserve Dev Console (command/control) and Debug Overlay (telemetry/visual) separation
34+
- macros compose only public APIs and approved commands/actions
35+
36+
## Advanced UX Components (v1)
37+
### Panel Group Infrastructure
38+
Purpose:
39+
- register reusable panel groups and apply group visibility actions.
40+
41+
Planned shared contracts:
42+
- `DebugPanelGroupRegistry`
43+
- `registerStandardPanelGroups()`
44+
45+
Initial shared groups:
46+
- `group.systems`
47+
- `group.rendering`
48+
- `group.scene`
49+
- `group.input`
50+
- `group.qa`
51+
52+
### Quick Toggles
53+
Purpose:
54+
- fast common workflow switches without manual multi-command sequences.
55+
56+
Initial shared toggles:
57+
- `toggle.overlay`
58+
- `toggle.minimal`
59+
- `toggle.systems`
60+
- `toggle.rendering`
61+
62+
### Macro Registry + Executor
63+
Purpose:
64+
- run named macro workflows composed from approved commands/actions.
65+
66+
Planned shared contracts:
67+
- `DebugMacroRegistry`
68+
- `DebugMacroExecutor`
69+
- `registerStandardDebugMacros()`
70+
71+
Initial shared macros:
72+
- `macro.minimal.focus`
73+
- `macro.qa.start`
74+
- `macro.render.inspect`
75+
- `macro.scene.inspect`
76+
77+
Macro composition rules (hard):
78+
1. Macros may call only approved public commands/actions.
79+
2. Macros may not call private runtime/overlay internals.
80+
3. Macros may not mutate panel objects directly.
81+
4. Macro execution reports must be deterministic and structured.
82+
83+
### Optional Shortcut Helpers
84+
Purpose:
85+
- optional debug-only shortcut binding helpers for groups/macros/toggles.
86+
87+
Planned shared contracts:
88+
- `registerDebugShortcutBindings()`
89+
90+
Rules:
91+
- optional opt-in registration only
92+
- no mandatory global bindings
93+
- no shortcut logic in engine-core
94+
95+
## Command Surface (v1)
96+
### Group Commands
97+
- `group.list`
98+
- `group.show <groupId>`
99+
- `group.hide <groupId>`
100+
- `group.toggle <groupId>`
101+
102+
### Macro Commands
103+
- `macro.list`
104+
- `macro.show <macroId>`
105+
- `macro.run <macroId>`
106+
107+
### Toggle Commands
108+
- `toggle.overlay`
109+
- `toggle.minimal`
110+
- `toggle.systems`
111+
- `toggle.rendering`
112+
113+
## Naming Conventions
114+
- Group IDs: `group.<domain>` (example: `group.rendering`)
115+
- Macro IDs: `macro.<domain>.<action>` (example: `macro.render.inspect`)
116+
- Toggle commands: `toggle.<name>`
117+
- Shared IDs must be generic and reusable (no project-specific names)
118+
119+
## Target Structure
120+
```text
121+
engine/
122+
debug/
123+
advanced/
124+
groups/
125+
DebugPanelGroupRegistry.js
126+
registerStandardPanelGroups.js
127+
macros/
128+
DebugMacroRegistry.js
129+
DebugMacroExecutor.js
130+
registerStandardDebugMacros.js
131+
toggles/
132+
registerQuickToggleCommands.js
133+
shortcuts/
134+
registerDebugShortcutBindings.js
135+
```
136+
137+
Project/sample/tool workflow implementations remain outside shared tree.
138+
139+
## Adoption Models
140+
### Minimal Adoption
141+
- register one panel group
142+
- register one quick toggle
143+
- optional macro commands
144+
145+
### Standard Adoption
146+
- register shared groups/macros/toggles
147+
- optional shortcut helper registration
148+
149+
### Hybrid Adoption
150+
- register shared advanced UX pieces
151+
- extend with project-local groups/macros/shortcuts outside shared layer
152+
153+
## Validation Strategy
154+
- registry/command surfaces register deterministically
155+
- groups and toggles operate through public APIs only
156+
- macro execution enforces approved composition boundaries
157+
- optional shortcuts remain optional and debug-only
158+
- project-specific workflow implementations remain outside shared layer
159+
160+
## Risk Controls
161+
- keep v1 narrow to groups/toggles/macros/optional shortcuts
162+
- block private API access from macros
163+
- keep shared inventory generic
164+
- defer complex UX systems to separate tracks
165+
166+
## Rollout Notes
167+
1. This PLAN PR is docs-only.
168+
2. BUILD PR defines authoritative implementation inventory and acceptance checks.
169+
3. APPLY PR implements incrementally: groups -> toggles -> macros -> optional shortcuts.
170+
4. Excluded scopes require separate PR tracks.
171+
172+
## Next Commands
173+
1. `BUILD_PR_DEBUG_SURFACES_ADVANCED_UX`
174+
2. `APPLY_PR_DEBUG_SURFACES_ADVANCED_UX`

0 commit comments

Comments
 (0)