BUILD_PR_SPRITE_EDITOR_USABILITY_POLISH.

Author: DavidQ

CODEX_COMMANDS.md

@@ -7,89 +7,38 @@ MODEL: GPT-5.4-codex
 REASONING: high
 
 COMMAND:
-Create BUILD_PR_SPRITE_EDITOR_FROM_SCRATCH.
-
-Hard requirements:
-1. Assume there is NO usable sprite editor in the repo.
-2. DO NOT review, assess, refactor, migrate, or depend on any existing sprite editor implementation.
-3. DO NOT delete, rename, overwrite, or clean up any current sprite-editor-related files or folders, even if they appear broken, old, duplicate, or unused.
-4. Build a NEW sprite editor from scratch as an isolated tool under:
-   tools/Sprite Editor/
-5. Keep the PR small and surgical, focused only on the new tool and its supporting docs.
-6. Follow repo rules:
-   - PLAN_PR -> BUILD_PR -> APPLY_PR
-   - docs-first
-   - one PR per purpose
-   - no destructive changes
-   - update docs with the change
-7. All NEW files must include the required file header standard at the top, using the file creation date.
-8. Preserve current repo structure and public/internal boundaries.
-
-Deliverables to create:
-- docs/pr/BUILD_PR_SPRITE_EDITOR_FROM_SCRATCH.md
+Create BUILD_PR_SPRITE_EDITOR_USABILITY_POLISH.
+
+Goal:
+Implement a small, surgical usability-polish PR for the isolated Sprite Editor now that core features are working.
+
+Scope rules:
+1. Do not review, modify, migrate, or delete any pre-existing sprite editor outside tools/Sprite Editor/
+2. Keep scope limited to tools/Sprite Editor/, tools/index.html only if needed, and docs/reports
+3. Do not expand into engine or unrelated tools
+4. Docs-first
+5. One PR per purpose
+6. Preserve required file headers
+7. No destructive changes
+
+Polish targets:
+- Better tool-state visibility for active tool / active color / active frame
+- Keyboard shortcuts plan (pencil, eraser, fill, grid toggle, onion skin toggle, frame next/prev)
+- Undo/redo implementation
+- Clear resize/new-canvas behavior contract messaging
+- Better import/export feedback messaging
+- Improved recent-color swatch behavior
+- Preview panel polish for FPS/play/pause clarity
+- Optional status bar (canvas size, zoom, active frame, cursor pixel position)
+- Mouse drag drawing reliability polish
+- Save/load UX cleanup
+
+Required outputs:
+- docs/pr/BUILD_PR_SPRITE_EDITOR_USABILITY_POLISH.md
 - CODEX_COMMANDS.md
 - docs/dev/reports/change_summary.txt
 - docs/dev/reports/validation_checklist.txt
 - docs/dev/reports/file_tree.txt
 
-Implementation target:
-Build a brand-new browser-based Sprite Editor tool that can stand alone and be opened from the repo tools area.
-
-Minimum feature set:
-- Create new sprite canvas
-- Grid on/off
-- Configurable canvas width/height in pixels
-- Configurable pixel size / zoom
-- Pencil tool
-- Eraser tool
-- Fill tool
-- Color palette with active color selection
-- Recent color swatches
-- Frame support for basic animation:
-  - add frame
-  - duplicate frame
-  - delete frame
-  - next/previous frame
-- Onion-skin preview toggle
-- Import PNG into a frame
-- Export PNG for current frame
-- Export sprite sheet for all frames
-- Save/load editor project as JSON
-- Transparent background support
-- Mouse-friendly editing with visible selected tool/state
-- Simple preview panel for animation playback with FPS control
-
-Integration constraints:
-- Add a link for the new tool in tools/index.html
-- Do not modify engine code unless absolutely required; prefer zero engine changes
-- Do not change unrelated tools
-- Do not touch samples unless needed for a tiny non-destructive launch link or docs reference
-- No deletion of existing assets, tools, or folders
-
-Build guidance:
-- Use plain HTML/CSS/JavaScript consistent with repo conventions
-- Keep code readable and modular
-- Prefer local utility modules within tools/Sprite Editor/
-- No external dependencies unless already standard for the repo
-- Favor simple data contracts so future Tile Map Editor / Parallax Editor integration is possible
-
-Validation:
-- Tool opens directly in browser
-- Can draw pixels and erase
-- Can add multiple frames
-- Can save JSON and reload it
-- Can import PNG and export PNG
-- Can export a sprite sheet
-- Tool link appears in tools/index.html
-- Existing repo content remains untouched
-
 Packaging:
-Produce a repo-structured delta ZIP at:
-<project folder>/tmp/BUILD_PR_SPRITE_EDITOR_FROM_SCRATCH_delta.zip
-
-Include only files relevant to this PR in the ZIP.
-Do not include unrelated files, dependencies, or full-repo copies.
-
-At completion also provide:
-- commit comment
-- next command
+- tmp/BUILD_PR_SPRITE_EDITOR_USABILITY_POLISH_delta.zip

docs/dev/reports/change_summary.txt

@@ -3,31 +3,30 @@ David Quesenberry
 04/03/2026
 change_summary.txt
 
-BUILD_PR target:
-Build a brand-new, isolated Sprite Editor from scratch under tools/Sprite Editor/ and expose it through tools/index.html.
+PLAN_PR target:
+Create a docs-only plan bundle for Sprite Editor usability polish without implementation edits.
 
-Scope executed:
-- New tool implementation only: tools/Sprite Editor/**
-- Tool hub integration link only: tools/index.html
-- Required docs/report deliverables for this PR bundle
+Planned BUILD scope (next step):
+- tools/Sprite Editor/** usability polish only
+- tools/index.html only if a tiny non-destructive update is strictly needed
+- docs/reports updates required by workflow
 
-Feature outcome summary:
-- New project canvas (width/height)
-- Zoom/pixel-size controls + grid toggle
-- Pencil, eraser, and flood fill tools
-- Active palette + recent color swatches
-- Frame timeline operations (add/duplicate/delete/prev/next)
-- Onion-skin overlay toggle
-- PNG import into current frame
-- PNG export for current frame
-- Sprite sheet export across all frames
-- JSON save/load project round-trip
-- Transparent pixel handling
-- Animation preview with FPS controls
+Planned polish focus:
+- state visibility
+- keyboard shortcuts
+- undo/redo
+- resize/new-canvas behavior clarity
+- import/export messaging clarity
+- recent-color polish
+- preview controls clarity
+- optional status bar telemetry
+- drag reliability
+- save/load UX cleanup
 
-Guardrails honored:
-- No dependency on existing SpriteEditor implementations
-- No deletion/rename/cleanup of existing sprite-editor-related paths
-- No engine code changes
-- No unrelated tool changes
-- Small, surgical PR surface
+Locked exclusions:
+- no engine changes
+- no unrelated tools
+- no samples/games edits
+- no legacy sprite-editor path modifications
+
+This PLAN bundle is docs-only and contains no implementation code changes.

docs/dev/reports/file_tree.txt

@@ -3,19 +3,10 @@ David Quesenberry
 04/03/2026
 file_tree.txt
 
-PR file tree for BUILD_PR_SPRITE_EDITOR_FROM_SCRATCH
+PLAN_PR_SPRITE_EDITOR_USABILITY_POLISH docs bundle file tree
 
 CODEX_COMMANDS.md
-docs/pr/BUILD_PR_SPRITE_EDITOR_FROM_SCRATCH.md
+docs/pr/PLAN_PR_SPRITE_EDITOR_USABILITY_POLISH.md
 docs/dev/reports/change_summary.txt
 docs/dev/reports/validation_checklist.txt
 docs/dev/reports/file_tree.txt
-tools/index.html
-tools/Sprite Editor/README.md
-tools/Sprite Editor/index.html
-tools/Sprite Editor/main.js
-tools/Sprite Editor/spriteEditor.css
-tools/Sprite Editor/modules/constants.js
-tools/Sprite Editor/modules/colorUtils.js
-tools/Sprite Editor/modules/projectModel.js
-tools/Sprite Editor/modules/spriteEditorApp.js

docs/dev/reports/validation_checklist.txt

@@ -3,31 +3,26 @@ David Quesenberry
 04/03/2026
 validation_checklist.txt
 
-Validation checklist for BUILD_PR_SPRITE_EDITOR_FROM_SCRATCH
+PLAN_PR_SPRITE_EDITOR_USABILITY_POLISH checklist
 
-[x] Tool opens directly: tools/Sprite Editor/index.html (static entry path validated)
-[x] Pencil draws visible pixels on canvas (implemented in pointer draw path)
-[x] Eraser clears pixels to transparent (implemented via null pixel writes)
-[x] Fill tool replaces contiguous region (flood-fill implementation)
-[x] Grid toggle on/off works (state + editor render gate)
-[x] Canvas width/height update applies correctly (resizeProject wired to controls)
-[x] Zoom/pixel-size control applies correctly (pixelSize control + rerender)
-[x] Add frame works (append new frame)
-[x] Duplicate frame works (clone current frame)
-[x] Delete frame works with minimum one frame preserved
-[x] Previous/next frame navigation works (wrapped index navigation)
-[x] Onion-skin toggle overlays adjacent frame preview
-[x] PNG import loads into current frame
-[x] Current-frame PNG export downloads expected image
-[x] Sprite sheet export downloads expected strip image
-[x] Save project JSON downloads valid data
-[x] Load project JSON restores frame/canvas/color state
-[x] Animation preview plays frames at selected FPS
-[x] Tool link appears in tools/index.html
-[x] Existing repo content untouched outside approved scope (this PR path list only)
+Docs bundle validation:
+[x] PLAN doc created at docs/pr/PLAN_PR_SPRITE_EDITOR_USABILITY_POLISH.md
+[x] CODEX_COMMANDS.md updated for BUILD_PR_SPRITE_EDITOR_USABILITY_POLISH
+[x] change_summary.txt updated
+[x] validation_checklist.txt updated
+[x] file_tree.txt updated
+[x] Bundle is docs-only (no implementation code changes)
+[x] Scope boundaries clearly documented
+[x] In-scope / out-of-scope clearly documented
+[x] Exact likely BUILD file list documented
+[x] UX behavior contract documented for each polish item
+[x] Manual validation checklist documented
+[x] BUILD command documented
+[x] Commit comment documented
+[x] Next command documented
 
-Automated checks run:
-[x] node --check tools/Sprite Editor/main.js
-[x] node --check tools/Sprite Editor/modules/spriteEditorApp.js
-[x] node --check tools/Sprite Editor/modules/projectModel.js
-[x] node --check tools/Sprite Editor/modules/colorUtils.js
+Guardrail checks:
+[x] No engine scope introduced
+[x] No unrelated tool scope introduced
+[x] No legacy sprite-editor migration/refactor scope introduced
+[x] No destructive/deletion instructions included