bill/whetstone_DSL
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
001-core-ast-structure
whetstone_DSL/sprint8_plan.md

14 KiB
Raw Permalink Blame History

Sprint 8: Refactor & UX Polish — Plan

Goal: Make Whetstone feel like a real editor out of the box. Fix the critical EditorState.h architecture violation, make text-first the default experience, properly dock panels on first launch, and add visual polish that shows off Dear ImGui capabilities.

Prerequisites: Sprint 7 complete (234 steps). All agent tooling and MCP infrastructure in place.

Key themes:

  1. Refactor EditorState.h (3,107 lines → multiple focused headers)
  2. Text-first default experience
  3. Proper DockBuilder layout on first launch
  4. Branded splash screen
  5. Visual effects (whetstone grinding sparks)
  6. Visual shortcut representation language

Phase 8a: Refactor EditorState.h (Steps 235–240)

EditorState.h is 3,107 lines (5.2x over the 600-line limit). Split it into domain-specific headers following the Sprint 6 panel extraction pattern.

  • Step 235: Extract RPC handler to AgentRPCHandler.h Move processAgentRequest() and all its JSON-RPC method handlers into a new header. This is the single largest block (~500+ lines) added across Sprints 5–7.

    • Free function: json processAgentRequest(EditorState&, const json&)
    • Includes all method dispatch (getAST, applyMutation, runPipeline, etc.)
    • EditorState keeps a one-liner that delegates to it New: editor/src/AgentRPCHandler.h

  • Step 236: Extract buffer operations to BufferOps.h Move file/buffer operations out of EditorState:

    • doOpen, doSave, doClose, createBuffer, makeUntitledName
    • handleFileChanges, refreshBuildSystem
    • File watcher logic, auto-save logic
    • Recent files management New: editor/src/BufferOps.h

  • Step 237: Extract editing operations to EditOps.h Move text editing, undo/redo, and navigation:

    • doUndo, doRedo, doFindNext, doReplace
    • navigateToTarget, goToLine
    • Multi-cursor operations
    • Clipboard operations New: editor/src/EditOps.h

  • Step 238: Extract LSP and diagnostics to LspOps.h Move LSP client management and diagnostic aggregation:

    • pollLspMessages, flushLspDidChange
    • publishDiagnostics handling
    • Whetstone diagnostic merging
    • LSP initialization and shutdown New: editor/src/LspOps.h

  • Step 239: Extract Emacs integration to EmacsOps.h Move Emacs-specific operations:

    • handleEmacsKeyChord, refreshEmacsModeLine
    • updateEmacsFunctionIndex
    • Emacs buffer sync, package queries New: editor/src/EmacsOps.h

  • Step 240: Verify EditorState.h under 600 lines + refactor tests After extraction, EditorState.h should be a thin shell:

    • State member variables and sub-state includes
    • init(), active(), notify() convenience methods
    • Delegation calls to extracted headers Tests:
    1. EditorState.h is under 600 lines
    2. All extracted headers are under 600 lines
    3. No function exceeds 80 lines
    4. Existing step206_test and step213_test still pass
    5. file_limits_test passes with new headers added New: step240_test.cpp

Phase 8b: Text-First Default & Dock Layout (Steps 241–244)

Make the editor feel familiar on first launch — a normal text editor with optional structured features.

  • Step 241: Text-first default mode Change the default buffer mode from Structured to Text:

    • BufferManager::BufferMode default → Text in BufferInfo and openBuffer()
    • getBufferMode() fallback → Text
    • First-run wizard: add "Editor Mode" step (Text recommended, Structured for power users)
    • Welcome screen tips updated to mention mode toggle
    • Settings: defaultBufferMode preference (text/structured) Modifies: BufferManager.h, FirstRunWizard.h, WelcomeScreen.h

  • Step 242: DockBuilder initial layout Apply the LayoutManager preset using ImGui DockBuilder on first launch:

    • On first run (no session), call ImGui::DockBuilderAddNode + DockBuilderSplitNode
    • VSCode preset: Explorer 20% left, Editor 60% center, Bottom panel 20%
    • Panels docked by name to the correct dock node IDs
    • Only runs once — after that, imgui.ini state takes over
    • Layout reset action in menu: "View → Reset Layout" re-applies DockBuilder Modifies: main.cpp, LayoutManager.h

  • Step 243: Clean first-launch experience Polish the out-of-box experience:

    • Window starts maximized (already done: SDL_WINDOW_MAXIMIZED)
    • Welcome tab opens in the editor area (not floating)
    • Explorer panel shows "Open Folder" prompt if no workspace
    • Status bar shows "Text Mode" / "Structured Mode" indicator
    • Bottom panel starts collapsed (user expands when needed) Modifies: main.cpp, panels/EditorPanel.h, panels/StatusBarPanel.h

  • Step 244: First-launch UX tests Tests verifying default experience:

    1. New buffers default to Text mode
    2. Text mode hides AST-specific UI (annotation gutter, AST tab)
    3. Structured mode shows full UI
    4. Mode toggle works and persists
    5. LayoutManager preset data matches DockBuilder application
    6. Settings defaultBufferMode preference respected New: step244_test.cpp

Phase 8c: Splash Screen & Branding (Steps 245–247)

A branded splash screen and polished startup feel.

  • Step 245: Startup splash overlay Render a branded splash on launch before editor loads:

    • Centered overlay: "Whetstone" logo text + version
    • Subtle animation (fade in, maybe spark trail — see Phase 8d)
    • Shows for ~1.5 seconds or until first interaction
    • "Loading..." progress text during init
    • Rendered as an ImGui overlay window (fullscreen, no decorations)
    • Configurable: "Show splash on startup" setting Modifies: main.cpp New: editor/src/SplashScreen.h

  • Step 246: Bottom notification bar A persistent slim bar at the bottom of the splash / welcome screen:

    • Shows tips, version info, or "What's New" on first launch after update
    • Can show keyboard shortcut of the day
    • Dismissable, remembers dismissed state
    • Separate from status bar — this is for onboarding/tips only Modifies: panels/StatusBarPanel.h or new panels/TipBar.h

  • Step 247: Splash and branding tests

    1. Splash state initializes correctly
    2. Splash dismisses after timeout or interaction
    3. Splash respects "don't show" setting
    4. Tip bar content rotates and dismisses persist New: step247_test.cpp

Phase 8d: Visual Effects — Whetstone Sparks (Steps 248–250)

Show off Dear ImGui's drawing capabilities with a signature visual effect: grinding sparks flying from a whetstone, rendered as an overlay.

  • Step 248: Particle system engine A lightweight 2D particle system using ImGui's ImDrawList:

    • Particle struct: position, velocity, lifetime, color, size
    • ParticleEmitter: spawn rate, direction cone, speed range, color gradient
    • ParticleSystem: update (gravity, fade, lifetime), render via GetForegroundDrawList()
    • Configurable: max particles, gravity, wind
    • Performance-safe: capped at 200 particles, skipped if reduce-motion enabled New: editor/src/ParticleSystem.h

  • Step 249: Whetstone spark effect Specific spark configuration for the whetstone theme:

    • Sparks fly from a configurable origin (e.g., bottom-left corner or cursor position)
    • Orange/yellow/white color gradient fading to dark
    • Short-lived particles (0.3–0.8s) with gravity pulling down
    • Sparks rendered on the foreground draw list (over all windows)
    • Triggered on: splash screen, save action, build success, or manual toggle
    • "Sparks" toggle in View menu and settings New: editor/src/SparkEffect.h Modifies: main.cpp

  • Step 250: Particle system tests

    1. Particle spawn and lifetime decay work correctly
    2. Dead particles are recycled
    3. Reduce-motion setting disables particles
    4. Particle count stays within cap
    5. Spark effect produces particles with correct color range New: step250_test.cpp

Phase 8e: Visual Shortcut Representation (Steps 251–254)

Visual encoding of keyboard shortcuts as modifier-box glyphs. Each key is a letter/symbol inside a square where the four edges encode modifiers:

  ┌───┐      ╔───┐      ╔───╗      ╔───╗
  │ K │      ║ K │      ║ K ║      ║ K ║
  └───┘      ╚───┘      ╚───╝      ╚═══╝
  (none)     Ctrl+K    Ctrl+Shift+K  All mods
  • Left edge = Ctrl — bright when active, dim when inactive
  • Bottom edge = Alt
  • Right edge = Shift
  • Top edge = Win/Super/Meta

Active modifier = bright white/accent line. Inactive = low-light gray. The glyph is overlaid on any widget — buttons, icons, tabs, panels. Every interactive element can show its shortcut visually, enabling mouse-free discovery. Since ImGui is immediate mode, glyphs update instantly when shortcuts are reassigned by external tools or IPC.

  • Step 251: Modifier-box glyph renderer Core rendering engine for the visual shortcut encoding:

    • ModifierBoxGlyph struct: key character/label, 4 modifier flags (ctrl, alt, shift, super)
    • renderModifierBox(ImDrawList*, ImVec2 pos, float size, ModifierBoxGlyph, theme): draws a square with 4 independently styled edges + centered key label
    • Active edge: bright color (theme accent or white), 2px line
    • Inactive edge: dim color (theme's muted gray), 1px line
    • Key label: monospace font, centered in box
    • Scalable: size parameter controls glyph dimensions (respects zoom)
    • Theme-aware: colors from ThemeEngine (active edge, inactive edge, label, background)
    • Chord sequences: multiple boxes with > arrow separator
    • Supports special key labels: "⏎" (Enter), "⇥" (Tab), "⎋" (Esc), "⌫" (Backspace), "↑↓←→" (arrows), mouse button glyphs, scroll wheel New: editor/src/ModifierBoxGlyph.h

  • Step 252: Widget shortcut overlay system Overlay modifier-box glyphs on any ImGui widget:

    • WidgetShortcutOverlay system: registry mapping widget IDs → shortcut glyphs
    • registerWidgetShortcut(widgetId, KeyCombo) → stores glyph data
    • renderWidgetOverlay(ImDrawList*, ImRect widgetBounds) → draws glyph in corner or center of widget (configurable placement: corner, center, beside)
    • Auto-detect: if a KeybindingManager action maps to a widget, overlay appears
    • Visibility modes: always, on hover, on Alt hold, never
    • Glyph placement: inside widget (bottom-right corner default) or beside label
    • Non-interactive: overlay doesn't consume clicks New: editor/src/WidgetShortcutOverlay.h

  • Step 253: Integration across all panels + dynamic reassignment API Wire the overlay system into every panel and expose it for external control:

    • Menu bar items: glyph beside each menu action
    • Toolbar buttons: glyph overlay on each button
    • Command palette: glyph column replaces text shortcuts
    • Explorer panel: glyph on "New File", "New Folder" actions
    • Tab bar: glyph on tab switch shortcuts (Ctrl+1..9)
    • Shortcut reference panel: full glyph rendering instead of text
    • Dynamic reassignment API (for external tools / window manager):
      • setWidgetShortcut(widgetId, KeyCombo) via JSON-RPC
      • getWidgetShortcuts() → returns all widget→shortcut mappings
      • clearWidgetShortcut(widgetId) → removes overlay
      • These methods added to processAgentRequest (or new IPC channel)
    • Settings: "Show shortcut glyphs" toggle, placement preference, visibility mode Modifies: panels/MenuBarPanel.h, panels/EditorPanel.h, panels/BottomPanel.h, panels/ExplorerPanel.h, ShortcutReference.h, WelcomeScreen.h, EditorState.h

  • Step 254: Shortcut glyph tests

    1. Modifier-box renders correct edges for each modifier combination (16 combos)
    2. Inactive edges are dim, active edges are bright
    3. Key label is centered in the box
    4. Chord sequences render as multiple boxes with separator
    5. Special key labels render correctly (Enter, Tab, arrows, mouse)
    6. Widget overlay appears at correct position relative to widget bounds
    7. Dynamic reassignment via API updates glyph immediately
    8. Visibility modes work (always, hover, alt-hold, never)
    9. Theme change updates glyph colors
    10. Zoom scaling applies to glyph size New: step254_test.cpp

Summary

Phase Steps Description
8a 235–240 Refactor EditorState.h (3,107 → <600 lines each)
8b 241–244 Text-first default + DockBuilder layout
8c 245–247 Splash screen & branding
8d 248–250 Whetstone spark particle effects
8e 251–254 Modifier-box shortcut glyphs + widget overlay system

Total: 20 steps across 5 phases.

Architecture Notes

  • Extraction pattern: Same as Sprint 6 panel extraction. Free functions taking EditorState& as first parameter. EditorState becomes a thin coordinator that includes and delegates.
  • 600-line limit enforced: file_limits_test must pass after Phase 8a.
  • Particle system: Uses ImGui::GetForegroundDrawList() for overlay rendering. No OpenGL calls — pure ImDrawList for portability.
  • Reduce-motion: All animations and particles respect the existing settings.getReduceMotion() flag.
  • Modifier-box glyphs: Rendered with ImDrawList::AddLine for edges and AddText for key labels. Each edge independently styled. The overlay system uses ImGui::GetForegroundDrawList() to render above widgets without interfering with widget interaction. External tools can reassign shortcuts via JSON-RPC, and glyphs update on the next frame (immediate mode).
  • No new dependencies: Everything uses existing ImGui, SDL2, nlohmann-json.

Sprint 9 Preview (for planning)

Sprint 9: Production Integration & Real-World Testing

  1. End-to-end testing with real LLM agents (Claude, GPT-4, Llama)
  2. Multi-file project support (project-wide AST, cross-file references)
  3. Git integration (diff view, blame, branch-aware sessions)
  4. Performance profiling with real workloads
  5. New language support (Phase A: PHP, C#, Kotlin)
  6. Production packaging and stable release
Reference in New Issue View Git Blame Copy Permalink