Skip to content

Commit f50bfb6

Browse files
author
DavidQ
committed
Define a docs-only integration plan for Sprite Editor palette authority and project/session lock behavior.
1 parent 1e95d54 commit f50bfb6

5 files changed

Lines changed: 226 additions & 92 deletions

File tree

‎CODEX_COMMANDS.md‎

Lines changed: 19 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -7,33 +7,29 @@ MODEL: GPT-5.4-codex
77
REASONING: high
88

99
COMMAND:
10-
Create BUILD_PR_SPRITE_EDITOR_USABILITY_POLISH.
10+
Create BUILD_PR_SPRITE_EDITOR_PROJECT_INTEGRATION.
1111

12-
Use docs/pr/PLAN_PR_SPRITE_EDITOR_USABILITY_POLISH.md as the approved plan source of truth.
12+
Use docs/pr/PLAN_PR_SPRITE_EDITOR_PROJECT_INTEGRATION.md as the approved plan source of truth.
1313

1414
Goal:
15-
Implement the approved usability-polish PR for the isolated Sprite Editor only.
15+
Implement a small, surgical Sprite Editor integration PR so palette flow uses engine authority and session/project lock rules.
1616

17-
Scope rules:
18-
1. Only implement the approved polish items from the plan.
19-
2. Do not expand scope beyond the approved plan.
20-
3. Do not review, modify, migrate, or delete any pre-existing sprite editor outside tools/Sprite Editor/
21-
4. Do not touch engine code or unrelated tools.
22-
5. Leave unrelated workspace modifications untouched.
23-
6. Preserve required file headers on all new files.
24-
7. Follow repo workflow and keep this PR small and surgical.
17+
Required integration rule:
18+
1. Sprite Editor must use engine paletteList as source of truth.
19+
2. Palette list is loaded from engine contract, not local hardcoded tool authority.
20+
3. Editing remains disabled until palette selected.
21+
4. Selected palette becomes locked for active project/session.
22+
5. Palette switching remains blocked unless explicit new/reset project flow is used.
23+
6. Lock behavior must match plan contracts for new project/load/import/resize/duplicate/save-load.
24+
7. No engine-boundary bypass and no duplicated palette authority inside tool.
2525

26-
Primary implementation targets:
27-
- Better tool-state visibility for active tool / active color / active frame
28-
- Keyboard shortcuts for approved actions from the plan
29-
- Undo/redo if approved in the plan
30-
- Clear resize/new-canvas behavior based on the approved contract
31-
- Better import/export feedback messaging
32-
- Improved recent-color swatch behavior
33-
- Preview panel polish for FPS / play / pause clarity
34-
- Optional status bar if approved in the plan
35-
- Mouse interaction polish for drag drawing reliability
36-
- Save/load UX cleanup
26+
Scope rules:
27+
- Do not review/modify legacy sprite editor implementations outside tools/Sprite Editor/
28+
- Keep scope small and surgical
29+
- Prefer public engine-facing contracts only
30+
- No unrelated engine/tool rewrites
31+
- Docs-first and one PR per purpose
32+
- Preserve file headers
3733

3834
Packaging:
39-
- tmp/BUILD_PR_SPRITE_EDITOR_USABILITY_POLISH_delta.zip
35+
- tmp/BUILD_PR_SPRITE_EDITOR_PROJECT_INTEGRATION_delta.zip

‎docs/dev/reports/change_summary.txt‎

Lines changed: 19 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -3,38 +3,25 @@ David Quesenberry
33
04/03/2026
44
change_summary.txt
55

6-
BUILD_PR target:
7-
Implement approved usability polish for the isolated Sprite Editor using PLAN_PR_SPRITE_EDITOR_USABILITY_POLISH as source of truth.
6+
PLAN_PR target:
7+
Define a docs-only integration plan for Sprite Editor palette authority and project/session lock behavior.
88

9-
Implemented areas:
10-
- tools/Sprite Editor/index.html
11-
- Added persistent state row for tool/color/frame/toggle/canvas+cursor status visibility
12-
- Added Undo/Redo controls
13-
- Updated preview controls to Play/Pause/Reset
14-
- Added usability hint text for shortcuts and resize/new-canvas behavior
15-
- tools/Sprite Editor/spriteEditor.css
16-
- Added state row and state pill styling
17-
- Added hint-text styling
18-
- Added touch-action guard on editor canvas for pointer reliability
19-
- tools/Sprite Editor/modules/constants.js
20-
- Added HISTORY_LIMIT for bounded undo/redo behavior
21-
- tools/Sprite Editor/modules/spriteEditorApp.js
22-
- Added keyboard shortcuts (P/E/F/G/O/[ / ] + Ctrl+Z/Ctrl+Y/Ctrl+Shift+Z)
23-
- Added bounded undo/redo stacks with UI controls
24-
- Added explicit resize/new-canvas behavior messaging
25-
- Added richer import/export/save/load feedback messages with file and size/frame context
26-
- Added improved recent-color handling/rendering consistency for transparent swatches
27-
- Added preview Play/Pause/Reset behavior and FPS status messages
28-
- Added status bar updates for canvas/zoom/frame/cursor
29-
- Added drag-stroke history-safe handling and pointer lifecycle reliability polish
30-
- tools/Sprite Editor/README.md
31-
- Documented usability behavior contracts and shortcuts
9+
Planned BUILD focus:
10+
- engine-authoritative palette source in Sprite Editor
11+
- disabled editing until palette selection
12+
- locked palette semantics for active project/session
13+
- palette reference persistence contract in project JSON
14+
- clear fallback behavior when engine palette source is unavailable
3215

33-
Docs/build artifacts:
34-
- docs/pr/BUILD_PR_SPRITE_EDITOR_USABILITY_POLISH.md
35-
- CODEX_COMMANDS.md
16+
Planned scope:
17+
- tools/Sprite Editor/** only for implementation
18+
- docs/reports for workflow outputs
19+
- no engine rewrites
20+
- no unrelated tools
21+
- no legacy sprite editor path modifications outside tools/Sprite Editor/
3622

37-
Scope guardrails honored:
38-
- No engine changes
39-
- No unrelated tool changes
40-
- No modifications to pre-existing sprite editor implementations outside tools/Sprite Editor/
23+
Boundary emphasis:
24+
- consume public engine palette contract only
25+
- do not duplicate palette authority in tool-local hardcoded catalog
26+
27+
This PLAN bundle is docs-only and includes no implementation code changes.

‎docs/dev/reports/file_tree.txt‎

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,10 @@ David Quesenberry
33
04/03/2026
44
file_tree.txt
55

6-
BUILD_PR_SPRITE_EDITOR_USABILITY_POLISH file tree
6+
PLAN_PR_SPRITE_EDITOR_PROJECT_INTEGRATION docs bundle file tree
77

88
CODEX_COMMANDS.md
9-
docs/pr/PLAN_PR_SPRITE_EDITOR_USABILITY_POLISH.md
10-
docs/pr/BUILD_PR_SPRITE_EDITOR_USABILITY_POLISH.md
9+
docs/pr/PLAN_PR_SPRITE_EDITOR_PROJECT_INTEGRATION.md
1110
docs/dev/reports/change_summary.txt
1211
docs/dev/reports/validation_checklist.txt
1312
docs/dev/reports/file_tree.txt
14-
tools/Sprite Editor/README.md
15-
tools/Sprite Editor/index.html
16-
tools/Sprite Editor/spriteEditor.css
17-
tools/Sprite Editor/modules/constants.js
18-
tools/Sprite Editor/modules/spriteEditorApp.js

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 25 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -3,35 +3,31 @@ David Quesenberry
33
04/03/2026
44
validation_checklist.txt
55

6-
BUILD_PR_SPRITE_EDITOR_USABILITY_POLISH validation checklist
6+
PLAN_PR_SPRITE_EDITOR_PROJECT_INTEGRATION checklist
77

8-
Scope and safety:
9-
[x] Changes limited to tools/Sprite Editor and docs/reports bundle files
10-
[x] No engine changes
11-
[x] No unrelated tool changes
12-
[x] No pre-existing sprite editor paths outside tools/Sprite Editor modified
8+
Docs bundle validation:
9+
[x] PLAN doc created at docs/pr/PLAN_PR_SPRITE_EDITOR_PROJECT_INTEGRATION.md
10+
[x] CODEX_COMMANDS.md updated for BUILD_PR_SPRITE_EDITOR_PROJECT_INTEGRATION
11+
[x] change_summary.txt updated
12+
[x] validation_checklist.txt updated
13+
[x] file_tree.txt updated
14+
[x] Bundle is docs-only (no implementation code changes)
1315

14-
Usability contracts:
15-
[x] Active tool/color/frame/toggle visibility row implemented
16-
[x] Status bar includes canvas size, zoom, frame, and cursor pixel coordinates
17-
[x] Keyboard shortcuts implemented: P, E, F, G, O, [, ], Ctrl+Z, Ctrl+Y, Ctrl+Shift+Z
18-
[x] Undo/redo controls and history stack implemented
19-
[x] New canvas behavior explicitly resets document with status messaging
20-
[x] Resize behavior explicitly preserves pixels with nearest-neighbor status messaging
21-
[x] Import/export/save/load feedback messages include file and dimension/frame context
22-
[x] Recent color swatches remain deduped/newest-first and transparent swatches are visually distinct
23-
[x] Preview controls clarified to Play/Pause/Reset and FPS messaging is explicit
24-
[x] Pointer drag reliability improved with stroke-history and pointer lifecycle handling
16+
Plan completeness validation:
17+
[x] Goals documented
18+
[x] In-scope / out-of-scope documented
19+
[x] Exact likely BUILD files documented
20+
[x] Engine palette integration contract documented
21+
[x] Disabled-until-selection behavior contract documented
22+
[x] Locked-palette behavior contract documented (including required operation cases)
23+
[x] Save/load palette reference contract documented
24+
[x] Manual validation checklist documented
25+
[x] BUILD command documented
26+
[x] Commit comment documented
27+
[x] Next command documented
2528

26-
Syntax checks:
27-
[x] node --check tools/Sprite Editor/modules/spriteEditorApp.js
28-
[x] node --check tools/Sprite Editor/modules/constants.js
29-
[x] node --check tools/Sprite Editor/main.js
30-
31-
Manual browser validation targets (for APPLY/QA pass):
32-
[ ] Open tools/Sprite Editor/index.html and confirm UI state row updates live
33-
[ ] Confirm all shortcuts perform expected actions
34-
[ ] Confirm undo/redo on draw/fill/frame/import/resize/new-canvas
35-
[ ] Confirm import/export/save/load messages in status panel
36-
[ ] Confirm preview play/pause/reset behavior and FPS feedback
37-
[ ] Confirm drag drawing remains reliable across fast pointer movement
29+
Boundary/risk validation:
30+
[x] No engine rewrite scope introduced
31+
[x] No unrelated tool scope introduced
32+
[x] No legacy sprite editor migration scope introduced
33+
[x] No destructive actions proposed

‎docs/pr/PLAN_PR_SPRITE_EDITOR_PROJECT_INTEGRATION.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/03/2026
4+
PLAN_PR_SPRITE_EDITOR_PROJECT_INTEGRATION.md
5+
6+
# PLAN_PR_SPRITE_EDITOR_PROJECT_INTEGRATION
7+
8+
## 1. Goals
9+
- Integrate isolated Sprite Editor with engine-authoritative palette flow.
10+
- Make engine palette list the single source of truth.
11+
- Enforce palette-gated editing and palette lock semantics for project/session consistency.
12+
- Define persistence contract for palette identity without duplicating palette authority.
13+
- Keep implementation small, boundary-safe, and compatible with future tool pipeline alignment.
14+
15+
## 2. In Scope / Out of Scope
16+
In scope:
17+
- Sprite Editor integration planning for engine palette contract consumption.
18+
- Disabled-until-palette-selected UX and locked-palette UX contracts.
19+
- Save/load project palette identity contract.
20+
- Error behavior contract when engine palette source is unavailable.
21+
- Docs/reports bundle for PLAN stage.
22+
23+
Out of scope:
24+
- Engine rewrites or new engine palette systems.
25+
- Changes to pre-existing sprite editor implementations outside `tools/Sprite Editor/`.
26+
- Unrelated tools or gameplay/runtime systems.
27+
- Any destructive or migration-heavy repo changes.
28+
29+
## 3. Exact Files Likely To Change (for BUILD_PR)
30+
Primary likely implementation files:
31+
- `tools/Sprite Editor/index.html`
32+
- `tools/Sprite Editor/modules/spriteEditorApp.js`
33+
- `tools/Sprite Editor/modules/projectModel.js`
34+
- `tools/Sprite Editor/modules/constants.js`
35+
- `tools/Sprite Editor/README.md`
36+
37+
Optional tiny integration point:
38+
- `tools/Sprite Editor/main.js` (only if bootstrap wiring required)
39+
40+
Required BUILD docs/report files:
41+
- `docs/pr/BUILD_PR_SPRITE_EDITOR_PROJECT_INTEGRATION.md`
42+
- `CODEX_COMMANDS.md`
43+
- `docs/dev/reports/change_summary.txt`
44+
- `docs/dev/reports/validation_checklist.txt`
45+
- `docs/dev/reports/file_tree.txt`
46+
47+
## 4. Engine Integration Contract For paletteList
48+
Authoritative source:
49+
- Engine-owned `engine/paletteList.js` exposes `globalThis.palettesList` / `window.palettesList`.
50+
51+
Tool integration rule:
52+
- Sprite Editor reads palette sets from that engine contract only.
53+
- Sprite Editor does not define a hardcoded tool-only authoritative palette catalog.
54+
55+
Boundary rule:
56+
- Sprite Editor uses read-only consumption of engine palette data.
57+
- No writes/mutations to `globalThis.palettesList`.
58+
- No duplicated authority copy in tool modules.
59+
60+
Loading rule:
61+
- If `globalThis.palettesList` is available and valid, build palette selector options from it.
62+
- If unavailable/invalid, editor enters blocked mode (non-destructive, no editing) and presents actionable recovery message.
63+
64+
Expected contract shape consumed by Sprite Editor:
65+
- paletteId -> array of entries
66+
- each entry expected to expose at minimum a usable `hex` color value
67+
- optional metadata (name/symbol) may be displayed but is not required for editing correctness
68+
69+
## 5. Disabled-Until-Palette-Selected Behavior Contract
70+
Initial load state:
71+
- Palette selector enabled.
72+
- Editing actions disabled until palette selected.
73+
74+
Disabled actions before selection:
75+
- draw/erase/fill interactions
76+
- frame editing actions
77+
- import PNG into frame
78+
- resize/new-canvas actions that mutate document pixels
79+
- export actions that rely on active edit context
80+
81+
Allowed actions before selection:
82+
- palette selection
83+
- load existing JSON project (to restore/resolve palette identity)
84+
- read-only UI browsing and status/help interactions
85+
86+
UX messaging requirement:
87+
- Status/readout must clearly state: "Select palette from engine list to enable editing."
88+
- Disabled controls should appear visibly disabled, not silently ignored.
89+
90+
## 6. Locked-Palette Behavior Contract
91+
Lock trigger:
92+
- First successful palette selection on new session/project, or
93+
- successful project load that resolves a saved palette identity to engine palette list.
94+
95+
Lock semantics:
96+
- After lock, palette selector is read-only for that active project/session.
97+
- User cannot switch to a different palette through normal interaction.
98+
99+
Explicit unlock flows (allowed):
100+
- New Project flow (creates fresh project and clears prior lock)
101+
- Approved reset/new-project action explicitly documented in UI
102+
103+
Operation-specific lock behavior:
104+
- New Project: clears existing lock and requires new palette selection before edits.
105+
- Load Existing JSON Project:
106+
- if saved paletteId resolves in engine list -> auto-lock to that palette.
107+
- if saved paletteId missing/unresolvable -> project loads into blocked palette-selection state; user must choose one palette, then it locks.
108+
- PNG Import: uses current locked palette context; does not unlock or change palette.
109+
- Resize Canvas: preserves current lock; no palette switching.
110+
- Duplicate Frame: preserves current lock.
111+
- Save/Load Flow: save records palette identity; load attempts restore and lock as above.
112+
113+
## 7. Save/Load Project Palette Contract
114+
Saved JSON contract addition:
115+
- Store palette reference block, not authoritative palette catalog copy.
116+
117+
Planned shape:
118+
- `paletteRef.source = "engine/paletteList"`
119+
- `paletteRef.id = <paletteId>`
120+
- `paletteRef.locked = true`
121+
- optional non-authoritative verification metadata (example: color count/signature) for diagnostics only
122+
123+
Load contract:
124+
- Resolve `paletteRef.id` against engine palette list.
125+
- On success: restore lock and enable editing.
126+
- On failure: keep editing blocked until user selects palette; then write new lock in memory.
127+
128+
No-authority-duplication rule:
129+
- Serialized project must not become an alternative palette authority source.
130+
- Tool may store convenience metadata but engine palette list remains source of truth.
131+
132+
## 8. Manual Validation Checklist (for BUILD/APPLY)
133+
- Confirm Sprite Editor loads engine palette list from engine contract path.
134+
- Confirm no tool-local hardcoded authoritative palette list is used.
135+
- Confirm editing is blocked on first load until palette selected.
136+
- Confirm selecting palette enables editing and locks selector.
137+
- Confirm palette cannot be changed during active project/session via normal controls.
138+
- Confirm New Project clears lock and requires new selection.
139+
- Confirm Load JSON with resolvable paletteRef auto-locks correctly.
140+
- Confirm Load JSON with missing paletteRef enters blocked selection state.
141+
- Confirm PNG import/resize/duplicate frame preserve lock.
142+
- Confirm save JSON includes paletteRef identity fields.
143+
- Confirm load/save messaging explains lock/resolution outcomes.
144+
- Confirm no engine or unrelated tool files were changed beyond approved integration touchpoints.
145+
146+
## 9. BUILD_PR Command
147+
`Create BUILD_PR_SPRITE_EDITOR_PROJECT_INTEGRATION.`
148+
149+
Required BUILD constraints:
150+
- Implement only this approved plan.
151+
- Keep PR small and surgical.
152+
- Use engine palette contract as single authority.
153+
- Do not modify pre-existing sprite editor implementations outside `tools/Sprite Editor/`.
154+
- Do not introduce engine rewrites.
155+
- Produce delta zip: `tmp/BUILD_PR_SPRITE_EDITOR_PROJECT_INTEGRATION_delta.zip`.
156+
157+
## 10. Commit Comment
158+
`BUILD_PR_SPRITE_EDITOR_PROJECT_INTEGRATION: integrate isolated Sprite Editor with engine-authoritative palette contract and locked palette flow`
159+
160+
## 11. Next Command
161+
`APPLY_PR_SPRITE_EDITOR_PROJECT_INTEGRATION`

0 commit comments

Comments
 (0)