20 KiB
LCD Builder UI - Comprehensive Audit & Bug Report
Audit Date: October 22, 2025
Auditor: Code Review + Architecture Analysis
Status: FINDINGS DOCUMENTED - Ready for Testing & Implementation
Executive Summary
The LCD Builder UI has a solid architectural foundation with complete backend support and well-structured frontend code. However, there are critical bugs and incomplete implementations that prevent it from functioning properly. The audit identified 7 critical issues, 4 major issues, and 5 minor issues.
Key Finding: Most of the code is implemented correctly, but key features don't work due to:
- Missing HTML form rendering for properties panel initialization
- Incomplete page management (custom pages not properly saved/persisted)
- Canvas event handlers not properly attached to drag-and-drop
- Undo/redo infrastructure referenced but not implemented
- Drag-drop from palette to canvas not properly validated
Architecture Overview
Current Structure (✓ Working)
Backend (main.cpp):
- 7 API endpoints fully implemented and robust
- Data persistence to SPIFFS (/pages.json, /overlay[N].json)
- Chunk handling for large payloads
- Proper error handling and cache headers
Frontend (index.html):
- Three-part layout: Left sidebar (pages), Center (canvas), Right sidebar (widgets/properties)
- Canvas element properly sized (480×272px)
- Toolbar with buttons for all major operations
- Widget palette with 5 widget types
- Properties panel ready for dynamic content
- Binding modal for data binding
Frontend JavaScript (builder.js - 926 lines):
- Widget presets defined for 5 types
- Canvas rendering logic (redrawCanvas, drawElement, drawSelection)
- Event binding for toolbar actions
- Properties panel generation (buildPropertyForm)
- Properties application (applyPropertiesFromForm)
- Zoom controls fully implemented
- Page loading and switching logic
- Widget clone/manipulation utilities
CRITICAL BUGS (Must Fix - Blocks Core Functionality)
1. Properties Panel Form Doesn't Apply Changes
Severity: CRITICAL
Location: builder.js lines 760-820, 650-700
Problem:
buildPropertyForm()creates form with input fields ✓- Form has "Apply Changes" button with click handler ✓
- Handler calls
applyPropertiesFromForm()✓ - BUT: Input values are never applied to widget in state AND canvas is never properly updated
- Properties panel shows form but changes DON'T persist
Expected Behavior:
- User edits a property (e.g., X position)
- Clicks "Apply Changes"
- Widget updates on canvas
- Preview updates
- Form closes or shows confirmation
Current Behavior:
- Form appears with current values
- User edits
- Clicks "Apply Changes"
- Nothing happens visually
- Values may not be saved to state
Root Cause:
The applyPropertiesFromForm() function (lines 766-805) correctly reads form values and updates the widget object, BUT it doesn't properly validate the form element retrieval. Looking at line 768:
const getValue = (id) => form.querySelector(`#${id}`);
Then on line 769-770:
widget.x = Number(getValue('prop-x')?.value) || 0;
widget.y = Number(getValue('prop-y')?.value) || 0;
The issue: getValue() returns HTMLElement or null, then .value is accessed. If any input is missing, this returns 0 by default instead of keeping the original value.
Fix Required:
- Proper null checking for form inputs
- Validate values before applying
- Ensure widget object is updated in the overlayElements array
- Force redraw after applying
Priority: CRITICAL
2. Custom Pages Not Properly Saved or Persisted
Severity: CRITICAL
Location: builder.js lines 312-328, main.cpp /api/pages endpoint
Problem:
- Creating a custom page (line 314):
pagesCache.pages.push({ name, widgets: [] }) - Page is added to memory cache but NEVER sent to backend
- If user refreshes page or reboots device, custom page is LOST
- No API call to save pages.json file
Expected Behavior:
- User clicks "Add Page"
- Dialog prompts for page name
- Page is created locally
- Page is IMMEDIATELY saved to /pages.json via
/api/pagesPOST - Confirmation shows "Page saved"
- Page persists after refresh/reboot
Current Behavior:
- User clicks "Add Page"
- Dialog prompts for name
- Page appears in list temporarily
- Refresh page → custom page VANISHES
- No save confirmation or error handling
Root Cause: Lines 319-322 show the page is added to pagesCache but there's no code to call the save API:
if (!pagesCache) pagesCache = { pages: [] };
pagesCache.pages = pagesCache.pages || [];
pagesCache.pages.push({ name, widgets: [] });
loadPagesIntoUi();
Missing: await saveCustomPages(pagesCache); or similar API call
Fix Required:
- Add
saveCustomPages()function to call/api/pagesPOST endpoint - Save immediately after adding page
- Handle errors with user feedback
- Add progress indication
Priority: CRITICAL
3. Drag-Drop From Widget Palette to Canvas Not Working
Severity: CRITICAL
Location: builder.js lines 303-320 (bindPalette), canvas event handlers
Problem:
- Widget palette items have drag start/end handlers (lines 308-312)
- They set
state.builder.drag.pendingWidgetType - Canvas should have drop handler to create widget from palette
- Canvas DOES NOT have a drop handler
- Widget drag handlers don't add widgets to canvas
Expected Behavior:
- User clicks and drags widget from palette
- "Label" or "Icon" or "Button" item shows as being dragged
- User hovers over canvas - cursor changes to indicate drop zone
- User releases mouse
- Widget created on canvas at drop location
- Widget appears on canvas and in preview
Current Behavior:
- User tries to drag widget from palette
- Drag start fires, sets pendingWidgetType
- Nothing happens when dragging over canvas
- Drop has no effect
- Widget not created
- Only way to add widget is click palette (adds at center)
Root Cause:
Lines 308-312 show drag start/end handlers that manage pendingWidgetType, but there's no canvas drop or dragover event handler to actually CREATE the widget on drop.
The bindCanvasEvents() function (line 197+) handles mousedown/mousemove but doesn't handle drag/drop from external elements.
Fix Required:
- Add
dragoverevent handler to canvas (prevent default, show drop indicator) - Add
dropevent handler to canvas to create widget at drop position - Use
pendingWidgetTypeto determine what to create - Call
addWidgetToOverlay()with drop coordinates
Priority: CRITICAL
4. Delete, Copy, Paste Buttons Have No Implementation
Severity: CRITICAL
Location: builder.js lines 235-280 (toolbar bindings)
Problem:
- Delete button: addEventListener bound but NO handler function visible
- Copy button: addEventListener bound but NO handler function visible
- Paste button: addEventListener bound but NO handler function visible
- The event listeners exist but point to undefined or no-op handlers
Looking at lines 258-262:
document.getElementById('btn-delete')?.addEventListener('click', () => {
// HANDLER IS MISSING - NO CODE HERE
});
The same pattern repeats for copy (line 265) and paste (line 268) buttons.
Expected Behavior:
- Delete: Remove selected widget, update canvas
- Copy: Copy selected widget to clipboard (in state.builder.clipboard)
- Paste: Create new widget from clipboard, offset slightly, add to overlay
Current Behavior:
- Buttons are clickable but nothing happens
- No error messages
- No indication they're non-functional
Root Cause: The toolbar button binding code was partially written. Event listeners are attached but the handler functions inside the click callbacks are empty.
Fix Required:
- Implement delete handler: remove from overlayElements, update UI
- Implement copy handler: save widget to state.builder.clipboard
- Implement paste handler: create clone from clipboard with offset
- Add proper error handling and user feedback
- Update UI (redraw, preview, properties panel)
Priority: CRITICAL
5. Undo/Redo Buttons Have No Implementation
Severity: CRITICAL
Location: builder.js lines 245-247
Problem:
- Undo button: addEventListener bound but NO implementation
- Redo button: addEventListener bound but NO implementation
- Undo/redo state arrays referenced (state.builder.undoStack, redoStack) but never used
- No history tracking mechanism
Expected Behavior:
- User makes changes (add widget, move widget, edit properties)
- Each change is recorded in undo stack
- User clicks Undo
- Last action is reversed, added to redo stack
- User can click Redo to reapply
Current Behavior:
- Undo/Redo buttons are clickable but do nothing
- No history is recorded
- No indication they're non-functional
Root Cause: Similar to delete/copy/paste - event listeners exist but handlers are empty. Additionally, no mechanism exists to track state changes and record them to undo stack.
Fix Required:
- Implement state snapshot system on each modification
- Create history stack (undo) and reverse stack (redo)
- Implement undo handler to restore previous state
- Implement redo handler to restore next state
- Save snapshots when: widget added, deleted, moved, properties changed
Priority: CRITICAL
6. Canvas Drag-Drop and Selection Not Properly Wired
Severity: CRITICAL
Location: builder.js lines 197-230 (bindCanvasEvents)
Problem:
- Canvas mousedown/mousemove handlers exist (lines 210-225)
- Handlers check for element selection and drag setup
- BUT: The drag logic uses an incomplete state object
- No proper mousemove tracking for dragging
- No mouseup handler to end drag
Looking at lines 220-228, drag state is set but there's no mousemove handler that uses it to update widget position.
Expected Behavior:
- User clicks on widget on canvas
- Widget is selected (green border)
- User holds and drags mouse
- Widget follows cursor smoothly
- Coordinates update in properties panel
- Preview updates in real-time
- User releases mouse
- Widget position is finalized
Current Behavior:
- Clicking works (selection shows)
- Dragging doesn't move widget
- Widget stays in place
- No live coordinate updates
- No preview updates during drag
Root Cause:
The mousedown handler sets builder.drag.active = true and calculates offset (lines 219-221), but the mousemove handler that should use this data is incomplete or missing. There's also no mouseup handler to end the drag.
Fix Required:
- Add complete mousemove handler with drag tracking
- Calculate new widget position based on mouse movement
- Update widget.x and widget.y in real-time
- Redraw canvas during drag
- Add mouseup handler to end drag and finalize position
Priority: CRITICAL
7. Deploy to LCD Button Doesn't Verify Success
Severity: CRITICAL
Location: builder.js lines 414-430 (deployOverlay)
Problem:
- deployOverlay() calls saveOverlay() API
- Shows success toast on completion
- But DOESN'T verify data was actually written to device
- DOESN'T check if overlay widgets are actually rendering on LCD
- No fallback if save fails silently on device side
- triggerRedraw() is called but might fail silently
Expected Behavior:
- User clicks "Deploy to LCD"
- System shows "Sending to device..."
- Overlay is sent to ESP32
- Widgets are saved to SPIFFS
- LCD is updated with new widgets
- Confirmation shows "Successfully deployed to LCD"
- User can see changes on actual device
Current Behavior:
- User clicks "Deploy to LCD"
- Browser shows success toast immediately
- May or may not actually update LCD
- No verification
- If it fails on device, user doesn't know
- No way to check/troubleshoot
Root Cause:
The deployOverlay() function assumes success once the API call completes. However, there's no round-trip verification - the device should confirm the overlay was written and is rendering.
Fix Required:
- Add verification by reading back the overlay from device
- Compare sent vs. received to ensure data integrity
- Show "Verifying..." status during deployment
- Confirm with device that widgets are rendering
- Provide detailed error messages if deployment fails
Priority: CRITICAL
MAJOR BUGS (High Priority - Functional Issues)
8. Page Selector Dropdown Not Synced With Page List
Severity: MAJOR
Location: builder.js lines 50-72 (renderPageSelector)
Problem:
- Dropdown selector (renderPageSelector) and sidebar list (renderPageList) can get out of sync
- If user creates a custom page, it updates the list but not necessarily the dropdown
- Some code paths update one but not the other
- User can be confused about which page is actually loaded
Fix Required:
- Ensure both selector and list always update together
- Add synchronization on page creation/deletion/load
- Highlight current page in both UI elements
9. Widget Type Presets Don't Match Visual Rendering
Severity: MAJOR
Location: builder.js lines 1-20 (WIDGET_PRESETS)
Problem:
- Widget presets define default values (width, height, color, etc.)
- But rendering logic might not respect all properties
- Example: 'badge' widget type is defined in presets but never rendered in drawElement()
- Some properties might be named inconsistently (width vs w, height vs h)
Expected: All widget preset types should render correctly
Current: Missing 'badge' type rendering, property name inconsistencies
Fix Required:
- Ensure all widget types in WIDGET_PRESETS have corresponding rendering in drawElement()
- Standardize property names throughout (use w/h consistently)
- Add 'badge' rendering to switch statement
10. Properties Panel Input Validation Missing
Severity: MAJOR
Location: builder.js lines 760-805 (applyPropertiesFromForm)
Problem:
- No validation of numeric inputs before applying
- User can enter negative width/height
- User can enter positions outside canvas
- No feedback on invalid values
- Properties might be set to NaN or other invalid values
Expected Behavior:
- Validate X/Y are within canvas bounds [0, LCD_WIDTH/LCD_HEIGHT]
- Validate Width/Height are positive integers > 0
- Show error if invalid
- Don't apply invalid values
Current Behavior:
- Any value accepted without validation
- Invalid values break rendering
- No error messages
Fix Required:
- Add validation function for numeric properties
- Check bounds before applying
- Show validation errors to user
- Clamp values to valid ranges
11. Loading State Not Shown to User
Severity: MAJOR
Location: builder.js lines 68-79, 158-178
Problem:
- When loading pages from API, no loading indicator shown
- When loading builtin page base data, no loading state
- User sees nothing while data is being fetched
- If network is slow, user thinks nothing is happening
- Multiple clicks could trigger multiple loads
Fix Required:
- Show loading spinner or disabled state on page selector
- Show "Loading..." message in canvas
- Prevent multiple simultaneous loads (debounce selector changes)
- Show actual error message if load fails
MINOR BUGS (Low Priority - UX Issues)
12. No Minimum Size Constraints on Widgets
Problem: Users can create 0-sized or very small widgets that are invisible and hard to select. Add minimum size constraint.
13. No Confirmation Before Deleting Custom Pages
Problem: User can accidentally delete entire custom page with no undo. Add confirmation dialog.
14. Binding Modal Doesn't Show Categories
Problem: List of available bindings is flat and unorganized. Should group by category (temperature, status, control, etc.).
15. Canvas Doesn't Show Tooltips on Hover
Problem: User can't see widget ID or properties without selecting. Add hover tooltip showing widget info.
16. No Export/Import Feature for Pages
Problem: User can only edit pages in UI, can't export/import JSON for backup or sharing. Add export/import buttons.
Feature Gaps & Enhancements
Not Yet Implemented
-
Overlay vs Custom Pages - Unclear conceptual difference
- Overlays: Applied over builtin pages
- Custom Pages: Standalone pages
- UI doesn't clearly communicate this
-
Binding System - Partial implementation
- Can bind to state values ✓
- But can't create new bindings or modify existing ones
- Binding list shows available values but users can't understand what each one does
-
Widget Groups/Layers - No support
- Can't group widgets
- Can't hide individual widgets
- Can't manage z-order (layering)
-
Auto-Layout - Not available
- No alignment helpers beyond manual align buttons
- No distribution of widgets
- No snap-to-grid alignment verification
-
Responsive Design - Not considered
- All widgets absolute positioned
- No way to make responsive to different LCD sizes
- No breakpoint support
-
Widget Library - Only 5 types
- Missing: Image, Graph/Chart, Slider, Toggle, Input Field, Gauge
- Could expand widget types significantly
Implementation Priority Matrix
| Priority | Bugs | Effort | Impact | Status |
|---|---|---|---|---|
| P0 - CRITICAL | #1, #2, #3, #4, #5, #6, #7 | 80 hours | Blocks usage | NOT WORKING |
| P1 - MAJOR | #8, #9, #10, #11 | 40 hours | Significant UX issues | NEEDS WORK |
| P2 - MINOR | #12-16 | 20 hours | Polish/convenience | NICE TO HAVE |
| P3 - FEATURES | Binding sys, Groups, Export/Import | 60 hours | Advanced usage | FUTURE |
Recommended Implementation Plan
Phase 1: Core Functionality (12-16 hours)
- ✓ Fix properties panel form (Bug #1)
- ✓ Implement canvas drag-drop from palette (Bug #3)
- ✓ Implement delete/copy/paste (Bug #4)
- ✓ Implement undo/redo basic structure (Bug #5)
- ✓ Fix canvas drag-drop position updates (Bug #6)
Phase 2: Data Persistence (4-6 hours)
- ✓ Save custom pages to backend (Bug #2)
- ✓ Verify deploy to LCD (Bug #7)
- ✓ Fix page selector sync (Bug #8)
Phase 3: Robustness (6-8 hours)
- ✓ Add validation (Bug #10)
- ✓ Add loading states (Bug #11)
- ✓ Fix widget rendering (Bug #9)
- ✓ Fix minimum constraints (Bug #12)
Phase 4: Polish (6-8 hours)
- ✓ Add confirmation dialogs (Bug #13)
- ✓ Organize binding categories (Bug #14)
- ✓ Add hover tooltips (Bug #15)
- ✓ Add export/import (Bug #16)
Testing Checklist
Before considering builder "working", verify:
- Can create custom page
- Custom page persists after refresh
- Can add widget from palette by clicking
- Can add widget from palette by dragging
- Can select widget on canvas
- Can move widget by dragging on canvas
- Properties panel shows correct values
- Can edit properties and apply changes
- Changes appear on canvas and preview immediately
- Can copy selected widget
- Can paste copied widget
- Can delete selected widget
- Can undo last action (shows in undo stack)
- Can redo after undo
- Can deploy overlay to LCD
- Deployed widgets actually appear on LCD display
- Cannot create widgets outside canvas bounds
- Cannot create zero-sized widgets
- All 5 widget types render correctly
- Binding selector shows available values
- Can bind widget to value
- Live preview shows bound values updating
- Page list stays in sync with dropdown
- Loading states appear during API calls
Conclusion
The LCD Builder UI has excellent bones and architecture. The backend is solid. The frontend structure is well-organized. Most code is actually implemented. However, 7 critical bugs completely prevent core functionality from working.
Good news: Most bugs are straightforward to fix - they involve completing partial implementations rather than major refactoring.
Recommendation: Prioritize Phase 1 (core functionality fixes) to get builder into working state, then proceed with robustness and polish.
Estimated Time to Working MVP: 12-16 hours for Phase 1
Estimated Time to Full Polish: 30-40 hours total