RadiaCode-Spectrometer/ESP32-S3-Touch/_archive_previous_project/LCD_BUILDER_AUDIT_FINDINGS.md

20 KiB
Raw Permalink Blame History

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:

  1. Missing HTML form rendering for properties panel initialization
  2. Incomplete page management (custom pages not properly saved/persisted)
  3. Canvas event handlers not properly attached to drag-and-drop
  4. Undo/redo infrastructure referenced but not implemented
  5. 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:

  1. User clicks "Add Page"
  2. Dialog prompts for page name
  3. Page is created locally
  4. Page is IMMEDIATELY saved to /pages.json via /api/pages POST
  5. Confirmation shows "Page saved"
  6. Page persists after refresh/reboot

Current Behavior:

  1. User clicks "Add Page"
  2. Dialog prompts for name
  3. Page appears in list temporarily
  4. Refresh page → custom page VANISHES
  5. 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/pages POST 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:

  1. User clicks and drags widget from palette
  2. "Label" or "Icon" or "Button" item shows as being dragged
  3. User hovers over canvas - cursor changes to indicate drop zone
  4. User releases mouse
  5. Widget created on canvas at drop location
  6. Widget appears on canvas and in preview

Current Behavior:

  1. User tries to drag widget from palette
  2. Drag start fires, sets pendingWidgetType
  3. Nothing happens when dragging over canvas
  4. Drop has no effect
  5. Widget not created
  6. 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 dragover event handler to canvas (prevent default, show drop indicator)
  • Add drop event handler to canvas to create widget at drop position
  • Use pendingWidgetType to 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:

  1. User clicks on widget on canvas
  2. Widget is selected (green border)
  3. User holds and drags mouse
  4. Widget follows cursor smoothly
  5. Coordinates update in properties panel
  6. Preview updates in real-time
  7. User releases mouse
  8. 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:

  1. User clicks "Deploy to LCD"
  2. System shows "Sending to device..."
  3. Overlay is sent to ESP32
  4. Widgets are saved to SPIFFS
  5. LCD is updated with new widgets
  6. Confirmation shows "Successfully deployed to LCD"
  7. User can see changes on actual device

Current Behavior:

  1. User clicks "Deploy to LCD"
  2. Browser shows success toast immediately
  3. May or may not actually update LCD
  4. No verification
  5. If it fails on device, user doesn't know
  6. 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

  1. Overlay vs Custom Pages - Unclear conceptual difference

    • Overlays: Applied over builtin pages
    • Custom Pages: Standalone pages
    • UI doesn't clearly communicate this
  2. 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
  3. Widget Groups/Layers - No support

    • Can't group widgets
    • Can't hide individual widgets
    • Can't manage z-order (layering)
  4. Auto-Layout - Not available

    • No alignment helpers beyond manual align buttons
    • No distribution of widgets
    • No snap-to-grid alignment verification
  5. Responsive Design - Not considered

    • All widgets absolute positioned
    • No way to make responsive to different LCD sizes
    • No breakpoint support
  6. 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

Phase 1: Core Functionality (12-16 hours)

  1. ✓ Fix properties panel form (Bug #1)
  2. ✓ Implement canvas drag-drop from palette (Bug #3)
  3. ✓ Implement delete/copy/paste (Bug #4)
  4. ✓ Implement undo/redo basic structure (Bug #5)
  5. ✓ Fix canvas drag-drop position updates (Bug #6)

Phase 2: Data Persistence (4-6 hours)

  1. ✓ Save custom pages to backend (Bug #2)
  2. ✓ Verify deploy to LCD (Bug #7)
  3. ✓ Fix page selector sync (Bug #8)

Phase 3: Robustness (6-8 hours)

  1. ✓ Add validation (Bug #10)
  2. ✓ Add loading states (Bug #11)
  3. ✓ Fix widget rendering (Bug #9)
  4. ✓ Fix minimum constraints (Bug #12)

Phase 4: Polish (6-8 hours)

  1. ✓ Add confirmation dialogs (Bug #13)
  2. ✓ Organize binding categories (Bug #14)
  3. ✓ Add hover tooltips (Bug #15)
  4. ✓ 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