Skip to content

Commit 057da6f

Browse files
author
DavidQ
committed
docs: build reusable presets plan for promoted debug surfaces
1 parent e7911f5 commit 057da6f

9 files changed

Lines changed: 219 additions & 202 deletions

‎docs/dev/CODEX_COMMANDS.md‎

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

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

77
Requirements:
88
- Follow PLAN_PR -> BUILD_PR -> APPLY_PR
99
- Docs-first only
1010
- One PR per purpose
11-
- Plan a reusable presets system for promoted debug surfaces
12-
- Define preset registry, preset applier, shared baseline presets, preset commands, precedence with persistence, adoption models, naming conventions, and target structure
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
1313
- Keep the first version small and opt-in
1414
- Focus only on panel visibility and optional ordering
15-
- Exclude layout editors, docking systems, 3D-specific, network-specific, and project-specific preset implementations from the shared layer
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()
1617
- Write outputs under docs/pr and docs/dev/reports
1718
- Put codex command and commit comment under docs/dev
18-
- Package to <project folder>/tmp/PLAN_PR_DEBUG_SURFACES_PRESETS_delta.zip
19+
- Package to <project folder>/tmp/BUILD_PR_DEBUG_SURFACES_PRESETS_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: plan reusable debug surfaces presets system with registry/applier contracts and persistence precedence
1+
docs: build reusable debug surfaces presets bundle with authoritative registry/applier and preset command contracts

‎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-
BUILD_PR_DEBUG_SURFACES_PRESETS
2+
APPLY_PR_DEBUG_SURFACES_PRESETS

‎docs/dev/reports/change_summary.txt‎

Lines changed: 12 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,26 @@
1-
PLAN_PR_DEBUG_SURFACES_PRESETS change summary
1+
BUILD_PR_DEBUG_SURFACES_PRESETS change summary
22

33
Summary
4-
- Refined docs-only presets planning bundle.
5-
- Kept one PR purpose: presets planning only.
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.
66
- Kept v1 small and opt-in.
77

8-
Plan now defines
9-
- preset registry contract
10-
- preset applier contract
11-
- shared baseline preset inventory
12-
- preset command surface
13-
- authoritative precedence with persistence
14-
- adoption models
15-
- naming conventions
16-
- target structure
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
1713

1814
Scope controls preserved
19-
- focus limited to panel visibility and optional ordering
20-
- excludes layout editors, docking systems, 3D-specific, network-specific, deep-inspector, and project-specific shared implementations
15+
- visibility and optional ordering only
16+
- excluded: layout editors, docking systems, role permissions, 3D-specific, network-specific, and project-specific shared implementations
2117

2218
Outputs
2319
- 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
2422
- docs/dev/codex_commands.md
2523
- docs/dev/commit_comment.txt
2624
- docs/dev/reports/change_summary.txt
2725
- docs/dev/reports/validation_checklist.txt
2826
- docs/dev/reports/file_tree.txt
29-
30-
Next recommended command
31-
- BUILD_PR_DEBUG_SURFACES_PRESETS

‎docs/dev/reports/file_tree.txt‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
HTML-JavaScript-Gaming/
22
|-- docs/
33
| |-- pr/
4-
| | `-- PLAN_PR_DEBUG_SURFACES_PRESETS.md
4+
| | |-- PLAN_PR_DEBUG_SURFACES_PRESETS.md
5+
| | |-- BUILD_PR_DEBUG_SURFACES_PRESETS.md
6+
| | `-- APPLY_PR_DEBUG_SURFACES_PRESETS.md
57
| `-- dev/
68
| |-- codex_commands.md
79
| |-- commit_comment.txt
@@ -10,4 +12,4 @@ HTML-JavaScript-Gaming/
1012
| |-- validation_checklist.txt
1113
| `-- file_tree.txt
1214
`-- tmp/
13-
`-- PLAN_PR_DEBUG_SURFACES_PRESETS_delta.zip
15+
`-- BUILD_PR_DEBUG_SURFACES_PRESETS_delta.zip

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,33 @@
1-
PLAN_PR_DEBUG_SURFACES_PRESETS validation checklist
1+
BUILD_PR_DEBUG_SURFACES_PRESETS validation checklist
22

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

8-
Plan Content
9-
- [done] Preset registry defined
10-
- [done] Preset applier defined
11-
- [done] Shared baseline presets defined
12-
- [done] Preset commands defined
8+
Build Content
9+
- [done] Authoritative target structure defined
10+
- [done] Shared preset inventory defined
11+
- [done] Shared preset commands defined
1312
- [done] Precedence with persistence defined
14-
- [done] Adoption models defined
15-
- [done] Naming conventions defined
16-
- [done] Target structure defined
13+
- [done] Adoption modes defined
14+
- [done] Validation goals defined
15+
- [done] Rollback strategy defined
16+
- [done] Required components explicitly included
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 editor scope excluded
22-
- [done] docking scope excluded
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
2324
- [done] 3D-specific scope excluded
2425
- [done] network-specific scope excluded
2526
- [done] project-specific shared implementations excluded
2627

2728
Outputs
28-
- [done] Plan doc under docs/pr
29+
- [done] Docs under docs/pr
30+
- [done] Reports under docs/dev/reports
2931
- [done] Codex command under docs/dev
3032
- [done] Commit comment under docs/dev
31-
- [done] Reports under docs/dev/reports
32-
- [done] Delta zip generated at <project folder>/tmp/PLAN_PR_DEBUG_SURFACES_PRESETS_delta.zip
33+
- [done] Delta zip generated at <project folder>/tmp/BUILD_PR_DEBUG_SURFACES_PRESETS_delta.zip

‎docs/pr/APPLY_PR_DEBUG_SURFACES_PRESETS.md‎

Lines changed: 23 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,27 @@
11
# APPLY_PR_DEBUG_SURFACES_PRESETS
22

3-
## Purpose
4-
5-
Apply the approved presets plan by creating the first reusable preset system and shared baseline presets for the promoted debug surfaces platform.
3+
## Objective
4+
Apply the approved presets build as a focused implementation PR with no expansion beyond the v1 preset scope.
65

76
## Apply Scope
8-
9-
### Create Shared Preset Infrastructure
10-
- preset registry
11-
- preset applier
12-
- preset commands
13-
14-
### Create Shared Presets
15-
- gameplay
16-
- rendering
17-
- systems
18-
- minimal
19-
- qa
20-
21-
### Keep Local
22-
- project-specific presets
23-
- scene-specific startup choices
24-
- tool-specific preset extensions
25-
26-
## Apply Rules
27-
28-
- keep adoption opt-in
29-
- preserve public API boundaries
30-
- define clear persistence precedence
31-
- do not introduce layout editing features
32-
- validate through sample and tool integrations
7+
- implement `DebugPresetRegistry`
8+
- implement `DebugPresetApplier`
9+
- implement `registerStandardDebugPresets()` with v1 shared inventory
10+
- implement `registerPresetCommands()` with v1 command set
11+
12+
## Guardrails
13+
- keep v1 to visibility + optional ordering
14+
- use public APIs only
15+
- keep project-specific presets outside shared layer
16+
- preserve precedence with persistence exactly as defined
17+
- no excluded scope features
18+
19+
## Apply Validation
20+
- preset registry/applier functions pass deterministic behavior checks
21+
- shared preset inventory loads and applies
22+
- preset command set works with safe failures
23+
- precedence with persistence is correct
24+
- no project-specific preset implementation leaks into shared layer
25+
26+
## Expected Outcome
27+
A small, opt-in presets system for promoted debug surfaces is ready with clear extension boundaries.

‎docs/pr/BUILD_PR_DEBUG_SURFACES_PRESETS.md‎

Lines changed: 111 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,121 @@
11
# BUILD_PR_DEBUG_SURFACES_PRESETS
22

3-
## Purpose
3+
## Objective
4+
Build an authoritative docs-only bundle for the first reusable presets system for promoted debug surfaces.
45

5-
Turn the presets plan into a docs-only build bundle for Codex.
6+
## Workflow
7+
PLAN_PR -> BUILD_PR -> APPLY_PR
68

7-
## Build Scope
9+
## Build Constraints
10+
- docs-first only
11+
- one PR purpose only
12+
- first version is small and opt-in
13+
- visibility + optional ordering only
14+
- no feature expansion beyond preset infrastructure and baseline presets
815

9-
Define:
16+
## Required Shared Components
17+
- `DebugPresetRegistry`
18+
- `DebugPresetApplier`
19+
- `registerStandardDebugPresets()`
20+
- `registerPresetCommands()`
1021

11-
- preset registry structure
12-
- preset application flow
13-
- initial shared preset inventory
14-
- preset commands
15-
- precedence rules with persistence
16-
- adoption patterns
17-
- validation rules
22+
## Authoritative Target Structure
23+
```text
24+
engine/
25+
debug/
26+
presets/
27+
DebugPresetRegistry.js
28+
DebugPresetApplier.js
29+
standard/
30+
presets/
31+
registerStandardDebugPresets.js
32+
preset.minimal.js
33+
preset.gameplay.js
34+
preset.rendering.js
35+
preset.systems.js
36+
preset.qa.js
37+
commands/
38+
registerPresetCommands.js
39+
```
1840

19-
## Required Deliverables
41+
## Shared Preset Inventory (v1)
42+
- `preset.minimal`
43+
- `preset.gameplay`
44+
- `preset.rendering`
45+
- `preset.systems`
46+
- `preset.qa`
2047

21-
- authoritative target tree
22-
- preset inventory
23-
- command inventory
24-
- precedence rules
25-
- adoption models
26-
- validation checklist
27-
- rollback notes
28-
- codex command
29-
- commit comment
30-
- next command
48+
Preset content scope:
49+
- `panels.enabled[]`
50+
- `panels.disabled[]`
51+
- `panels.order[]` (optional)
3152

32-
## Build Rules
53+
## Preset Commands (v1)
54+
- `preset.help`
55+
- `preset.list`
56+
- `preset.current`
57+
- `preset.apply <presetId>`
58+
- `preset.reset`
3359

34-
- one PR purpose only
35-
- docs-first only
36-
- keep the initial preset system small
37-
- start with panel visibility and optional ordering only
38-
- no docking/layout editor features
39-
- no project-specific presets in shared layer
60+
## Registration Pattern
61+
1. `registerStandardDebugPresets()` registers shared preset descriptors.
62+
2. `registerPresetCommands()` registers shared `preset.*` commands.
63+
3. Commands resolve presets via `DebugPresetRegistry`.
64+
4. Apply flows execute via `DebugPresetApplier` only.
65+
66+
Rules:
67+
- deterministic registration and lookup
68+
- public APIs only
69+
- no direct panel object mutation from command handlers
70+
71+
## Precedence Rules with Persistence (authoritative)
72+
1. Base registry panel defaults.
73+
2. Persisted panel state restore.
74+
3. Explicit `preset.apply` override.
75+
4. Subsequent explicit operator panel commands.
76+
77+
Save behavior:
78+
- after successful `preset.apply`, persist resulting panel state snapshot.
79+
80+
## Adoption Modes
81+
- Minimal: registry + applier + 1 shared preset (+ optional commands)
82+
- Standard: full shared preset set + shared preset commands
83+
- Hybrid: shared presets plus project-local presets outside shared layer
84+
85+
## Exclusions (hard)
86+
- layout editors
87+
- docking systems
88+
- role permissions
89+
- 3D-specific preset content
90+
- network-specific preset content
91+
- project-specific preset implementations in shared layer
92+
93+
## Validation Goals
94+
- registry accepts and lists shared presets deterministically
95+
- applier applies visibility/ordering deterministically
96+
- unknown panel IDs are ignored safely
97+
- commands route through registry/applier only
98+
- persistence precedence behaves as defined
99+
- minimal and standard adoption both validate
100+
101+
## Rollback Strategy
102+
If v1 is unstable or too broad:
103+
1. keep structure and core component names intact
104+
2. reduce preset inventory to `preset.minimal` + one focused preset
105+
3. preserve command surface and precedence rules
106+
4. revalidate minimal adoption before expansion
107+
108+
## Rollout Notes
109+
- BUILD bundle is docs-only and implementation-ready
110+
- APPLY should proceed incrementally: registry -> applier -> shared presets -> preset commands
111+
- do not expand scope into excluded areas in this track
112+
113+
## Deliverables
114+
- `docs/pr/PLAN_PR_DEBUG_SURFACES_PRESETS.md`
115+
- `docs/pr/BUILD_PR_DEBUG_SURFACES_PRESETS.md`
116+
- `docs/pr/APPLY_PR_DEBUG_SURFACES_PRESETS.md`
117+
- `docs/dev/codex_commands.md`
118+
- `docs/dev/commit_comment.txt`
119+
- `docs/dev/reports/change_summary.txt`
120+
- `docs/dev/reports/validation_checklist.txt`
121+
- `docs/dev/reports/file_tree.txt`

0 commit comments

Comments
 (0)