whetstone_DSL/sprint13_plan.md

Sprint 13 Plan: GUI Overhaul Phase 1

Context

The human-in-the-loop thesis is load-bearing. If humans are supposed to be architects and reviewers — not button-pushers — then the interface must make the system intuitive to understand. The current GUI has floating windows, no key combination symbols, and doesn't look like a professional product. This sprint fixes that.

Sprint 12 delivered the workflow model and routing engine. The GUI needs to surface that workflow state — but the heavy workflow visualization comes in Sprint 19. This sprint focuses on the structural foundation: docking, styling, navigation, and key symbols so the editor feels like a real tool.

Current GUI state:

• ImGui-based with SDL backend
• Text editor with syntax highlighting
• AST tree view panel
• Diagnostics panel
• Annotation panel
• Floating windows (not docked)
• No keyboard shortcut display or customization
• Default ImGui color scheme

Sprint 13 Deliverables:

• All windows docked in a professional layout
• Keyboard shortcut system with displayable key combination symbols
• Professional dark color scheme with consistent visual language
• Clean navigation: panel switching, breadcrumbs, command palette
• Status bar with project/workflow/language info
• Resizable, saveable layout that persists across sessions

---

Phase 13a: Docking Layout (Steps 342-346)

Convert every floating window to a docked panel in a professional layout.

Step 342: ImGui Docking Infrastructure (12 tests)

Goal: Set up the ImGui docking system and define the default layout.

Modifies: editor/src/EditorState.h (or new editor/src/DockingLayout.h)

• Enable ImGui docking via io.ConfigFlags |= ImGuiConfigFlags_DockingEnable
• Define DockSpace as the root of the editor window
• Default layout:

  ┌──────────────┬──────────────────────────────┬──────────────┐
  │  File Tree   │        Code Editor           │  AST View    │
  │              │                               │              │
  │              │                               │              │
  │              ├──────────────────────────────┤              │
  │              │  Diagnostics / Output         │              │
  └──────────────┴──────────────────────────────┴──────────────┘
  

• Left dock: file tree / project navigator (20% width)
• Center: code editor (60% width, split top/bottom)
• Right dock: AST view / annotations (20% width)
• Bottom: diagnostics, output, workflow status (25% height)

Tests: docking enabled, DockSpace renders, default layout has 4 regions, panels render in correct regions, no floating windows, window positions persist after frame, layout ID stable across frames, DockSpace fills viewport.

Step 343: Panel Registration System (12 tests)

Goal: Every panel registers itself with a panel manager that controls docking position, visibility, and ordering.

New file: editor/src/PanelManager.h (~300 lines)

• PanelInfo struct: id, title, defaultDock (left/center/right/bottom), isVisible, order, icon
• PanelManager class:
  • registerPanel(id, title, dock, renderFn) — register a panel
  • setVisible(id, bool) — show/hide
  • isVisible(id) -> bool
  • renderAll() — render all visible panels in docked positions
  • getPanelList() -> vector<PanelInfo> — for UI menus
  • togglePanel(id) — flip visibility
  • focusPanel(id) — bring panel to front in its dock

Registered panels:

• file-tree — project file browser (left)
• code-editor — main text editor (center-top)
• ast-view — AST tree visualization (right)
• annotations — annotation list/editor (right, tabbed with AST)
• diagnostics — error/warning list (bottom)
• output — generated code output (bottom, tabbed with diagnostics)
• workflow — workflow status summary (bottom, tabbed)
• properties — selected node properties (right, tabbed)

Tests: register 8 panels, all render without error, visibility toggle, focus panel brings to front, default dock positions, panel ordering, hidden panel doesn't render, getPanelList returns all registered.

Step 344: File Tree Panel (12 tests)

Goal: Replace any floating file browser with a docked file tree that shows the workspace structure with icons and expand/collapse.

New file: editor/src/panels/FileTreePanel.h (~250 lines)

• Tree view of workspace files using FileTree.h data
• Expand/collapse directories
• File type icons (or text indicators): source files, headers, configs
• Click to open file in editor (calls openFile RPC internally)
• Highlight active file
• Respect .gitignore (already in FileTree.h)
• Right-click context menu: new file, rename, delete (future)

Tests: renders workspace tree, directories expandable, click opens file, active file highlighted, .gitignore respected, empty workspace shows message, nested directories render correctly, file count matches workspace index.

Step 345: Tabbed Bottom Panel (12 tests)

Goal: Diagnostics, output, and workflow share the bottom dock as tabs.

Modifies: existing diagnostic/output rendering

• Tab bar: Diagnostics | Output | Workflow | Console
• Diagnostics tab: structured diagnostic list with severity icons, click-to-navigate (jumps to error line in editor)
• Output tab: generated code with syntax highlighting
• Workflow tab: summary stats (placeholder for Sprint 19 deep visualization)
• Console tab: MCP tool log / agent interaction log
• Tab badge: unread count (e.g., "Diagnostics (3)" when 3 new errors)

Tests: 4 tabs render, tab switching works, diagnostics click navigates to line, output shows generated code, workflow shows stats placeholder, badge count updates on new diagnostic, default tab is diagnostics, tabs persist across frames.

Step 346: Phase 13a Integration — Layout Persistence (8 tests)

Goal: Save and restore dock layout across sessions.

Modifies: editor/src/DockingLayout.h (or PanelManager)

• saveLayout(path) — serialize ImGui dock state + panel visibility to JSON
• loadLayout(path) — restore from JSON
• Auto-save on exit, auto-load on startup
• Default layout if no saved state exists
• Path: .whetstone/layout.json in workspace

Tests:

1. Default layout applied on first run
2. Resize panel → save → reload → same size
3. Hide panel → save → reload → still hidden
4. Move panel to different dock → save → reload → same dock
5. Tab order preserved
6. Multiple workspaces have independent layouts
7. Corrupt layout file → falls back to default
8. Layout file location correct (.whetstone/layout.json)

---

Phase 13b: Color Scheme + Visual Polish (Steps 347-350)

Professional dark theme with consistent visual hierarchy.

Step 347: Theme System (12 tests)

Goal: Centralized theme definition that every panel reads from.

New file: editor/src/Theme.h (~300 lines)

• WhetstoneTheme struct with named semantic colors:
  • bg, bgAlt, bgPanel, bgPopup
  • text, textDim, textAccent, textError, textWarning, textSuccess
  • border, borderFocused
  • accent, accentHover, accentActive — primary brand color
  • selectionBg, selectionText
  • scrollbar, scrollbarHover
  • diagnostic_error, diagnostic_warning, diagnostic_info, diagnostic_hint
  • syntax_keyword, syntax_string, syntax_number, syntax_comment, syntax_function, syntax_type, syntax_operator, syntax_annotation
• applyTheme(theme) — sets all ImGui style colors from theme
• getDefaultDarkTheme() -> WhetstoneTheme — professional dark theme
• getDefaultLightTheme() -> WhetstoneTheme — clean light alternative
• Font configuration: primary (monospace), UI (sans-serif), sizes

Color palette (dark theme):

• Background: deep blue-grey (#1a1d23, #22252b, #2a2d35)
• Text: warm white (#e0e0e0), dim (#808890), accent (#7aa2f7)
• Borders: subtle (#3a3d45), focused (#7aa2f7)
• Errors: soft red (#f7768e), warnings: amber (#e0af68), success: green (#9ece6a), info: blue (#7dcfff)
• Syntax: keywords blue (#7aa2f7), strings green (#9ece6a), numbers orange (#ff9e64), comments grey (#565f89)

Tests: dark theme applies without crash, all semantic colors defined, no color is pure black or pure white (contrast), light theme alternative, applyTheme sets ImGui colors, font sizes reasonable, theme roundtrip to JSON, syntax colors distinct from each other, diagnostic colors match severity, accent color used for focused elements.

Step 348: Syntax Highlighting Refresh (12 tests)

Goal: Update the text editor's syntax highlighting to use theme colors and cover all 10 supported languages.

Modifies: syntax highlighting in text editor component

• Use theme's syntax colors instead of hardcoded values
• Language-aware highlighting (keywords differ per language)
• Semanno comment highlighting: @semanno:type(key=value) gets distinct annotation color
• Line numbers in textDim color
• Current line highlight with subtle bgAlt background
• Selection uses selectionBg / selectionText
• Matching bracket highlight

Tests: Python keywords highlighted, C++ keywords highlighted, Kotlin keywords highlighted, Semanno comments get annotation color, strings in string color, numbers in number color, comments in comment color, current line highlighted, line numbers dimmed, selection visible, theme change updates highlighting, bracket matching visible.

Step 349: Icon System + Visual Indicators (12 tests)

Goal: Consistent iconography across all panels using Unicode symbols (no external icon font dependency — keep it header-only).

New file: editor/src/Icons.h (~100 lines)

• Unicode symbol constants for common items:
  • File types: source, header, config, folder, image
  • Diagnostics: error circle, warning triangle, info, hint
  • Workflow: pending clock, in-progress spinner, complete check, rejected cross, review eye
  • AST: function, class, variable, annotation, module
  • Navigation: arrow right, arrow down, search, settings
• renderIcon(iconType, color) — render icon with theme color
• Fallback: if Unicode doesn't render, use text abbreviations (ERR, WARN, etc.)

Tests: all icon constants defined, renderIcon doesn't crash, error icon is distinct from warning icon, file type icons cover 10 languages, workflow status icons cover all states, fallback text works, icon + text alignment correct, icon colors respect theme.

Step 350: Phase 13b Integration — Visual Consistency (8 tests)

Goal: Every panel uses the theme and icons consistently.

Tests:

1. All panels use theme background colors (no default ImGui grey)
2. Diagnostic panel uses severity icons + colors from theme
3. AST panel uses node type icons
4. File tree uses folder/file icons
5. Status text uses textDim for secondary info
6. Focused panel border uses accent color
7. Theme switch (dark→light) updates all panels
8. No visual artifacts: no overlapping text, no clipped content, no invisible text

---

Phase 13c: Keyboard System + Key Symbols (Steps 351-355)

The key combination symbol system the user has been asking for.

Step 351: Keybinding Registry (12 tests)

Goal: Centralized keybinding system where every action has a named binding that can be displayed, customized, and persisted.

New file: editor/src/KeybindingRegistry.h (~350 lines)

KeyCombo struct:

• modifiers: uint8_t — bitmask: Ctrl, Alt, Shift, Super/Meta
• key: int — ImGui key code
• toString() -> string — "Ctrl+Shift+P", "Alt+F4", etc.
• toSymbols() -> string — "⌃⇧P", "⌥F4" (platform-aware symbols)
  • macOS: ⌘ ⌥ ⌃ ⇧
  • Linux/Windows: Ctrl Alt Shift Super
• matches(ImGuiIO&) -> bool — check if currently pressed

KeyAction enum (or string-based for extensibility):

• OpenFile, SaveBuffer, SaveAll, CloseBuffer
• TogglePanel_FileTree, TogglePanel_AST, TogglePanel_Diagnostics
• FocusEditor, FocusCommandPalette
• NextDiagnostic, PrevDiagnostic
• RunPipeline, GenerateCode
• Undo, Redo
• FindInFile, FindInProject
• ToggleAnnotations, InferAnnotations
• CreateWorkflow, RouteAll

KeybindingRegistry class:

• bind(action, combo) — set binding for action
• getBinding(action) -> KeyCombo — get current binding
• getSymbols(action) -> string — get display symbols for an action
• processInput(ImGuiIO&) -> optional<KeyAction> — check all bindings
• getAll() -> map<KeyAction, KeyCombo> — for settings UI
• loadDefaults() — standard keybindings
• saveToJson(path) / loadFromJson(path) — persistence

Default bindings:

• Ctrl+S: SaveBuffer, Ctrl+Shift+S: SaveAll
• Ctrl+P: CommandPalette
• Ctrl+B: TogglePanel_FileTree
• Ctrl+Shift+D: TogglePanel_Diagnostics
• F5: RunPipeline
• Ctrl+Z: Undo, Ctrl+Shift+Z: Redo
• Ctrl+F: FindInFile, Ctrl+Shift+F: FindInProject
• F8: NextDiagnostic, Shift+F8: PrevDiagnostic

Tests: bind and retrieve, default bindings loaded, key combo toString, key combo toSymbols (platform-aware), processInput detects active combo, save/load roundtrip, rebind action, conflict detection (same combo for two actions), getSymbols returns displayable string, modifier bitmask correct, matches detects key press.

Step 352: Key Symbol Rendering (12 tests)

Goal: Display key combination symbols inline in menus, tooltips, and the command palette — like every professional editor does.

New file: editor/src/KeySymbolRenderer.h (~150 lines)

• renderKeySymbol(combo, theme) — renders a styled key badge inline
  • Background: slightly lighter than panel bg
  • Border: subtle rounded rect
  • Text: key symbol in small monospace font
  • Example: [⌃S] rendered as a neat badge
• renderActionWithKey(label, action, registry, theme) — renders "Save Buffer ⌃S" with right-aligned key symbols (menu item style)
• renderKeyChord(combos, theme) — for multi-key sequences ("⌃K ⌃S" style chords)

Tests: single key renders, modifier+key renders, platform symbols correct, menu item layout (label left, key right), chord rendering, key badge has background, theme colors used, empty binding shows nothing, special keys (Enter, Escape, Tab, F-keys) render correctly, long label doesn't overlap key badge.

Step 353: Command Palette (12 tests)

Goal: Ctrl+P opens a fuzzy-search command palette (VS Code style) that lists all available actions with their key symbols.

New file: editor/src/CommandPalette.h (~300 lines)

• Modal popup centered in editor
• Text input at top with fuzzy search
• List of matching actions below, each showing:
  • Icon (from Icons.h)
  • Action name ("Save Buffer", "Toggle AST Panel", "Run Pipeline")
  • Key binding symbol (right-aligned)
• Enter executes selected action
• Escape closes
• Arrow keys navigate list
• Search matches action name, panel name, and command aliases
• Recently used actions appear first

Action sources:

• All KeyAction entries from KeybindingRegistry
• Panel toggles from PanelManager
• RPC methods (RunPipeline, GenerateCode, InferAnnotations, etc.)
• File operations (Open, Save, Close)

Tests: palette opens on Ctrl+P, fuzzy search filters actions, Enter executes action, Escape closes, key symbols displayed, arrow navigation, recent actions first, empty search shows all, partial match works, palette closes after execution, multiple action sources merged, no duplicate entries.

Step 354: Menu Bar with Key Symbols (12 tests)

Goal: Top menu bar (File, Edit, View, Tools, Workflow) with key symbols on every menu item.

Modifies: main editor rendering

• File: New | Open | Save (⌃S) | Save All (⌃⇧S) | Close
• Edit: Undo (⌃Z) | Redo (⌃⇧Z) | Find (⌃F) | Find in Project (⌃⇧F)
• View: Toggle File Tree (⌃B) | Toggle AST | Toggle Diagnostics (⌃⇧D) | Toggle Annotations | Reset Layout
• Tools: Run Pipeline (F5) | Generate Code | Infer Annotations | Validate | Export Semanno
• Workflow: Create Workflow | Route All | View Ready Tasks | Save Workflow
• Help: About | Keyboard Shortcuts

Every menu item uses renderActionWithKey() for consistent key symbol display.

Tests: all 5 menus render, File menu has Save with ⌃S, Edit menu has Undo with ⌃Z, View menu toggles panels, Tools menu runs pipeline, menu items execute correct actions, key symbols visible, menu closes after selection, separator lines between groups, workflow menu items present, submenu rendering.

Step 355: Phase 13c Integration — Keyboard Shortcuts Help Panel (8 tests)

Goal: A dedicated keyboard shortcuts panel and verification that the entire keybinding system works end-to-end.

New panel: Keyboard Shortcuts (accessible from Help menu or Ctrl+?)

• Grouped by category: File, Edit, View, Tools, Workflow, Navigation
• Each row: action name | key symbol | description
• Search/filter bar
• "Customize" button (opens keybinding editor — basic version)

Tests:

1. All default bindings displayed in shortcuts panel
2. Ctrl+S triggers save action
3. Ctrl+P opens command palette
4. Command palette shows key symbols for all actions
5. Menu items show correct key symbols
6. Rebind action → shortcut panel updates
7. Key symbols render correctly on current platform
8. Full keyboard-driven workflow: Ctrl+P → type "pipeline" → Enter → pipeline runs

---

Phase 13d: Navigation + Status Bar (Steps 356-360)

Clean navigation: breadcrumbs, status bar, and go-to-definition.

Step 356: Breadcrumb Navigation (12 tests)

Goal: Breadcrumb bar above the code editor showing the current location in the AST hierarchy: Module > Class > Method > Function.

New file: editor/src/panels/BreadcrumbBar.h (~150 lines)

• Displays path from module root to cursor position's AST node
• Each breadcrumb is clickable → navigates to that node
• Dropdown on each segment → shows siblings (other methods in class, etc.)
• Updates as cursor moves
• Uses compact AST names from CompactAST::getNodeName()

Tests: breadcrumb shows module name, nested path updates with cursor, click navigates to node, dropdown shows siblings, empty file shows module only, deep nesting (4+ levels) renders without overflow, breadcrumb uses theme colors, annotation nodes appear in path.

Step 357: Status Bar (12 tests)

Goal: Bottom status bar showing project state at a glance.

New file: editor/src/panels/StatusBar.h (~200 lines)

• Left section: language indicator + file path
• Center section: cursor position (Ln 42, Col 8) | encoding | line ending
• Right section: workflow status (if active), MCP connection indicator, diagnostic summary (3 errors, 2 warnings)

Status bar segments:

• Language badge: colored badge with language name ("Python", "C++", "Kotlin")
• Workflow badge: phase indicator if workflow active ("Executing 3/10" with progress ring)
• Diagnostic summary: clickable → jumps to diagnostics panel
• MCP indicator: green dot if MCP connected, grey if headless-only

Tests: language badge shows current buffer language, cursor position updates, diagnostic count accurate, workflow badge shows when active, click diagnostic count focuses diagnostics panel, status bar uses theme colors, language changes when switching buffers, encoding display, all sections fit without overflow.

Step 358: Go-to-Definition + Go-to-Symbol (12 tests)

Goal: Navigate by AST structure, not just text search.

Modifies: editor/src/panels/ or code editor component

• Go-to-Definition (F12): Click on a function call → jump to its definition (uses cross-file symbol resolution from Sprint 9d)
• Go-to-Symbol (Ctrl+Shift+O): Open a symbol picker showing all functions/classes/variables in current file with icons
• Go-to-Symbol in Project (Ctrl+T): Same but across all open buffers
• Uses existing searchProject and getInScopeSymbols RPC infrastructure

Tests: F12 on function call jumps to definition, Ctrl+Shift+O lists file symbols, Ctrl+T lists project symbols, symbol list shows icons by type, filter works on symbol list, cross-file jump opens target buffer, no match shows message, symbols sorted by line number.

Step 359: Find and Replace Improvements (12 tests)

Goal: In-file and project-wide find/replace with result highlighting.

Modifies: text editor component

• Ctrl+F: find bar appears at top of editor (not floating window)
• Result highlighting in editor (all matches highlighted, current match distinct color)
• Match count display ("3 of 17")
• Enter: next match, Shift+Enter: previous match
• Ctrl+H: replace mode (adds replace input field)
• Ctrl+Shift+F: project-wide find (results in bottom panel)
• Search uses searchProject for AST-aware results when possible

Tests: Ctrl+F opens find bar, typing filters matches, match highlighting visible, match count accurate, Enter cycles through matches, Ctrl+H shows replace field, replace works, project-wide search shows results in bottom panel, Escape closes find bar, empty search clears highlights.

Step 360: Phase 13d Integration + Sprint 13 Summary (8 tests)

Goal: Full navigation workflow and sprint verification.

Tests:

1. Full keyboard workflow: open file → navigate to function → go-to-definition → breadcrumb click back
2. Command palette → "find" → project-wide search → navigate to result
3. Status bar reflects buffer switches (language, cursor, diagnostics)
4. All panels docked, no floating windows
5. Theme consistent across all panels and navigation elements
6. Key symbols visible in menus, palette, and shortcuts panel
7. Layout save → restart → same layout restored
8. Sprint 13 totals: all panels docked, theme applied, keybindings functional, navigation operational

---

Step & Test Summary

Phase	Steps	Tests	Theme
13a	342-346	56	Docking layout, panel system, file tree, tabbed bottom
13b	347-350	44	Theme system, syntax highlighting, icons, visual consistency
13c	351-355	56	Keybinding registry, key symbols, command palette, menus
13d	356-360	56	Breadcrumbs, status bar, go-to-definition, find/replace
Total	342-360	~212	19 steps

---

Key Files

New files:

• editor/src/DockingLayout.h — ImGui docking setup, default layout, persistence
• editor/src/PanelManager.h — panel registration, visibility, rendering
• editor/src/Theme.h — semantic color themes, dark/light, font configuration
• editor/src/Icons.h — Unicode icon constants, renderIcon
• editor/src/KeybindingRegistry.h — keybindings, key combos, persistence
• editor/src/KeySymbolRenderer.h — key badge rendering, menu item key display
• editor/src/CommandPalette.h — fuzzy-search command palette
• editor/src/panels/FileTreePanel.h — docked file tree browser
• editor/src/panels/BreadcrumbBar.h — AST breadcrumb navigation
• editor/src/panels/StatusBar.h — status bar with language/workflow/diagnostic info

Modified files:

• editor/src/EditorState.h — docking enable, layout integration
• editor/src/main.cpp — theme application, panel manager initialization
• All existing panel renderers — migrate to PanelManager registration
• editor/CMakeLists.txt — test targets for steps 342-360

---

Design Principles

1. No floating windows. Every panel docks. Period.
2. Key symbols everywhere. If an action has a keybinding, its symbol is visible wherever that action appears — menus, palette, tooltips, shortcuts panel.
3. Theme is semantic. Colors are named by purpose (textError, syntax_keyword) not by value. Changing the theme changes everything.
4. Keyboard-first. Every action reachable by keyboard. Mouse is optional.
5. Professional defaults. First-run experience should look polished, not like a developer's test harness.