feat(profiles): seed twinkle preset defaults

Made-with: Cursor

.cursor/debug.log

@@ -0,0 +1,116 @@
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434706543}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434706552}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434707852}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434707860}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434708466}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434708474}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/create-form-fragment","targetId":""},"timestamp":1768434709765}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/create-form-fragment","targetId":""},"timestamp":1768434709787}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs","targetId":"tabs-list"},"timestamp":1768434717888}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":201,"responseURL":"http://localhost:5000/tabs","targetId":"tabs-list"},"timestamp":1768434717903}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434717904}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434717913}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434738084}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434738093}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434739031}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434739040}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434746453}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434746496}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/create-form-fragment","targetId":""},"timestamp":1768434748859}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/create-form-fragment","targetId":""},"timestamp":1768434748866}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs","targetId":"tabs-list"},"timestamp":1768434773921}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":201,"responseURL":"http://localhost:5000/tabs","targetId":"tabs-list"},"timestamp":1768434773931}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434773931}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434773940}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/create-form-fragment","targetId":""},"timestamp":1768434810105}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/create-form-fragment","targetId":""},"timestamp":1768434810119}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs","targetId":"tabs-list"},"timestamp":1768434816383}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":201,"responseURL":"http://localhost:5000/tabs","targetId":"tabs-list"},"timestamp":1768434816399}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434816400}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434816414}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434944656}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434944756}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434945369}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434945427}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434946108}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434946162}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434946680}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434946736}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/create-form-fragment","targetId":""},"timestamp":1768434947640}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/create-form-fragment","targetId":""},"timestamp":1768434947656}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs","targetId":"tabs-list"},"timestamp":1768434953064}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":201,"responseURL":"http://localhost:5000/tabs","targetId":"tabs-list"},"timestamp":1768434953079}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434953080}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768434953093}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435103720}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435103776}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435104593}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435104647}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435105158}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435105253}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435275247}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435275315}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435276178}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435276278}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435276945}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435276998}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/create-form-fragment","targetId":""},"timestamp":1768435278150}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/create-form-fragment","targetId":""},"timestamp":1768435278162}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs","targetId":"tabs-list"},"timestamp":1768435281966}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":400,"responseURL":"http://localhost:5000/tabs","targetId":"tabs-list"},"timestamp":1768435281988}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435387623}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435387680}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435388399}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435388454}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/create-form-fragment","targetId":""},"timestamp":1768435389910}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/create-form-fragment","targetId":""},"timestamp":1768435389922}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs","targetId":"tabs-list"},"timestamp":1768435393213}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs","targetId":"tabs-list"},"timestamp":1768435393231}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435393233}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435393245}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/12/content-fragment","targetId":"tab-content"},"timestamp":1768435395729}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/12/content-fragment","targetId":"tab-content"},"timestamp":1768435395748}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/13/content-fragment","targetId":"tab-content"},"timestamp":1768435396771}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/13/content-fragment","targetId":"tab-content"},"timestamp":1768435396788}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/12/content-fragment","targetId":"tab-content"},"timestamp":1768435398656}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/12/content-fragment","targetId":"tab-content"},"timestamp":1768435398674}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/13/content-fragment","targetId":"tab-content"},"timestamp":1768435399748}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/13/content-fragment","targetId":"tab-content"},"timestamp":1768435399774}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435668310}
+{"sessionId":"debug-session","runId":"palette-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:DOMContentLoaded","message":"palette elements presence","data":{"hasPaletteButton":true,"hasPaletteModal":false,"hasPaletteContainer":false,"hasLightingController":false},"timestamp":1768435668311}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435668355}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435669841}
+{"sessionId":"debug-session","runId":"palette-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:DOMContentLoaded","message":"palette elements presence","data":{"hasPaletteButton":true,"hasPaletteModal":false,"hasPaletteContainer":false,"hasLightingController":false},"timestamp":1768435669842}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435669852}
+{"sessionId":"debug-session","runId":"palette-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:color-palette-btn","message":"color palette button clicked","data":{"hasPaletteModal":false,"modalActive":null},"timestamp":1768435672686}
+{"sessionId":"debug-session","runId":"palette-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:color-palette-btn","message":"color palette button clicked","data":{"hasPaletteModal":false,"modalActive":null},"timestamp":1768435673713}
+{"sessionId":"debug-session","runId":"palette-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:color-palette-btn","message":"color palette button clicked","data":{"hasPaletteModal":false,"modalActive":null},"timestamp":1768435674316}
+{"sessionId":"debug-session","runId":"palette-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:color-palette-btn","message":"color palette button clicked","data":{"hasPaletteModal":false,"modalActive":null},"timestamp":1768435674560}
+{"sessionId":"debug-session","runId":"palette-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:color-palette-btn","message":"color palette button clicked","data":{"hasPaletteModal":false,"modalActive":null},"timestamp":1768435680419}
+{"sessionId":"debug-session","runId":"palette-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:color-palette-btn","message":"color palette button clicked","data":{"hasPaletteModal":false,"modalActive":null},"timestamp":1768435680897}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435814285}
+{"sessionId":"debug-session","runId":"palette-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:DOMContentLoaded","message":"palette elements presence","data":{"hasPaletteButton":true,"hasPaletteModal":true,"hasPaletteContainer":false,"hasLightingController":false},"timestamp":1768435814287}
+{"sessionId":"debug-session","runId":"palette-pre-fix","hypothesisId":"H3","location":"src/static/color_palette.js:DOMContentLoaded","message":"palette script loaded","data":{"hasButton":true,"hasModal":true,"hasClose":true},"timestamp":1768435814287}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435814350}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435815080}
+{"sessionId":"debug-session","runId":"palette-pre-fix","hypothesisId":"H3","location":"src/static/color_palette.js:DOMContentLoaded","message":"palette script loaded","data":{"hasButton":true,"hasModal":true,"hasClose":true},"timestamp":1768435815081}
+{"sessionId":"debug-session","runId":"palette-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:DOMContentLoaded","message":"palette elements presence","data":{"hasPaletteButton":true,"hasPaletteModal":true,"hasPaletteContainer":false,"hasLightingController":false},"timestamp":1768435815082}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435815135}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435815724}
+{"sessionId":"debug-session","runId":"palette-pre-fix","hypothesisId":"H3","location":"src/static/color_palette.js:DOMContentLoaded","message":"palette script loaded","data":{"hasButton":true,"hasModal":true,"hasClose":true},"timestamp":1768435815725}
+{"sessionId":"debug-session","runId":"palette-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:DOMContentLoaded","message":"palette elements presence","data":{"hasPaletteButton":true,"hasPaletteModal":true,"hasPaletteContainer":false,"hasLightingController":false},"timestamp":1768435815725}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435815778}
+{"sessionId":"debug-session","runId":"palette-pre-fix","hypothesisId":"H4","location":"src/static/color_palette.js:openModal","message":"palette modal opened","data":{"active":true},"timestamp":1768435817104}
+{"sessionId":"debug-session","runId":"palette-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:color-palette-btn","message":"color palette button clicked","data":{"hasPaletteModal":true,"modalActive":true},"timestamp":1768435817105}
+{"sessionId":"debug-session","runId":"palette-pre-fix","hypothesisId":"H4","location":"src/static/color_palette.js:closeModal","message":"palette modal closed","data":{"active":false},"timestamp":1768435820180}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435931118}
+{"sessionId":"debug-session","runId":"palette-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:DOMContentLoaded","message":"palette elements presence","data":{"hasPaletteButton":true,"hasPaletteModal":true,"hasPaletteContainer":true,"hasLightingController":false},"timestamp":1768435931120}
+{"sessionId":"debug-session","runId":"palette-pre-fix","hypothesisId":"H3","location":"src/static/color_palette.js:DOMContentLoaded","message":"palette script loaded","data":{"hasButton":true,"hasModal":true,"hasClose":true,"hasContainer":true,"hasAddButton":true},"timestamp":1768435931119}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435931173}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:htmx:beforeRequest","message":"htmx request","data":{"path":"/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435931791}
+{"sessionId":"debug-session","runId":"palette-pre-fix","hypothesisId":"H1","location":"src/templates/index.html:DOMContentLoaded","message":"palette elements presence","data":{"hasPaletteButton":true,"hasPaletteModal":true,"hasPaletteContainer":true,"hasLightingController":false},"timestamp":1768435931793}
+{"sessionId":"debug-session","runId":"palette-pre-fix","hypothesisId":"H3","location":"src/static/color_palette.js:DOMContentLoaded","message":"palette script loaded","data":{"hasButton":true,"hasModal":true,"hasClose":true,"hasContainer":true,"hasAddButton":true},"timestamp":1768435931793}
+{"sessionId":"debug-session","runId":"tabs-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:htmx:afterRequest","message":"htmx response","data":{"status":200,"responseURL":"http://localhost:5000/tabs/list-fragment","targetId":"tabs-list"},"timestamp":1768435931895}
+{"sessionId":"debug-session","runId":"palette-pre-fix","hypothesisId":"H2","location":"src/templates/index.html:color-palette-btn","message":"color palette button clicked","data":{"hasPaletteModal":true,"modalActive":true},"timestamp":1768435933111}
+{"sessionId":"debug-session","runId":"palette-pre-fix","hypothesisId":"H4","location":"src/static/color_palette.js:openModal","message":"palette modal opened","data":{"active":true},"timestamp":1768435933110}
+{"sessionId":"debug-session","runId":"palette-pre-fix","hypothesisId":"H4","location":"src/static/color_palette.js:closeModal","message":"palette modal closed","data":{"active":false},"timestamp":1768435943332}

.cursor/rules/commit.mdc

@@ -0,0 +1,26 @@
+---
+description: Git commit messages and how to split work into commits
+alwaysApply: true
+---
+
+# Commits
+
+When preparing commits (especially when the user asks to commit):
+
+1. **Prefer multiple commits** over one large commit when changes span distinct concerns (e.g. UI vs docs vs API). One logical unit per commit.
+2. **Message format:** `type(scope): short imperative subject` (lowercase subject after the colon; no trailing period).
+   - **Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf` (use what fits).
+   - **Scope:** optional but encouraged — e.g. `ui`, `api`, `profiles`, `presets`, `esp32`.
+3. **Subject line:** ~50 characters or less; describe *what* changed, not the ticket number alone.
+4. **Body:** only when needed (breaking change, non-obvious rationale, or multiple bullets). Otherwise subject is enough.
+
+**Examples**
+
+- `feat(ui): gate profile delete to edit mode`
+- `docs: document run vs edit in API`
+- `fix(api): resolve preset delete route argument clash`
+
+**Do not**
+
+- Squash unrelated fixes and doc tweaks into one commit unless the user explicitly wants a single commit.
+- Use vague messages like `update`, `fixes`, or `wip`.

.cursor/rules/led-driver.mdc

@@ -0,0 +1,45 @@
+---
+description: led-driver — MicroPython ESP32: mpremote, imports, layout, I/O, no pycache in src
+globs: led-driver/**
+alwaysApply: false
+---
+
+# led-driver (MicroPython / ESP32)
+
+## Device and tests
+
+1. Validate **MicroPython behaviour** under **`led-driver/`** with **`mpremote connect <PORT> …`** on the chip. Host **`python3`** does **not** prove the firmware build.
+
+2. **Execution target is fixed:** treat **`led-driver/`** code as firmware that runs **only on MicroPython ESP32 devices**. Do **not** run `led-driver/src/main.py` (or other firmware modules) with host CPython as a normal execution path.
+
+3. **Flow:** `mpremote connect <PORT> cp <local> :<on-flash>` then `run <script>.py`. Inline commands only — no **`.sh`** wrappers unless the user asks. Default serial placeholder: **`/dev/ttyACM0`**.
+
+4. Checks that **import and run** code from **`led-driver/src/`** belong in **`led-driver/tests/`** and run with **`mpremote run …`**. **Do not** add **`pytest`** under **`led-controller/tests/`** that **`sys.path`**-loads **`led-driver/src`** and runs those modules on CPython.
+
+## Import layout
+
+4. **No** **`sys.path.insert`**, **`__file__`** path stitching, or other import-path hacks under **`led-driver/`**. Use device flash search path, or host **`PYTHONPATH`** / layout you control.
+
+5. **No** “import fixer” code — fix copy order, flash paths, or env instead.
+
+## Imports (fail loudly)
+
+6. If a dependency does not load, **crash** and fix deployment or filesystem. **Do not** catch **`ImportError`** / **`ModuleNotFoundError`** around **`import`** / **`from … import`** for app/firmware modules (`settings`, `utils`, `network`, `machine`, …).
+
+7. **Allowed — stdlib name pairs only** (MicroPython vs CPython): one **`except ImportError`**, then **one** fallback import, **no** extra logic in **`except`**:
+   - `uos` → `os`
+   - `ubinascii` → `binascii`
+   - `utime` → `time`  
+   Not for “maybe the file exists on flash” — only different **stdlib** names.
+
+8. **No** large inline reimplementations after **`except ImportError`** — deploy the real module.
+
+## I/O
+
+9. Non-blocking **recv** / **accept**: use plain **`except OSError:`** (or **break** on empty). **No** errno / EAGAIN / EWOULDBLOCK tables or **`getattr(errno, …)`** unless fixing a **documented** target bug.
+
+10. Minimal **`try` / `except OSError`** around optional socket options (e.g. **`SO_REUSEADDR`**) is fine.
+
+## Host Python and `src/`
+
+11. **Do not** leave **`__pycache__/`** or **`.pyc`** under **`led-driver/src/`** from host runs. Remove if created; **`.gitignore`** already ignores it. Prefer **`PYTHONDONTWRITEBYTECODE=1`** or **`-B`** when host Python must touch **`led-driver/src/`**.

.cursor/rules/scoped-fixes.mdc

@@ -0,0 +1,18 @@
+---
+description: Fix only the issue or task the user gave; no refactors unless requested
+alwaysApply: true
+---
+
+# Scoped fixes (no overscoping)
+
+1. **Change only what is needed** to satisfy the user’s *current* request (bug, error, feature, or explicit follow-up). Prefer the smallest diff that fixes it.
+
+2. **Refactors:** Do **not** refactor (restructure, rename, extract functions, change abstractions, or “make it nicer”) **unless the user explicitly asked for a refactor**. A bug fix may touch nearby lines only as much as required to correct the bug.
+
+3. **Do not** rename, reformat, or “clean up” unrelated code; do not add extra error handling, logging, or features you were not asked for.
+
+4. **Related issues:** If you spot other problems (missing functions, wrong types elsewhere, style), you may **mention them in prose** — do **not** fix them unless the user explicitly asks.
+
+5. **Tests and docs:** Add or change tests or documentation **only** when the user asked for them or they are strictly required to verify the requested fix.
+
+6. **Multiple distinct fixes:** If the user reported one error (e.g. a single `TypeError`), fix **that** cause first. Offer to tackle follow-ups separately rather than bundling.

.cursor/rules/spelling.mdc

@@ -0,0 +1,10 @@
+---
+description: British spelling for user-facing text; technical identifiers stay as-is
+alwaysApply: true
+---
+
+# Spelling: colour
+
+- **User-facing strings** (Help modal, button labels, README prose, `docs/`, error messages shown in the UI): use **British English** — **colour**, **favour**, **behaviour**, etc., unless quoting existing product names.
+- **Do not rename** existing code for spelling: **identifiers**, file names, URL paths, JSON keys, CSS properties (`color`), HTML attributes (`type="color"`), and API field names stay as they are (`color`, `colors`, `palette`, etc.) so nothing breaks.
+- **New** UI copy and docs should follow **colour** in prose; new code symbols may still use `color` when matching surrounding APIs or conventions.

.cursor/rules/strict-user-scope.mdc

@@ -0,0 +1,16 @@
+---
+description: enforce strict user-scoped changes only
+alwaysApply: true
+---
+
+# Strict User Scope
+
+1. Only implement exactly what the user asked for in the current message.
+
+2. Do not add extra refactors, cleanups, renames, architecture changes, or behavioural changes unless the user explicitly asked for them.
+
+3. If a potential improvement is noticed, mention it briefly and ask before changing code.
+
+4. For revert/undo requests, perform the narrowest possible revert and do not modify anything else.
+
+5. Keep edits minimal and local to the requested area.

.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+# led-driver/src is MicroPython source — never keep host __pycache__ there (see .cursor/rules/led-driver.mdc)
+led-driver/src/__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+docs/.help-print.html
+settings.json
+*.log
+*.db
+*.sqlite
+.pytest_cache/
+.ropeproject/

.gitmodules

@@ -0,0 +1,6 @@
+[submodule "led-driver"]
+	path = led-driver
+	url = git@git.technical.kiwi:technicalkiwi/led-driver.git
+[submodule "led-tool"]
+	path = led-tool
+	url = git@git.technical.kiwi:technicalkiwi/led-tool.git

Pipfile

@@ -7,8 +7,24 @@ name = "pypi"
 mpremote = "*"
 pyserial = "*"
 esptool = "*"
+pyjwt = "*"
+watchfiles = "*"
+requests = "*"
+selenium = "*"
+adafruit-ampy = "*"
+microdot = "*"
+websockets = "*"
 
 [dev-packages]
+pytest = "*"
 
 [requires]
 python_version = "3.12"
+
+[scripts]
+web = "python /home/pi/led-controller/tests/web.py"
+watch = "python -m watchfiles 'python tests/web.py' src tests"
+install = "pipenv install"
+run = "sh -c 'cd src && python main.py'"
+dev = "watchfiles \"sh -c 'cd src && python main.py'\" src"
+help-pdf = "sh scripts/build_help_pdf.sh"

README.md

@@ -1,2 +1,43 @@
 # led-controller
 
+LED controller web app for managing profiles, **zones**, presets, and colour palettes, and sending commands to LED devices. Outbound paths include:
+
+- **Serial → ESP-NOW bridge**: JSON lines over UART to an ESP32 that forwards ESP-NOW frames (configure `serial_port` and baud in `settings.json` / Settings model).
+- **Wi-Fi LED drivers**: TCP JSON lines (default port **8765** on the Pi; drivers discover the controller via **UDP 8766** broadcast).
+
+## Run
+
+- One-time setup for port 80 without root: `sudo scripts/setup-port80.sh`
+- Start app: `pipenv run run` (override listen port with the **`PORT`** environment variable)
+- Dev watcher (auto-restart on `src/` changes): `pipenv run dev`
+- Regenerate **`docs/help.pdf`** from **`docs/help.md`**: `pipenv run help-pdf` (requires **pandoc** and **chromium** on the host)
+
+## UI modes
+
+- **Run mode**: focused control view. Select zones/presets and apply profiles. Editing actions are hidden.
+- **Edit mode**: management view. Shows **Zones**, Presets, Patterns, Colour Palette, and Send Presets controls, plus per-tile preset edit/remove and drag-reorder.
+
+## Profiles
+
+- Applying a profile updates session scope and refreshes the active zone content.
+- In **Run mode**, Profiles supports apply-only behaviour (no create/clone/delete).
+- In **Edit mode**, Profiles supports create/clone/delete.
+- Creating a profile always creates a populated `default` zone (starter presets).
+- Optional **DJ zone** seeding creates:
+  - `dj` zone bound to device name `dj`
+  - starter DJ presets (rainbow, single colour, transition)
+
+## Preset colours and palette linking
+
+- In preset editor, selecting a colour picker value auto-adds it when the picker closes.
+- Use **From Palette** to add a palette-linked preset colour.
+- Linked colours are stored as palette references and shown with a `P` badge.
+- When profile palette colours change, linked preset colours update across that profile.
+
+## API docs
+
+- Main API reference: `docs/API.md`
+
+## Driver pattern modules
+
+Pattern **`.py`** sources live under **`led-driver/src/patterns`**. The Pi app resolves that path via `util.driver_patterns.driver_patterns_dir()`. If you deploy without that tree next to the app, set **`LED_CONTROLLER_PATTERNS_DIR`** to the directory that contains those files.

db/device.json

@@ -0,0 +1 @@
+{"188b0e1560a8": {"id": "188b0e1560a8", "name": "led-188b0e1560a8", "type": "led", "transport": "wifi", "address": "10.1.1.192", "default_pattern": null, "zones": []}, "f0f5bdfb9d30": {"id": "f0f5bdfb9d30", "name": "led-f0f5bdfb9d30", "type": "led", "transport": "wifi", "address": "10.1.1.232", "default_pattern": null, "zones": []}}

db/group.json

@@ -0,0 +1 @@
+{"1": {"name": "Main Group", "devices": ["1", "2", "3"]}, "2": {"name": "Accent Group", "devices": ["4", "5"]}}

db/palette.json

@@ -0,0 +1 @@
+{"1": ["#FF0000", "#00FF00", "#0000FF", "#FFFF00", "#FF00FF", "#00FFFF", "#FFFFFF", "#000000"], "2": [], "3": [], "4": [], "5": [], "6": [], "7": ["#FF0000", "#00FF00", "#0000FF", "#FFFF00", "#FF00FF", "#00FFFF", "#FFFFFF", "#000000"], "8": [], "9": [], "10": [], "11": [], "12": ["#890b0b", "#0b8935"]}

db/pattern.json

@@ -0,0 +1,92 @@
+{
+    "on": {
+            "min_delay": 10,
+            "max_delay": 10000,
+            "max_colors": 1
+        },
+    "off": {
+        "min_delay": 10,
+        "max_delay": 10000,
+        "max_colors": 0
+    },
+    "rainbow": {
+        "n1": "Step Rate",
+        "min_delay": 10,
+        "max_delay": 10000,
+        "max_colors": 0
+    },
+    "colour_cycle": {
+        "n1": "Step Rate",
+        "min_delay": 10,
+        "max_delay": 10000,
+        "max_colors": 10
+    },
+    "transition": {
+        "min_delay": 10,
+        "max_delay": 10000,
+        "max_colors": 10
+    },
+    "chase": {
+        "n1": "Colour 1 Length",
+        "n2": "Colour 2 Length",
+        "n3": "Step 1",
+        "n4": "Step 2",
+        "min_delay": 10,
+        "max_delay": 10000,
+        "max_colors": 2
+    },
+    "pulse": {
+        "n1": "Attack",
+        "n2": "Hold",
+        "n3": "Decay",
+        "min_delay": 10,
+        "max_delay": 10000,
+        "max_colors": 10
+    },
+    "circle": {
+        "n1": "Head Rate",
+        "n2": "Max Length",
+        "n3": "Tail Rate",
+        "n4": "Min Length",
+        "min_delay": 10,
+        "max_delay": 10000,
+        "max_colors": 2
+    },
+    "blink": {
+        "min_delay": 10,
+        "max_delay": 10000,
+        "max_colors": 10
+    },
+    "flicker": {
+        "n1": "Min brightness",
+        "min_delay": 10,
+        "max_delay": 10000,
+        "max_colors": 10
+    },
+    "flame": {
+        "n1": "Min brightness",
+        "n2": "Breath period (ms)",
+        "n3": "Spark gap min (ms, 0=default 10–30 s, -1=off)",
+        "n4": "Spark gap max (ms)",
+        "min_delay": 10,
+        "max_delay": 10000,
+        "max_colors": 10
+    },
+    "twinkle": {
+        "n1": "Twinkle activity (1–255, higher = more changes)",
+        "n2": "Density (0–255, higher = more of the strip lit)",
+        "n3": "Min adjacent LEDs per twinkle (same as max for fixed length)",
+        "n4": "Max adjacent LEDs per twinkle (same as min for fixed length)",
+        "min_delay": 10,
+        "max_delay": 10000,
+        "max_colors": 10
+    },
+    "radiate": {
+        "n1": "Node spacing (LEDs)",
+        "n2": "Out time (ms)",
+        "n3": "In time (ms)",
+        "min_delay": 10,
+        "max_delay": 10000,
+        "max_colors": 2
+    }
+}

db/profile.json

@@ -0,0 +1 @@
+{"1": {"name": "default", "type": "zones", "zones": ["1", "8"], "scenes": [], "palette_id": "1"}, "2": {"name": "test", "type": "zones", "zones": ["6", "7"], "scenes": [], "palette_id": "12"}}

db/scene.json

@@ -0,0 +1,22 @@
+{
+    "1": {
+        "name": "Default Scene",
+        "sequences": [
+            "1"
+        ],
+        "groups": [
+            "1"
+        ]
+    },
+    "2": {
+        "name": "Party Mode",
+        "sequences": [
+            "1",
+            "2"
+        ],
+        "groups": [
+            "1",
+            "2"
+        ]
+    }
+}

db/sequence.json

@@ -0,0 +1 @@
+{"1": {"group_name": "Main Group", "presets": ["1", "2"], "sequence_duration": 3000, "sequence_transition": 500, "sequence_loop": true, "sequence_repeat_count": 0, "sequence_active": false, "sequence_index": 0, "sequence_start_time": 0}, "2": {"group_name": "Accent Group", "presets": ["2", "3"], "sequence_duration": 2000, "sequence_transition": 300, "sequence_loop": true, "sequence_repeat_count": 0, "sequence_active": false, "sequence_index": 0, "sequence_start_time": 0}}

db/zone.json

@@ -0,0 +1 @@
+{"1": {"name": "default", "names": ["led-188b0e1560a8", "led-f0f5bdfb9d30"], "presets": [["4", "2", "7"], ["3", "14", "5"], ["8", "9", "1"], ["6", "38", "42"], ["39", "40", "41"]], "presets_flat": ["4", "2", "7", "3", "14", "5", "8", "9", "1", "6", "38", "42", "39", "40", "41"], "default_preset": "4"}, "2": {"name": "default", "names": ["1", "2", "3", "4", "5", "6", "7", "8", "0", "a"], "presets": [["16", "17", "18"], ["19", "20", "21"], ["22", "23", "24"], ["25", "26", "27"], ["28", "29", "30"]], "presets_flat": ["16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30"]}, "3": {"name": "default", "names": ["1"], "presets": [], "default_preset": null}, "4": {"name": "default", "names": ["1"], "presets": [], "default_preset": null}, "5": {"name": "dj", "names": ["dj"], "presets": [["31", "32", "33"]], "default_preset": "31", "presets_flat": ["31", "32", "33"]}, "6": {"name": "default", "names": ["1"], "presets": [], "default_preset": null}, "7": {"name": "dj", "names": ["dj"], "presets": [["34", "35", "36"]], "default_preset": "34", "presets_flat": ["34", "35", "36"]}, "8": {"name": "test", "names": ["led-188b0e1560a8"], "presets": [["1", "2", "3"], ["4", "5"]], "default_preset": "1", "presets_flat": ["1", "2", "3", "4", "5"]}}

dev.py

@@ -1,33 +0,0 @@
-#!/usr/bin/env python3
-
-import subprocess
-import serial
-import sys
-
-print(sys.argv)
-
-port = sys.argv[1]
-
-cmd = sys.argv[1]
-
-for cmd in sys.argv[1:]:
-    print(cmd)
-    match cmd:
-        case "src":
-            subprocess.call(["mpremote", "connect", port, "fs", "cp", "-r", ".", ":" ], cwd="src")
-        case "lib":
-            subprocess.call(["mpremote", "connect", port, "fs", "cp", "-r", "lib", ":" ])
-        case "ls":
-            subprocess.call(["mpremote", "connect", port, "fs", "ls", ":" ])
-        case "reset":
-            with serial.Serial(port, baudrate=115200) as ser:
-                ser.write(b'\x03\x03\x04')
-        case "follow":
-            with serial.Serial(port, baudrate=115200) as ser:
-                while True:
-                    if ser.in_waiting > 0:  # Check if there is data in the buffer
-                        data = ser.readline().decode('utf-8').strip()  # Read and decode the data
-                        print(data)
-
-
-

docs/API.md

@@ -1,504 +1,358 @@
-# LED Controller API Specification
+# LED Controller API
 
-**Base URL:** `http://device-ip/` or `http://192.168.4.1/` (when in AP mode)  
+This document covers:
-**Protocol:** HTTP/1.1  
-**Content-Type:** `application/json`
 
-## Presets API
+1. **HTTP and WebSocket** exposed by the Raspberry Pi app (`src/main.py`) — profiles, zones, presets, transport send, pattern OTA helpers, and related resources.
+2. **LED driver JSON** — the compact **v1** message format. It is sent over the **serial → ESP-NOW bridge** to ESP32 peers and as **single JSON text messages** over the **outbound WebSocket** to **Wi-Fi** drivers (same logical fields).
 
-### GET /presets
+Default HTTP listen address: `0.0.0.0`. Port defaults to **80**; override with the **`PORT`** environment variable (see `pipenv run run`).
 
-List all presets.
+**Serial:** UART path and baud come from settings (defaults include `serial_port` such as `/dev/ttyS0` and `serial_baudrate`). **Wi-Fi drivers:** **UDP** on port **8766** is the **discovery** channel: each driver’s JSON hello (**`device_name`**, **MAC**, optional **`type`**) **creates or updates** that device in **`db/device.json`** (keyed by MAC); the Pi echoes the datagram. After a valid hello with **`v`:** **`"1"`**, the Pi also opens an **outbound WebSocket** to that IP (**`wifi_driver_ws_port`**, default **80**; **`wifi_driver_ws_path`**, default **`/ws`**) for v1 commands; presets are not pushed automatically on connect (use **Send Presets** / profile apply). The Pi may send periodic UDP **hello** nudges to known Wi‑Fi device IPs when the WebSocket is down (**`wifi_driver_hello_interval_s`** in settings).
+
+All JSON APIs use `Content-Type: application/json` for bodies and responses unless noted.
+
+---
+
+## UI behavior notes
+
+The main UI has two modes controlled by the mode toggle:
+
+- **Run mode**: optimized for operation (zone/preset selection and profile apply).
+- **Edit mode**: shows editing/management controls (zones, presets, patterns, colour palette, send presets, profile management actions, **Devices** registry for LED driver names/MACs, and related tools).
+
+Profiles are available in both modes, but behavior differs:
+
+- **Run mode**: profile **apply** only.
+- **Edit mode**: profile **create/clone/delete/apply**.
+
+`POST /presets/send` is wired to the **Send Presets** UI action, which is exposed in Edit mode.
+
+---
+
+## Session and scoping
+
+Several routes use **`@with_session`**: the server stores a **current profile** in the session (cookie). Endpoints that scope data to “the current profile” (notably **`/presets`**) only return or mutate presets whose `profile_id` matches that session value.
+
+Profiles are selected with **`POST /profiles/<id>/apply`**, which sets `current_profile` in the session.
+
+---
+
+## Static pages and assets
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/` | Main UI (`templates/index.html`) |
+| GET | `/settings` | Settings page (`templates/settings.html`) |
+| GET | `/favicon.ico` | Empty response (204) |
+| GET | `/static/<path>` | Static files under `src/static/` |
+
+---
+
+## WebSocket: `/ws`
+
+Connect to **`ws://<host>:<port>/ws`**.
+
+- Send **JSON**: the object is forwarded through the **serial sender** (6-byte MAC prefix + payload to the ESP-NOW bridge). Optional key **`to`**: 12-character hex MAC address; if present it is removed from the object and the payload is sent to that peer; otherwise the default destination from settings is used.
+- Send **non-JSON text**: forwarded as raw bytes with the default address.
+- On send failure, the server may reply with `{"error": "Send failed"}`.
+
+Wi-Fi devices are not targeted by `/ws` directly; use **`POST /presets/send`**, device routes, or **`POST /patterns/<name>/send`** as appropriate.
+
+---
+
+## HTTP API by resource
+
+Below, `<id>` values are string identifiers used by the JSON stores (numeric strings in practice).
+
+### Settings — `/settings`
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/settings` | Full settings object (from `settings.json` / `Settings` model). |
+| PUT | `/settings/settings` | Merge keys into settings and save. Returns `{"message": "Settings updated successfully"}`. |
+| GET | `/settings/wifi/ap` | Saved Wi‑Fi AP fields: `saved_ssid`, `saved_password`, `saved_channel`, `active` (Pi: `active` is always false). |
+| POST | `/settings/wifi/ap` | Body: `ssid` (required), `password`, `channel` (1–11). Persists AP-related settings. |
+| GET | `/settings/page` | Serves `templates/settings.html` (same page as `GET /settings` from the root app, for convenience). |
+
+### Devices — `/devices`
+
+Registry in `db/device.json`: storage key **`<id>`** (string, e.g. `"1"`) maps to an object that always includes:
+
+| Field | Description |
+|-------|-------------|
+| **`id`** | Same as the storage key (stable handle for URLs). |
+| **`name`** | Shown in the UI and used in `select` keys. |
+| **`type`** | `led` (only value today; extensible). |
+| **`transport`** | `espnow` or `wifi`. |
+| **`address`** | For **`espnow`**: optional 12-character lowercase hex MAC. For **`wifi`**: optional IP or hostname string. |
+| **`default_pattern`**, **`zones`** | Optional. Legacy **`tabs`** may still appear in old files and is migrated away on load. |
+
+Existing records without `type` / `transport` / `id` are backfilled on load (`led`, `espnow`, and `id` = key).
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/devices` | Map of device id → device object. |
+| GET | `/devices/<id>` | One device, 404 if missing. |
+| POST | `/devices` | Create. Body: **`name`** (required), **`type`** (default `led`), **`transport`** (default `espnow`), optional **`address`**, **`default_pattern`**, **`zones`**. Returns `{ "<id>": { ... } }`, 201. |
+| PUT | `/devices/<id>` | Partial update. **`name`** cannot be cleared. **`id`** in the body is ignored. **`type`** / **`transport`** validated; **`address`** normalised for the resulting transport. |
+| DELETE | `/devices/<id>` | Remove device. |
+
+### Profiles — `/profiles`
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/profiles` | `{"profiles": {...}, "current_profile_id": "<id>"}`. Ensures a default current profile when possible. |
+| GET | `/profiles/current` | `{"id": "...", "profile": {...}}` |
+| GET | `/profiles/<id>` | Single profile. If `<id>` is `current`, same as `/profiles/current`. |
+| POST | `/profiles` | Create profile. Body may include `name` and other fields. Optional `seed_dj_zone` (request-only) seeds a DJ zone + presets. New profiles always get a populated `default` zone. Returns `{ "<id>": { ... } }` with status 201. |
+| POST | `/profiles/<id>/apply` | Sets session current profile to `<id>`. |
+| POST | `/profiles/<id>/clone` | Clone profile (zones, palettes, presets). Body may include `name`. |
+| PUT | `/profiles/current` | Update the current profile (from session). |
+| PUT | `/profiles/<id>` | Update profile by id. |
+| DELETE | `/profiles/<id>` | Delete profile. |
+
+### Presets — `/presets`
+
+Scoped to **current profile** in session (see above).
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/presets` | Map of preset id → preset object for the current profile only. |
+| GET | `/presets/<id>` | One preset, 404 if missing or wrong profile. |
+| POST | `/presets` | Create preset; server assigns id and sets `profile_id`. Body fields stored on the preset. Returns `{ "<id>": { ... } }`, 201. |
+| PUT | `/presets/<id>` | Update preset (must belong to current profile). |
+| DELETE | `/presets/<id>` | Delete preset. |
+| POST | `/presets/send` | Push presets to the LED driver over the configured transport (see below). |
+
+**`POST /presets/send` body:**
 
-**Response:** `200 OK`
 ```json
 {
-  "preset1": {
+  "preset_ids": ["1", "2"],
-    "name": "preset1",
+  "save": true,
-    "pattern": "on",
+  "default": "1",
-    "colors": [[255, 0, 0]],
+  "destination_mac": "aabbccddeeff"
-    "delay": 100,
+}
-    "n1": 0,
+```
-    "n2": 0,
+
-    "n3": 0,
+- **`preset_ids`** (or **`ids`**): non-empty list of preset ids to include.
-    "n4": 0,
+- **`save`**: if true, the outgoing message includes `"save": true` so the driver may persist presets (default true).
-    "n5": 0,
+- **`default`**: optional preset id string; forwarded as top-level `"default"` in the driver message (startup selection on device).
-    "n6": 0,
+- **`destination_mac`** (or **`to`**): optional 12-character hex MAC for unicast; omitted uses the transport default (e.g. broadcast).
-    "n7": 0,
+
-    "n8": 0
+Response on success includes `presets_sent`, `messages_sent` (chunking splits payloads so each JSON string stays ≤ 240 bytes).
+
+Stored preset records can include:
+
+- `colors`: resolved hex colours for editor/display.
+- `palette_refs`: optional array of palette indexes parallel to `colors`. If a slot contains an integer index, the colour is linked to the current profile palette at that index.
+
+### Zones — `/zones`
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/zones` | `zones` (map of zone id → zone object), `zone_order`, `current_zone_id`, `profile_id` for the session-backed profile. |
+| GET | `/zones/current` | Current zone from cookie/session. |
+| POST | `/zones` | Create zone; optional JSON `name`, `names`, `presets`; can append to current profile’s zone list. |
+| GET | `/zones/<id>` | Zone JSON. |
+| PUT | `/zones/<id>` | Update zone. |
+| DELETE | `/zones/<id>` | Delete zone; can delete `current` to remove the active zone; updates profile zone list. |
+| POST | `/zones/<id>/set-current` | Sets `current_zone` cookie. |
+| POST | `/zones/<id>/clone` | Clone zone into current profile. |
+
+### Palettes — `/palettes`
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/palettes` | Map of id → colour list. |
+| GET | `/palettes/<id>` | `{"colors": [...], "id": "<id>"}` |
+| POST | `/palettes` | Body may include `colors`. Returns palette object with `id`, 201. |
+| PUT | `/palettes/<id>` | Update colours (`name` ignored). |
+| DELETE | `/palettes/<id>` | Delete palette. |
+
+### Groups — `/groups`
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/groups` | All groups. |
+| GET | `/groups/<id>` | One group. |
+| POST | `/groups` | Create; optional `name` and fields. |
+| PUT | `/groups/<id>` | Update. |
+| DELETE | `/groups/<id>` | Delete. |
+
+### Scenes — `/scenes`
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/scenes` | All scenes. |
+| GET | `/scenes/<id>` | One scene. |
+| POST | `/scenes` | Create (body JSON stored on scene). |
+| PUT | `/scenes/<id>` | Update. |
+| DELETE | `/scenes/<id>` | Delete. |
+
+### Sequences — `/sequences`
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/sequences` | All sequences. |
+| GET | `/sequences/<id>` | One sequence. |
+| POST | `/sequences` | Create; may use `group_name`, `presets` in body. |
+| PUT | `/sequences/<id>` | Update. |
+| DELETE | `/sequences/<id>` | Delete. |
+
+### Patterns — `/patterns`
+
+Pattern metadata lives in **`db/pattern.json`**; driver source files live under **`led-driver/src/patterns/`**. Several routes expose a **runtime map** (metadata merged with on-disk `.py` names so new files appear in menus).
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/patterns` | Runtime pattern map (object keyed by pattern id). |
+| GET | `/patterns/definitions` | Same runtime map (intended for UI “definitions” clients). |
+| GET | `/patterns/ota/manifest` | JSON `{"files":[{"name":"blink.py","url":"http://<Host>/patterns/ota/file/blink.py"},...]}` for OTA pulls. Requires **`Host`** header. |
+| GET | `/patterns/ota/file/<name>` | Raw **`.py`** source for one driver pattern (`name` must be a safe filename, e.g. `rainbow.py`). |
+| POST | `/patterns/<name>/send` | Push a **manifest** JSON line to **Wi-Fi** devices so they pull one pattern file over HTTP. Body may include **`device_id`** to target one device; otherwise all Wi-Fi devices with an **`address`** are tried. **`<name>`** may be with or without `.py`. |
+| POST | `/patterns/upload` | Body JSON: **`name`**, **`code`**, optional **`overwrite`** (default true). Writes **`led-driver/src/patterns/<name>.py`**. |
+| POST | `/patterns/driver` | Body JSON: **`name`** (identifier), **`code`**, optional metadata (`min_delay`, `max_delay`, `max_colors`, `n1`…`n8`, **`overwrite`**). Creates/updates both the **`.py`** file and **`db/pattern.json`** via the Pattern model. |
+| GET | `/patterns/<id>` | One pattern record from the Pattern model (metadata only). |
+| POST | `/patterns` | Create (`name`, optional `data`). |
+| PUT | `/patterns/<id>` | Update. |
+| DELETE | `/patterns/<id>` | Delete. |
+
+**Devices — pattern OTA push**
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/devices/<id>/patterns/push` | Wi-Fi only. Asks the driver at **`address`** to pull pattern files from this server. Optional body **`manifest`**: either a **URL string** pointing at a manifest JSON document, or a **manifest object** (same shape as in driver messages). If omitted, a default manifest is built from the request **`Host`** header. |
+
+---
+
+## LED driver message format (transport / ESP-NOW / Wi-Fi)
+
+Messages are JSON objects. The Pi **`build_message()`** helper (`src/util/espnow_message.py`) produces the same shape sent over serial and forwarded by the ESP32 bridge, and the same logical object can be sent as a **single JSON text message** to a Wi-Fi driver over the **WebSocket**.
+
+### Top-level fields
+
+```json
+{
+  "v": "1",
+  "presets": { },
+  "select": { },
+  "save": true,
+  "default": "preset_id",
+  "b": 255
+}
+```
+
+- **`v`** (required): Must be `"1"` or the driver ignores the message.
+- **`presets`**: Map of **preset id** (string) → preset object (see below). Optional **`name`** field on each value is accepted for display; the driver keys presets by map key.
+- **`select`**: Map of **device name** (as in device settings) → `[ "preset_id" ]` or `[ "preset_id", step ]`.
+- **`save`**: If present (e.g. true), the driver may persist presets to flash after applying.
+- **`default`**: Preset id string to use as startup default on the device.
+- **`b`**: Optional **global** brightness 0–255 (driver applies this in addition to per-preset brightness).
+
+### Preset object (wire / driver keys)
+
+On the wire, presets use **short keys** (saves space in the ≤240-byte chunks):
+
+| Key | Meaning | Notes |
+|-----|---------|--------|
+| `p` | Pattern id | `off`, `on`, `blink`, `rainbow`, `pulse`, `transition`, `chase`, `circle` |
+| `c` | Colours | Array of `"#RRGGBB"` hex strings; converted to RGB on device |
+| `d` | Delay ms | Default 100 |
+| `b` | Preset brightness | 0–255; combined with global `b` on the device |
+| `a` | Auto | `true`: run continuously; `false`: one step/cycle per “beat” |
+| `n1`–`n6` | Pattern parameters | See below |
+
+The HTTP app’s **`POST /presets/send`** path builds this from stored presets via **`build_preset_dict()`** (long names like `pattern` / `colors` in the DB are translated to `p` / `c` / …).
+
+### Pattern-specific parameters (`n1`–`n6`)
+
+#### Rainbow
+- **`n1`**: Step increment on the colour wheel per update (default 1).
+
+#### Pulse
+- **`n1`**: Attack (fade in) ms  
+- **`n2`**: Hold ms  
+- **`n3`**: Decay (fade out) ms  
+- **`d`**: Off time between pulses ms  
+
+#### Transition
+- **`d`**: Transition duration ms  
+
+#### Chase
+- **`n1`**: LEDs with first colour  
+- **`n2`**: LEDs with second colour  
+- **`n3`**: Movement on even steps (may be negative)  
+- **`n4`**: Movement on odd steps (may be negative)  
+
+#### Circle
+- **`n1`**: Head speed (LEDs/s)  
+- **`n2`**: Max length  
+- **`n3`**: Tail speed (LEDs/s)  
+- **`n4`**: Min length  
+
+### Select messages
+
+```json
+{
+  "select": {
+    "device_name": ["preset_id"],
+    "other_device": ["preset_id", 10]
   }
 }
 ```
 
-### GET /presets/{name}
+- One element: select preset; step behavior follows driver rules (reset on `off`, etc.).
+- Two elements: explicit **step** for sync.
 
-Get a specific preset by name.
+### Beat and sync behavior
+
+- Sending **`select`** again with the **same** preset name acts as a **beat** (advances manual patterns / restarts generators per driver logic).
+- Choosing **`off`** resets step as a sync point; then selecting a pattern aligns step 0 across devices unless a step is passed explicitly.
+
+### Example (compact preset map)
 
-**Response:** `200 OK`
 ```json
 {
-  "name": "preset1",
+  "v": "1",
-  "pattern": "on",
+  "save": true,
-  "colors": [[255, 0, 0]],
+  "presets": {
-  "delay": 100,
+    "1": {
-  "n1": 0,
+      "name": "Red blink",
-  "n2": 0,
+      "p": "blink",
-  "n3": 0,
+      "c": ["#FF0000"],
-  "n4": 0,
+      "d": 200,
-  "n5": 0,
+      "b": 255,
-  "n6": 0,
+      "a": true,
-  "n7": 0,
+      "n1": 0, "n2": 0, "n3": 0, "n4": 0, "n5": 0, "n6": 0
-  "n8": 0
+    }
-}
+  },
-```
+  "select": {
-
+    "living-room": ["1"]
-**Response:** `404 Not Found`
-```json
-{
-  "error": "Preset not found"
-}
-```
-
-### POST /presets
-
-Create a new preset.
-
-**Request Body:**
-```json
-{
-  "name": "preset1",
-  "pattern": "on",
-  "colors": [[255, 0, 0]],
-  "delay": 100,
-  "n1": 0,
-  "n2": 0,
-  "n3": 0,
-  "n4": 0,
-  "n5": 0,
-  "n6": 0,
-  "n7": 0,
-  "n8": 0
-}
-```
-
-**Response:** `201 Created` - Returns the created preset
-
-**Response:** `400 Bad Request`
-```json
-{
-  "error": "Name is required"
-}
-```
-
-**Response:** `409 Conflict`
-```json
-{
-  "error": "Preset already exists"
-}
-```
-
-### PUT /presets/{name}
-
-Update an existing preset.
-
-**Request Body:**
-```json
-{
-  "delay": 200,
-  "colors": [[0, 255, 0]]
-}
-```
-
-**Response:** `200 OK` - Returns the updated preset
-
-**Response:** `404 Not Found`
-```json
-{
-  "error": "Preset not found"
-}
-```
-
-### DELETE /presets/{name}
-
-Delete a preset.
-
-**Response:** `200 OK`
-```json
-{
-  "message": "Preset deleted successfully"
-}
-```
-
-**Response:** `404 Not Found`
-```json
-{
-  "error": "Preset not found"
-}
-```
-
-## Profiles API
-
-### GET /profiles
-
-List all profiles.
-
-**Response:** `200 OK`
-```json
-{
-  "profile1": {
-    "name": "profile1",
-    "description": "Profile description",
-    "scenes": []
   }
 }
 ```
 
-### GET /profiles/{name}
+---
 
-Get a specific profile by name.
+## Processing summary (driver)
 
-**Response:** `200 OK`
+1. Reject if `v != "1"`.
-```json
+2. Apply optional top-level **`b`** (global brightness).
-{
+3. For each entry in **`presets`**, normalize colours and upsert preset by id.
-  "name": "profile1",
+4. If this device’s **`name`** appears in **`select`**, run selection (optional step).
-  "description": "Profile description",
+5. If **`default`** is set, store startup preset id.
-  "scenes": []
+6. If **`save`** is set, persist presets.
-}
-```
 
-**Response:** `404 Not Found`
+---
-```json
-{
-  "error": "Profile not found"
-}
-```
 
-### POST /profiles
+## Error handling (HTTP)
 
-Create a new profile.
+Controllers typically return JSON with an **`error`** string and 4xx/5xx status codes. Invalid JSON bodies often yield `{"error": "Invalid JSON"}`.
 
-**Request Body:**
+---
-```json
-{
-  "name": "profile1",
-  "description": "Profile description",
-  "scenes": []
-}
-```
 
-**Response:** `201 Created` - Returns the created profile
+## Notes
 
-**Response:** `400 Bad Request`
+- **Human-readable preset fields** (`pattern`, `colors`, `delay`, …) are fine in the **web app / database**; the **send path** converts them to **`p` / `c` / `d`** for the driver.
-```json
+- For a copy of the older long-key reference, see **`led-driver/docs/API.md`** in this repo (conceptually the same behavior; wire format prefers short keys).
-{
-  "error": "Name is required"
-}
-```
-
-**Response:** `409 Conflict`
-```json
-{
-  "error": "Profile already exists"
-}
-```
-
-### PUT /profiles/{name}
-
-Update an existing profile.
-
-**Request Body:**
-```json
-{
-  "description": "Updated description"
-}
-```
-
-**Response:** `200 OK` - Returns the updated profile
-
-**Response:** `404 Not Found`
-```json
-{
-  "error": "Profile not found"
-}
-```
-
-### DELETE /profiles/{name}
-
-Delete a profile.
-
-**Response:** `200 OK`
-```json
-{
-  "message": "Profile deleted successfully"
-}
-```
-
-**Response:** `404 Not Found`
-```json
-{
-  "error": "Profile not found"
-}
-```
-
-## Scenes API
-
-### GET /scenes
-
-List all scenes. Optionally filter by profile using query parameter.
-
-**Query Parameters:**
-- `profile` (optional): Filter scenes by profile name
-
-**Example:** `GET /scenes?profile=profile1`
-
-**Response:** `200 OK`
-```json
-{
-  "profile1:scene1": {
-    "name": "scene1",
-    "profile_name": "profile1",
-    "description": "Scene description",
-    "transition_time": 0,
-    "devices": [
-      {"device_name": "device1", "preset_name": "preset1"},
-      {"device_name": "device2", "preset_name": "preset2"}
-    ]
-  }
-}
-```
-
-### GET /scenes/{profile_name}/{scene_name}
-
-Get a specific scene.
-
-**Response:** `200 OK`
-```json
-{
-  "name": "scene1",
-  "profile_name": "profile1",
-  "description": "Scene description",
-  "transition_time": 0,
-  "devices": [
-    {"device_name": "device1", "preset_name": "preset1"},
-    {"device_name": "device2", "preset_name": "preset2"}
-  ]
-}
-```
-
-**Response:** `404 Not Found`
-```json
-{
-  "error": "Scene not found"
-}
-```
-
-### POST /scenes
-
-Create a new scene.
-
-**Request Body:**
-```json
-{
-  "name": "scene1",
-  "profile_name": "profile1",
-  "description": "Scene description",
-  "transition_time": 0,
-  "devices": [
-    {"device_name": "device1", "preset_name": "preset1"},
-    {"device_name": "device2", "preset_name": "preset2"}
-  ]
-}
-```
-
-**Response:** `201 Created` - Returns the created scene
-
-**Response:** `400 Bad Request`
-```json
-{
-  "error": "Name is required"
-}
-```
-or
-```json
-{
-  "error": "Profile name is required"
-}
-```
-
-**Response:** `409 Conflict`
-```json
-{
-  "error": "Scene already exists"
-}
-```
-
-### PUT /scenes/{profile_name}/{scene_name}
-
-Update an existing scene.
-
-**Request Body:**
-```json
-{
-  "transition_time": 500,
-  "description": "Updated description"
-}
-```
-
-**Response:** `200 OK` - Returns the updated scene
-
-**Response:** `404 Not Found`
-```json
-{
-  "error": "Scene not found"
-}
-```
-
-### DELETE /scenes/{profile_name}/{scene_name}
-
-Delete a scene.
-
-**Response:** `200 OK`
-```json
-{
-  "message": "Scene deleted successfully"
-}
-```
-
-**Response:** `404 Not Found`
-```json
-{
-  "error": "Scene not found"
-}
-```
-
-### POST /scenes/{profile_name}/{scene_name}/devices
-
-Add a device assignment to a scene.
-
-**Request Body:**
-```json
-{
-  "device_name": "device1",
-  "preset_name": "preset1"
-}
-```
-
-**Response:** `200 OK` - Returns the updated scene
-
-**Response:** `400 Bad Request`
-```json
-{
-  "error": "Device name and preset name are required"
-}
-```
-
-**Response:** `404 Not Found`
-```json
-{
-  "error": "Scene not found"
-}
-```
-
-### DELETE /scenes/{profile_name}/{scene_name}/devices/{device_name}
-
-Remove a device assignment from a scene.
-
-**Response:** `200 OK` - Returns the updated scene
-
-**Response:** `404 Not Found`
-```json
-{
-  "error": "Scene not found"
-}
-```
-
-## Patterns API
-
-### GET /patterns
-
-Get the list of available pattern names.
-
-**Response:** `200 OK`
-```json
-["on", "bl", "cl", "rb", "sb", "o"]
-```
-
-### POST /patterns
-
-Add a new pattern name to the list.
-
-**Request Body:**
-```json
-{
-  "name": "new_pattern"
-}
-```
-
-**Response:** `201 Created` - Returns the updated list of patterns
-```json
-["on", "bl", "cl", "rb", "sb", "o", "new_pattern"]
-```
-
-**Response:** `400 Bad Request`
-```json
-{
-  "error": "Name is required"
-}
-```
-
-**Response:** `409 Conflict`
-```json
-{
-  "error": "Pattern already exists"
-}
-```
-
-### DELETE /patterns/{name}
-
-Remove a pattern name from the list.
-
-**Response:** `200 OK`
-```json
-{
-  "message": "Pattern deleted successfully"
-}
-```
-
-**Response:** `404 Not Found`
-```json
-{
-  "error": "Pattern not found"
-}
-```
-
-## Error Responses
-
-All endpoints may return the following error responses:
-
-**400 Bad Request** - Invalid request data
-```json
-{
-  "error": "Error message"
-}
-```
-
-**404 Not Found** - Resource not found
-```json
-{
-  "error": "Resource not found"
-}
-```
-
-**409 Conflict** - Resource already exists
-```json
-{
-  "error": "Resource already exists"
-}
-```
-
-**500 Internal Server Error** - Server error
-```json
-{
-  "error": "Error message"
-}
-```

docs/SPECIFICATION.md

@@ -44,7 +44,7 @@ The LED Driver system is a MicroPython-based application for controlling LED str
 - Pattern configuration and control (patterns run on remote devices)
 - Real-time brightness and speed control
 - Global brightness setting (system-wide brightness multiplier)
-- Multi-color support with customizable color palettes
+- Multi-colour support with customizable colour palettes
 - Device grouping for synchronized control
 - Preset system for saving and loading pattern configurations
 - Profile and Scene system for complex lighting setups
@@ -239,7 +239,7 @@ Primary interface for real-time LED control and monitoring.
 - **Grid Layout:** 4-column responsive grid
   - Pattern Selection Card
   - Brightness & Speed Card
-  - Color Selection Card
+  - Colour Selection Card
   - Device Status Card
 - **Action Bar:** Apply and Save buttons
 
@@ -273,12 +273,12 @@ Primary interface for real-time LED control and monitoring.
 - **Default:** 100ms
 - **Step:** 10ms increments
 
-**Color Selection**
+**Colour Selection**
-- **Type:** Color picker inputs (HTML5 color input)
+- **Type:** Colour picker inputs (HTML5 colour input)
-- **Quantity:** Multiple colors (minimum 2, expandable)
+- **Quantity:** Multiple colours (minimum 2, expandable)
-- **Format:** Hex color codes (e.g., #FF0000)
+- **Format:** Hex colour codes (e.g., #FF0000)
-- **Display:** Large color swatches (60x60px)
+- **Display:** Large colour swatches (60x60px)
-- **Action:** "Add Color" button for additional colors
+- **Action:** "Add Colour" button for additional colours
 
 **Device Status List**
 - **Type:** List of connected devices
@@ -295,7 +295,7 @@ Primary interface for real-time LED control and monitoring.
 - **Save to Device:** Persist settings to device storage
 
 #### Design Specifications
-- **Color Scheme:** Purple gradient background (#667eea to #764ba2)
+- **Colour Scheme:** Purple gradient background (#667eea to #764ba2)
 - **Cards:** White background, rounded corners (12px), shadow
 - **Hover Effects:** Card lift (translateY -2px), increased shadow
 - **Typography:** System font stack, 1.25rem headings
@@ -350,10 +350,10 @@ Manage connected devices and create/manage device groups.
 
 #### Layout
 - **Header:** Title with "Add Device" button
-- **Tabs:** Devices and Groups tabs
+- **Zones:** Devices and Groups zones (zone buttons / zone strip)
-- **Content Area:** Tab-specific content
+- **Content Area:** Zone-specific content
 
-#### Devices Tab
+#### Devices Zone
 
 **Device List**
 - **Display:** List of all known devices
@@ -375,7 +375,7 @@ Manage connected devices and create/manage device groups.
 - **Actions:** Cancel, Save
 - **Note:** Only one master device per system. Adding a new master will demote existing master to slave.
 
-#### Groups Tab
+#### Groups Zone
 
 **Group List**
 - **Display:** List of all device groups
@@ -397,7 +397,7 @@ Manage connected devices and create/manage device groups.
 - **Actions:** Cancel, Create
 
 #### Design Specifications
-- **Tab Style:** Active tab has purple background, white text
+- **Zone Style:** Active zone has purple background, white text
 - **List Items:** Bordered cards with hover effects
 - **Modal:** Centered overlay with white card, shadow
 - **Status Badges:** Colored pills (green for online, red for offline)
@@ -509,7 +509,7 @@ Comprehensive device configuration interface.
 - Device Name (text input)
 - LED Pin (number input, 0-40)
 - Number of LEDs (number input, 1-1000)
-- Color Order (visual selector with 6 options: RGB, RBG, GRB, GBR, BRG, BGR)
+- Colour Order (visual selector with 6 options: RGB, RBG, GRB, GBR, BRG, BGR)
 
 **2. Pattern Settings**
 - Pattern (dropdown selection)
@@ -577,16 +577,16 @@ Comprehensive device configuration interface.
 - Range: Slider with real-time value display
 - Select: Dropdown menu
 - Checkbox: Toggle switch
-- Color: HTML5 color picker
+- Colour: HTML5 colour picker
 
-**Color Order Selector**
+**Colour Order Selector**
 - **Type:** Visual button grid
 - **Options:** RGB, RBG, GRB, GBR, BRG, BGR
-- **Display:** Color boxes showing order (R=red, G=green, B=blue)
+- **Display:** Colour boxes showing order (R=red, G=green, B=blue)
 - **Selection:** Single selection with visual feedback
 
 #### Design Specifications
-- **Section Headers:** Purple color (#667eea), 1.5rem font, bottom border
+- **Section Headers:** Purple colour (#667eea), 1.5rem font, bottom border
 - **Form Groups:** 24px spacing between fields
 - **Labels:** Bold, 500 weight, dark gray (#333)
 - **Help Text:** Small gray text below inputs
@@ -611,7 +611,7 @@ Save, load, and manage preset configurations for quick pattern switching.
 Each preset card displays:
 - **Name:** Preset name (bold, 1.25rem)
 - **Pattern Badge:** Current pattern type
-- **Color Preview:** Swatches showing preset colors
+- **Colour Preview:** Swatches showing preset colours
 - **Quick Info:** Delay and brightness values
 - **Actions:** Apply, Edit, Delete buttons
 
@@ -620,7 +620,7 @@ Each preset card displays:
 **Fields:**
 - Preset Name (text input, required)
 - Pattern (dropdown selection)
-- Colors (multiple color pickers, minimum 2)
+- Colours (multiple colour pickers, minimum 2)
 - Delay (slider, 10-1000ms)
 - Step Offset (number input, optional, default: 0)
   - Tooltip: "Step offset for group synchronization. Applied per device when preset is used in a group."
@@ -667,7 +667,7 @@ Each preset card displays:
 #### Design Specifications
 - **Card Style:** White background, rounded corners, shadow
 - **Pattern Badge:** Colored pill with pattern name
-- **Color Swatches:** 40x40px squares in card header
+- **Colour Swatches:** 40x40px squares in card header
 - **Hover Effect:** Card lift, border highlight
 - **Selected State:** Purple border, subtle background tint
 
@@ -681,7 +681,7 @@ Patterns are configured on the controller and sent to remote devices for executi
 
 - **Pattern Type:** Identifier for the pattern (e.g., "on", "off", "blink", "chase", "pulse", "rainbow", etc.)
 - **Pattern Parameters:** Numeric parameters (N1-N8) that configure pattern-specific behavior
-- **Colors:** Color palette for the pattern
+- **Colours:** Colour palette for the pattern
 - **Timing:** Delay and speed settings
 
 **Note:** Pattern execution happens on the remote devices. The controller sends configuration commands to devices.
@@ -698,7 +698,7 @@ Pattern-specific numeric parameters:
 
 #### Overview
 
-Presets allow users to save complete pattern configurations for quick recall and application. A preset encapsulates all pattern settings including pattern type, colors, timing, and all pattern parameters.
+Presets allow users to save complete pattern configurations for quick recall and application. A preset encapsulates all pattern settings including pattern type, colours, timing, and all pattern parameters.
 
 **Note:** Presets are optional. Devices can be controlled directly without presets.
 
@@ -708,7 +708,7 @@ A preset contains the following fields:
 
 - **name** (string, required): Unique identifier for the preset
 - **pattern** (string, required): Pattern type identifier (sent to remote devices)
-- **colors** (array of strings, required): Array of hex color codes (minimum 2 colors)
+- **colours** (array of strings, required): Array of hex colour codes (minimum 2 colours)
 - **delay** (integer, required): Delay in milliseconds (10-1000)
 - **n1** (integer, optional): Pattern parameter 1 (0-255, default: 0)
 - **n2** (integer, optional): Pattern parameter 2 (0-255, default: 0)
@@ -889,7 +889,7 @@ A preset contains the following fields:
 #### Group Properties
 - **Name:** Unique group identifier
 - **Devices:** List of device names (can include master and/or slaves)
-- **Settings:** Pattern, delay, colors
+- **Settings:** Pattern, delay, colours
 - **Step Offset:** Per-device step offset sent to devices for synchronized patterns (integer, can be negative)
   - Each device in group can receive different step offset
   - Creates wave/chase effect across multiple LED strips
@@ -953,7 +953,7 @@ Byte 1: Flags (bit 0: names, bit 1: groups, bit 2: settings, bit 3: save)
 |-----|------|-------------|--------------|
 | `pt` | string | Pattern type | on, off, blink, chase, circle, pulse, rainbow, transition |
 | `pm` | string | Pattern mode | auto, single_shot |
-| `cl` | array | Colors (hex strings) | Array of hex color codes |
+| `cl` | array | Colours (hex strings) | Array of hex colour codes |
 | `br` | int | Global brightness | 0-100 |
 | `dl` | int | Delay (ms) | 10-1000 |
 | `n1` | int | Parameter 1 | 0-255 |
@@ -966,7 +966,7 @@ Byte 1: Flags (bit 0: names, bit 1: groups, bit 2: settings, bit 3: save)
 | `n8` | int | Parameter 8 | 0-255 |
 | `led_pin` | int | GPIO pin | 0-40 |
 | `num_leds` | int | LED count | 1-1000 |
-| `color_order` | string | Color order | rgb, rbg, grb, gbr, brg, bgr |
+| `color_order` | string | Colour order | rgb, rbg, grb, gbr, brg, bgr |
 | `name` | string | Device name | Any string |
 | `brightness` | int | Global brightness | 0-100 |
 | `delay` | int | Delay | 10-1000 |
@@ -1247,7 +1247,7 @@ CREATE TABLE IF NOT EXISTS presets (
 **Preset Fields:**
 - `name` (string, required): Unique preset identifier
 - `pattern` (string, required): Pattern type
-- `colors` (array of strings, required): Hex color codes (minimum 2)
+- `colors` (array of strings, required): Hex colour codes (minimum 2)
 - `delay` (integer, required): Delay in milliseconds (10-1000)
 - `n1` through `n8` (integer, optional): Pattern parameters (0-255, default: 0)
 
@@ -1289,7 +1289,7 @@ CREATE TABLE IF NOT EXISTS presets (
 
 **POST /api/presets**
 - Create a new preset
-- Body: Preset object (name, pattern, colors, delay, n1-n8)
+- Body: Preset object (name, pattern, colours, delay, n1-n8)
 - Response: Created preset object
 
 **GET /api/presets/{name}**
@@ -1495,7 +1495,7 @@ peak_mem = usqlite.mem_peak()
 
 ### Flow 2: Create Device Group
 
-1. User navigates to Device Management → Groups tab
+1. User navigates to Device Management → Groups zone
 2. User clicks "Create Group", enters name, selects pattern/settings
 3. User selects devices to add (can include master), clicks "Create"
 4. Group appears in list
@@ -1506,7 +1506,7 @@ peak_mem = usqlite.mem_peak()
 
 1. User navigates to Settings page
 2. User modifies settings in sections:
-   - Basic Settings (pin, LED count, color order)
+   - Basic Settings (pin, LED count, colour order)
    - Pattern Settings (pattern, delay)
    - Global Brightness
    - Advanced Settings (N1-N8 parameters)
@@ -1519,7 +1519,7 @@ peak_mem = usqlite.mem_peak()
 ### Flow 4: Multi-Device Control
 
 1. User selects multiple devices or a group
-2. User changes pattern/colors/global brightness
+2. User changes pattern/colours/global brightness
 3. User clicks "Apply Settings"
 4. System sends message targeting selected devices/groups
 5. All targeted devices update simultaneously
@@ -1585,7 +1585,7 @@ peak_mem = usqlite.mem_peak()
 
 ## Design Guidelines
 
-### Color Palette
+### Colour Palette
 
 - **Primary:** Purple gradient `#667eea` to `#764ba2`, Light gradient `#f5f7fa` to `#c3cfe2`
 - **UI:** Primary `#667eea`, Hover `#5568d3`, Secondary `#e0e0e0`
@@ -1612,8 +1612,8 @@ peak_mem = usqlite.mem_peak()
 - Disabled: 50% opacity, no pointer events
 
 **Inputs:**
-- Focus: Border color changes to primary purple
+- Focus: Border colour changes to primary purple
-- Hover: Slight border color change
+- Hover: Slight border colour change
 - Error: Red border
 
 **Cards:**
@@ -1738,7 +1738,7 @@ peak_mem = usqlite.mem_peak()
 - Validation
 
 **Preset Management:**
-- Preset creation with all fields (name, pattern, colors, delay, n1-n8)
+- Preset creation with all fields (name, pattern, colours, delay, n1-n8)
 - Preset loading and application
 - Preset editing and deletion
 - Name uniqueness validation
@@ -1758,7 +1758,7 @@ peak_mem = usqlite.mem_peak()
 - Configuration parameters are properly formatted
 
 **Preset Application:**
-- Preset loads all parameters correctly (pattern, colors, delay, n1-n8)
+- Preset loads all parameters correctly (pattern, colours, delay, n1-n8)
 - Preset applies to single device
 - Preset applies to device group
 - Preset values match saved configuration
@@ -1774,7 +1774,7 @@ peak_mem = usqlite.mem_peak()
 - Buttons respond to clicks
 - Sliders update values
 - Modals open/close
-- Tabs switch correctly
+- Zone buttons switch correctly
 - Preset selector works
 - Preset creation form validates input
 - Preset cards display correctly

docs/help.md

@@ -0,0 +1,114 @@
+# LED controller — user guide
+
+This page describes the **main web UI** served from the Raspberry Pi app: profiles, **zones**, presets, colour palettes, and sending commands to LED devices. Traffic may go over the **serial → ESP-NOW bridge** or **Wi-Fi** (TCP to drivers on the LAN), depending on each device’s transport.
+
+For HTTP routes and the wire format the driver expects, see **[API.md](API.md)**. For running the app locally, see the project **README**.
+
+Figures below are **schematic** (layout and ideas), not pixel-perfect screenshots.
+
+---
+
+## Run mode and Edit mode
+
+The header has a mode toggle (desktop and mobile menu). The **label on the button is the mode you switch to** when you press it.
+
+![Schematic: zone buttons on the left; Profiles, Zones, Presets, Patterns, and the mode toggle on the right (example shows Edit mode with “Run mode” on the button).](images/help/header-toolbar.svg)
+
+*The active zone is highlighted. Extra management buttons appear only in Edit mode.*
+
+| Mode | Purpose |
+|------|--------|
+| **Run mode** | Day-to-day control: choose a zone, tap presets, apply profiles. Management buttons are hidden. |
+| **Edit mode** | Full setup: zones, presets, patterns, colour palette, **Send Presets**, profile create/clone/delete, preset reordering, and per-tile **Edit** on the strip. |
+
+**Profiles** is available in both modes: in Run mode you can only **apply** a profile; in Edit mode you can also **create**, **clone**, and **delete** profiles.
+
+---
+
+## Zones
+
+- **Select a zone**: click its button in the top bar. The main area shows that zone’s preset strip and controls.
+- **Edit mode — open zone settings**: **right-click** a zone button to change its name, **device IDs** (comma-separated), and which presets appear on the zone. Device identifiers are matched to each device’s **name** when the app builds `select` messages for the driver.
+- **Zones modal** (Edit mode): create new zones from the header **Zones** button. New zones need a name and device ID list (defaults to `1` if you leave a simple placeholder).
+- **Brightness slider** (per zone): adjusts **global** brightness sent to devices (`b` in the driver message), with a short debounce so small drags do not flood the link.
+
+---
+
+## Presets on the zone strip
+
+- **Run and Edit mode**: click the **main part** of a preset tile to **select** that preset on all devices assigned to the current zone (same logical action as a `select` in the driver API).
+- **Edit mode only**:
+  - **Edit** beside a tile opens the preset editor for that preset, scoped to the current zone (so you can **Remove from zone** without deleting the preset from the profile).
+  - **Drag and drop** tiles to reorder them; order is saved for that zone.
+
+![Schematic: zone title, brightness slider, and a row of preset tiles; Edit mode adds an Edit control and drag handles for reordering.](images/help/zone-preset-strip.svg)
+
+*The slider controls global brightness for the zone’s devices. Click the coloured area of a tile to select that preset.*
+
+The **Presets** header button (Edit mode) opens a **profile-wide** list: **Add** new presets, **Edit**, **Send** (push definition over the transport), and **Delete** (removes the preset from the profile entirely).
+
+---
+
+## Preset editor
+
+- **Pattern**: chosen from the dropdown; optional **n1–n8** fields depend on the pattern (see **Pattern-specific parameters** in [API.md](API.md)).
+- **Colours**: choosing a value in the colour picker **adds** a swatch when the picker closes. Swatches can be **reordered** by dragging. Changing a swatch with the picker **clears** palette linkage for that slot.
+- **From Palette**: inserts a colour **linked** to the current profile’s palette. Linked slots show a **P** badge; if you change that palette entry later, presets using it update.
+- **Brightness (0–255)** and **Delay (ms)**: stored on the preset and sent with the compact preset payload.
+- **Try**: sends the current form values to devices on the **current zone**, then selects that preset — **without** `save` on the device (good for auditioning).
+- **Default**: updates the zone’s **default preset** and sends a **default** hint for those devices; it does not force the same live selection behaviour as clicking a tile.
+- **Save & Send**: writes the preset to the server, then pushes definitions with **save** so devices may persist them. It does **not** auto-select the preset on devices (use the strip or **Try** if you want that).
+- **Remove from zone** (when you opened the editor from a zone): removes the preset from **this zone’s list only**; the preset remains in the profile for other zones.
+
+![Schematic: preset editor with name, pattern, colour swatches (one with a P badge for palette-linked), and action buttons.](images/help/preset-editor.svg)
+
+*Try previews without persisting on the device; **Save & Send** stores the preset and pushes definitions with save.*
+
+---
+
+## Profiles
+
+- **Apply**: sets the **current profile** in your session. Zones and presets you see are scoped to that profile.
+- **Edit mode — Create**: new profiles always get a populated **default** zone. Optionally tick **DJ zone** to also create a `dj` zone (device name `dj`) with starter DJ-oriented presets.
+- **Clone** / **Delete**: available in Edit mode from the profile list.
+
+---
+
+## Send Presets (Edit mode)
+
+**Send Presets** walks **every zone** in the **current profile**, collects each zone’s preset IDs, and calls **`POST /presets/send`** per zone (including each zone’s **default** preset when set). Use this to bulk-push definitions to hardware after editing, without clicking **Send** on every preset individually.
+
+---
+
+## Patterns
+
+The **Patterns** dialog (Edit mode) lists pattern names and typical **delay** ranges from the pattern definitions. Choosing a pattern still happens inside the preset editor.
+
+**Wi-Fi drivers** can install new pattern modules over HTTP: the REST API exposes **`/patterns/ota/*`**, **`POST /patterns/<name>/send`**, **`POST /patterns/upload`**, and **`POST /patterns/driver`** (see [API.md](API.md)). ESP-NOW devices follow the bridge/serial path you configure for preset traffic.
+
+---
+
+## Colour palette
+
+**Colour Palette** (Edit mode) edits the **current profile’s** palette swatches. Those colours are reused by **From Palette** in the preset editor and stay in sync while the **P** link remains.
+
+![Schematic: palette modal with a row of swatches for the current profile.](images/help/colour-palette.svg)
+
+*Add or change swatches here; linked preset colours update automatically.*
+
+---
+
+## Mobile layout
+
+On narrow screens, use **Menu** to reach the same actions as the desktop header (Profiles, Zones, Presets, Help, mode toggle, etc.).
+
+![Schematic: narrow layout with Menu and the same header actions in a dropdown.](images/help/mobile-menu.svg)
+
+*Preset tiles behave the same once a zone is selected.*
+
+---
+
+## Further reading
+
+- **[API.md](API.md)** — REST routes, session scoping, WebSocket `/ws`, and LED driver JSON (`presets`, `select`, `save`, `default`, pattern keys, pattern **manifest**).
+- **README** — `pipenv run run`, port 80 setup, and high-level behaviour.

docs/images/help/colour-palette.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 140" width="480" height="140">
+  <title>Colour Palette modal (concept)</title>
+  <rect width="480" height="140" fill="#2a2a2a" stroke="#555" stroke-width="1" rx="6"/>
+  <text x="20" y="28" fill="#fff" font-family="sans-serif" font-size="15" font-weight="600">Colour Palette</text>
+  <text x="20" y="48" fill="#888" font-family="sans-serif" font-size="10">Profile: current profile name</text>
+  <rect x="20" y="58" width="44" height="44" rx="4" fill="#e53935" stroke="#333"/>
+  <rect x="72" y="58" width="44" height="44" rx="4" fill="#fdd835" stroke="#333"/>
+  <rect x="124" y="58" width="44" height="44" rx="4" fill="#43a047" stroke="#333"/>
+  <rect x="176" y="58" width="44" height="44" rx="4" fill="#1e88e5" stroke="#333"/>
+  <rect x="228" y="58" width="44" height="44" rx="4" fill="#8e24aa" stroke="#333"/>
+  <rect x="280" y="70" width="36" height="28" rx="3" fill="#1a1a1a" stroke="#666"/>
+  <text x="288" y="88" fill="#ccc" font-family="sans-serif" font-size="10">+</text>
+  <text x="20" y="122" fill="#aaa" font-family="sans-serif" font-size="10">Swatches belong to the profile; preset editor uses them via From Palette.</text>
+</svg>

docs/images/help/header-toolbar.svg

@@ -0,0 +1,24 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 820 108" width="820" height="108">
+  <title>Header: tab buttons and action bar</title>
+  <rect width="820" height="108" fill="#1a1a1a"/>
+  <rect x="0" y="106" width="820" height="2" fill="#4a4a4a"/>
+  <text x="16" y="28" fill="#888" font-family="sans-serif" font-size="11">Tabs</text>
+  <rect x="16" y="40" width="72" height="36" rx="4" fill="#333" stroke="#666" stroke-width="1"/>
+  <text x="34" y="63" fill="#ccc" font-family="sans-serif" font-size="13">default</text>
+  <rect x="96" y="40" width="88" height="36" rx="4" fill="#2a4a7a" stroke="#5a8fd4" stroke-width="2"/>
+  <text x="108" y="63" fill="#fff" font-family="sans-serif" font-size="13">lounge</text>
+  <rect x="192" y="40" width="56" height="36" rx="4" fill="#333" stroke="#666" stroke-width="1"/>
+  <text x="204" y="63" fill="#ccc" font-family="sans-serif" font-size="13">dj</text>
+  <text x="380" y="28" fill="#888" font-family="sans-serif" font-size="11">Actions (Edit mode)</text>
+  <rect x="380" y="40" width="72" height="30" rx="3" fill="#3d3d3d" stroke="#555" stroke-width="1"/>
+  <text x="396" y="59" fill="#e0e0e0" font-family="sans-serif" font-size="11">Profiles</text>
+  <rect x="458" y="40" width="52" height="30" rx="3" fill="#3d3d3d" stroke="#555" stroke-width="1"/>
+  <text x="470" y="59" fill="#e0e0e0" font-family="sans-serif" font-size="11">Tabs</text>
+  <rect x="516" y="40" width="64" height="30" rx="3" fill="#3d3d3d" stroke="#555" stroke-width="1"/>
+  <text x="524" y="59" fill="#e0e0e0" font-family="sans-serif" font-size="11">Presets</text>
+  <rect x="586" y="40" width="78" height="30" rx="3" fill="#3d3d3d" stroke="#555" stroke-width="1"/>
+  <text x="598" y="59" fill="#e0e0e0" font-family="sans-serif" font-size="11">Patterns</text>
+  <rect x="670" y="40" width="134" height="30" rx="3" fill="#4a4a6a" stroke="#7a7aaf" stroke-width="1"/>
+  <text x="688" y="59" fill="#e0e0e0" font-family="sans-serif" font-size="11">Run mode</text>
+  <text x="16" y="98" fill="#aaa" font-family="sans-serif" font-size="10">Active tab highlighted. Mode button shows the mode you switch to next.</text>
+</svg>

docs/images/help/mobile-menu.svg

@@ -0,0 +1,26 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 300 340" width="300" height="340" role="img" aria-labelledby="t">
+  <title id="t">Narrow screen: Menu aggregates header actions</title>
+  <rect width="300" height="340" fill="#2e2e2e"/>
+  <rect x="0" y="0" width="300" height="52" fill="#1a1a1a"/>
+  <rect x="12" y="12" width="56" height="28" rx="4" fill="#3d3d3d" stroke="#555" stroke-width="1"/>
+  <text x="22" y="30" fill="#eee" font-family="DejaVu Sans, Liberation Sans, Arial, sans-serif" font-size="12">Menu <20></text>
+  <rect x="76" y="14" width="52" height="24" rx="4" fill="#333" stroke="#666" stroke-width="1"/>
+  <text x="86" y="30" fill="#ccc" font-family="DejaVu Sans, Liberation Sans, Arial, sans-serif" font-size="11">tab</text>
+  <rect x="136" y="14" width="52" height="24" rx="4" fill="#2a4a7a" stroke="#5a8fd4" stroke-width="1"/>
+  <text x="142" y="30" fill="#fff" font-family="DejaVu Sans, Liberation Sans, Arial, sans-serif" font-size="11">tab</text>
+  <rect x="12" y="60" width="276" height="168" rx="4" fill="#252525" stroke="#4a4a4a" stroke-width="1"/>
+  <text x="24" y="84" fill="#888" font-family="DejaVu Sans, Liberation Sans, Arial, sans-serif" font-size="10">Dropdown (same actions as desktop header)</text>
+  <g font-family="DejaVu Sans, Liberation Sans, Arial, sans-serif" font-size="12" fill="#e8e8e8">
+    <text x="24" y="108">Run mode</text>
+    <text x="24" y="132">Profiles</text>
+    <text x="24" y="156">Tabs</text>
+    <text x="24" y="180">Presets</text>
+    <text x="24" y="204">Help</text>
+  </g>
+  <rect x="12" y="240" width="276" height="80" rx="6" fill="#222" stroke="#444" stroke-width="1"/>
+  <text x="24" y="268" fill="#aaa" font-family="DejaVu Sans, Liberation Sans, Arial, sans-serif" font-size="10">Content area  presets as on desktop</text>
+  <rect x="24" y="278" width="80" height="32" rx="4" fill="#333" stroke="#555"/>
+  <text x="36" y="298" fill="#ddd" font-family="DejaVu Sans, Liberation Sans, Arial, sans-serif" font-size="11">preset</text>
+  <rect x="112" y="278" width="80" height="32" rx="4" fill="#333" stroke="#555"/>
+  <text x="124" y="298" fill="#ddd" font-family="DejaVu Sans, Liberation Sans, Arial, sans-serif" font-size="11">preset</text>
+</svg>

docs/images/help/preset-editor.svg

@@ -0,0 +1,31 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 520 400" width="520" height="400">
+  <title>Preset editor modal (simplified)</title>
+  <rect width="520" height="400" fill="#1e1e1e"/>
+  <rect x="40" y="28" width="440" height="344" rx="8" fill="#2a2a2a" stroke="#555" stroke-width="1"/>
+  <text x="60" y="58" fill="#fff" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="17" font-weight="600">Preset</text>
+  <text x="60" y="86" fill="#aaa" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="11">Name</text>
+  <rect x="60" y="92" width="200" height="28" rx="3" fill="#1a1a1a" stroke="#444" stroke-width="1"/>
+  <text x="72" y="111" fill="#ddd" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="12">evening glow</text>
+  <text x="280" y="86" fill="#aaa" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="11">Pattern</text>
+  <rect x="280" y="92" width="160" height="28" rx="3" fill="#1a1a1a" stroke="#444" stroke-width="1"/>
+  <text x="292" y="111" fill="#ddd" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="12">pulse</text>
+  <text x="60" y="148" fill="#aaa" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="11">Colours</text>
+  <rect x="60" y="156" width="48" height="48" rx="4" fill="#7e57c2" stroke="#333" stroke-width="1"/>
+  <circle cx="66" cy="162" r="8" fill="#3f51b5" stroke="#fff" stroke-width="1"/>
+  <text x="63" y="166" fill="#fff" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="7" font-weight="700">P</text>
+  <rect x="116" y="156" width="48" height="48" rx="4" fill="#26a69a" stroke="#333" stroke-width="1"/>
+  <text x="176" y="184" fill="#888" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="10">P = palette-linked</text>
+  <text x="60" y="232" fill="#aaa" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="11">Brightness, delay, n1-n8</text>
+  <rect x="60" y="238" width="120" height="24" rx="3" fill="#1a1a1a" stroke="#444" stroke-width="1"/>
+  <text x="68" y="254" fill="#888" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="11">0-255</text>
+  <text x="60" y="290" fill="#aaa" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="10">Actions</text>
+  <rect x="60" y="298" width="44" height="26" rx="3" fill="#444" stroke="#666" stroke-width="1"/>
+  <text x="72" y="315" fill="#eee" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="11">Try</text>
+  <rect x="112" y="298" width="56" height="26" rx="3" fill="#444" stroke="#666" stroke-width="1"/>
+  <text x="120" y="315" fill="#eee" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="11">Default</text>
+  <rect x="176" y="298" width="88" height="26" rx="3" fill="#3d5a80" stroke="#5a7ab8" stroke-width="1"/>
+  <text x="188" y="315" fill="#fff" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="11">Save+Send</text>
+  <rect x="272" y="298" width="48" height="26" rx="3" fill="#444" stroke="#666" stroke-width="1"/>
+  <text x="284" y="315" fill="#eee" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="11">Close</text>
+  <text x="60" y="352" fill="#888" font-family="DejaVu Sans,Liberation Sans,Arial,sans-serif" font-size="9">Try: preview without device save. Save+Send: store and push with save.</text>
+</svg>

docs/images/help/tab-preset-strip.svg

@@ -0,0 +1,35 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 220" width="800" height="220">
+  <title>Main area: brightness and preset tiles</title>
+  <defs>
+    <linearGradient id="rg1" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#ffd54f"/><stop offset="100%" style="stop-color:#fff8e1"/>
+    </linearGradient>
+    <linearGradient id="rg2" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#e53935"/><stop offset="33%" style="stop-color:#fdd835"/>
+      <stop offset="66%" style="stop-color:#43a047"/><stop offset="100%" style="stop-color:#1e88e5"/>
+    </linearGradient>
+    <linearGradient id="rg3" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#00897b"/><stop offset="100%" style="stop-color:#4db6ac"/>
+    </linearGradient>
+  </defs>
+  <rect width="800" height="220" fill="#2e2e2e"/>
+  <text x="20" y="32" fill="#fff" font-family="sans-serif" font-size="16" font-weight="600">lounge</text>
+  <text x="20" y="56" fill="#aaa" font-family="sans-serif" font-size="11">Brightness (global)</text>
+  <rect x="20" y="64" width="320" height="8" rx="4" fill="#444"/>
+  <rect x="20" y="64" width="200" height="8" rx="4" fill="#6a9ee2"/>
+  <circle cx="220" cy="68" r="10" fill="#ccc" stroke="#333" stroke-width="1"/>
+  <text x="360" y="74" fill="#888" font-family="sans-serif" font-size="11">drag to adjust</text>
+  <text x="20" y="108" fill="#aaa" font-family="sans-serif" font-size="11">Click tile body to select on tab devices</text>
+  <rect x="20" y="118" width="200" height="72" rx="6" fill="#252525" stroke="#555" stroke-width="1"/>
+  <rect x="28" y="128" width="184" height="36" rx="4" fill="url(#rg1)"/>
+  <text x="32" y="180" fill="#eee" font-family="sans-serif" font-size="13" font-weight="600">warm white</text>
+  <rect x="232" y="118" width="200" height="72" rx="6" fill="#252525" stroke="#6a9ee2" stroke-width="2"/>
+  <rect x="240" y="128" width="184" height="36" rx="4" fill="url(#rg2)"/>
+  <text x="244" y="180" fill="#eee" font-family="sans-serif" font-size="13" font-weight="600">rainbow</text>
+  <rect x="444" y="118" width="200" height="72" rx="6" fill="#252525" stroke="#555" stroke-width="1"/>
+  <rect x="452" y="128" width="184" height="36" rx="4" fill="url(#rg3)"/>
+  <text x="456" y="180" fill="#eee" font-family="sans-serif" font-size="13" font-weight="600">chase</text>
+  <rect x="656" y="130" width="56" height="48" rx="4" fill="#3d3d3d" stroke="#555" stroke-width="1"/>
+  <text x="670" y="158" fill="#ddd" font-family="sans-serif" font-size="11">Edit</text>
+  <text x="656" y="198" fill="#888" font-family="sans-serif" font-size="10">Edit mode: drag tiles to reorder</text>
+</svg>

docs/mockups/COLOR_PICKER_README.md

@@ -1,13 +1,13 @@
-# Custom Color Picker Component
+# Custom Colour Picker Component
 
-A cross-platform, cross-browser color picker component that provides a consistent user experience across all operating systems and browsers.
+A cross-platform, cross-browser colour picker component that provides a consistent user experience across all operating systems and browsers.
 
 ## Features
 
 ✅ **Consistent UI** - Same appearance and behavior on Windows, macOS, Linux, iOS, and Android  
 ✅ **Browser Support** - Works in Chrome, Firefox, Safari, Edge, Opera, and mobile browsers  
 ✅ **Touch Support** - Full touch/gesture support for mobile devices  
-✅ **HSB Color Model** - Uses Hue, Saturation, Brightness for intuitive color selection  
+✅ **HSB Colour Model** - Uses Hue, Saturation, Brightness for intuitive colour selection  
 ✅ **Multiple Input Methods** - Hex input, RGB inputs, and visual picker  
 ✅ **Accessible** - Keyboard accessible and screen reader friendly  
 ✅ **Customizable** - Easy to style and integrate  
@@ -33,7 +33,7 @@ A cross-platform, cross-browser color picker component that provides a consisten
 <div id="my-color-picker"></div>
 ```
 
-### 3. Initialize the color picker
+### 3. Initialize the colour picker
 
 ```javascript
 const picker = new ColorPicker('#my-color-picker', {
@@ -57,8 +57,8 @@ new ColorPicker(container, options)
 - `options` (object) - Configuration options
 
 **Options:**
-- `initialColor` (string) - Initial color in hex format (default: '#FF0000')
+- `initialColor` (string) - Initial colour in hex format (default: '#FF0000')
-- `onColorChange` (function) - Callback when color changes (receives hex color string)
+- `onColorChange` (function) - Callback when colour changes (receives hex colour string)
 - `showHexInput` (boolean) - Show hex input field (default: true)
 
 ### Methods
@@ -101,7 +101,7 @@ const picker = new ColorPicker('#picker1', {
 });
 ```
 
-### Multiple Color Pickers
+### Multiple Colour Pickers
 
 ```javascript
 const colors = ['#FF0000', '#00FF00', '#0000FF'];
@@ -116,7 +116,7 @@ const pickers = colors.map((color, index) => {
 });
 ```
 
-### Dynamic Color Picker Creation
+### Dynamic Colour Picker Creation
 
 ```javascript
 function addColorPicker(containerId, initialColor = '#000000') {
@@ -139,12 +139,12 @@ addColorPicker('color-2', '#00FF00');
 
 ## Styling
 
-The color picker uses CSS classes that can be customized:
+The colour picker uses CSS classes that can be customized:
 
 - `.color-picker-container` - Main container
-- `.color-picker-preview` - Color preview button
+- `.color-picker-preview` - Colour preview button
 - `.color-picker-panel` - Dropdown panel
-- `.color-picker-main` - Main color area
+- `.color-picker-main` - Main colour area
 - `.color-picker-hue` - Hue slider
 - `.color-picker-controls` - Controls section
 
@@ -183,20 +183,20 @@ The color picker uses CSS classes that can be customized:
 - ✅ iOS 12+
 - ✅ Android 7+
 
-## Color Format
+## Colour Format
 
-The color picker uses **hex color format** (`#RRGGBB`):
+The colour picker uses **hex colour format** (`#RRGGBB`):
 - Always returns uppercase hex strings (e.g., `#FF0000`)
 - Accepts both uppercase and lowercase input
 - Automatically validates hex format
 
 ## Integration with LED Driver Mockups
 
-The color picker is integrated into:
+The colour picker is integrated into:
-- `dashboard.html` - Color selection for patterns
+- `dashboard.html` - Colour selection for patterns
-- `presets.html` - Color selection when creating/editing presets
+- `presets.html` - Colour selection when creating/editing presets
 
-### Example: Getting Colors from Multiple Pickers
+### Example: Getting Colours from Multiple Pickers
 
 ```javascript
 const colorPickers = [];
@@ -218,7 +218,7 @@ function sendColorsToDevice() {
 ## Performance
 
 - Lightweight: ~14KB JavaScript, ~4KB CSS
-- Fast rendering: Uses Canvas API for color gradients
+- Fast rendering: Uses Canvas API for colour gradients
 - Smooth interactions: Optimized event handling
 - Memory efficient: No external dependencies
 
@@ -235,5 +235,5 @@ Part of the LED Driver project. Use freely in your projects.
 
 ## Demo
 
-See `color-picker-demo.html` for a live demonstration of the color picker component.
+See `color-picker-demo.html` for a live demonstration of the colour picker component.
 

docs/mockups/device-management.html

@@ -67,7 +67,7 @@
             box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
         }
 
-        .tab {
+        .zone {
             flex: 1;
             padding: 12px 24px;
             border: none;
@@ -78,16 +78,16 @@
             transition: all 0.2s;
         }
 
-        .tab.active {
+        .zone.active {
             background: #667eea;
             color: white;
         }
 
-        .tab-content {
+        .zone-content {
             display: none;
         }
 
-        .tab-content.active {
+        .zone-content.active {
             display: block;
         }
 
@@ -249,12 +249,12 @@
         </div>
 
         <div class="tabs">
-            <button class="tab active" onclick="switchTab('devices')">Devices</button>
+            <button class="zone active" onclick="switchTab('devices')">Devices</button>
-            <button class="tab" onclick="switchTab('groups')">Groups</button>
+            <button class="zone" onclick="switchTab('groups')">Groups</button>
         </div>
 
-        <!-- Devices Tab -->
+        <!-- Devices Zone -->
-        <div id="devices-tab" class="tab-content active">
+        <div id="devices-zone" class="zone-content active">
             <div class="card">
                 <h2>Connected Devices</h2>
                 <div class="device-item">
@@ -313,8 +313,8 @@
             </div>
         </div>
 
-        <!-- Groups Tab -->
+        <!-- Groups Zone -->
-        <div id="groups-tab" class="tab-content">
+        <div id="groups-zone" class="zone-content">
             <div class="card">
                 <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 20px;">
                     <h2>Groups</h2>
@@ -386,12 +386,12 @@
     </div>
 
     <script>
-        function switchTab(tab) {
+        function switchTab(zone) {
-            document.querySelectorAll('.tab').forEach(t => t.classList.remove('active'));
+            document.querySelectorAll('.zone').forEach(t => t.classList.remove('active'));
-            document.querySelectorAll('.tab-content').forEach(c => c.classList.remove('active'));
+            document.querySelectorAll('.zone-content').forEach(c => c.classList.remove('active'));
             
             event.target.classList.add('active');
-            document.getElementById(tab + '-tab').classList.add('active');
+            document.getElementById(zone + '-zone').classList.add('active');
         }
 
         function showAddDeviceModal() {

docs/msg.json

@@ -1,30 +1,23 @@
 {
-    "grps": [
+    "g":{ 
-        {
+        "df": {
-            "n": "group1",
             "pt": "on",
-            "cl": [
+            "cl": ["#ff0000"],
-                "000000",
+            "br": 200,
-                "000000"
+            "n1": 10,
-            ],
+            "n2": 10,
-            "br": 100,
+            "n3": 10,
-            "dl": 100,
+            "n4": 10,
-            "n1": 0,
+            "n5": 10,
-            "n2": 0,
+            "n6": 10,
-            "n3": 0,
-            "n4": 0,
-            "n5": 0,
-            "n6": 0
-        },
-        {
-            "n": "group2",
-            "pt": "on",
-            "cl": [
-                "000000",
-                "000000"
-            ],
-            "br": 100,
             "dl": 100
+        },
+        "dj": {
+            "pt": "blink",
+            "cl": ["#00ff00"],
+            "dl": 500
         }
-    ]
+    },
+    "sv": true,
+    "st": 0
 }

lib/microdot/session.py

@@ -0,0 +1,225 @@
+try:
+    import jwt
+    HAS_JWT = True
+except ImportError:
+    HAS_JWT = False
+    try:
+        import ubinascii
+    except ImportError:
+        import binascii as ubinascii
+    try:
+        import uhashlib as hashlib
+    except ImportError:
+        import hashlib
+    try:
+        import uhmac as hmac
+    except ImportError:
+        try:
+            import hmac
+        except ImportError:
+            hmac = None
+    import json
+
+from microdot.microdot import invoke_handler
+from microdot.helpers import wraps
+
+
+class SessionDict(dict):
+    """A session dictionary.
+
+    The session dictionary is a standard Python dictionary that has been
+    extended with convenience ``save()`` and ``delete()`` methods.
+    """
+    def __init__(self, request, session_dict):
+        super().__init__(session_dict)
+        self.request = request
+
+    def save(self):
+        """Update the session cookie."""
+        self.request.app._session.update(self.request, self)
+
+    def delete(self):
+        """Delete the session cookie."""
+        self.request.app._session.delete(self.request)
+
+
+class Session:
+    """Session handling
+
+    :param app: The application instance.
+    :param secret_key: The secret key, as a string or bytes object.
+    :param cookie_options: A dictionary with cookie options to pass as
+                           arguments to :meth:`Response.set_cookie()
+                           <microdot.Response.set_cookie>`.
+    """
+    secret_key = None
+
+    def __init__(self, app=None, secret_key=None, cookie_options=None):
+        self.secret_key = secret_key
+        self.cookie_options = cookie_options or {}
+        if app is not None:
+            self.initialize(app)
+
+    def initialize(self, app, secret_key=None, cookie_options=None):
+        if secret_key is not None:
+            self.secret_key = secret_key
+        if cookie_options is not None:
+            self.cookie_options = cookie_options
+        if 'path' not in self.cookie_options:
+            self.cookie_options['path'] = '/'
+        if 'http_only' not in self.cookie_options:
+            self.cookie_options['http_only'] = True
+        app._session = self
+
+    def get(self, request):
+        """Retrieve the user session.
+
+        :param request: The client request.
+
+        The return value is a session dictionary with the data stored in the
+        user's session, or ``{}`` if the session data is not available or
+        invalid.
+        """
+        if not self.secret_key:
+            raise ValueError('The session secret key is not configured')
+        if hasattr(request.g, '_session'):
+            return request.g._session
+        session = request.cookies.get('session')
+        if session is None:
+            request.g._session = SessionDict(request, {})
+            return request.g._session
+        request.g._session = SessionDict(request, self.decode(session))
+        return request.g._session
+
+    def update(self, request, session):
+        """Update the user session.
+
+        :param request: The client request.
+        :param session: A dictionary with the update session data for the user.
+
+        Applications would normally not call this method directly, instead they
+        would use the :meth:`SessionDict.save` method on the session
+        dictionary, which calls this method. For example::
+
+            @app.route('/')
+            @with_session
+            def index(request, session):
+                session['foo'] = 'bar'
+                session.save()
+                return 'Hello, World!'
+
+        Calling this method adds a cookie with the updated session to the
+        request currently being processed.
+        """
+        if not self.secret_key:
+            raise ValueError('The session secret key is not configured')
+
+        encoded_session = self.encode(session)
+
+        @request.after_request
+        def _update_session(request, response):
+            response.set_cookie('session', encoded_session,
+                                **self.cookie_options)
+            return response
+
+    def delete(self, request):
+        """Remove the user session.
+
+        :param request: The client request.
+
+        Applications would normally not call this method directly, instead they
+        would use the :meth:`SessionDict.delete` method on the session
+        dictionary, which calls this method. For example::
+
+            @app.route('/')
+            @with_session
+            def index(request, session):
+                session.delete()
+                return 'Hello, World!'
+
+        Calling this method adds a cookie removal header to the request
+        currently being processed.
+        """
+        @request.after_request
+        def _delete_session(request, response):
+            response.delete_cookie('session', **self.cookie_options)
+            return response
+
+    def encode(self, payload, secret_key=None):
+        """Encode session data using JWT if available, otherwise use simple HMAC."""
+        if HAS_JWT:
+            return jwt.encode(payload, secret_key or self.secret_key,
+                              algorithm='HS256')
+        else:
+            # Simple encoding for MicroPython: base64(json) + HMAC signature
+            key = (secret_key or self.secret_key).encode() if isinstance(secret_key or self.secret_key, str) else (secret_key or self.secret_key)
+            payload_json = json.dumps(payload)
+            payload_b64 = ubinascii.b2a_base64(payload_json.encode()).decode().strip()
+            
+            # Create HMAC signature
+            if hmac:
+                # Use hmac module if available
+                h = hmac.new(key, payload_json.encode(), hashlib.sha256)
+            else:
+                # Fallback: simple SHA256(key + message)
+                h = hashlib.sha256(key + payload_json.encode())
+            signature = ubinascii.b2a_base64(h.digest()).decode().strip()
+            
+            return f"{payload_b64}.{signature}"
+
+    def decode(self, session, secret_key=None):
+        """Decode session data using JWT if available, otherwise use simple HMAC."""
+        if HAS_JWT:
+            try:
+                payload = jwt.decode(session, secret_key or self.secret_key,
+                                     algorithms=['HS256'])
+            except jwt.exceptions.PyJWTError:  # pragma: no cover
+                return {}
+            return payload
+        else:
+            try:
+                # Simple decoding for MicroPython
+                if '.' not in session:
+                    return {}
+                
+                payload_b64, signature = session.rsplit('.', 1)
+                payload_json = ubinascii.a2b_base64(payload_b64).decode()
+                
+                # Verify HMAC signature
+                key = (secret_key or self.secret_key).encode() if isinstance(secret_key or self.secret_key, str) else (secret_key or self.secret_key)
+                if hmac:
+                    # Use hmac module if available
+                    h = hmac.new(key, payload_json.encode(), hashlib.sha256)
+                else:
+                    # Fallback: simple SHA256(key + message)
+                    h = hashlib.sha256(key + payload_json.encode())
+                expected_signature = ubinascii.b2a_base64(h.digest()).decode().strip()
+                
+                if signature != expected_signature:
+                    return {}
+                
+                return json.loads(payload_json)
+            except Exception:
+                return {}
+
+
+def with_session(f):
+    """Decorator that passes the user session to the route handler.
+
+    The session dictionary is passed to the decorated function as an argument
+    after the request object. Example::
+
+        @app.route('/')
+        @with_session
+        def index(request, session):
+            return 'Hello, World!'
+
+    Note that the decorator does not save the session. To update the session,
+    call the :func:`session.save() <microdot.session.SessionDict.save>` method.
+    """
+    @wraps(f)
+    async def wrapper(request, *args, **kwargs):
+        return await invoke_handler(
+            f, request, request.app._session.get(request), *args, **kwargs)
+
+    return wrapper

pyproject.toml

@@ -0,0 +1,3 @@
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_endpoints_pytest.py"]

scripts/build_help_pdf.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env sh
+# Build docs/help.pdf from docs/help.md.
+# Requires: pandoc, chromium (headless print-to-PDF).
+set -eu
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# HTML next to docs/help.md so relative image paths (e.g. images/help/*.svg) resolve.
+HTML="$ROOT/docs/.help-print.html"
+trap 'rm -f "$HTML"' EXIT
+
+pandoc "$ROOT/docs/help.md" -s \
+  --css="$ROOT/scripts/help-pdf.css" \
+  --metadata title="LED controller — user guide" \
+  -o "$HTML"
+
+chromium --headless --no-sandbox --disable-gpu \
+  --print-to-pdf="$ROOT/docs/help.pdf" \
+  "file://${HTML}"
+
+echo "Wrote $ROOT/docs/help.pdf ($(wc -c < "$ROOT/docs/help.pdf") bytes)"

scripts/help-pdf.css

@@ -0,0 +1,96 @@
+/* Print stylesheet for docs/help.md → PDF (Chromium headless) */
+@page {
+  margin: 18mm;
+  size: A4;
+}
+html {
+  font-size: 11pt;
+  line-height: 1.4;
+}
+body {
+  font-family: "DejaVu Sans", "Liberation Sans", Helvetica, Arial, sans-serif;
+  color: #222;
+  max-width: 100%;
+}
+h1 {
+  font-size: 1.45rem;
+  border-bottom: 2px solid #333;
+  padding-bottom: 0.25em;
+  margin-top: 0;
+}
+h2 {
+  font-size: 1.15rem;
+  margin-top: 1.25em;
+  page-break-after: avoid;
+}
+h3 {
+  font-size: 1.05rem;
+  margin-top: 1em;
+  page-break-after: avoid;
+}
+code {
+  font-family: "DejaVu Sans Mono", "Liberation Mono", Consolas, monospace;
+  font-size: 0.92em;
+  background: #f3f3f3;
+  padding: 0.1em 0.35em;
+  border-radius: 3px;
+}
+pre {
+  font-family: "DejaVu Sans Mono", "Liberation Mono", Consolas, monospace;
+  font-size: 0.88em;
+  background: #f5f5f5;
+  border: 1px solid #ddd;
+  padding: 0.65em 0.85em;
+  overflow-x: auto;
+  page-break-inside: avoid;
+}
+pre code {
+  background: none;
+  padding: 0;
+}
+table {
+  border-collapse: collapse;
+  width: 100%;
+  margin: 0.75em 0;
+  font-size: 0.95em;
+  page-break-inside: avoid;
+}
+th, td {
+  border: 1px solid #bbb;
+  padding: 6px 8px;
+  text-align: left;
+  vertical-align: top;
+}
+th {
+  background: #eee;
+}
+a {
+  color: #1a5276;
+  text-decoration: none;
+}
+hr {
+  border: none;
+  border-top: 1px solid #ccc;
+  margin: 1.25em 0;
+}
+ul, ol {
+  padding-left: 1.35em;
+}
+li {
+  margin: 0.2em 0;
+}
+
+/* Images in docs/help.md */
+img {
+  max-width: 100%;
+  height: auto;
+  page-break-inside: avoid;
+  border: 1px solid #ccc;
+  border-radius: 4px;
+}
+p.help-figure-caption {
+  font-size: 0.9em;
+  color: #555;
+  margin: 0.35em 0 1em 0;
+  line-height: 1.35;
+}

scripts/install-boot-service.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Install systemd service so LED controller starts at boot.
+# Run once: sudo scripts/install-boot-service.sh
+set -e
+cd "$(dirname "$0")/.."
+REPO="$(pwd)"
+SERVICE_NAME="led-controller.service"
+UNIT_PATH="/etc/systemd/system/$SERVICE_NAME"
+if [ ! -f "scripts/led-controller.service" ]; then
+  echo "Run this script from the repo root."
+  exit 1
+fi
+chmod +x scripts/start.sh
+sudo cp "scripts/led-controller.service" "$UNIT_PATH"
+sudo systemctl daemon-reload
+sudo systemctl enable "$SERVICE_NAME"
+echo "Installed and enabled $SERVICE_NAME"
+echo "Start now:  sudo systemctl start $SERVICE_NAME"
+echo "Status:     sudo systemctl status $SERVICE_NAME"
+echo "Logs:       journalctl -u $SERVICE_NAME -f"

scripts/led-controller.service

@@ -0,0 +1,17 @@
+[Unit]
+Description=LED Controller web server
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=pi
+WorkingDirectory=/home/pi/led-controller
+Environment=PORT=80
+Environment=PATH=/home/pi/.local/bin:/usr/local/bin:/usr/bin:/bin
+ExecStart=/bin/bash /home/pi/led-controller/scripts/start.sh
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target

scripts/setup-port80.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Allow the app to bind to port 80 without root.
+# Run once: sudo scripts/setup-port80.sh (from repo root)
+# Or: scripts/setup-port80.sh (will prompt for sudo only for setcap)
+
+set -e
+cd "$(dirname "$0")/.."
+REPO_ROOT="$(pwd)"
+# If run under sudo, use the invoking user's pipenv so the venv is found
+if [ -n "$SUDO_USER" ]; then
+  VENV="$(sudo -u "$SUDO_USER" bash -c "cd '$REPO_ROOT' && pipenv --venv" 2>/dev/null)" || true
+else
+  VENV="$(pipenv --venv 2>/dev/null)" || true
+fi
+if [ -z "$VENV" ]; then
+  echo "Run 'pipenv install' first, then run this script again."
+  exit 1
+fi
+PYTHON="${VENV}/bin/python3"
+if [ ! -f "$PYTHON" ]; then
+  PYTHON="${VENV}/bin/python"
+fi
+if [ ! -f "$PYTHON" ]; then
+  echo "Python not found in venv: $VENV"
+  exit 1
+fi
+# Use the real binary (setcap can fail on symlinks or some filesystems)
+REAL_PYTHON="$(readlink -f "$PYTHON" 2>/dev/null)" || REAL_PYTHON="$PYTHON"
+if sudo setcap 'cap_net_bind_service=+ep' "$REAL_PYTHON" 2>/dev/null; then
+  echo "OK: port 80 enabled for $REAL_PYTHON"
+  echo "Start the app with: pipenv run run"
+else
+  echo "setcap failed on $REAL_PYTHON"
+  exit 1
+fi

scripts/start.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Start the LED controller web server (port 80 by default).
+cd "$(dirname "$0")/.."
+export PORT="${PORT:-80}"
+pipenv run run

scripts/test-port80.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Test the app on port 80. Run after: sudo scripts/setup-port80.sh
+# Usage: ./scripts/test-port80.sh
+
+set -e
+cd "$(dirname "$0")/.."
+APP_URL="${APP_URL:-http://127.0.0.1:80}"
+
+echo "Starting app on port 80 in background..."
+pipenv run run &
+PID=$!
+trap "kill $PID 2>/dev/null; exit" EXIT
+
+echo "Waiting for server to start..."
+for i in 1 2 3 4 5 6 7 8 9 10; do
+  if curl -s -o /dev/null -w "%{http_code}" "$APP_URL/" 2>/dev/null | grep -q 200; then
+    echo "Server is up."
+    break
+  fi
+  sleep 1
+done
+
+echo "Requesting $APP_URL/ ..."
+CODE=$(curl -s -o /dev/null -w "%{http_code}" "$APP_URL/")
+if [ "$CODE" = "200" ]; then
+  echo "OK: GET / returned HTTP $CODE"
+  curl -s "$APP_URL/" | head -5
+  echo "..."
+  exit 0
+else
+  echo "FAIL: GET / returned HTTP $CODE (expected 200)"
+  exit 1
+fi

src/boot.py

@@ -1,8 +1,6 @@
-import settings
+# Boot script (ESP only; no-op on Pi)
-import wifi
+import settings  # noqa: F401
 from settings import Settings
 
 s = Settings()
-
+# AP setup was here when running on ESP; Pi uses system networking.
-name = s.get('name', 'led')
-wifi.ap(name, '')

src/controllers/__init__.py

@@ -0,0 +1 @@
+# Controllers package

src/controllers/device.py

@@ -0,0 +1,393 @@
+from microdot import Microdot
+from models.device import (
+    Device,
+    derive_device_mac,
+    validate_device_transport,
+    validate_device_type,
+)
+from models.transport import get_current_sender
+from models.wifi_ws_clients import (
+    normalize_tcp_peer_ip,
+    send_json_line_to_ip,
+    tcp_client_connected,
+)
+from util.driver_patterns import driver_patterns_dir
+from util.espnow_message import build_message
+import asyncio
+import json
+import os
+import socket
+from urllib.parse import quote
+
+# Ephemeral driver preset name (never written to Pi preset store; ``save`` not set on wire).
+_IDENTIFY_PRESET_KEY = "__identify"
+
+# Short-key payload: 10 Hz full cycle = 50 ms on + 50 ms off (driver ``blink`` toggles each ``d`` ms).
+_IDENTIFY_DRIVER_PRESET = {
+    "p": "blink",
+    "c": ["#ff0000"],
+    "d": 50,
+    "b": 128,
+    "a": True,
+    "n1": 0,
+    "n2": 0,
+    "n3": 0,
+    "n4": 0,
+    "n5": 0,
+    "n6": 0,
+}
+
+
+def _compact_v1_json(*, presets=None, select=None, save=False):
+    """Single-line v1 object; compact so serial/ESP-NOW stays small."""
+    body = {"v": "1"}
+    if presets is not None:
+        body["presets"] = presets
+        if save:
+            body["save"] = True
+    if select is not None:
+        body["select"] = select
+    return json.dumps(body, separators=(",", ":"))
+
+# Seconds after identify blink before selecting built-in ``off`` (tests may monkeypatch).
+IDENTIFY_OFF_DELAY_S = 2.0
+
+controller = Microdot()
+devices = Device()
+
+
+def _device_live_connected(dev_dict):
+    """
+    Wi-Fi: whether the controller has an outbound WebSocket to this device's IP.
+    ESP-NOW: None (no Wi-Fi session on the Pi for that transport).
+    """
+    tr = (dev_dict.get("transport") or "espnow").strip().lower()
+    if tr != "wifi":
+        return None
+    ip = normalize_tcp_peer_ip(dev_dict.get("address") or "")
+    if not ip:
+        return False
+    return tcp_client_connected(ip)
+
+
+def _device_json_with_live_status(dev_dict):
+    row = dict(dev_dict)
+    row["connected"] = _device_live_connected(dev_dict)
+    return row
+
+
+def _safe_pattern_filename(name):
+    if not isinstance(name, str):
+        return False
+    if not name.endswith(".py"):
+        return False
+    if "/" in name or "\\" in name or ".." in name:
+        return False
+    return True
+
+
+def _http_post_pattern_source(ip, filename, code_text, reload_patterns=True, timeout_s=10.0):
+    """POST source to driver /patterns/upload?name=...&reload=...; return True on 2xx."""
+    if not isinstance(ip, str) or not ip.strip():
+        return False
+    if not isinstance(filename, str) or not filename:
+        return False
+    if not isinstance(code_text, str):
+        return False
+
+    name_q = quote(filename, safe="")
+    reload_q = "1" if reload_patterns else "0"
+    path = "/patterns/upload?name=%s&reload=%s" % (name_q, reload_q)
+    body = code_text.encode("utf-8")
+    req = (
+        "POST %s HTTP/1.1\r\n"
+        "Host: %s\r\n"
+        "Content-Type: text/plain; charset=utf-8\r\n"
+        "Content-Length: %d\r\n"
+        "Connection: close\r\n"
+        "\r\n" % (path, ip, len(body))
+    ).encode("utf-8") + body
+
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        sock.settimeout(timeout_s)
+        sock.connect((ip.strip(), 80))
+        sock.sendall(req)
+        data = b""
+        while True:
+            chunk = sock.recv(1024)
+            if not chunk:
+                break
+            data += chunk
+    except OSError:
+        return False
+    finally:
+        try:
+            sock.close()
+        except Exception:
+            pass
+
+    first_line = data.split(b"\r\n", 1)[0] if data else b""
+    return b" 2" in first_line
+
+
+async def _identify_send_off_after_delay(sender, transport, wifi_ip, dev_id, name):
+    try:
+        await asyncio.sleep(IDENTIFY_OFF_DELAY_S)
+        off_msg = build_message(select={name: ["off"]})
+        if transport == "wifi":
+            await send_json_line_to_ip(wifi_ip, off_msg)
+        else:
+            await sender.send(off_msg, addr=dev_id)
+    except Exception:
+        pass
+
+
+@controller.get("")
+async def list_devices(request):
+    """List all devices (includes ``connected`` for live Wi-Fi WebSocket presence)."""
+    devices_data = {}
+    for dev_id in devices.list():
+        d = devices.read(dev_id)
+        if d:
+            devices_data[dev_id] = _device_json_with_live_status(d)
+    return json.dumps(devices_data), 200, {"Content-Type": "application/json"}
+
+
+@controller.get("/<id>")
+async def get_device(request, id):
+    """Get a device by ID (includes ``connected`` for live Wi-Fi WebSocket presence)."""
+    dev = devices.read(id)
+    if dev:
+        return json.dumps(_device_json_with_live_status(dev)), 200, {
+            "Content-Type": "application/json",
+        }
+    return json.dumps({"error": "Device not found"}), 404, {
+        "Content-Type": "application/json",
+    }
+
+
+@controller.post("")
+async def create_device(request):
+    """Create a new device."""
+    try:
+        data = request.json or {}
+        name = data.get("name", "").strip()
+        if not name:
+            return json.dumps({"error": "name is required"}), 400, {
+                "Content-Type": "application/json",
+            }
+        try:
+            device_type = validate_device_type(data.get("type", "led"))
+            transport = validate_device_transport(data.get("transport", "espnow"))
+        except ValueError as e:
+            return json.dumps({"error": str(e)}), 400, {
+                "Content-Type": "application/json",
+            }
+        address = data.get("address")
+        mac = data.get("mac")
+        if derive_device_mac(mac=mac, address=address, transport=transport) is None:
+            return json.dumps(
+                {
+                    "error": "mac is required (12 hex digits); for Wi-Fi include mac plus IP in address"
+                }
+            ), 400, {"Content-Type": "application/json"}
+        default_pattern = data.get("default_pattern")
+        zl = data.get("zones")
+        if isinstance(zl, list):
+            zl = [str(t) for t in zl]
+        else:
+            zl = []
+        dev_id = devices.create(
+            name=name,
+            address=address,
+            mac=mac,
+            default_pattern=default_pattern,
+            zones=zl,
+            device_type=device_type,
+            transport=transport,
+        )
+        dev = devices.read(dev_id)
+        return json.dumps({dev_id: dev}), 201, {"Content-Type": "application/json"}
+    except ValueError as e:
+        msg = str(e)
+        code = 409 if "already exists" in msg.lower() else 400
+        return json.dumps({"error": msg}), code, {"Content-Type": "application/json"}
+    except Exception as e:
+        return json.dumps({"error": str(e)}), 400, {"Content-Type": "application/json"}
+
+
+@controller.put("/<id>")
+async def update_device(request, id):
+    """Update a device."""
+    try:
+        raw = request.json or {}
+        data = dict(raw)
+        data.pop("id", None)
+        data.pop("addresses", None)
+        data.pop("connected", None)
+        if "name" in data:
+            n = (data.get("name") or "").strip()
+            if not n:
+                return json.dumps({"error": "name cannot be empty"}), 400, {
+                    "Content-Type": "application/json",
+                }
+            data["name"] = n
+        if "type" in data:
+            data["type"] = validate_device_type(data.get("type"))
+        if "transport" in data:
+            data["transport"] = validate_device_transport(data.get("transport"))
+        if "zones" in data and isinstance(data["zones"], list):
+            data["zones"] = [str(t) for t in data["zones"]]
+        if devices.update(id, data):
+            return json.dumps(devices.read(id)), 200, {"Content-Type": "application/json"}
+        return json.dumps({"error": "Device not found"}), 404, {
+            "Content-Type": "application/json",
+        }
+    except ValueError as e:
+        return json.dumps({"error": str(e)}), 400, {"Content-Type": "application/json"}
+    except Exception as e:
+        return json.dumps({"error": str(e)}), 400, {"Content-Type": "application/json"}
+
+
+@controller.delete("/<id>")
+async def delete_device(request, id):
+    """Delete a device."""
+    if devices.delete(id):
+        return (
+            json.dumps({"message": "Device deleted successfully"}),
+            200,
+            {"Content-Type": "application/json"},
+        )
+    return json.dumps({"error": "Device not found"}), 404, {
+        "Content-Type": "application/json",
+    }
+
+
+@controller.post("/<id>/identify")
+async def identify_device(request, id):
+    """
+    One v1 JSON object: ``presets.__identify`` (``d``=50 ms → 10 Hz blink) plus ``select`` for
+    this device name — same combined shape as profile sends the driver already accepts over TCP
+    / ESP-NOW. No ``save``. After ``IDENTIFY_OFF_DELAY_S``, a background task selects ``off``.
+    """
+    dev = devices.read(id)
+    if not dev:
+        return json.dumps({"error": "Device not found"}), 404, {
+            "Content-Type": "application/json",
+        }
+    sender = get_current_sender()
+    if not sender:
+        return json.dumps({"error": "Transport not configured"}), 503, {
+            "Content-Type": "application/json",
+        }
+    name = str(dev.get("name") or "").strip()
+    if not name:
+        return json.dumps({"error": "Device must have a name to identify"}), 400, {
+            "Content-Type": "application/json",
+        }
+
+    transport = dev.get("transport") or "espnow"
+    wifi_ip = None
+    if transport == "wifi":
+        wifi_ip = dev.get("address")
+        if not wifi_ip:
+            return json.dumps({"error": "Device has no IP address"}), 400, {
+                "Content-Type": "application/json",
+            }
+
+    try:
+        msg = _compact_v1_json(
+            presets={_IDENTIFY_PRESET_KEY: dict(_IDENTIFY_DRIVER_PRESET)},
+            select={name: [_IDENTIFY_PRESET_KEY]},
+        )
+        if transport == "wifi":
+            ok = await send_json_line_to_ip(wifi_ip, msg)
+            if not ok:
+                return json.dumps({"error": "Wi-Fi driver not connected"}), 503, {
+                    "Content-Type": "application/json",
+                }
+        else:
+            await sender.send(msg, addr=id)
+
+        asyncio.create_task(
+            _identify_send_off_after_delay(sender, transport, wifi_ip, id, name)
+        )
+    except Exception as e:
+        return json.dumps({"error": str(e)}), 503, {"Content-Type": "application/json"}
+    return json.dumps({"message": "Identify sent"}), 200, {
+        "Content-Type": "application/json",
+    }
+
+
+@controller.post("/<id>/patterns/push")
+async def push_patterns_ota(request, id):
+    """
+    Push all local pattern files directly to a Wi-Fi LED driver over HTTP upload.
+    """
+    dev = devices.read(id)
+    if not dev:
+        return json.dumps({"error": "Device not found"}), 404, {
+            "Content-Type": "application/json",
+        }
+    if (dev.get("transport") or "").lower() != "wifi":
+        return json.dumps({"error": "Pattern OTA push is only supported for Wi-Fi devices"}), 400, {
+            "Content-Type": "application/json",
+        }
+    wifi_ip = str(dev.get("address") or "").strip()
+    if not wifi_ip:
+        return json.dumps({"error": "Device has no IP address"}), 400, {
+            "Content-Type": "application/json",
+        }
+
+    base_dir = driver_patterns_dir()
+    try:
+        names = sorted(os.listdir(base_dir))
+    except OSError as e:
+        return json.dumps({"error": str(e)}), 500, {
+            "Content-Type": "application/json",
+        }
+
+    files = [n for n in names if _safe_pattern_filename(n) and n != "__init__.py"]
+    if not files:
+        return json.dumps({"error": "No pattern files found"}), 404, {
+            "Content-Type": "application/json",
+        }
+
+    sent = []
+    failed = []
+    total = len(files)
+    for idx, filename in enumerate(files):
+        path = os.path.join(base_dir, filename)
+        try:
+            with open(path, "r") as f:
+                code = f.read()
+        except OSError:
+            failed.append(filename)
+            continue
+        reload_patterns = idx == (total - 1)
+        ok = _http_post_pattern_source(
+            wifi_ip,
+            filename,
+            code,
+            reload_patterns=reload_patterns,
+            timeout_s=10.0,
+        )
+        if ok:
+            sent.append(filename)
+        else:
+            failed.append(filename)
+
+    if not sent:
+        return json.dumps({"error": "Wi-Fi driver did not accept pattern uploads", "failed": failed}), 503, {
+            "Content-Type": "application/json",
+        }
+
+    return json.dumps({
+        "message": "Pattern files uploaded",
+        "sent_count": len(sent),
+        "sent": sent,
+        "failed": failed,
+    }), 200, {
+        "Content-Type": "application/json",
+    }

src/controllers/led_tool.py

@@ -0,0 +1,189 @@
+import json
+import os
+import subprocess
+import sys
+
+from microdot import Microdot
+from serial.tools import list_ports
+
+controller = Microdot()
+
+
+def _repo_root() -> str:
+    return os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+
+
+def _led_cli_path() -> str:
+    return os.path.join(_repo_root(), "led-tool", "cli.py")
+
+
+def _build_led_cli_command(port: str, payload: dict):
+    cmd = [sys.executable, _led_cli_path(), "--port", port]
+
+    flag_map = (
+        ("name", "--name"),
+        ("led_pin", "--pin"),
+        ("num_leds", "--leds"),
+        ("brightness", "--brightness"),
+        ("transport", "--transport"),
+        ("ssid", "--ssid"),
+        ("password", "--wifi-password"),
+        ("wifi_channel", "--wifi-channel"),
+        ("default", "--default"),
+    )
+
+    for key, flag in flag_map:
+        value = payload.get(key)
+        if value is None:
+            continue
+        value_str = str(value).strip()
+        if value_str == "":
+            continue
+        cmd.extend([flag, value_str])
+
+    return cmd
+
+
+def _run_led_cli_command(cmd, cli_path: str, timeout_s=180):
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout_s,
+            cwd=os.path.dirname(cli_path),
+        )
+    except subprocess.TimeoutExpired:
+        return (
+            json.dumps({"error": "led-tool command timed out after 180 seconds"}),
+            504,
+            {"Content-Type": "application/json"},
+        )
+    except Exception as exc:
+        return (
+            json.dumps({"error": str(exc)}),
+            500,
+            {"Content-Type": "application/json"},
+        )
+
+    return (
+        json.dumps(
+            {
+                "ok": result.returncode == 0,
+                "returncode": result.returncode,
+                "stdout": result.stdout,
+                "stderr": result.stderr,
+                "command": cmd,
+            }
+        ),
+        200,
+        {"Content-Type": "application/json"},
+    )
+
+
+def _extract_settings_from_stdout(stdout: str):
+    text = (stdout or "").strip()
+    if not text:
+        return None
+    try:
+        parsed = json.loads(text)
+        return parsed if isinstance(parsed, dict) else None
+    except Exception:
+        return None
+
+
+@controller.get("/ports")
+async def list_serial_ports(request):
+    ports = []
+    for info in list_ports.comports():
+        ports.append(
+            {
+                "device": info.device,
+                "description": info.description,
+                "hwid": info.hwid,
+            }
+        )
+    return (
+        json.dumps(
+            {
+                "ports": ports,
+                "led_cli_exists": os.path.exists(_led_cli_path()),
+            }
+        ),
+        200,
+        {"Content-Type": "application/json"},
+    )
+
+
+@controller.post("/settings")
+async def apply_settings(request):
+    data = request.json or {}
+    port = str(data.get("port") or "").strip()
+    if not port:
+        return (
+            json.dumps({"error": "port is required"}),
+            400,
+            {"Content-Type": "application/json"},
+        )
+
+    cli_path = _led_cli_path()
+    if not os.path.exists(cli_path):
+        return (
+            json.dumps({"error": "led-tool/cli.py not found"}),
+            500,
+            {"Content-Type": "application/json"},
+        )
+
+    cmd = _build_led_cli_command(port, data) + ["--follow"]
+    return _run_led_cli_command(cmd, cli_path, timeout_s=None)
+
+
+@controller.post("/reset")
+@controller.post("/reset/")
+async def reset_device(request):
+    data = request.json or {}
+    port = str(data.get("port") or "").strip()
+    if not port:
+        return (
+            json.dumps({"error": "port is required"}),
+            400,
+            {"Content-Type": "application/json"},
+        )
+
+    cli_path = _led_cli_path()
+    if not os.path.exists(cli_path):
+        return (
+            json.dumps({"error": "led-tool/cli.py not found"}),
+            500,
+            {"Content-Type": "application/json"},
+        )
+
+    cmd = [sys.executable, cli_path, "--port", port, "--reset", "--follow"]
+    return _run_led_cli_command(cmd, cli_path, timeout_s=None)
+
+
+@controller.get("/settings")
+async def read_settings(request):
+    port = str(request.args.get("port") or "").strip()
+    if not port:
+        return (
+            json.dumps({"error": "port is required"}),
+            400,
+            {"Content-Type": "application/json"},
+        )
+
+    cli_path = _led_cli_path()
+    if not os.path.exists(cli_path):
+        return (
+            json.dumps({"error": "led-tool/cli.py not found"}),
+            500,
+            {"Content-Type": "application/json"},
+        )
+
+    cmd = [sys.executable, cli_path, "--port", port, "--show"]
+    body, status, headers = _run_led_cli_command(cmd, cli_path)
+    if status != 200:
+        return body, status, headers
+    data = json.loads(body)
+    data["settings"] = _extract_settings_from_stdout(data.get("stdout") or "")
+    return json.dumps(data), status, headers

src/controllers/palette.py

@@ -8,14 +8,18 @@ palettes = Palette()
 @controller.get('')
 async def list_palettes(request):
     """List all palettes."""
-    return json.dumps(palettes), 200, {'Content-Type': 'application/json'}
+    data = {}
+    for pid in palettes.list():
+        colors = palettes.read(pid)
+        data[pid] = colors
+    return json.dumps(data), 200, {'Content-Type': 'application/json'}
 
 @controller.get('/<id>')
 async def get_palette(request, id):
     """Get a specific palette by ID."""
-    palette = palettes.read(id)
+    if str(id) in palettes:
-    if palette:
+        palette = palettes.read(id)
-        return json.dumps(palette), 200, {'Content-Type': 'application/json'}
+        return json.dumps({"colors": palette or [], "id": str(id)}), 200, {'Content-Type': 'application/json'}
     return json.dumps({"error": "Palette not found"}), 404
 
 @controller.post('')
@@ -23,12 +27,11 @@ async def create_palette(request):
     """Create a new palette."""
     try:
         data = request.json or {}
-        name = data.get("name", "")
         colors = data.get("colors", None)
-        palette_id = palettes.create(name, colors)
+        # Palette no longer needs a name; only colors are stored.
-        if data:
+        palette_id = palettes.create("", colors)
-            palettes.update(palette_id, data)
+        created_colors = palettes.read(palette_id) or []
-        return json.dumps(palettes.read(palette_id)), 201, {'Content-Type': 'application/json'}
+        return json.dumps({"id": str(palette_id), "colors": created_colors}), 201, {'Content-Type': 'application/json'}
     except Exception as e:
         return json.dumps({"error": str(e)}), 400
 
@@ -36,9 +39,13 @@ async def create_palette(request):
 async def update_palette(request, id):
     """Update an existing palette."""
     try:
-        data = request.json
+        data = request.json or {}
+        # Ignore any name field; only colors are relevant.
+        if "name" in data:
+            data.pop("name", None)
         if palettes.update(id, data):
-            return json.dumps(palettes.read(id)), 200, {'Content-Type': 'application/json'}
+            colors = palettes.read(id) or []
+            return json.dumps({"id": str(id), "colors": colors}), 200, {'Content-Type': 'application/json'}
         return json.dumps({"error": "Palette not found"}), 404
     except Exception as e:
         return json.dumps({"error": str(e)}), 400

src/controllers/pattern.py

@@ -0,0 +1,500 @@
+from microdot import Microdot
+from models.pattern import Pattern
+from models.device import Device
+from util.driver_patterns import (
+    driver_patterns_dir,
+    is_firmware_builtin_pattern_module,
+    normalize_pattern_py_filename,
+)
+import json
+import re
+import os
+import socket
+from urllib.parse import quote
+
+controller = Microdot()
+patterns = Pattern()
+
+
+def _project_root():
+    """Project root (parent of ``src/``). CWD is often ``src/`` when running ``main.py``."""
+    here = os.path.dirname(os.path.abspath(__file__))
+    return os.path.abspath(os.path.join(here, "..", ".."))
+
+
+def _safe_pattern_filename(name):
+    if not isinstance(name, str):
+        return False
+    if not name.endswith(".py"):
+        return False
+    if "/" in name or "\\" in name or ".." in name:
+        return False
+    return True
+
+
+_PATTERN_KEY_RE = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]{0,63}$")
+
+
+def _normalize_pattern_key(raw):
+    """Pattern id / module basename (no .py)."""
+    if not isinstance(raw, str):
+        return ""
+    s = raw.strip()
+    if s.lower().endswith(".py"):
+        s = s[:-3].strip()
+    return s
+
+
+def _valid_pattern_key(key):
+    return bool(key and _PATTERN_KEY_RE.match(key))
+
+
+def _http_post_pattern_source(ip, filename, code_text, reload_patterns=True, timeout_s=10.0):
+    """POST source to driver /patterns/upload?name=...&reload=...; return True on 2xx."""
+    if not isinstance(ip, str) or not ip.strip():
+        return False
+    if not isinstance(filename, str) or not filename:
+        return False
+    if not isinstance(code_text, str):
+        return False
+
+    name_q = quote(filename, safe="")
+    reload_q = "1" if reload_patterns else "0"
+    path = "/patterns/upload?name=%s&reload=%s" % (name_q, reload_q)
+    body = code_text.encode("utf-8")
+    req = (
+        "POST %s HTTP/1.1\r\n"
+        "Host: %s\r\n"
+        "Content-Type: text/plain; charset=utf-8\r\n"
+        "Content-Length: %d\r\n"
+        "Connection: close\r\n"
+        "\r\n" % (path, ip, len(body))
+    ).encode("utf-8") + body
+
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        sock.settimeout(timeout_s)
+        sock.connect((ip.strip(), 80))
+        sock.sendall(req)
+        data = b""
+        while True:
+            chunk = sock.recv(1024)
+            if not chunk:
+                break
+            data += chunk
+    except OSError:
+        return False
+    finally:
+        try:
+            sock.close()
+        except Exception:
+            pass
+
+    first_line = data.split(b"\r\n", 1)[0] if data else b""
+    # Accept any 2xx status.
+    return b" 2" in first_line
+
+def load_pattern_definitions():
+    """Load pattern definitions from pattern.json file."""
+    try:
+        root = _project_root()
+        paths = [
+            os.path.join(root, "db", "pattern.json"),
+            os.path.join(root, "pattern.json"),
+            "db/pattern.json",
+            "pattern.json",
+            "/db/pattern.json",
+        ]
+        for path in paths:
+            try:
+                with open(path, "r") as f:
+                    return json.load(f)
+            except OSError:
+                continue
+        return {}
+    except Exception as e:
+        print(f"Error loading pattern.json: {e}")
+        return {}
+
+
+def load_driver_pattern_names():
+    """List available pattern module names from led-driver/src/patterns."""
+    try:
+        names = []
+        for filename in os.listdir(driver_patterns_dir()):
+            if not _safe_pattern_filename(filename) or filename == "__init__.py":
+                continue
+            names.append(filename[:-3])
+        names.sort()
+        return names
+    except OSError:
+        return []
+
+
+def build_runtime_pattern_map():
+    """
+    Runtime pattern map for UI menus.
+    Keep pattern DB metadata as primary, then add any local driver pattern files
+    missing from the DB so new OTA files still appear in menus.
+    """
+    definitions = load_pattern_definitions()
+    available = load_driver_pattern_names()
+    result = {}
+    for name, meta in definitions.items():
+        result[name] = dict(meta) if isinstance(meta, dict) else {}
+    for name in available:
+        if name not in result:
+            result[name] = {}
+    return result
+
+@controller.get('/definitions')
+async def get_pattern_definitions(request):
+    """Get definitions for patterns currently available on the driver."""
+    definitions = build_runtime_pattern_map()
+    return json.dumps(definitions), 200, {'Content-Type': 'application/json'}
+
+
+@controller.get('/ota/manifest')
+async def ota_manifest(request):
+    """Manifest of driver pattern source files for OTA pulls."""
+    base_dir = driver_patterns_dir()
+    host = request.headers.get("Host", "")
+    if not host:
+        return json.dumps({"error": "Missing Host header"}), 400, {
+            "Content-Type": "application/json"
+        }
+    try:
+        names = sorted(os.listdir(base_dir))
+    except OSError as e:
+        return json.dumps({"error": str(e)}), 500, {"Content-Type": "application/json"}
+
+    files = []
+    for name in names:
+        if not _safe_pattern_filename(name) or name == "__init__.py":
+            continue
+        files.append({
+            "name": name,
+            "url": "http://%s/patterns/ota/file/%s" % (host, name),
+        })
+
+    return json.dumps({"files": files}), 200, {"Content-Type": "application/json"}
+
+
+@controller.get('/ota/file/<name>')
+async def ota_pattern_file(request, name):
+    """Serve one driver pattern source file for OTA pulls."""
+    fname = normalize_pattern_py_filename(name)
+    if not fname or not _safe_pattern_filename(fname) or fname == "__init__.py":
+        return json.dumps({"error": "Invalid filename"}), 400, {
+            "Content-Type": "application/json"
+        }
+    if is_firmware_builtin_pattern_module(fname):
+        return json.dumps(
+            {
+                "error": "on and off are built into the driver firmware; there is no module file to serve.",
+            }
+        ), 400, {
+            "Content-Type": "application/json"
+        }
+    base = driver_patterns_dir()
+    path = os.path.join(base, fname)
+    try:
+        with open(path, "r") as f:
+            content = f.read()
+    except OSError:
+        return json.dumps(
+            {
+                "error": "Pattern file not found",
+                "path": path,
+                "hint": "Ensure led-driver is present or set LED_CONTROLLER_PATTERNS_DIR.",
+            }
+        ), 404, {
+            "Content-Type": "application/json"
+        }
+    return content, 200, {"Content-Type": "text/plain; charset=utf-8"}
+
+
+@controller.post('/<name>/send')
+async def send_pattern_to_device(request, name):
+    """Push one pattern source file directly to Wi-Fi driver(s) over HTTP."""
+    if not isinstance(name, str):
+        return json.dumps({"error": "Invalid pattern name"}), 400, {
+            "Content-Type": "application/json"
+        }
+    filename = normalize_pattern_py_filename(name)
+    if not filename or not _safe_pattern_filename(filename) or filename == "__init__.py":
+        return json.dumps({"error": "Invalid pattern filename"}), 400, {
+            "Content-Type": "application/json"
+        }
+    if is_firmware_builtin_pattern_module(filename):
+        return json.dumps(
+            {
+                "error": "on and off are built into the driver firmware; send does not apply.",
+            }
+        ), 400, {
+            "Content-Type": "application/json"
+        }
+
+    devices = Device()
+    body = request.json or {}
+    requested_device_id = str(body.get("device_id") or "").strip()
+
+    base = driver_patterns_dir()
+    path = os.path.join(base, filename)
+    if not os.path.exists(path):
+        return json.dumps(
+            {
+                "error": "Pattern file not found",
+                "path": path,
+                "hint": "Ensure led-driver is present or set LED_CONTROLLER_PATTERNS_DIR.",
+            }
+        ), 404, {
+            "Content-Type": "application/json"
+        }
+
+    try:
+        with open(path, "r") as f:
+            source = f.read()
+    except OSError as e:
+        return json.dumps({"error": str(e)}), 500, {"Content-Type": "application/json"}
+    target_ids = []
+    if requested_device_id:
+        dev = devices.read(requested_device_id)
+        if not dev:
+            return json.dumps({"error": "Device not found"}), 404, {
+                "Content-Type": "application/json"
+            }
+        if (dev.get("transport") or "").lower() != "wifi":
+            return json.dumps({"error": "Pattern send is only supported for Wi-Fi devices"}), 400, {
+                "Content-Type": "application/json"
+            }
+        target_ids = [requested_device_id]
+    else:
+        for did in devices.list():
+            dev = devices.read(did) or {}
+            if (dev.get("transport") or "").lower() == "wifi":
+                target_ids.append(str(did))
+        if not target_ids:
+            return json.dumps({"error": "No Wi-Fi devices found"}), 404, {
+                "Content-Type": "application/json"
+            }
+
+    sent_ids = []
+    for did in target_ids:
+        dev = devices.read(did) or {}
+        ip = str(dev.get("address") or "").strip()
+        if not ip:
+            continue
+        ok = _http_post_pattern_source(ip, filename, source, reload_patterns=True, timeout_s=10.0)
+        if ok:
+            sent_ids.append(did)
+
+    if not sent_ids:
+        return json.dumps({"error": "No Wi-Fi drivers accepted pattern upload"}), 503, {
+            "Content-Type": "application/json"
+        }
+    return json.dumps({"message": "Pattern sent", "pattern": filename, "device_ids": sent_ids, "sent_count": len(sent_ids)}), 200, {
+        "Content-Type": "application/json"
+    }
+
+
+@controller.post('/upload')
+async def upload_pattern_file(request):
+    """
+    Upload a pattern source file to led-controller local storage.
+
+    Body JSON:
+      {
+        "name": "sparkle.py" | "sparkle",
+        "code": "class Sparkle: ...",
+        "overwrite": true | false   # optional, default true
+      }
+    """
+    data = request.json or {}
+    raw_name = data.get("name") or data.get("filename")
+    code = data.get("code")
+    overwrite = data.get("overwrite", True)
+    overwrite = bool(overwrite)
+
+    if not isinstance(raw_name, str) or not raw_name.strip():
+        return json.dumps({"error": "name is required"}), 400, {
+            "Content-Type": "application/json"
+        }
+    filename = raw_name.strip()
+    if not filename.endswith(".py"):
+        filename += ".py"
+    if not _safe_pattern_filename(filename) or filename == "__init__.py":
+        return json.dumps({"error": "invalid pattern filename"}), 400, {
+            "Content-Type": "application/json"
+        }
+    if is_firmware_builtin_pattern_module(filename):
+        return json.dumps(
+            {"error": "on and off are built into the driver firmware; use a different pattern name."}
+        ), 400, {
+            "Content-Type": "application/json"
+        }
+    if not isinstance(code, str) or not code.strip():
+        return json.dumps({"error": "code is required"}), 400, {
+            "Content-Type": "application/json"
+        }
+
+    path = os.path.join(driver_patterns_dir(), filename)
+    exists = os.path.exists(path)
+    if exists and not overwrite:
+        return json.dumps({"error": "pattern file already exists", "name": filename}), 409, {
+            "Content-Type": "application/json"
+        }
+
+    try:
+        with open(path, "w") as f:
+            f.write(code)
+    except OSError as e:
+        return json.dumps({"error": str(e)}), 500, {"Content-Type": "application/json"}
+
+    return json.dumps({
+        "message": "Pattern uploaded",
+        "name": filename,
+        "overwrote": bool(exists),
+    }), 201, {"Content-Type": "application/json"}
+
+
+@controller.post('/driver')
+async def create_driver_pattern(request):
+    """
+    Create a driver pattern: save ``.py`` under led-driver/src/patterns and
+    metadata in db/pattern.json (Pattern model).
+
+    Body JSON:
+      name, code (required),
+      min_delay, max_delay, max_colors (optional numbers),
+      n1..n8 (optional string labels),
+      overwrite (optional, default true).
+    """
+    data = request.json or {}
+    key = _normalize_pattern_key(data.get("name") or "")
+    if not _valid_pattern_key(key):
+        return json.dumps({
+            "error": "name must be a valid Python identifier (e.g. sparkle, my_pattern)",
+        }), 400, {"Content-Type": "application/json"}
+    if is_firmware_builtin_pattern_module(key):
+        return json.dumps(
+            {"error": "on and off are built into the driver firmware; use a different pattern name."}
+        ), 400, {
+            "Content-Type": "application/json"
+        }
+
+    code = data.get("code")
+    if not isinstance(code, str) or not code.strip():
+        return json.dumps({"error": "code is required (upload a .py file or paste source)"}), 400, {
+            "Content-Type": "application/json"
+        }
+
+    overwrite = bool(data.get("overwrite", True))
+
+    filename = key + ".py"
+    py_path = os.path.join(driver_patterns_dir(), filename)
+    if os.path.exists(py_path) and not overwrite:
+        return json.dumps({"error": "pattern file already exists", "name": filename}), 409, {
+            "Content-Type": "application/json"
+        }
+
+    meta = {}
+    for fld in ("min_delay", "max_delay", "max_colors"):
+        if fld not in data:
+            continue
+        try:
+            meta[fld] = int(data[fld])
+        except (TypeError, ValueError):
+            return json.dumps({"error": "%s must be an integer" % fld}), 400, {
+                "Content-Type": "application/json"
+            }
+
+    for i in range(1, 9):
+        nk = "n%d" % i
+        if nk not in data:
+            continue
+        lab = data[nk]
+        if lab is None:
+            continue
+        s = str(lab).strip()
+        if s:
+            meta[nk] = s
+
+    try:
+        with open(py_path, "w") as f:
+            f.write(code)
+    except OSError as e:
+        return json.dumps({"error": str(e)}), 500, {"Content-Type": "application/json"}
+
+    if patterns.read(key):
+        patterns.update(key, meta)
+    else:
+        patterns.create(key, meta)
+
+    return json.dumps({
+        "message": "Pattern created",
+        "name": key,
+        "file": filename,
+        "metadata": patterns.read(key),
+    }), 201, {"Content-Type": "application/json"}
+
+
+@controller.get('')
+async def list_patterns(request):
+    """List patterns for UI (DB metadata + local driver additions)."""
+    return json.dumps(build_runtime_pattern_map()), 200, {'Content-Type': 'application/json'}
+
+
+@controller.get('/<id>')
+async def get_pattern(request, id):
+    """Get a specific pattern by ID."""
+    pattern = patterns.read(id)
+    if pattern is not None:
+        return json.dumps(pattern), 200, {'Content-Type': 'application/json'}
+    return json.dumps({"error": "Pattern not found"}), 404
+
+
+@controller.post('')
+async def create_pattern(request):
+    """Create a new pattern."""
+    try:
+        payload = request.json or {}
+        name = payload.get("name", "")
+        pattern_data = payload.get("data", {})
+
+        # IMPORTANT:
+        # `patterns.create()` stores `pattern_data` as the underlying dict value.
+        # If we then call `patterns.update(pattern_id, payload)` with the full
+        # request object, it may assign `payload["data"]` back onto that same
+        # dict object, creating a circular reference (json.dumps fails).
+        pattern_id = patterns.create(name, pattern_data)
+
+        # Only merge "extra" metadata fields (anything except name/data).
+        extra = dict(payload)
+        extra.pop("name", None)
+        extra.pop("data", None)
+        if extra:
+            patterns.update(pattern_id, extra)
+        return json.dumps(patterns.read(pattern_id)), 201, {'Content-Type': 'application/json'}
+    except Exception as e:
+        return json.dumps({"error": str(e)}), 400
+
+
+@controller.put('/<id>')
+async def update_pattern(request, id):
+    """Update an existing pattern."""
+    try:
+        data = request.json
+        if patterns.update(id, data):
+            return json.dumps(patterns.read(id)), 200, {'Content-Type': 'application/json'}
+        return json.dumps({"error": "Pattern not found"}), 404
+    except Exception as e:
+        return json.dumps({"error": str(e)}), 400
+
+
+@controller.delete('/<id>')
+async def delete_pattern(request, id):
+    """Delete a pattern."""
+    if patterns.delete(id):
+        return json.dumps({"message": "Pattern deleted successfully"}), 200
+    return json.dumps({"error": "Pattern not found"}), 404

src/controllers/preset.py

@@ -1,49 +1,322 @@
 from microdot import Microdot
+from microdot.session import with_session
 from models.preset import Preset
+from models.profile import Profile
+from models.device import Device, normalize_mac
+from models.transport import get_current_sender
+from util.driver_delivery import deliver_json_messages, deliver_preset_broadcast_then_per_device
+from util.espnow_message import build_message, build_preset_dict
 import json
 
 controller = Microdot()
 presets = Preset()
+profiles = Profile()
+
+def get_current_profile_id(session=None):
+    """Get the current active profile ID from session or fallback to first."""
+    profile_list = profiles.list()
+    session_profile = None
+    if session is not None:
+        session_profile = session.get('current_profile')
+    if session_profile and session_profile in profile_list:
+        return session_profile
+    if profile_list:
+        return profile_list[0]
+    return None
 
 @controller.get('')
-async def list_presets(request):
+@with_session
-    """List all presets."""
+async def list_presets(request, session):
-    return json.dumps(presets), 200, {'Content-Type': 'application/json'}
+    """List presets for the current profile."""
+    current_profile_id = get_current_profile_id(session)
+    if not current_profile_id:
+        return json.dumps({}), 200, {'Content-Type': 'application/json'}
+    scoped = {
+        pid: pdata for pid, pdata in presets.items()
+        if isinstance(pdata, dict) and str(pdata.get("profile_id")) == str(current_profile_id)
+    }
+    return json.dumps(scoped), 200, {'Content-Type': 'application/json'}
 
-@controller.get('/<id>')
+@controller.get('/<preset_id>')
-async def get_preset(request, id):
+@with_session
-    """Get a specific preset by ID."""
+async def get_preset(request, session, preset_id):
-    preset = presets.read(id)
+    """Get a specific preset by ID (current profile only)."""
-    if preset:
+    preset = presets.read(preset_id)
+    current_profile_id = get_current_profile_id(session)
+    if preset and str(preset.get("profile_id")) == str(current_profile_id):
         return json.dumps(preset), 200, {'Content-Type': 'application/json'}
     return json.dumps({"error": "Preset not found"}), 404
 
 @controller.post('')
-async def create_preset(request):
+@with_session
-    """Create a new preset."""
+async def create_preset(request, session):
+    """Create a new preset for the current profile."""
     try:
-        data = request.json
+        try:
-        preset_id = presets.create()
+            data = request.json or {}
+        except Exception:
+            return json.dumps({"error": "Invalid JSON"}), 400, {'Content-Type': 'application/json'}
+        current_profile_id = get_current_profile_id(session)
+        if not current_profile_id:
+            return json.dumps({"error": "No profile available"}), 404
+        preset_id = presets.create(current_profile_id)
+        if not isinstance(data, dict):
+            data = {}
+        data = dict(data)
+        data["profile_id"] = str(current_profile_id)
         if presets.update(preset_id, data):
-            return json.dumps(presets.read(preset_id)), 201, {'Content-Type': 'application/json'}
+            preset_data = presets.read(preset_id)
+            return json.dumps({preset_id: preset_data}), 201, {'Content-Type': 'application/json'}
         return json.dumps({"error": "Failed to create preset"}), 400
     except Exception as e:
         return json.dumps({"error": str(e)}), 400
 
-@controller.put('/<id>')
+@controller.put('/<preset_id>')
-async def update_preset(request, id):
+@with_session
-    """Update an existing preset."""
+async def update_preset(request, session, preset_id):
+    """Update an existing preset (current profile only)."""
     try:
-        data = request.json
+        preset = presets.read(preset_id)
-        if presets.update(id, data):
+        current_profile_id = get_current_profile_id(session)
-            return json.dumps(presets.read(id)), 200, {'Content-Type': 'application/json'}
+        if not preset or str(preset.get("profile_id")) != str(current_profile_id):
+            return json.dumps({"error": "Preset not found"}), 404
+        try:
+            data = request.json or {}
+        except Exception:
+            return json.dumps({"error": "Invalid JSON"}), 400, {'Content-Type': 'application/json'}
+        if not isinstance(data, dict):
+            data = {}
+        data = dict(data)
+        data["profile_id"] = str(current_profile_id)
+        if presets.update(preset_id, data):
+            return json.dumps(presets.read(preset_id)), 200, {'Content-Type': 'application/json'}
         return json.dumps({"error": "Preset not found"}), 404
     except Exception as e:
         return json.dumps({"error": str(e)}), 400
 
-@controller.delete('/<id>')
+@controller.delete('/<preset_id>')
-async def delete_preset(request, id):
+@with_session
-    """Delete a preset."""
+async def delete_preset(request, *args, **kwargs):
-    if presets.delete(id):
+    """Delete a preset (current profile only)."""
+    # Be tolerant of wrapper/arg-order variations.
+    session = None
+    preset_id = None
+    if len(args) > 0:
+        session = args[0]
+    if len(args) > 1:
+        preset_id = args[1]
+    if 'session' in kwargs and kwargs.get('session') is not None:
+        session = kwargs.get('session')
+    if 'preset_id' in kwargs and kwargs.get('preset_id') is not None:
+        preset_id = kwargs.get('preset_id')
+    if 'id' in kwargs and kwargs.get('id') is not None and preset_id is None:
+        preset_id = kwargs.get('id')
+    if preset_id is None:
+        return json.dumps({"error": "Preset ID is required"}), 400
+    preset = presets.read(preset_id)
+    current_profile_id = get_current_profile_id(session)
+    if not preset or str(preset.get("profile_id")) != str(current_profile_id):
+        return json.dumps({"error": "Preset not found"}), 404
+    if presets.delete(preset_id):
         return json.dumps({"message": "Preset deleted successfully"}), 200
     return json.dumps({"error": "Preset not found"}), 404
+
+
+@controller.post('/send')
+@with_session
+async def send_presets(request, session):
+    """
+    Send one or more presets to LED drivers (serial/ESP-NOW and/or TCP Wi-Fi clients).
+
+    Body JSON:
+        {"preset_ids": ["1", "2", ...]}  or  {"ids": ["1", "2", ...]}
+        Optional "targets": ["aabbccddeeff", ...] — registry MACs. When set: preset
+        chunks are ESP-NOW broadcast once each; Wi-Fi drivers get the same chunks
+        over TCP; if "default" is set, each target then gets a unicast default
+        message (serial or TCP) with that device name in "targets".
+        Omit targets for broadcast-only serial (legacy).
+
+    Optional "destination_mac" / "to": single MAC when targets is omitted.
+    """
+    try:
+        data = request.json or {}
+    except Exception:
+        return json.dumps({"error": "Invalid JSON"}), 400, {'Content-Type': 'application/json'}
+
+    preset_ids = data.get('preset_ids') or data.get('ids')
+    if not isinstance(preset_ids, list) or not preset_ids:
+        return json.dumps({"error": "preset_ids must be a non-empty list"}), 400, {'Content-Type': 'application/json'}
+    save_flag = data.get('save', True)
+    save_flag = bool(save_flag)
+    default_id = data.get('default')
+    destination_mac = data.get('destination_mac') or data.get('to')
+
+    # Build API-compliant preset map keyed by preset ID, include name
+    current_profile_id = get_current_profile_id(session)
+    presets_by_name = {}
+    for pid in preset_ids:
+        preset_data = presets.read(str(pid))
+        if not preset_data:
+            continue
+        if str(preset_data.get("profile_id")) != str(current_profile_id):
+            continue
+        preset_key = str(pid)
+        preset_payload = build_preset_dict(preset_data)
+        preset_payload["name"] = preset_data.get("name", "")
+        presets_by_name[preset_key] = preset_payload
+
+    if not presets_by_name:
+        return json.dumps({"error": "No matching presets found"}), 404, {'Content-Type': 'application/json'}
+
+    if default_id is not None and str(default_id) not in presets_by_name:
+        default_id = None
+
+    sender = get_current_sender()
+    if not sender:
+        return json.dumps({"error": "Transport not configured"}), 503, {'Content-Type': 'application/json'}
+
+    MAX_BYTES = 240
+    send_delay_s = 0.1
+    entries = list(presets_by_name.items())
+    total_presets = len(entries)
+
+    batch = {}
+    chunk_messages = []
+    for name, preset_obj in entries:
+        test_batch = dict(batch)
+        test_batch[name] = preset_obj
+        test_msg = build_message(presets=test_batch, save=save_flag, default=default_id)
+        size = len(test_msg)
+
+        if size <= MAX_BYTES or not batch:
+            batch = test_batch
+        else:
+            chunk_messages.append(
+                build_message(
+                    presets=dict(batch),
+                    save=False,
+                    default=None,
+                )
+            )
+            batch = {name: preset_obj}
+
+    if batch:
+        chunk_messages.append(
+            build_message(
+                presets=dict(batch),
+                save=save_flag,
+                default=default_id,
+            )
+        )
+
+    target_list = None
+    raw_targets = data.get("targets")
+    if isinstance(raw_targets, list) and raw_targets:
+        target_list = []
+        for t in raw_targets:
+            m = normalize_mac(str(t))
+            if m:
+                target_list.append(m)
+        target_list = list(dict.fromkeys(target_list))
+        if not target_list:
+            target_list = None
+    elif destination_mac:
+        dm = normalize_mac(str(destination_mac))
+        target_list = [dm] if dm else None
+
+    try:
+        if target_list:
+            deliveries = await deliver_preset_broadcast_then_per_device(
+                sender,
+                chunk_messages,
+                target_list,
+                Device(),
+                str(default_id) if default_id is not None else None,
+                delay_s=send_delay_s,
+            )
+        else:
+            deliveries, _chunks = await deliver_json_messages(
+                sender,
+                chunk_messages,
+                None,
+                Device(),
+                delay_s=send_delay_s,
+            )
+    except Exception:
+        return json.dumps({"error": "Send failed"}), 503, {'Content-Type': 'application/json'}
+
+    return json.dumps({
+        "message": "Presets sent",
+        "presets_sent": total_presets,
+        "messages_sent": deliveries,
+    }), 200, {'Content-Type': 'application/json'}
+
+
+@controller.post('/push')
+@with_session
+async def push_driver_messages(request, session):
+    """
+    Deliver one or more raw v1 JSON objects to devices (ESP-NOW and/or TCP).
+
+    Body:
+        {"sequence": [{ "v": "1", ... }, ...], "targets": ["mac", ...]}
+    or a single {"payload": {...}, "targets": [...]}.
+    """
+    try:
+        data = request.json or {}
+    except Exception:
+        return json.dumps({"error": "Invalid JSON"}), 400, {'Content-Type': 'application/json'}
+
+    seq = data.get("sequence")
+    if not seq and data.get("payload") is not None:
+        seq = [data["payload"]]
+    if not isinstance(seq, list) or not seq:
+        return json.dumps({"error": "sequence or payload required"}), 400, {'Content-Type': 'application/json'}
+
+    raw_targets = data.get("targets")
+    target_list = None
+    if isinstance(raw_targets, list) and raw_targets:
+        target_list = []
+        for t in raw_targets:
+            m = normalize_mac(str(t))
+            if m:
+                target_list.append(m)
+        target_list = list(dict.fromkeys(target_list))
+        if not target_list:
+            target_list = None
+
+    sender = get_current_sender()
+    if not sender:
+        return json.dumps({"error": "Transport not configured"}), 503, {'Content-Type': 'application/json'}
+
+    messages = []
+    for item in seq:
+        if isinstance(item, dict):
+            messages.append(json.dumps(item))
+        elif isinstance(item, str):
+            messages.append(item)
+        else:
+            return json.dumps({"error": "sequence items must be objects or strings"}), 400, {'Content-Type': 'application/json'}
+
+    delay_s = data.get("delay_s", 0.05)
+    try:
+        delay_s = float(delay_s)
+    except (TypeError, ValueError):
+        delay_s = 0.05
+
+    try:
+        deliveries, _chunks = await deliver_json_messages(
+            sender,
+            messages,
+            target_list,
+            Device(),
+            delay_s=delay_s,
+        )
+    except Exception:
+        return json.dumps({"error": "Send failed"}), 503, {'Content-Type': 'application/json'}
+
+    return json.dumps({
+        "message": "Delivered",
+        "deliveries": deliveries,
+    }), 200, {'Content-Type': 'application/json'}
+

src/controllers/profile.py

@@ -1,33 +1,373 @@
 from microdot import Microdot
+from microdot.session import with_session
 from models.profile import Profile
+from models.zone import Zone
+from models.preset import Preset
 import json
 
 controller = Microdot()
 profiles = Profile()
+zones = Zone()
+presets = Preset()
 
 @controller.get('')
-async def list_profiles(request):
+@with_session
-    """List all profiles."""
+async def list_profiles(request, session):
-    return json.dumps(profiles), 200, {'Content-Type': 'application/json'}
+    """List all profiles with current profile info."""
+    profile_list = profiles.list()
+    current_id = session.get('current_profile')
+    if current_id and current_id not in profile_list:
+        current_id = None
+    
+    # If no current profile in session, use first one
+    if not current_id and profile_list:
+        current_id = profile_list[0]
+        session['current_profile'] = str(current_id)
+        session.save()
+    
+    # Build profiles object
+    profiles_data = {}
+    for profile_id in profile_list:
+        profile_data = profiles.read(profile_id)
+        if profile_data:
+            profiles_data[profile_id] = profile_data
+    
+    return json.dumps({
+        "profiles": profiles_data,
+        "current_profile_id": current_id
+    }), 200, {'Content-Type': 'application/json'}
+
+@controller.get('/current')
+@with_session
+async def get_current_profile(request, session):
+    """Get the current profile ID from session (or fallback)."""
+    profile_list = profiles.list()
+    current_id = session.get('current_profile')
+    if current_id and current_id not in profile_list:
+        current_id = None
+    if not current_id and profile_list:
+        current_id = profile_list[0]
+        session['current_profile'] = str(current_id)
+        session.save()
+    if current_id:
+        profile = profiles.read(current_id)
+        return json.dumps({"id": current_id, "profile": profile}), 200, {'Content-Type': 'application/json'}
+    return json.dumps({"error": "No profile available"}), 404
 
 @controller.get('/<id>')
-async def get_profile(request, id):
+@with_session
+async def get_profile(request, id, session):
     """Get a specific profile by ID."""
+    # Handle 'current' as a special case
+    if id == 'current':
+        return await get_current_profile(request, session)
+    
     profile = profiles.read(id)
     if profile:
         return json.dumps(profile), 200, {'Content-Type': 'application/json'}
     return json.dumps({"error": "Profile not found"}), 404
 
+@controller.post('/<id>/apply')
+@with_session
+async def apply_profile(request, session, id):
+    """Apply a profile by saving it to session."""
+    if not profiles.read(id):
+        return json.dumps({"error": "Profile not found"}), 404
+    session['current_profile'] = str(id)
+    session.save()
+    return json.dumps({"message": "Profile applied", "id": str(id)}), 200, {'Content-Type': 'application/json'}
+
 @controller.post('')
 async def create_profile(request):
     """Create a new profile."""
     try:
-        data = request.json or {}
+        data = dict(request.json or {})
         name = data.get("name", "")
+        seed_raw = data.get("seed_dj_zone", False)
+        if isinstance(seed_raw, str):
+            seed_dj_zone = seed_raw.strip().lower() in ("1", "true", "yes", "on")
+        else:
+            seed_dj_zone = bool(seed_raw)
+        # Request-only flag: do not persist on profile records.
+        data.pop("seed_dj_zone", None)
         profile_id = profiles.create(name)
+        # Avoid persisting request-only fields.
+        data.pop("name", None)
         if data:
             profiles.update(profile_id, data)
-        return json.dumps(profiles.read(profile_id)), 201, {'Content-Type': 'application/json'}
+
+        # New profiles always start with a default zone pre-populated with starter presets.
+        default_preset_ids = []
+        default_preset_defs = [
+            {
+                "name": "on",
+                "pattern": "on",
+                "colors": ["#FFFFFF"],
+                "brightness": 255,
+                "delay": 100,
+                "auto": True,
+            },
+            {
+                "name": "off",
+                "pattern": "off",
+                "colors": [],
+                "brightness": 0,
+                "delay": 100,
+                "auto": True,
+            },
+            {
+                "name": "rainbow",
+                "pattern": "rainbow",
+                "colors": [],
+                "brightness": 255,
+                "delay": 100,
+                "auto": True,
+                "n1": 2,
+            },
+            {
+                "name": "Colour Cycle",
+                "pattern": "colour_cycle",
+                "colors": ["#FF0000", "#00FF00", "#0000FF"],
+                "brightness": 255,
+                "delay": 100,
+                "auto": True,
+                "n1": 1,
+            },
+            {
+                "name": "transition",
+                "pattern": "transition",
+                "colors": ["#FF0000", "#00FF00", "#0000FF"],
+                "brightness": 255,
+                "delay": 500,
+                "auto": True,
+            },
+            {
+                "name": "flicker",
+                "pattern": "flicker",
+                "colors": ["#FFB84D"],
+                "brightness": 255,
+                "delay": 80,
+                "auto": True,
+                "n1": 30,
+            },
+            {
+                "name": "flame",
+                "pattern": "flame",
+                "colors": [],
+                "brightness": 255,
+                "delay": 50,
+                "auto": True,
+                "n1": 35,
+                "n2": 2600,
+                "n3": 0,
+                "n4": 0,
+            },
+            {
+                "name": "twinkle",
+                "pattern": "twinkle",
+                "colors": ["#78C8FF", "#508CFF", "#B478FF", "#64DCE8", "#A0C8FF"],
+                "brightness": 255,
+                "delay": 55,
+                "auto": True,
+                "n1": 72,
+                "n2": 140,
+                "n3": 2,
+                "n4": 6,
+            },
+        ]
+
+        for preset_data in default_preset_defs:
+            pid = presets.create(profile_id)
+            presets.update(pid, preset_data)
+            default_preset_ids.append(str(pid))
+
+        default_tab_id = zones.create(name="default", names=["1"], presets=[default_preset_ids])
+        zones.update(default_tab_id, {
+            "presets_flat": default_preset_ids,
+            "default_preset": default_preset_ids[0] if default_preset_ids else None,
+        })
+
+        profile = profiles.read(profile_id) or {}
+        profile_tabs = profile.get("zones", []) if isinstance(profile.get("zones", []), list) else []
+        profile_tabs.append(str(default_tab_id))
+
+        if seed_dj_zone:
+            # Seed a DJ-focused zone with three starter presets.
+            seeded_preset_ids = []
+            preset_defs = [
+                {
+                    "name": "DJ Rainbow",
+                    "pattern": "rainbow",
+                    "colors": [],
+                    "brightness": 220,
+                    "delay": 60,
+                    "n1": 12,
+                },
+                {
+                    "name": "DJ Single Color",
+                    "pattern": "on",
+                    "colors": ["#ff00ff"],
+                    "brightness": 220,
+                    "delay": 100,
+                },
+                {
+                    "name": "DJ Transition",
+                    "pattern": "transition",
+                    "colors": ["#ff0000", "#00ff00", "#0000ff"],
+                    "brightness": 220,
+                    "delay": 250,
+                },
+            ]
+
+            for preset_data in preset_defs:
+                pid = presets.create(profile_id)
+                presets.update(pid, preset_data)
+                seeded_preset_ids.append(str(pid))
+
+            dj_tab_id = zones.create(name="dj", names=["dj"], presets=[seeded_preset_ids])
+            zones.update(dj_tab_id, {
+                "presets_flat": seeded_preset_ids,
+                "default_preset": seeded_preset_ids[0] if seeded_preset_ids else None,
+            })
+
+            profile_tabs.append(str(dj_tab_id))
+
+        profiles.update(profile_id, {"zones": profile_tabs})
+
+        profile_data = profiles.read(profile_id)
+        return json.dumps({profile_id: profile_data}), 201, {'Content-Type': 'application/json'}
+    except Exception as e:
+        return json.dumps({"error": str(e)}), 400
+
+@controller.post('/<id>/clone')
+async def clone_profile(request, id):
+    """Clone an existing profile along with its tabs and palette."""
+    try:
+        source = profiles.read(id)
+        if not source:
+            return json.dumps({"error": "Profile not found"}), 404
+
+        data = request.json or {}
+        source_name = source.get("name") or f"Profile {id}"
+        new_name = data.get("name") or source_name
+        profile_type = source.get("type", "zones")
+
+        def allocate_id(model, cache):
+            if "next" not in cache:
+                max_id = max((int(k) for k in model.keys() if str(k).isdigit()), default=0)
+                cache["next"] = max_id + 1
+            next_id = str(cache["next"])
+            cache["next"] += 1
+            return next_id
+
+        def map_preset_container(value, id_map, preset_cache, new_profile_id, new_presets):
+            if isinstance(value, list):
+                return [map_preset_container(v, id_map, preset_cache, new_profile_id, new_presets) for v in value]
+            if value is None:
+                return None
+            preset_id = str(value)
+            if preset_id in id_map:
+                return id_map[preset_id]
+            preset_data = presets.read(preset_id)
+            if not preset_data:
+                return None
+            new_preset_id = allocate_id(presets, preset_cache)
+            clone_data = dict(preset_data)
+            clone_data["profile_id"] = str(new_profile_id)
+            new_presets[new_preset_id] = clone_data
+            id_map[preset_id] = new_preset_id
+            return new_preset_id
+
+        # Prepare new IDs without writing until everything is ready.
+        profile_cache = {}
+        palette_cache = {}
+        tab_cache = {}
+        preset_cache = {}
+
+        new_profile_id = allocate_id(profiles, profile_cache)
+        new_palette_id = allocate_id(profiles._palette_model, palette_cache)
+
+        # Clone palette colors into the new profile's palette
+        src_palette_id = source.get("palette_id")
+        palette_colors = []
+        if src_palette_id:
+            try:
+                palette_colors = profiles._palette_model.read(src_palette_id)
+            except Exception:
+                palette_colors = []
+
+        # Clone tabs and presets used by those tabs
+        source_tabs = source.get("zones")
+        if not isinstance(source_tabs, list) or len(source_tabs) == 0:
+            source_tabs = source.get("zone_order", [])
+        source_tabs = source_tabs or []
+        cloned_tab_ids = []
+        preset_id_map = {}
+        new_tabs = {}
+        new_presets = {}
+        for zone_id in source_tabs:
+            zone = zones.read(zone_id)
+            if not zone:
+                continue
+            tab_name = zone.get("name") or f"Zone {zone_id}"
+            clone_name = tab_name
+            mapped_presets = map_preset_container(zone.get("presets"), preset_id_map, preset_cache, new_profile_id, new_presets)
+            clone_id = allocate_id(zones, tab_cache)
+            clone_data = {
+                "name": clone_name,
+                "names": zone.get("names") or [],
+                "presets": mapped_presets if mapped_presets is not None else []
+            }
+            extra = {k: v for k, v in zone.items() if k not in ("name", "names", "presets")}
+            if "presets_flat" in extra:
+                extra["presets_flat"] = map_preset_container(extra.get("presets_flat"), preset_id_map, preset_cache, new_profile_id, new_presets)
+            if extra:
+                clone_data.update(extra)
+            new_tabs[clone_id] = clone_data
+            cloned_tab_ids.append(clone_id)
+
+        new_profile_data = {
+            "name": new_name,
+            "type": profile_type,
+            "zones": cloned_tab_ids,
+            "scenes": list(source.get("scenes", [])) if isinstance(source.get("scenes", []), list) else [],
+            "palette_id": str(new_palette_id),
+        }
+
+        # Commit all changes and save once per model.
+        profiles._palette_model[str(new_palette_id)] = list(palette_colors) if palette_colors else []
+        for pid, pdata in new_presets.items():
+            presets[pid] = pdata
+        for tid, tdata in new_tabs.items():
+            zones[tid] = tdata
+        profiles[str(new_profile_id)] = new_profile_data
+
+        profiles._palette_model.save()
+        presets.save()
+        zones.save()
+        profiles.save()
+
+        return json.dumps({new_profile_id: new_profile_data}), 201, {'Content-Type': 'application/json'}
+    except Exception as e:
+        return json.dumps({"error": str(e)}), 400
+
+@controller.put('/current')
+@with_session
+async def update_current_profile(request, session):
+    """Update the current profile using session (or fallback)."""
+    try:
+        data = request.json or {}
+        profile_list = profiles.list()
+        current_id = session.get('current_profile')
+        if not current_id and profile_list:
+            current_id = profile_list[0]
+            session['current_profile'] = str(current_id)
+            session.save()
+        if not current_id:
+            return json.dumps({"error": "No profile available"}), 404
+        if profiles.update(current_id, data):
+            return json.dumps(profiles.read(current_id)), 200, {'Content-Type': 'application/json'}
+        return json.dumps({"error": "Profile not found"}), 404
     except Exception as e:
         return json.dumps({"error": str(e)}), 400
 

src/controllers/scene.py

@@ -0,0 +1,49 @@
+from microdot import Microdot
+from models.scene import Scene
+import json
+
+controller = Microdot()
+scenes = Scene()
+
+@controller.get('')
+async def list_scenes(request):
+    """List all scenes."""
+    return json.dumps(scenes), 200, {'Content-Type': 'application/json'}
+
+@controller.get('/<id>')
+async def get_scene(request, id):
+    """Get a specific scene by ID."""
+    scene = scenes.read(id)
+    if scene:
+        return json.dumps(scene), 200, {'Content-Type': 'application/json'}
+    return json.dumps({"error": "Scene not found"}), 404
+
+@controller.post('')
+async def create_scene(request):
+    """Create a new scene."""
+    try:
+        data = request.json
+        scene_id = scenes.create()
+        if scenes.update(scene_id, data):
+            return json.dumps(scenes.read(scene_id)), 201, {'Content-Type': 'application/json'}
+        return json.dumps({"error": "Failed to create scene"}), 400
+    except Exception as e:
+        return json.dumps({"error": str(e)}), 400
+
+@controller.put('/<id>')
+async def update_scene(request, id):
+    """Update an existing scene."""
+    try:
+        data = request.json
+        if scenes.update(id, data):
+            return json.dumps(scenes.read(id)), 200, {'Content-Type': 'application/json'}
+        return json.dumps({"error": "Scene not found"}), 404
+    except Exception as e:
+        return json.dumps({"error": str(e)}), 400
+
+@controller.delete('/<id>')
+async def delete_scene(request, id):
+    """Delete a scene."""
+    if scenes.delete(id):
+        return json.dumps({"message": "Scene deleted successfully"}), 200
+    return json.dumps({"error": "Scene not found"}), 404

src/controllers/settings.py

@@ -0,0 +1,87 @@
+from microdot import Microdot, send_file
+from settings import Settings
+import json
+
+controller = Microdot()
+settings = Settings()
+
+@controller.get('')
+async def get_settings(request):
+    """Get all settings."""
+    # Settings is already a dict subclass; avoid dict() wrapper which can
+    # trigger MicroPython's "dict update sequence has wrong length" quirk.
+    return json.dumps(settings), 200, {'Content-Type': 'application/json'}
+
+@controller.get('/wifi/ap')
+async def get_ap_config(request):
+    """Get saved AP configuration (Pi: no in-device AP)."""
+    config = {
+        'saved_ssid': settings.get('wifi_ap_ssid'),
+        'saved_password': settings.get('wifi_ap_password'),
+        'saved_channel': settings.get('wifi_ap_channel'),
+        'active': False,
+    }
+    return json.dumps(config), 200, {'Content-Type': 'application/json'}
+
+@controller.post('/wifi/ap')
+async def configure_ap(request):
+    """Save AP configuration to settings (Pi: no in-device AP)."""
+    try:
+        data = request.json
+        ssid = data.get('ssid')
+        password = data.get('password', '')
+        channel = data.get('channel')
+        
+        if not ssid:
+            return json.dumps({"error": "SSID is required"}), 400
+        
+        # Validate channel (1-11 for 2.4GHz)
+        if channel is not None:
+            channel = int(channel)
+            if channel < 1 or channel > 11:
+                return json.dumps({"error": "Channel must be between 1 and 11"}), 400
+        
+        settings['wifi_ap_ssid'] = ssid
+        settings['wifi_ap_password'] = password
+        if channel is not None:
+            settings['wifi_ap_channel'] = channel
+        settings.save()
+        
+        return json.dumps({
+            "message": "AP settings saved",
+            "ssid": ssid,
+            "channel": channel
+        }), 200, {'Content-Type': 'application/json'}
+    except Exception as e:
+        return json.dumps({"error": str(e)}), 500
+
+def _validate_wifi_channel(value):
+    """Return int 1–11 or raise ValueError."""
+    ch = int(value)
+    if ch < 1 or ch > 11:
+        raise ValueError("wifi_channel must be between 1 and 11")
+    return ch
+
+
+@controller.put('/settings')
+async def update_settings(request):
+    """Update general settings."""
+    try:
+        data = request.json
+        for key, value in data.items():
+            if key == 'wifi_channel' and value is not None:
+                settings[key] = _validate_wifi_channel(value)
+            else:
+                settings[key] = value
+        settings.save()
+        return json.dumps({"message": "Settings updated successfully"}), 200, {'Content-Type': 'application/json'}
+    except ValueError as e:
+        return json.dumps({"error": str(e)}), 400
+    except Exception as e:
+        return json.dumps({"error": str(e)}), 500
+
+@controller.get('/page')
+async def settings_page(request):
+    """Serve the settings page."""
+    return send_file('templates/settings.html')
+

src/controllers/tab.py

@@ -1,52 +0,0 @@
-from microdot import Microdot
-from models.tab import Tab
-import json
-
-controller = Microdot()
-tabs = Tab()
-
-@controller.get('')
-async def list_tabs(request):
-    """List all tabs."""
-    return json.dumps(tabs), 200, {'Content-Type': 'application/json'}
-
-@controller.get('/<id>')
-async def get_tab(request, id):
-    """Get a specific tab by ID."""
-    tab = tabs.read(id)
-    if tab:
-        return json.dumps(tab), 200, {'Content-Type': 'application/json'}
-    return json.dumps({"error": "Tab not found"}), 404
-
-@controller.post('')
-async def create_tab(request):
-    """Create a new tab."""
-    try:
-        data = request.json or {}
-        name = data.get("name", "")
-        names = data.get("names", None)
-        preset_ids = data.get("presets", None)
-        tab_id = tabs.create(name, names, preset_ids)
-        if data:
-            tabs.update(tab_id, data)
-        return json.dumps(tabs.read(tab_id)), 201, {'Content-Type': 'application/json'}
-    except Exception as e:
-        return json.dumps({"error": str(e)}), 400
-
-@controller.put('/<id>')
-async def update_tab(request, id):
-    """Update an existing tab."""
-    try:
-        data = request.json
-        if tabs.update(id, data):
-            return json.dumps(tabs.read(id)), 200, {'Content-Type': 'application/json'}
-        return json.dumps({"error": "Tab not found"}), 404
-    except Exception as e:
-        return json.dumps({"error": str(e)}), 400
-
-@controller.delete('/<id>')
-async def delete_tab(request, id):
-    """Delete a tab."""
-    if tabs.delete(id):
-        return json.dumps({"message": "Tab deleted successfully"}), 200
-    return json.dumps({"error": "Tab not found"}), 404

src/controllers/zone.py

@@ -0,0 +1,361 @@
+from microdot import Microdot, send_file
+from microdot.session import with_session
+from models.zone import Zone
+from models.profile import Profile
+import json
+
+controller = Microdot()
+zones = Zone()
+profiles = Profile()
+
+
+def get_current_profile_id(session=None):
+    """Get the current active profile ID from session or fallback to first."""
+    profile_list = profiles.list()
+    session_profile = None
+    if session is not None:
+        session_profile = session.get("current_profile")
+    if session_profile and session_profile in profile_list:
+        return session_profile
+    if profile_list:
+        return profile_list[0]
+    return None
+
+
+def _profile_zone_id_list(profile):
+    """Ordered zone ids for a profile (``zones``, legacy ``tabs``, or ``zone_order``)."""
+    if not profile or not isinstance(profile, dict):
+        return []
+    z = profile.get("zones")
+    if isinstance(z, list) and z:
+        return list(z)
+    t = profile.get("zones")
+    if isinstance(t, list) and t:
+        return list(t)
+    o = profile.get("zone_order")
+    if isinstance(o, list) and o:
+        return list(o)
+    return []
+
+
+def get_profile_zone_order(profile_id):
+    if not profile_id:
+        return []
+    profile = profiles.read(profile_id)
+    return _profile_zone_id_list(profile)
+
+
+def _set_profile_zone_order(profile, ids):
+    profile["zones"] = list(ids)
+    profile.pop("tabs", None)
+    profile.pop("zone_order", None)
+
+
+def get_current_zone_id(request, session=None):
+    """Cookie ``current_zone``, legacy ``current_zone``, then first zone in profile."""
+    z = request.cookies.get("current_zone") or request.cookies.get("current_zone")
+    if z:
+        return z
+    profile_id = get_current_profile_id(session)
+    if profile_id:
+        profile = profiles.read(profile_id)
+        order = _profile_zone_id_list(profile)
+        if order:
+            return order[0]
+    return None
+
+
+def _render_zones_list_fragment(request, session):
+    """Render zone strip HTML for HTMX / JS."""
+    profile_id = get_current_profile_id(session)
+    if not profile_id:
+        return (
+            '<div class="zones-list">No profile selected</div>',
+            200,
+            {"Content-Type": "text/html"},
+        )
+
+    zone_order = get_profile_zone_order(profile_id)
+    current_zone_id = get_current_zone_id(request, session)
+
+    html = '<div class="zones-list">'
+    for zid in zone_order:
+        zdata = zones.read(zid)
+        if zdata:
+            active_class = "active" if str(zid) == str(current_zone_id) else ""
+            zname = zdata.get("name", "Zone " + str(zid))
+            html += (
+                '<button class="zone-button ' + active_class + '" '
+                'hx-get="/zones/' + str(zid) + '/content-fragment" '
+                'hx-target="#zone-content" '
+                'hx-swap="innerHTML" '
+                'hx-push-url="true" '
+                'hx-trigger="click" '
+                'onclick="document.querySelectorAll(\'.zone-button\').forEach(b => b.classList.remove(\'active\')); this.classList.add(\'active\');">'
+                + zname
+                + "</button>"
+            )
+    html += "</div>"
+    return html, 200, {"Content-Type": "text/html"}
+
+
+def _render_zone_content_fragment(request, session, id):
+    if id == "current":
+        current_zone_id = get_current_zone_id(request, session)
+        if not current_zone_id:
+            accept_header = request.headers.get("Accept", "")
+            wants_html = "text/html" in accept_header
+            if wants_html:
+                return (
+                    '<div class="error">No current zone set</div>',
+                    404,
+                    {"Content-Type": "text/html"},
+                )
+            return json.dumps({"error": "No current zone set"}), 404
+        id = current_zone_id
+
+    z = zones.read(id)
+    if not z:
+        return '<div>Zone not found</div>', 404, {"Content-Type": "text/html"}
+
+    session["current_zone"] = str(id)
+    session.save()
+
+    if not request.headers.get("HX-Request"):
+        return send_file("templates/index.html")
+
+    html = (
+        '<div class="presets-section" data-zone-id="' + str(id) + '">'
+        "<h3>Presets</h3>"
+        '<div class="profiles-actions" style="margin-bottom: 1rem;"></div>'
+        '<div id="presets-list-zone" class="presets-list">'
+        "<!-- Presets will be loaded here -->"
+        "</div>"
+        "</div>"
+    )
+    return html, 200, {"Content-Type": "text/html"}
+
+
+@controller.get("/<id>/content-fragment")
+@with_session
+async def zone_content_fragment(request, session, id):
+    return _render_zone_content_fragment(request, session, id)
+
+
+@controller.get("")
+@with_session
+async def list_zones(request, session):
+    profile_id = get_current_profile_id(session)
+    current_zone_id = get_current_zone_id(request, session)
+    zone_order = get_profile_zone_order(profile_id) if profile_id else []
+
+    zones_data = {}
+    for zid in zones.list():
+        zdata = zones.read(zid)
+        if zdata:
+            zones_data[zid] = zdata
+
+    return (
+        json.dumps(
+            {
+                "zones": zones_data,
+                "zone_order": zone_order,
+                "current_zone_id": current_zone_id,
+                "profile_id": profile_id,
+            }
+        ),
+        200,
+        {"Content-Type": "application/json"},
+    )
+
+
+@controller.get("/current")
+@with_session
+async def get_current_zone(request, session):
+    current_zone_id = get_current_zone_id(request, session)
+    if not current_zone_id:
+        return (
+            json.dumps({"error": "No current zone set", "zone": None, "zone_id": None}),
+            404,
+        )
+
+    z = zones.read(current_zone_id)
+    if z:
+        return (
+            json.dumps({"zone": z, "zone_id": current_zone_id}),
+            200,
+            {"Content-Type": "application/json"},
+        )
+    return (
+        json.dumps({"error": "Zone not found", "zone": None, "zone_id": None}),
+        404,
+    )
+
+
+@controller.post("/<id>/set-current")
+async def set_current_zone(request, id):
+    z = zones.read(id)
+    if not z:
+        return json.dumps({"error": "Zone not found"}), 404
+
+    response_data = json.dumps({"message": "Current zone set", "zone_id": id})
+    return (
+        response_data,
+        200,
+        {
+            "Content-Type": "application/json",
+            "Set-Cookie": (
+                f"current_zone={id}; Path=/; Max-Age=31536000; SameSite=Lax"
+            ),
+        },
+    )
+
+
+@controller.get("/<id>")
+async def get_zone(request, id):
+    z = zones.read(id)
+    if z:
+        return json.dumps(z), 200, {"Content-Type": "application/json"}
+    return json.dumps({"error": "Zone not found"}), 404
+
+
+@controller.put("/<id>")
+async def update_zone(request, id):
+    try:
+        data = request.json
+        if zones.update(id, data):
+            return json.dumps(zones.read(id)), 200, {"Content-Type": "application/json"}
+        return json.dumps({"error": "Zone not found"}), 404
+    except Exception as e:
+        return json.dumps({"error": str(e)}), 400
+
+
+@controller.delete("/<id>")
+@with_session
+async def delete_zone(request, session, id):
+    try:
+        if id == "current":
+            current_zone_id = get_current_zone_id(request, session)
+            if current_zone_id:
+                id = current_zone_id
+            else:
+                return json.dumps({"error": "No current zone to delete"}), 404
+
+        if zones.delete(id):
+            profile_id = get_current_profile_id(session)
+            if profile_id:
+                profile = profiles.read(profile_id)
+                if profile:
+                    zlist = _profile_zone_id_list(profile)
+                    if id in zlist:
+                        zlist.remove(id)
+                        _set_profile_zone_order(profile, zlist)
+                        profiles.update(profile_id, profile)
+
+            current_zone_id = get_current_zone_id(request, session)
+            if current_zone_id == id:
+                response_data = json.dumps({"message": "Zone deleted successfully"})
+                return (
+                    response_data,
+                    200,
+                    {
+                        "Content-Type": "application/json",
+                        "Set-Cookie": (
+                            "current_zone=; Path=/; Max-Age=0; SameSite=Lax"
+                        ),
+                    },
+                )
+
+            return json.dumps({"message": "Zone deleted successfully"}), 200, {
+                "Content-Type": "application/json"
+            }
+
+        return json.dumps({"error": "Zone not found"}), 404
+    except Exception as e:
+        import sys
+
+        try:
+            sys.print_exception(e)
+        except Exception:
+            pass
+        return json.dumps({"error": str(e)}), 500, {"Content-Type": "application/json"}
+
+
+@controller.post("")
+@with_session
+async def create_zone(request, session):
+    try:
+        if request.form:
+            name = request.form.get("name", "").strip()
+            ids_str = request.form.get("ids", "1").strip()
+            names = [i.strip() for i in ids_str.split(",") if i.strip()]
+            preset_ids = None
+        else:
+            data = request.json or {}
+            name = data.get("name", "")
+            names = data.get("names")
+            if names is None:
+                names = data.get("ids")
+            preset_ids = data.get("presets", None)
+
+        if not name:
+            return json.dumps({"error": "Zone name cannot be empty"}), 400
+
+        zid = zones.create(name, names, preset_ids)
+
+        profile_id = get_current_profile_id(session)
+        if profile_id:
+            profile = profiles.read(profile_id)
+            if profile:
+                zlist = _profile_zone_id_list(profile)
+                if zid not in zlist:
+                    zlist.append(zid)
+                    _set_profile_zone_order(profile, zlist)
+                    profiles.update(profile_id, profile)
+
+        zdata = zones.read(zid)
+        return json.dumps({zid: zdata}), 201, {"Content-Type": "application/json"}
+    except Exception as e:
+        import sys
+
+        sys.print_exception(e)
+        return json.dumps({"error": str(e)}), 400
+
+
+@controller.post("/<id>/clone")
+@with_session
+async def clone_zone(request, session, id):
+    try:
+        source = zones.read(id)
+        if not source:
+            return json.dumps({"error": "Zone not found"}), 404
+
+        data = request.json or {}
+        source_name = source.get("name") or f"Zone {id}"
+        new_name = data.get("name") or f"{source_name} Copy"
+        clone_id = zones.create(new_name, source.get("names"), source.get("presets"))
+        extra = {k: v for k, v in source.items() if k not in ("name", "names", "presets")}
+        if extra:
+            zones.update(clone_id, extra)
+
+        profile_id = get_current_profile_id(session)
+        if profile_id:
+            profile = profiles.read(profile_id)
+            if profile:
+                zlist = _profile_zone_id_list(profile)
+                if clone_id not in zlist:
+                    zlist.append(clone_id)
+                    _set_profile_zone_order(profile, zlist)
+                    profiles.update(profile_id, profile)
+
+        zdata = zones.read(clone_id)
+        return json.dumps({clone_id: zdata}), 201, {"Content-Type": "application/json"}
+    except Exception as e:
+        import sys
+
+        try:
+            sys.print_exception(e)
+        except Exception:
+            pass
+        return json.dumps({"error": str(e)}), 400
+

src/main.py

@@ -1,41 +1,300 @@
 import asyncio
-from settings import Settings
+import errno
-import gc
+import json
-import machine
+import os
+import signal
+import socket
+import threading
+import traceback
 from microdot import Microdot, send_file
 from microdot.websocket import with_websocket
+from microdot.session import Session
+from settings import Settings
 
-import aioespnow
+import controllers.preset as preset
-import network
-from controllers.preset import preset
 import controllers.profile as profile
 import controllers.group as group
 import controllers.sequence as sequence
-import controllers.tab as tab
+import controllers.zone as zone
 import controllers.palette as palette
+import controllers.scene as scene
+import controllers.pattern as pattern
+import controllers.settings as settings_controller
+import controllers.device as device_controller
+import controllers.led_tool as led_tool_controller
+from models.transport import get_sender, set_sender, get_current_sender
+from models.device import Device, normalize_mac
+from models import wifi_ws_clients as tcp_client_registry
+from util.device_status_broadcaster import (
+    broadcast_device_tcp_snapshot_to,
+    broadcast_device_tcp_status,
+    register_device_status_ws,
+    unregister_device_status_ws,
+)
+
+_tcp_device_lock = threading.Lock()
+
+DISCOVERY_UDP_PORT = 8766
 
 
+def _register_udp_device_sync(
+    device_name: str, peer_ip: str, mac, device_type=None
+) -> None:
+    with _tcp_device_lock:
+        try:
+            d = Device()
+            did, persisted = d.upsert_wifi_tcp_client(
+                device_name, peer_ip, mac, device_type=device_type
+            )
+            if did and persisted:
+                print(
+                    f"UDP device registered: mac={did} name={device_name!r} ip={peer_ip!r}"
+                )
+        except Exception as e:
+            print(f"UDP device registry failed: {e}")
+            traceback.print_exception(type(e), e, e.__traceback__)
 
-async def main():
+
+async def _handle_udp_discovery(sock, udp_holder=None) -> None:
+    while True:
+        try:
+            data, addr = await asyncio.get_running_loop().sock_recvfrom(sock, 2048)
+        except asyncio.CancelledError:
+            raise
+        except OSError as e:
+            if udp_holder and udp_holder.get("closing"):
+                break
+            print(f"[UDP] recv failed: {e!r}")
+            continue
+        except Exception as e:
+            print(f"[UDP] recv failed: {e!r}")
+            continue
+        peer_ip = addr[0] if addr else ""
+        line = data.split(b"\n", 1)[0].strip()
+        if line:
+            try:
+                parsed = json.loads(line.decode("utf-8"))
+                if isinstance(parsed, dict):
+                    dns = str(parsed.get("device_name") or "").strip()
+                    mac = parsed.get("mac") or parsed.get("device_mac") or parsed.get(
+                        "sta_mac"
+                    )
+                    device_type = parsed.get("type") or parsed.get("device_type")
+                    if dns and normalize_mac(mac):
+                        _register_udp_device_sync(dns, peer_ip, mac, device_type)
+                        if str(parsed.get("v") or "") == "1":
+                            tcp_client_registry.ensure_driver_connection(peer_ip)
+            except (UnicodeError, ValueError, TypeError):
+                pass
+        try:
+            await asyncio.get_running_loop().sock_sendto(sock, data, addr)
+        except Exception as e:
+            print(f"[UDP] echo send failed: {e!r}")
+
+
+def _prime_wifi_outbound_driver_connections() -> None:
+    """
+    For each Wi‑Fi device in the registry with a usable IPv4, start (or keep) the
+    outbound WebSocket task. The client loop reconnects automatically if the link
+    drops. Presets are not pushed automatically; use Send Presets / profile apply.
+    """
+    n = 0
+    try:
+        dev = Device()
+        for mac_key, doc in list(dev.items()):
+            if not isinstance(doc, dict):
+                continue
+            if doc.get("transport") != "wifi":
+                continue
+            ip = _ipv4_address(str(doc.get("address") or ""))
+            if not ip:
+                continue
+            tcp_client_registry.ensure_driver_connection(ip)
+            n += 1
+    except Exception as e:
+        print(f"[startup] Wi-Fi driver connection prime failed: {e!r}")
+        traceback.print_exception(type(e), e, e.__traceback__)
+        return
+    if n:
+        print(f"[startup] primed outbound WebSocket for {n} Wi-Fi driver(s)")
+
+
+def _ipv4_address(addr: str) -> str | None:
+    """Return dotted IPv4 string or None (hostnames skipped for UDP nudge)."""
+    s = (addr or "").strip()
+    if not s:
+        return None
+    parts = s.split(".")
+    if len(parts) != 4:
+        return None
+    try:
+        nums = [int(p) for p in parts]
+    except ValueError:
+        return None
+    if not all(0 <= n <= 255 for n in nums):
+        return None
+    return s
+
+
+async def _periodic_wifi_driver_hello_loop(settings, udp_holder) -> None:
+    """
+    While a registered Wi-Fi driver has no outbound WebSocket, send a short JSON hello on
+    UDP discovery port so the device can announce itself and we can reconnect.
+    """
+    try:
+        interval = float(settings.get("wifi_driver_hello_interval_s", 10.0))
+    except (TypeError, ValueError):
+        interval = 10.0
+    if interval <= 0:
+        return
+
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    sock.setblocking(False)
+    loop = asyncio.get_running_loop()
+    try:
+        while True:
+            await asyncio.sleep(interval)
+            if udp_holder.get("closing"):
+                break
+            try:
+                dev = Device()
+            except Exception as e:
+                print(f"[hello] device list failed: {e!r}")
+                continue
+            for _mac_key, doc in list(dev.items()):
+                if not isinstance(doc, dict):
+                    continue
+                if doc.get("transport") != "wifi":
+                    continue
+                ip = _ipv4_address(str(doc.get("address") or ""))
+                if not ip:
+                    continue
+                if tcp_client_registry.tcp_client_connected(ip):
+                    continue
+                name = (doc.get("name") or "").strip()
+                mac = normalize_mac(doc.get("id") or _mac_key)
+                if not name or not mac:
+                    continue
+                line = (
+                    json.dumps(
+                        {"m": "hello", "device_name": name, "mac": mac},
+                        separators=(",", ":"),
+                    )
+                    + "\n"
+                )
+                try:
+                    await loop.sock_sendto(
+                        sock, line.encode("utf-8"), (ip, DISCOVERY_UDP_PORT)
+                    )
+                except OSError as e:
+                    print(f"[hello] UDP to {ip!r} failed: {e!r}")
+    finally:
+        try:
+            sock.close()
+        except OSError:
+            pass
+
+
+async def _run_udp_discovery_server(udp_holder=None) -> None:
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    sock.setblocking(False)
+    try:
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    except (AttributeError, OSError):
+        pass
+    try:
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
+    except (AttributeError, OSError):
+        pass
+    sock.bind(("0.0.0.0", DISCOVERY_UDP_PORT))
+    if udp_holder is not None:
+        udp_holder["sock"] = sock
+    print(f"UDP discovery listening on 0.0.0.0:{DISCOVERY_UDP_PORT}")
+    try:
+        await _handle_udp_discovery(sock, udp_holder)
+    finally:
+        if udp_holder is not None:
+            udp_holder.pop("sock", None)
+        try:
+            sock.close()
+        except Exception:
+            pass
+
+
+async def _send_bridge_wifi_channel(settings, sender):
+    """Tell the serial ESP32 bridge to set STA channel (settings wifi_channel); not forwarded as ESP-NOW."""
+    try:
+        ch = int(settings.get("wifi_channel", 6))
+    except (TypeError, ValueError):
+        ch = 6
+    ch = max(1, min(11, ch))
+    payload = json.dumps({"m": "bridge", "ch": ch}, separators=(",", ":"))
+    try:
+        await sender.send(payload, addr="ffffffffffff")
+        print(f"[startup] bridge Wi-Fi channel -> {ch}")
+    except Exception as e:
+        print(f"[startup] bridge channel message failed: {e}")
+
+
+async def main(port=80):
     settings = Settings()
+    print(settings)
     print("Starting")
 
-    network.WLAN(network.STA_IF).active(True)
+    # Initialize transport (serial to ESP32 bridge)
-
+    sender = get_sender(settings)
-
+    set_sender(sender)
-    e = aioespnow.AIOESPNow()
-    e.active(True)
-    e.add_peer(b"\xbb\xbb\xbb\xbb\xbb\xbb")
 
     app = Microdot()
     
+    # Initialize sessions with a secret key from settings
+    secret_key = settings.get('session_secret_key', 'led-controller-secret-key-change-in-production')
+    Session(app, secret_key=secret_key)
+    
     # Mount model controllers as subroutes
-    app.mount('/presets', preset.controller)
+    # Verify controllers are Microdot instances before mounting
-    app.mount('/profiles', profile.controller)
+    controllers_to_mount = [
-    app.mount('/groups', group.controller)
+        ('/presets', preset, 'preset'),
-    app.mount('/sequences', sequence.controller)
+        ('/profiles', profile, 'profile'),
-    app.mount('/tabs', tab.controller)
+        ('/groups', group, 'group'),
-    app.mount('/palettes', palette.controller)
+        ('/sequences', sequence, 'sequence'),
+        ('/zones', zone, 'zone'),
+        ('/palettes', palette, 'palette'),
+        ('/scenes', scene, 'scene'),
+    ]
+    
+    # Mount model controllers as subroutes
+    app.mount(preset.controller, '/presets')
+    app.mount(profile.controller, '/profiles')
+    app.mount(group.controller, '/groups')
+    app.mount(sequence.controller, '/sequences')
+    app.mount(zone.controller, '/zones')
+    app.mount(palette.controller, '/palettes')
+    app.mount(scene.controller, '/scenes')
+    app.mount(pattern.controller, '/patterns')
+    app.mount(settings_controller.controller, '/settings')
+    app.mount(device_controller.controller, '/devices')
+    app.mount(led_tool_controller.controller, '/led-tool')
+
+    tcp_client_registry.set_settings(settings)
+    tcp_client_registry.set_tcp_status_broadcaster(broadcast_device_tcp_status)
+
+    # Serve index.html at root (cwd is src/ when run via pipenv run run)
+    @app.route('/')
+    def index(request):
+        """Serve the main web UI."""
+        return send_file('templates/index.html')
+    
+    # Serve settings page
+    @app.route('/settings')
+    def settings_page(request):
+        """Serve the settings page."""
+        return send_file('templates/settings.html')
+
+    # Favicon: avoid 404 in browser console (no file needed)
+    @app.route('/favicon.ico')
+    def favicon(request):
+        return '', 204
 
     # Static file route
     @app.route("/static/<path:path>")
@@ -49,26 +308,106 @@ async def main():
     @app.route('/ws')
     @with_websocket
     async def ws(request, ws):
-        while True:
+        await register_device_status_ws(ws)
-            data = await ws.receive()
+        await broadcast_device_tcp_snapshot_to(ws)
-            if data:
+        try:
-                await e.asend(b"\xbb\xbb\xbb\xbb\xbb\xbb", data)
+            while True:
+                data = await ws.receive()
                 print(data)
-            else:
+                if data:
-                break
+                    try:
+                        parsed = json.loads(data)
+                        print("WS received JSON:", parsed)
+                        # Optional "to": 12-char hex MAC; rest is payload (sent with that address).
+                        addr = parsed.pop("to", None)
+                        payload = json.dumps(parsed) if parsed else data
+                        await sender.send(payload, addr=addr)
+                    except json.JSONDecodeError:
+                        # Not JSON: send raw with default address
+                        try:
+                            await sender.send(data)
+                        except Exception:
+                            try:
+                                await ws.send(json.dumps({"error": "Send failed"}))
+                            except Exception:
+                                pass
+                    except Exception:
+                        try:
+                            await ws.send(json.dumps({"error": "Send failed"}))
+                        except Exception:
+                            pass
+                else:
+                    break
+        finally:
+            await unregister_device_status_ws(ws)
 
 
 
-    server = asyncio.create_task(app.start_server(host="0.0.0.0", port=80))
+    # Touch Device singleton early so db/device.json exists before first UDP hello.
+    Device()
+    await _send_bridge_wifi_channel(settings, sender)
+    _prime_wifi_outbound_driver_connections()
 
-    wdt = machine.WDT(timeout=10000)
+    udp_holder = {"closing": False}
-    wdt.feed()
+    loop = asyncio.get_running_loop()
 
-    while True:
+    def _graceful_shutdown(*_args):
-        gc.collect()
+        print("[server] shutting down...")
-        for i in range(60):
+        udp_holder["closing"] = True
-            wdt.feed()
+        u = udp_holder.get("sock")
-            await asyncio.sleep_ms(500)
+        if u is not None:
-    # cleanup before ending the application
+            try:
+                u.close()
+            except OSError:
+                pass
+        tcp_client_registry.cancel_all_driver_tasks()
+        if getattr(app, "server", None) is not None:
+            app.shutdown()
 
-asyncio.run(main())
+    shutdown_handlers_registered = False
+    try:
+        try:
+            for sig in (signal.SIGINT, signal.SIGTERM):
+                loop.add_signal_handler(sig, _graceful_shutdown)
+            shutdown_handlers_registered = True
+        except (NotImplementedError, RuntimeError):
+            pass
+
+        # Await HTTP + UDP discovery; bind failures (e.g. port 80 in use) surface here.
+        try:
+            await asyncio.gather(
+                app.start_server(host="0.0.0.0", port=port),
+                _run_udp_discovery_server(udp_holder),
+                _periodic_wifi_driver_hello_loop(settings, udp_holder),
+            )
+        except OSError as e:
+            if e.errno == errno.EADDRINUSE:
+                print(
+                    f"[server] bind failed (address already in use): {e!s}\n"
+                    f"[server] HTTP is configured for port {port} (env PORT). "
+                    f"Stop the other process or use a free port, e.g. PORT=8080 pipenv run run"
+                )
+            raise
+    finally:
+        srv = getattr(app, "server", None)
+        if srv is not None:
+            try:
+                srv.close()
+                await srv.wait_closed()
+            except Exception:
+                pass
+            try:
+                app.server = None
+            except Exception:
+                pass
+        if shutdown_handlers_registered:
+            for sig in (signal.SIGINT, signal.SIGTERM):
+                try:
+                    loop.remove_signal_handler(sig)
+                except (NotImplementedError, OSError, ValueError):
+                    pass
+
+if __name__ == "__main__":
+    import os
+    port = int(os.environ.get("PORT", 80))
+    asyncio.run(main(port=port))

src/models/__init__.py

@@ -0,0 +1 @@
+# Models package

src/models/device.py

@@ -0,0 +1,285 @@
+"""
+LED driver registry persisted in ``db/device.json``.
+
+Storage key and **id** field are the device **MAC**: 12 lowercase hex characters
+(no colons). **name** is for ``select`` / zones (not unique). **address** is the
+reachability hint: same as MAC for ESP-NOW, or IP/hostname for Wi-Fi.
+"""
+
+from models.model import Model
+
+DEVICE_TYPES = frozenset({"led"})
+DEVICE_TRANSPORTS = frozenset({"wifi", "espnow"})
+
+
+def validate_device_type(value):
+    t = (value or "led").strip().lower()
+    if t not in DEVICE_TYPES:
+        raise ValueError(f"type must be one of: {', '.join(sorted(DEVICE_TYPES))}")
+    return t
+
+
+def validate_device_transport(value):
+    tr = (value or "espnow").strip().lower()
+    if tr not in DEVICE_TRANSPORTS:
+        raise ValueError(
+            f"transport must be one of: {', '.join(sorted(DEVICE_TRANSPORTS))}"
+        )
+    return tr
+
+
+def normalize_mac(mac):
+    """Normalise to 12-char lowercase hex or None."""
+    if mac is None:
+        return None
+    s = str(mac).strip().lower().replace(":", "").replace("-", "")
+    if len(s) == 12 and all(c in "0123456789abcdef" for c in s):
+        return s
+    return None
+
+
+def derive_device_mac(mac=None, address=None, transport="espnow"):
+    """
+    Resolve the device MAC used as storage id.
+
+    Explicit ``mac`` wins. For ESP-NOW, ``address`` is the peer MAC. For Wi-Fi,
+    ``mac`` must be supplied (``address`` is typically an IP).
+    """
+    m = normalize_mac(mac)
+    if m:
+        return m
+    tr = validate_device_transport(transport)
+    if tr == "espnow":
+        return normalize_mac(address)
+    return None
+
+
+def normalize_address_for_transport(addr, transport):
+    """ESP-NOW → 12 hex or None; Wi-Fi → trimmed string or None."""
+    tr = validate_device_transport(transport)
+    if tr == "espnow":
+        return normalize_mac(addr)
+    if addr is None:
+        return None
+    s = str(addr).strip()
+    return s if s else None
+
+
+class Device(Model):
+    def __init__(self):
+        super().__init__()
+
+    def load(self):
+        super().load()
+        changed = False
+        for sid, doc in list(self.items()):
+            if not isinstance(doc, dict):
+                continue
+            if self._migrate_record(str(sid), doc):
+                changed = True
+        if self._rekey_legacy_ids():
+            changed = True
+        if changed:
+            self.save()
+
+    def _migrate_record(self, storage_id, doc):
+        changed = False
+        if doc.get("type") not in DEVICE_TYPES:
+            doc["type"] = "led"
+            changed = True
+        if doc.get("transport") not in DEVICE_TRANSPORTS:
+            doc["transport"] = "espnow"
+            changed = True
+        raw_list = doc.get("addresses")
+        if isinstance(raw_list, list) and raw_list:
+            picked = None
+            for item in raw_list:
+                n = normalize_mac(item)
+                if n:
+                    picked = n
+                    break
+            if picked:
+                doc["address"] = picked
+            del doc["addresses"]
+            changed = True
+        elif "addresses" in doc:
+            del doc["addresses"]
+            changed = True
+        tr = doc["transport"]
+        norm = normalize_address_for_transport(doc.get("address"), tr)
+        if doc.get("address") != norm:
+            doc["address"] = norm
+            changed = True
+        mac_key = normalize_mac(storage_id)
+        if mac_key and mac_key == storage_id and str(doc.get("id") or "") != mac_key:
+            doc["id"] = mac_key
+            changed = True
+        elif str(doc.get("id") or "").strip() != storage_id:
+            doc["id"] = storage_id
+            changed = True
+        doc.pop("mac", None)
+        return changed
+
+    def _rekey_legacy_ids(self):
+        """Move numeric-keyed rows to MAC keys when ESP-NOW MAC is known."""
+        changed = False
+        moves = []
+        for sid in list(self.keys()):
+            doc = self.get(sid)
+            if not isinstance(doc, dict):
+                continue
+            if normalize_mac(sid) == sid:
+                continue
+            if not str(sid).isdigit():
+                continue
+            tr = doc.get("transport", "espnow")
+            cand = None
+            if tr == "espnow":
+                cand = normalize_mac(doc.get("address"))
+            if not cand:
+                continue
+            moves.append((sid, cand))
+        for old, mac in moves:
+            if old not in self:
+                continue
+            doc = self.pop(old)
+            if mac in self:
+                existing = dict(self[mac])
+                for k, v in doc.items():
+                    if k not in existing or existing[k] in (None, "", []):
+                        existing[k] = v
+                doc = existing
+            doc["id"] = mac
+            self[mac] = doc
+            changed = True
+        return changed
+
+    def create(
+        self,
+        name="",
+        address=None,
+        mac=None,
+        default_pattern=None,
+        zones=None,
+        device_type="led",
+        transport="espnow",
+    ):
+        dt = validate_device_type(device_type)
+        tr = validate_device_transport(transport)
+        mac_hex = derive_device_mac(mac=mac, address=address, transport=tr)
+        if not mac_hex:
+            raise ValueError(
+                "mac is required (12 hex characters); for Wi-Fi pass mac separately from IP address"
+            )
+        if mac_hex in self:
+            raise ValueError("device with this mac already exists")
+        addr = normalize_address_for_transport(address, tr)
+        if tr == "espnow":
+            addr = mac_hex
+        self[mac_hex] = {
+            "id": mac_hex,
+            "name": name,
+            "type": dt,
+            "transport": tr,
+            "address": addr,
+            "default_pattern": default_pattern if default_pattern else None,
+            "zones": list(zones) if zones else [],
+        }
+        self.save()
+        return mac_hex
+
+    def read(self, id):
+        m = normalize_mac(id)
+        if m is not None and m in self:
+            return self.get(m)
+        return self.get(str(id), None)
+
+    def update(self, id, data):
+        id_str = normalize_mac(id)
+        if id_str is None:
+            id_str = str(id)
+        if id_str not in self:
+            return False
+        incoming = dict(data)
+        incoming.pop("id", None)
+        incoming.pop("addresses", None)
+        in_mac = normalize_mac(incoming.get("mac"))
+        if in_mac is not None and in_mac != id_str:
+            raise ValueError("cannot change device mac; delete and re-add")
+        incoming.pop("mac", None)
+        merged = dict(self[id_str])
+        merged.update(incoming)
+        merged["type"] = validate_device_type(merged.get("type"))
+        merged["transport"] = validate_device_transport(merged.get("transport"))
+        tr = merged["transport"]
+        merged["address"] = normalize_address_for_transport(merged.get("address"), tr)
+        if tr == "espnow":
+            merged["address"] = id_str
+        merged["id"] = id_str
+        self[id_str] = merged
+        self.save()
+        return True
+
+    def delete(self, id):
+        id_str = normalize_mac(id)
+        if id_str is None:
+            id_str = str(id)
+        if id_str not in self:
+            return False
+        self.pop(id_str)
+        self.save()
+        return True
+
+    def list(self):
+        return list(self.keys())
+
+    def upsert_wifi_tcp_client(self, device_name, peer_ip, mac, device_type=None):
+        """
+        Register or update a Wi-Fi client by **MAC** (storage id). Updates **name**,
+        **address** (peer IP), and optionally **type** from the client hello when valid.
+
+        Returns ``(mac_hex | None, persisted)`` where **persisted** is True iff ``save()``
+        ran (new row or field changes). Duplicate hellos with identical data are no-ops.
+        """
+        mac_hex = normalize_mac(mac)
+        if not mac_hex:
+            return None, False
+        name = (device_name or "").strip()
+        if not name:
+            return None, False
+        ip = normalize_address_for_transport(peer_ip, "wifi")
+        if not ip:
+            return None, False
+        resolved_type = None
+        if device_type is not None:
+            try:
+                resolved_type = validate_device_type(device_type)
+            except ValueError:
+                resolved_type = None
+        if mac_hex in self:
+            prev = self[mac_hex]
+            merged = dict(prev)
+            merged["name"] = name
+            if resolved_type is not None:
+                merged["type"] = resolved_type
+            else:
+                merged["type"] = validate_device_type(merged.get("type"))
+            merged["transport"] = "wifi"
+            merged["address"] = ip
+            merged["id"] = mac_hex
+            if merged == prev:
+                return mac_hex, False
+            self[mac_hex] = merged
+            self.save()
+            return mac_hex, True
+        self[mac_hex] = {
+            "id": mac_hex,
+            "name": name,
+            "type": resolved_type or "led",
+            "transport": "wifi",
+            "address": ip,
+            "default_pattern": None,
+            "zones": [],
+        }
+        self.save()
+        return mac_hex, True

src/models/http_driver.py

@@ -0,0 +1,125 @@
+"""Wi-Fi LED drivers over HTTP long-poll (same port as the web UI).
+
+Drivers POST /driver/v1/poll; the controller responds with queued JSON lines.
+Presence: last poll within DRIVER_HTTP_SEEN_S counts as connected.
+"""
+
+import asyncio
+import time
+
+from models.wifi_peer import normalize_wifi_peer_ip
+
+# Must exceed max ``wait_s`` (60) on /driver/v1/poll so sessions are not pruned mid-wait.
+DRIVER_HTTP_SEEN_S = 90.0
+_QUEUE_MAX = 64
+
+_queues: dict[str, asyncio.Queue] = {}
+_last_poll: dict[str, float] = {}
+_connected_flag: set[str] = set()
+_status_broadcast = None
+
+
+def set_wifi_driver_status_broadcaster(coro) -> None:
+    global _status_broadcast
+    _status_broadcast = coro
+
+
+def _schedule_status(ip: str, connected: bool) -> None:
+    fn = _status_broadcast
+    if not fn:
+        return
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        return
+    try:
+        loop.create_task(fn(ip, connected))
+    except Exception:
+        pass
+
+
+def _get_queue(ip: str) -> asyncio.Queue:
+    q = _queues.get(ip)
+    if q is None:
+        q = asyncio.Queue(maxsize=_QUEUE_MAX)
+        _queues[ip] = q
+    return q
+
+
+def prune_stale_http_sessions() -> None:
+    """Drop timed-out sessions, clear queues, broadcast disconnect."""
+    now = time.monotonic()
+    for ip in list(_last_poll.keys()):
+        if now - _last_poll[ip] <= DRIVER_HTTP_SEEN_S:
+            continue
+        _last_poll.pop(ip, None)
+        _queues.pop(ip, None)
+        if ip in _connected_flag:
+            _connected_flag.discard(ip)
+            _schedule_status(ip, False)
+            print(f"[HTTP driver] session timed out: {ip}")
+
+
+def touch_http_session(ip: str) -> None:
+    ip = normalize_wifi_peer_ip(ip)
+    if not ip:
+        return
+    prune_stale_http_sessions()
+    now = time.monotonic()
+    _last_poll[ip] = now
+    if ip not in _connected_flag:
+        _connected_flag.add(ip)
+        _schedule_status(ip, True)
+
+
+def wifi_driver_connected(ip: str) -> bool:
+    prune_stale_http_sessions()
+    key = normalize_wifi_peer_ip(ip)
+    return bool(key and key in _connected_flag)
+
+
+def list_connected_driver_ips():
+    prune_stale_http_sessions()
+    return list(_connected_flag)
+
+
+async def enqueue_json_line(ip: str, json_str: str) -> bool:
+    ip = normalize_wifi_peer_ip(ip)
+    if not ip:
+        return False
+    line = json_str[:-1] if json_str.endswith("\n") else json_str
+    q = _get_queue(ip)
+    while True:
+        try:
+            q.put_nowait(line)
+            return True
+        except asyncio.QueueFull:
+            try:
+                q.get_nowait()
+            except asyncio.QueueEmpty:
+                pass
+
+
+async def send_json_line_to_ip(ip: str, json_str: str) -> bool:
+    """Queue one JSON line for the driver to receive on the next long-poll."""
+    return await enqueue_json_line(ip, json_str)
+
+
+async def collect_lines_after_touch(ip: str, wait_s: float) -> list[str]:
+    """Wait up to wait_s for first line, then drain the rest (non-blocking)."""
+    ip = normalize_wifi_peer_ip(ip)
+    if not ip:
+        return []
+    q = _get_queue(ip)
+    lines: list[str] = []
+    try:
+        first = await asyncio.wait_for(q.get(), timeout=wait_s)
+        lines.append(first)
+        while True:
+            try:
+                lines.append(q.get_nowait())
+            except asyncio.QueueEmpty:
+                break
+    except asyncio.TimeoutError:
+        pass
+    return lines

src/models/model.py

@@ -1,18 +1,42 @@
 import json
-import wifi
+import os
-import ubinascii
+import traceback
-import machine
+
+# DB directory: project root / db (writable without root)
+def _db_dir():
+    try:
+        # src/models/model.py -> project root
+        base = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+        return os.path.join(base, "db")
+    except Exception:
+        return "db"
 
 class Model(dict):
+    def __new__(cls, *args, **kwargs):
+        # Singleton pattern: return existing instance if it exists
+        if not hasattr(cls, '_instance'):
+            cls._instance = super().__new__(cls)
+        return cls._instance
     
     def __init__(self):
-        self.file = self.__class__.__name__ + ".json"
+        # Only initialize once (check if already initialized)
+        if hasattr(self, '_initialized'):
+            return
+        
+        db_dir = _db_dir()
+        try:
+            os.makedirs(db_dir, exist_ok=True)
+        except OSError:
+            pass
+        self.class_name = self.__class__.__name__
+        self.file = os.path.join(db_dir, f"{self.class_name.lower()}.json")
         super().__init__()
 
         self.load()  # Load settings from file during initialization
+        self._initialized = True
 
     def set_defaults(self):
-        self = {}
+        self.clear()
 
     def get_next_id(self):
         """Get the next available ID for creating a new record."""
@@ -23,20 +47,67 @@ class Model(dict):
 
     def save(self):
         try:
+            db_dir = os.path.dirname(self.file)
+            try:
+                os.makedirs(db_dir, exist_ok=True)
+            except OSError:
+                pass
             j = json.dumps(self)
             with open(self.file, 'w') as file:
                 file.write(j)
-            print("Settings saved successfully.")
+                file.flush()  # Ensure data is written to buffer
+            # Try to sync filesystem if available (MicroPython)
+            try:
+                os.sync()
+            except (AttributeError, OSError):
+                pass  # os.sync() not available on all platforms
+            print(f"{self.class_name} saved successfully to {self.file}")
         except Exception as e:
-            print(f"Error saving settings: {e}")
+            print(f"Error saving {self.class_name} to {self.file}: {e}")
+            traceback.print_exception(type(e), e, e.__traceback__)
 
     def load(self):
         try:
-            with open(self.file, 'r') as file:
+            # Check if file exists first
-                loaded_settings = json.load(file)
+            try:
-            self.update(loaded_settings)
+                with open(self.file, 'r') as file:
-            print("Settings loaded successfully.")
+                    content = file.read().strip()
-        except Exception as e:
+            except OSError:
-            print(f"Error loading settings")
+                # File doesn't exist
+                raise
+            
+            if not content:
+                # Empty file
+                loaded_settings = {}
+            else:
+                # Parse JSON content
+                loaded_settings = json.loads(content)
+            
+            # Verify it's a dictionary
+            if not isinstance(loaded_settings, dict):
+                raise ValueError(f"File does not contain a dictionary, got {type(loaded_settings)}")
+            
+            # Clear and update with loaded data
+            # Clear first
+            self.clear()
+            # Manually copy items to avoid any update() method issues
+            for key, value in loaded_settings.items():
+                self[key] = value
+            print(f"{self.class_name} loaded successfully.")
+        except OSError as e:
+            # File doesn't exist yet - this is normal on first run
+            # Create an empty file with defaults
+            self.set_defaults()
+            self.save()
+            print(f"{self.class_name} initialized (new file created).")
+        except ValueError:
+            # JSON parsing error - file exists but is corrupted
+            # Note: MicroPython uses ValueError for JSON errors, not JSONDecodeError
+            print(f"Error loading {self.class_name}: Invalid JSON format. Resetting to defaults.")
+            self.set_defaults()
+            self.save()
+        except Exception:
+            # Other unexpected errors - avoid trying to format exception to prevent further errors
+            print(f"Error loading {self.class_name}. Resetting to defaults.")
             self.set_defaults()
             self.save()

src/models/pallet.py

@@ -6,22 +6,30 @@ class Palette(Model):
 
     def create(self, name="", colors=None):
         next_id = self.get_next_id()
-        self[next_id] = {
+        # Store palette as a simple list of colors; name is ignored.
-            "name": name,
+        self[next_id] = list(colors) if colors else []
-            "colors": colors if colors else []
-        }
         self.save()
         return next_id
 
     def read(self, id):
         id_str = str(id)
-        return self.get(id_str, None)
+        value = self.get(id_str, None)
+        # Backwards compatibility: if stored as {"colors": [...]}, unwrap.
+        if isinstance(value, dict) and "colors" in value:
+            return value.get("colors") or []
+        # Otherwise, expect a list of colors.
+        return value or []
     
     def update(self, id, data):
         id_str = str(id)
         if id_str not in self:
             return False
-        self[id_str].update(data)
+        # Accept either {"colors": [...]} or a raw list.
+        if isinstance(data, dict):
+            colors = data.get("colors", [])
+        else:
+            colors = data
+        self[id_str] = list(colors) if colors else []
         self.save()
         return True
     

src/models/pattern.py

@@ -0,0 +1,38 @@
+from models.model import Model
+
+
+class Pattern(Model):
+    def __init__(self):
+        super().__init__()
+
+    def create(self, name="", data=None):
+        pattern_name = str(name).strip()
+        if not pattern_name:
+            pattern_name = self.get_next_id()
+        self[pattern_name] = data if isinstance(data, dict) else {}
+        self.save()
+        return pattern_name
+
+    def read(self, id):
+        id_str = str(id)
+        return self.get(id_str, None)
+
+    def update(self, id, data):
+        id_str = str(id)
+        if id_str not in self:
+            return False
+        if isinstance(data, dict):
+            self[id_str].update(data)
+        self.save()
+        return True
+
+    def delete(self, id):
+        id_str = str(id)
+        if id_str not in self:
+            return False
+        self.pop(id_str)
+        self.save()
+        return True
+
+    def list(self):
+        return list(self.keys())

src/models/preset.py

@@ -1,10 +1,26 @@
 from models.model import Model
+from models.profile import Profile
 
 class Preset(Model):
     def __init__(self):
         super().__init__()
+        # Backfill profile ownership for existing presets.
+        try:
+            profiles = Profile()
+            profile_list = profiles.list()
+            default_profile_id = profile_list[0] if profile_list else None
+            changed = False
+            for preset_id, preset_data in list(self.items()):
+                if isinstance(preset_data, dict) and "profile_id" not in preset_data:
+                    if default_profile_id is not None:
+                        preset_data["profile_id"] = str(default_profile_id)
+                        changed = True
+            if changed:
+                self.save()
+        except Exception:
+            pass
 
-    def create(self):
+    def create(self, profile_id=None):
         next_id = self.get_next_id()
         self[next_id] = {
             "name": "",
@@ -18,6 +34,9 @@ class Preset(Model):
             "n4": 0,
             "n5": 0,
             "n6": 0,
+            "n7": 0,
+            "n8": 0,
+            "profile_id": str(profile_id) if profile_id is not None else None,
         }
         self.save()
         return next_id

src/models/profile.py

@@ -1,16 +1,45 @@
 from models.model import Model
+from models.pallet import Palette
+
 
 class Profile(Model):
     def __init__(self):
-        super().__init__()
+        """Profile model.
 
-    def create(self, name=""):
+        Each profile owns a single, unique palette stored in the Palette model.
+        The profile stores a `palette_id` that points to its palette; any legacy
+        inline `palette` arrays are migrated to a dedicated Palette entry.
+        """
+        super().__init__()
+        self._palette_model = Palette()
+
+        # Migrate legacy inline palettes to separate Palette entries.
+        changed = False
+        for pid, pdata in list(self.items()):
+            if isinstance(pdata, dict):
+                if "palette" in pdata and "palette_id" not in pdata:
+                    colors = pdata.get("palette") or []
+                    palette_id = self._palette_model.create(colors=colors)
+                    pdata.pop("palette", None)
+                    pdata["palette_id"] = str(palette_id)
+                    changed = True
+        if changed:
+            self.save()
+
+    def create(self, name="", profile_type="zones"):
+        """Create a new profile and its own empty palette.
+
+        profile_type: "zones" or "scenes" (ignoring scenes for now)
+        """
         next_id = self.get_next_id()
+        # Create a unique palette for this profile.
+        palette_id = self._palette_model.create(colors=[])
         self[next_id] = {
             "name": name,
-            "tabs": {},
+            "type": profile_type,  # "zones" or "scenes"
-            "palette": [],
+            "zones": [],  # Array of zone IDs
-            "tab_order": []
+            "scenes": [],  # Array of scene IDs (for future use)
+            "palette_id": str(palette_id),
         }
         self.save()
         return next_id

src/models/scene.py

@@ -1,15 +1,15 @@
 from models.model import Model
 
-class Tab(Model):
+class Scene(Model):
     def __init__(self):
         super().__init__()
 
-    def create(self, name="", names=None, presets=None):
+    def create(self, name="", sequences=None, groups=None):
         next_id = self.get_next_id()
         self[next_id] = {
             "name": name,
-            "names": names if names else [],
+            "sequences": sequences if sequences else [],
-            "presets": presets if presets else []
+            "groups": groups if groups else []
         }
         self.save()
         return next_id

src/models/serial.py

@@ -0,0 +1,12 @@
+class Serial:
+    def __init__(self, port, baudrate):
+        self.port = port
+        self.baudrate = baudrate
+        self.uart = UART(1, baudrate, tx=Pin(21), rx=Pin(6))
+
+    def send(self, data):
+        self.uart.write(data)
+
+    def receive(self):
+        return self.uart.read()
+        

src/models/transport.py

@@ -0,0 +1,68 @@
+import asyncio
+import json
+
+
+# Default: broadcast (6 bytes). Pi always sends 6-byte address + payload to ESP32.
+BROADCAST_MAC = bytes.fromhex("ffffffffffff")
+
+
+def _encode_payload(data):
+    if isinstance(data, str):
+        return data.encode()
+    if isinstance(data, dict):
+        return json.dumps(data).encode()
+    return data
+
+
+def _parse_mac(addr):
+    """Convert 12-char hex string or 6-byte bytes to 6-byte MAC."""
+    if addr is None or addr == b"":
+        return BROADCAST_MAC
+    if isinstance(addr, bytes) and len(addr) == 6:
+        return addr
+    if isinstance(addr, str) and len(addr) == 12:
+        return bytes.fromhex(addr)
+    return BROADCAST_MAC
+
+
+async def _to_thread(func, *args):
+    to_thread = getattr(asyncio, "to_thread", None)
+    if to_thread:
+        return await to_thread(func, *args)
+    loop = asyncio.get_event_loop()
+    return await loop.run_in_executor(None, func, *args)
+
+
+class SerialSender:
+    def __init__(self, port, baudrate, default_addr=None):
+        import serial
+
+        self._serial = serial.Serial(port, baudrate=baudrate, timeout=1)
+        self._default_addr = _parse_mac(default_addr)
+        self._write_lock = asyncio.Lock()
+
+    async def send(self, data, addr=None):
+        mac = _parse_mac(addr) if addr is not None else self._default_addr
+        payload = _encode_payload(data)
+        async with self._write_lock:
+            await _to_thread(self._serial.write, mac + payload)
+        return True
+
+
+_current_sender = None
+
+
+def set_sender(sender):
+    global _current_sender
+    _current_sender = sender
+
+
+def get_current_sender():
+    return _current_sender
+
+
+def get_sender(settings):
+    port = settings.get("serial_port", "/dev/ttyS0")
+    baudrate = settings.get("serial_baudrate", 912000)
+    default_addr = settings.get("serial_destination_mac", "ffffffffffff")
+    return SerialSender(port, baudrate, default_addr=default_addr)

src/models/wifi_peer.py

@@ -0,0 +1,8 @@
+"""Normalise Wi-Fi client addresses (strip IPv4-mapped IPv6 prefix)."""
+
+
+def normalize_wifi_peer_ip(ip: str) -> str:
+    s = str(ip).strip()
+    if s.lower().startswith("::ffff:"):
+        s = s[7:]
+    return s

src/models/wifi_ws_clients.py

@@ -0,0 +1,281 @@
+"""Outbound WebSocket clients to Wi-Fi LED drivers (firmware serves ``/ws`` on device)."""
+
+from __future__ import annotations
+
+import asyncio
+import errno
+import json
+import traceback
+
+import websockets
+from websockets.exceptions import ConnectionClosed
+
+_connections: dict[str, object] = {}
+_send_locks: dict[str, asyncio.Lock] = {}
+_tasks: dict[str, asyncio.Task] = {}
+_unreachable_counts: dict[str, int] = {}
+_settings = None
+
+_tcp_status_broadcast = None
+
+
+def set_settings(settings) -> None:
+    global _settings
+    _settings = settings
+
+
+def set_tcp_status_broadcaster(coro) -> None:
+    global _tcp_status_broadcast
+    _tcp_status_broadcast = coro
+
+
+def _schedule_status_broadcast(ip: str, connected: bool) -> None:
+    fn = _tcp_status_broadcast
+    if not fn:
+        return
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        return
+    try:
+        loop.create_task(fn(ip, connected))
+    except Exception:
+        pass
+
+
+def _benign_ws_connect_failure(exc: BaseException) -> bool:
+    """True for common \"driver down / no route\" errors while dialling the WebSocket."""
+    if isinstance(exc, (asyncio.TimeoutError, TimeoutError)):
+        return True
+    if isinstance(exc, ConnectionRefusedError):
+        return True
+    if not isinstance(exc, OSError):
+        return False
+    en = exc.errno
+    if en is None:
+        return False
+    codes = {errno.ECONNREFUSED, errno.ETIMEDOUT}
+    for name in ("EHOSTUNREACH", "ENETUNREACH", "ENETDOWN", "EADDRNOTAVAIL"):
+        if hasattr(errno, name):
+            codes.add(getattr(errno, name))
+    return en in codes
+
+
+def normalize_tcp_peer_ip(ip: str) -> str:
+    """Match peer addresses to registry IPs (strip IPv4-mapped IPv6 prefix)."""
+    s = str(ip).strip()
+    if s.lower().startswith("::ffff:"):
+        s = s[7:]
+    return s
+
+
+def _ws_open(ws) -> bool:
+    try:
+        return ws.close_code is None
+    except Exception:
+        return False
+
+
+def prune_stale_tcp_writers() -> None:
+    """Drop closed WebSocket entries (name kept for callers)."""
+    stale = [ip for ip, ws in list(_connections.items()) if not _ws_open(ws)]
+    for ip in stale:
+        _connections.pop(ip, None)
+        _schedule_status_broadcast(ip, False)
+
+
+def _register_ws(ip: str, ws) -> None:
+    key = normalize_tcp_peer_ip(ip)
+    if not key:
+        return
+    _connections[key] = ws
+    _unreachable_counts.pop(key, None)
+    if key not in _send_locks:
+        _send_locks[key] = asyncio.Lock()
+    _schedule_status_broadcast(key, True)
+    print(f"[WS] driver connected {key!r}")
+
+
+def unregister_tcp_writer(peer_ip: str, ws=None) -> str:
+    """
+    Remove the WebSocket for peer_ip. If ``ws`` is given, only pop when it is still
+    the registered instance.
+
+    Returns ``removed``, ``noop``, or ``superseded`` (same contract as former TCP registry).
+    """
+    if not peer_ip:
+        return "noop"
+    key = normalize_tcp_peer_ip(peer_ip)
+    if not key:
+        return "noop"
+    current = _connections.get(key)
+    if ws is not None:
+        if current is None:
+            return "noop"
+        if current is not ws:
+            return "superseded"
+    had = key in _connections
+    if had:
+        _connections.pop(key, None)
+        _schedule_status_broadcast(key, False)
+        print(f"[WS] driver disconnected: {key}")
+        return "removed"
+    return "noop"
+
+
+def list_connected_ips():
+    """IPs with an active outbound WebSocket to the driver."""
+    prune_stale_tcp_writers()
+    return list(_connections.keys())
+
+
+def tcp_client_connected(ip: str) -> bool:
+    """True if the controller has an outbound WebSocket to this driver IP."""
+    prune_stale_tcp_writers()
+    key = normalize_tcp_peer_ip(ip)
+    return bool(key and key in _connections)
+
+
+async def send_json_line_to_ip(ip: str, json_str: str) -> bool:
+    """Send one JSON text frame (v1 line; trailing newline stripped for WebSocket)."""
+    ip = normalize_tcp_peer_ip(ip)
+    ws = _connections.get(ip)
+    if ws is None or not _ws_open(ws):
+        return False
+    text = json_str.rstrip("\n")
+    lock = _send_locks.setdefault(ip, asyncio.Lock())
+    try:
+        async with lock:
+            await ws.send(text)
+        return True
+    except Exception as exc:
+        print(f"[WS] send to {ip} failed: {exc}")
+        unregister_tcp_writer(ip, ws)
+        return False
+
+
+async def _recv_forward_loop(ip: str, ws) -> None:
+    from models.transport import get_current_sender
+
+    sender = get_current_sender()
+    async for message in ws:
+        if isinstance(message, bytes):
+            try:
+                text = message.decode("utf-8")
+            except UnicodeDecodeError:
+                print(f"[WS] recv {ip} (non-UTF-8, {len(message)} bytes)")
+                continue
+        else:
+            text = message
+        text = text.strip()
+        if not text:
+            continue
+        print(f"[WS] recv {ip}: {text}")
+        if not sender:
+            continue
+        try:
+            parsed = json.loads(text)
+        except json.JSONDecodeError:
+            try:
+                await sender.send(text)
+            except Exception:
+                pass
+            continue
+        if isinstance(parsed, dict):
+            addr = parsed.pop("to", None)
+            payload = json.dumps(parsed) if parsed else "{}"
+            try:
+                await sender.send(payload, addr=addr)
+            except Exception as e:
+                print(f"[WS] forward to bridge failed: {e}")
+        else:
+            try:
+                await sender.send(text)
+            except Exception:
+                pass
+
+
+async def _driver_connection_loop(ip: str) -> None:
+    global _settings
+    if _settings is None:
+        return
+    port = int(_settings.get("wifi_driver_ws_port", 80))
+    path = str(_settings.get("wifi_driver_ws_path", "/ws"))
+    if not path.startswith("/"):
+        path = "/" + path
+    uri = f"ws://{ip}:{port}{path}"
+    retry_interval_s = 2.0
+    retry_window_s = 30.0
+    deadline = asyncio.get_running_loop().time() + retry_window_s
+    try:
+        while True:
+            now = asyncio.get_running_loop().time()
+            if now >= deadline:
+                print(
+                    f"[WS] driver {ip} still unreachable after {int(retry_window_s)}s; "
+                    "stopping retries until next hello"
+                )
+                break
+            try:
+                print(f"[WS] connecting to {uri!r}")
+                async with websockets.connect(
+                    uri,
+                    ping_interval=20,
+                    ping_timeout=15,
+                    open_timeout=30,
+                ) as ws:
+                    _register_ws(ip, ws)
+                    try:
+                        await _recv_forward_loop(ip, ws)
+                    finally:
+                        unregister_tcp_writer(ip, ws)
+            except asyncio.CancelledError:
+                raise
+            except ConnectionClosed as e:
+                print(f"[WS] driver {ip} closed: {e}")
+                unregister_tcp_writer(ip, None)
+            except Exception as e:
+                if _benign_ws_connect_failure(e):
+                    n = _unreachable_counts.get(ip, 0) + 1
+                    _unreachable_counts[ip] = n
+                    if n == 1 or (n % 30) == 0:
+                        print(f"[WS] driver {ip} unreachable, retry in 2s: {e} (x{n})")
+                else:
+                    print(f"[WS] driver {ip} session error: {e!r}")
+                    traceback.print_exception(type(e), e, e.__traceback__)
+                    _unreachable_counts.pop(ip, None)
+                unregister_tcp_writer(ip, None)
+            await asyncio.sleep(retry_interval_s)
+    except asyncio.CancelledError:
+        unregister_tcp_writer(ip, None)
+        raise
+    finally:
+        _tasks.pop(ip, None)
+
+
+def ensure_driver_connection(peer_ip: str) -> None:
+    """Start (or keep) a background task that maintains ``ws://<ip>:port/ws``."""
+    key = normalize_tcp_peer_ip(peer_ip)
+    if not key:
+        return
+    t = _tasks.get(key)
+    if t is not None and not t.done():
+        return
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        return
+    _tasks[key] = loop.create_task(_driver_connection_loop(key))
+
+
+def cancel_all_driver_tasks() -> None:
+    """Signal shutdown: cancel outbound driver connection tasks."""
+    for _ip, t in list(_tasks.items()):
+        if not t.done():
+            t.cancel()
+    _tasks.clear()
+    for ip in list(_connections.keys()):
+        _schedule_status_broadcast(ip, False)
+    _connections.clear()
+    _send_locks.clear()
+    _unreachable_counts.clear()

src/models/zone.py

@@ -0,0 +1,62 @@
+import os
+import shutil
+
+from models.model import Model
+
+
+def _maybe_migrate_tab_json_to_zone():
+    """One-time copy ``db/tab.json`` → ``db/zone.json`` when upgrading."""
+    try:
+        base = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+        db_dir = os.path.join(base, "db")
+        zone_path = os.path.join(db_dir, "zone.json")
+        tab_path = os.path.join(db_dir, "tab.json")
+        if not os.path.exists(zone_path) and os.path.exists(tab_path):
+            shutil.copy2(tab_path, zone_path)
+            print("Migrated db/tab.json -> db/zone.json")
+    except OSError:
+        pass
+
+
+class Zone(Model):
+    """Preset layout row (stored in ``db/zone.json``); legacy storage was ``tab.json`` / Tab."""
+
+    def __init__(self):
+        if not getattr(Zone, "_migration_checked", False):
+            _maybe_migrate_tab_json_to_zone()
+            Zone._migration_checked = True
+        super().__init__()
+
+    def create(self, name="", names=None, presets=None):
+        next_id = self.get_next_id()
+        self[next_id] = {
+            "name": name,
+            "names": names if names else [],
+            "presets": presets if presets else [],
+            "default_preset": None,
+        }
+        self.save()
+        return next_id
+
+    def read(self, id):
+        id_str = str(id)
+        return self.get(id_str, None)
+
+    def update(self, id, data):
+        id_str = str(id)
+        if id_str not in self:
+            return False
+        self[id_str].update(data)
+        self.save()
+        return True
+
+    def delete(self, id):
+        id_str = str(id)
+        if id_str not in self:
+            return False
+        self.pop(id_str)
+        self.save()
+        return True
+
+    def list(self):
+        return list(self.keys())

src/settings.py

@@ -1,17 +1,62 @@
 import json
-import wifi
+import os
-import ubinascii
+import binascii
-import machine
+
+
+def _settings_path():
+    """Path to settings.json in project root (writable without root)."""
+    try:
+        base = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        return os.path.join(base, "settings.json")
+    except Exception:
+        return "settings.json"
+
 
 class Settings(dict):
-    SETTINGS_FILE = "/settings.json"
+    SETTINGS_FILE = None  # Set in __init__ from _settings_path()
 
     def __init__(self):
         super().__init__()
+        if Settings.SETTINGS_FILE is None:
+            Settings.SETTINGS_FILE = _settings_path()
         self.load()  # Load settings from file during initialization
 
+    def generate_secret_key(self):
+        """Generate a random secret key for session signing."""
+        try:
+            # Try to use os.urandom for secure random bytes
+            random_bytes = os.urandom(32)
+            return binascii.hexlify(random_bytes).decode('utf-8')
+        except (AttributeError, NotImplementedError):
+            # Fallback for MicroPython or systems without os.urandom
+            try:
+                import secrets
+                return secrets.token_hex(32)
+            except ImportError:
+                # Last resort: use a combination of time and random
+                import time
+                import random
+                random.seed(time.time())
+                return binascii.hexlify(bytes([random.randint(0, 255) for _ in range(32)])).decode('utf-8')
+
     def set_defaults(self):
-        self = {}
+        """Set default settings if they don't exist."""
+        if 'session_secret_key' not in self:
+            self['session_secret_key'] = self.generate_secret_key()
+            # Save immediately when generating a new key
+            self.save()
+        # ESP-NOW STA channel (2.4 GHz) for LED drivers / bridge alignment; 1–11
+        if 'wifi_channel' not in self:
+            self['wifi_channel'] = 6
+        # Wi-Fi LED drivers: controller opens WebSocket to device (firmware serves /ws)
+        if 'wifi_driver_ws_port' not in self:
+            self['wifi_driver_ws_port'] = 80
+        if 'wifi_driver_ws_path' not in self:
+            self['wifi_driver_ws_path'] = '/ws'
+        # Seconds between UDP discovery nudges when a Wi-Fi driver WebSocket is
+        # down (0 disables). Helps drivers that reconnect after seeing traffic on 8766.
+        if 'wifi_driver_hello_interval_s' not in self:
+            self['wifi_driver_hello_interval_s'] = 10.0
 
     def save(self):
         try:
@@ -23,12 +68,19 @@ class Settings(dict):
             print(f"Error saving settings: {e}")
 
     def load(self):
+        loaded_from_file = False
         try:
             with open(self.SETTINGS_FILE, 'r') as file:
                 loaded_settings = json.load(file)
             self.update(loaded_settings)
+            loaded_from_file = True
             print("Settings loaded successfully.")
         except Exception as e:
             print(f"Error loading settings")
+            self.clear()
+        finally:
+            # Ensure defaults are set even if file exists but is missing keys
             self.set_defaults()
-            self.save()
+            # Only save if file didn't exist or was invalid
+            if not loaded_from_file:
+                self.save()

src/static/color_palette.js

@@ -0,0 +1,194 @@
+document.addEventListener('DOMContentLoaded', () => {
+  const paletteButton = document.getElementById('color-palette-btn');
+  const paletteModal = document.getElementById('color-palette-modal');
+  const closeButton = document.getElementById('color-palette-close-btn');
+  const paletteContainer = document.getElementById('palette-container');
+  const paletteNewColor = document.getElementById('palette-new-color');
+  const profileNameDisplay = document.getElementById('palette-current-profile-name');
+
+  if (!paletteButton || !paletteModal || !paletteContainer) {
+    return;
+  }
+
+  let currentProfileId = null;
+  let currentPaletteId = null;
+  let currentPalette = [];
+  let currentProfileName = null;
+
+  const renderPalette = () => {
+    paletteContainer.innerHTML = '';
+    if (!currentPalette.length) {
+      const empty = document.createElement('p');
+      empty.className = 'muted-text';
+      empty.textContent = 'No colors in palette.';
+      paletteContainer.appendChild(empty);
+      return;
+    }
+    currentPalette.forEach((color, index) => {
+      const row = document.createElement('div');
+      row.className = 'profiles-row';
+      row.dataset.color = color;
+      row.style.cssText = 'display: flex; align-items: center; gap: 1rem;';
+      // Ensure no text content
+      row.textContent = '';
+
+      const swatch = document.createElement('div');
+      swatch.style.cssText = `
+        width: 64px;
+        height: 64px;
+        border-radius: 8px;
+        background-color: ${color};
+        border: 2px solid #4a4a4a;
+        cursor: pointer;
+        flex-shrink: 0;
+        box-shadow: 0 2px 4px rgba(0,0,0,0.3);
+      `;
+      swatch.title = color; // Show hex code on hover only
+      swatch.setAttribute('aria-label', `Color ${color}`);
+
+      const removeButton = document.createElement('button');
+      removeButton.className = 'btn btn-danger btn-small';
+      removeButton.textContent = 'Remove';
+      removeButton.style.fontSize = '0.8rem'; // Restore font size for button
+      removeButton.addEventListener('click', async (e) => {
+        e.stopPropagation();
+        const updated = currentPalette.filter((_, i) => i !== index);
+        await savePalette(updated);
+      });
+
+      row.appendChild(swatch);
+      row.appendChild(removeButton);
+      paletteContainer.appendChild(row);
+    });
+  };
+
+  const loadPalette = async () => {
+    try {
+      const currentResponse = await fetch('/profiles/current', {
+        headers: { Accept: 'application/json' },
+      });
+      if (!currentResponse.ok) {
+        throw new Error('Failed to load current profile');
+      }
+      const currentData = await currentResponse.json();
+      currentProfileId = currentData.id || null;
+      const profile = currentData.profile || null;
+      currentProfileName = profile ? profile.name : null;
+      if (profileNameDisplay) {
+        profileNameDisplay.textContent = currentProfileName || currentProfileId || 'None';
+      }
+
+      if (!currentProfileId || !profile) {
+        currentPalette = [];
+        renderPalette();
+        return;
+      }
+
+      // Prefer palette_id-based storage; fall back to legacy inline palette.
+      currentPaletteId = profile.palette_id || profile.paletteId || null;
+      if (currentPaletteId) {
+        try {
+          const palResponse = await fetch(`/palettes/${currentPaletteId}`, {
+            headers: { Accept: 'application/json' },
+          });
+          if (palResponse.ok) {
+            const palData = await palResponse.json();
+            currentPalette = (palData.colors) || [];
+          } else {
+            currentPalette = [];
+          }
+        } catch (e) {
+          console.error('Failed to load palette by id:', e);
+          currentPalette = [];
+        }
+      } else {
+        // Legacy: palette stored directly on profile
+        currentPalette = profile.palette || profile.color_palette || [];
+      }
+      renderPalette();
+    } catch (error) {
+      console.error('Failed to load palette:', error);
+      currentPalette = [];
+      renderPalette();
+    }
+  };
+
+  const savePalette = async (newPalette) => {
+    if (!currentProfileId) {
+      alert('No profile selected.');
+      return;
+    }
+    try {
+      // Ensure we have a palette ID for this profile.
+      if (!currentPaletteId) {
+        const createResponse = await fetch('/palettes', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ colors: newPalette }),
+        });
+        if (!createResponse.ok) {
+          throw new Error('Failed to create palette');
+        }
+        const pal = await createResponse.json();
+        currentPaletteId = pal.id || Object.keys(pal)[0];
+
+        // Link the new palette to the current profile.
+        const linkResponse = await fetch('/profiles/current', {
+          method: 'PUT',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            palette_id: currentPaletteId,
+          }),
+        });
+        if (!linkResponse.ok) {
+          throw new Error('Failed to link palette to profile');
+        }
+      } else {
+        // Update existing palette colors
+        const updateResponse = await fetch(`/palettes/${currentPaletteId}`, {
+          method: 'PUT',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ colors: newPalette }),
+        });
+        if (!updateResponse.ok) {
+          throw new Error('Failed to save palette');
+        }
+      }
+
+      currentPalette = newPalette;
+      renderPalette();
+    } catch (error) {
+      console.error('Failed to save palette:', error);
+      alert('Failed to save palette.');
+    }
+  };
+
+  const openModal = () => {
+    paletteModal.classList.add('active');
+    loadPalette();
+  };
+
+  const closeModal = () => {
+    paletteModal.classList.remove('active');
+  };
+
+  paletteButton.addEventListener('click', openModal);
+  if (closeButton) {
+    closeButton.addEventListener('click', closeModal);
+  }
+  if (paletteNewColor) {
+    const addSelectedColor = async () => {
+      const color = paletteNewColor.value;
+      if (!color) {
+        return;
+      }
+      if (currentPalette.includes(color)) {
+        alert('Color already in palette.');
+        return;
+      }
+      await savePalette([...currentPalette, color]);
+    };
+    // Add when the picker closes (user confirms selection).
+    paletteNewColor.addEventListener('change', addSelectedColor);
+  }
+});

src/static/devices.js

@@ -0,0 +1,446 @@
+// Device registry: name, id (storage key), type (led), transport (wifi|espnow), address
+
+const HEX_BOX_COUNT = 12;
+
+/** Last TCP snapshot from WebSocket (so we can apply after async list render). */
+let lastTcpSnapshotIps = null;
+
+/** Match server-side ``normalize_tcp_peer_ip`` for WS events vs registry rows. */
+function normalizeWifiAddressForMatch(addr) {
+    let s = String(addr || '').trim();
+    if (s.toLowerCase().startsWith('::ffff:')) {
+        s = s.slice(7);
+    }
+    return s;
+}
+
+const DEVICES_MODAL_POLL_MS = 1000;
+
+let devicesModalLiveTimer = null;
+
+function stopDevicesModalLiveRefresh() {
+    if (devicesModalLiveTimer != null) {
+        clearInterval(devicesModalLiveTimer);
+        devicesModalLiveTimer = null;
+    }
+}
+
+/**
+ * Refetch registry and re-render the list (no loading spinner). Keeps scroll position.
+ * Used while the devices modal stays open so new TCP devices, renames, and removals appear live.
+ */
+async function refreshDevicesListQuiet() {
+    const modal = document.getElementById('devices-modal');
+    if (!modal || !modal.classList.contains('active')) return;
+    const container = document.getElementById('devices-list-modal');
+    if (!container) return;
+    const prevTop = container.scrollTop;
+    try {
+        const res = await fetch('/devices', { headers: { Accept: 'application/json' } });
+        if (!res.ok) return;
+        const data = await res.json();
+        renderDevicesList(data || {});
+        container.scrollTop = prevTop;
+    } catch (_) {
+        /* ignore */
+    }
+}
+
+function startDevicesModalLiveRefresh() {
+    stopDevicesModalLiveRefresh();
+    devicesModalLiveTimer = setInterval(() => {
+        refreshDevicesListQuiet();
+    }, DEVICES_MODAL_POLL_MS);
+}
+
+function updateWifiRowDot(row, connected) {
+    const dot = row.querySelector('.device-status-dot');
+    if (!dot) return;
+    if ((row.dataset.deviceTransport || '') !== 'wifi') return;
+    dot.classList.remove('device-status-dot--online', 'device-status-dot--offline', 'device-status-dot--unknown');
+    if (connected) {
+        dot.classList.add('device-status-dot--online');
+        dot.title = 'Connected (Wi-Fi TCP session)';
+    } else {
+        dot.classList.add('device-status-dot--offline');
+        dot.title = 'Not connected (no Wi-Fi TCP session)';
+    }
+    dot.setAttribute('aria-label', dot.title);
+}
+
+function applyTcpSnapshot(ips) {
+    const set = new Set(
+        (ips || []).map((x) => normalizeWifiAddressForMatch(x)).filter(Boolean),
+    );
+    const container = document.getElementById('devices-list-modal');
+    if (!container) return;
+    container.querySelectorAll('.profiles-row[data-device-transport="wifi"]').forEach((row) => {
+        const addr = normalizeWifiAddressForMatch(row.dataset.deviceAddress);
+        updateWifiRowDot(row, set.has(addr));
+    });
+}
+
+/** Keep cached snapshot aligned with incremental WS events (connect/disconnect). */
+function mergeTcpSnapshotPresence(ip, connected) {
+    const n = normalizeWifiAddressForMatch(ip);
+    if (!n) return;
+    const prev = lastTcpSnapshotIps;
+    const set = new Set(
+        (Array.isArray(prev) ? prev : []).map((x) => normalizeWifiAddressForMatch(x)).filter(Boolean),
+    );
+    if (connected) {
+        set.add(n);
+    } else {
+        set.delete(n);
+    }
+    lastTcpSnapshotIps = Array.from(set);
+}
+
+function makeHexAddressBoxes(container) {
+    if (!container || container.querySelector('.hex-addr-box')) return;
+    container.innerHTML = '';
+    for (let i = 0; i < HEX_BOX_COUNT; i++) {
+        const input = document.createElement('input');
+        input.type = 'text';
+        input.className = 'hex-addr-box';
+        input.maxLength = 1;
+        input.autocomplete = 'off';
+        input.setAttribute('data-index', i);
+        input.setAttribute('inputmode', 'numeric');
+        input.setAttribute('aria-label', `Hex digit ${i + 1}`);
+        input.addEventListener('input', (e) => {
+            const v = e.target.value.replace(/[^0-9a-fA-F]/g, '');
+            e.target.value = v;
+            if (v && e.target.nextElementSibling && e.target.nextElementSibling.classList.contains('hex-addr-box')) {
+                e.target.nextElementSibling.focus();
+            }
+        });
+        input.addEventListener('keydown', (e) => {
+            if (e.key === 'Backspace' && !e.target.value && e.target.previousElementSibling) {
+                e.target.previousElementSibling.focus();
+            }
+        });
+        input.addEventListener('paste', (e) => {
+            e.preventDefault();
+            const pasted = (e.clipboardData.getData('text') || '').replace(/[^0-9a-fA-F]/g, '').slice(0, HEX_BOX_COUNT);
+            const boxes = container.querySelectorAll('.hex-addr-box');
+            for (let j = 0; j < pasted.length && j < boxes.length; j++) {
+                boxes[j].value = pasted[j];
+            }
+            if (pasted.length > 0) {
+                const nextIdx = Math.min(pasted.length, boxes.length - 1);
+                boxes[nextIdx].focus();
+            }
+        });
+        container.appendChild(input);
+    }
+}
+
+function setAddressToBoxes(container, addrStr) {
+    if (!container) return;
+    const s = (addrStr || '').replace(/[^0-9a-fA-F]/g, '').slice(0, HEX_BOX_COUNT);
+    const boxes = container.querySelectorAll('.hex-addr-box');
+    boxes.forEach((b, i) => {
+        b.value = s[i] || '';
+    });
+}
+
+function applyTransportVisibility(transport) {
+    const isWifi = transport === 'wifi';
+    const esp = document.getElementById('edit-device-address-espnow');
+    const wifiWrap = document.getElementById('edit-device-address-wifi-wrap');
+    if (esp) esp.hidden = isWifi;
+    if (wifiWrap) wifiWrap.hidden = !isWifi;
+}
+
+function getAddressForPayload(transport) {
+    if (transport === 'wifi') {
+        const el = document.getElementById('edit-device-address-wifi');
+        const v = (el && el.value.trim()) || '';
+        return v || null;
+    }
+    const boxEl = document.getElementById('edit-device-address-boxes');
+    if (!boxEl) return null;
+    const boxes = boxEl.querySelectorAll('.hex-addr-box');
+    const hex = Array.from(boxes).map((b) => b.value).join('').toLowerCase();
+    return hex || null;
+}
+
+async function loadDevicesModal() {
+    const container = document.getElementById('devices-list-modal');
+    if (!container) return;
+    if (typeof window.getEspnowSocket === 'function') {
+        window.getEspnowSocket();
+    }
+    container.innerHTML = '<span class="muted-text">Loading...</span>';
+    try {
+        const response = await fetch('/devices', { headers: { Accept: 'application/json' } });
+        if (!response.ok) throw new Error('Failed to load devices');
+        const devices = await response.json();
+        renderDevicesList(devices || {});
+    } catch (e) {
+        console.error('loadDevicesModal:', e);
+        container.innerHTML = '<span class="muted-text">Failed to load devices.</span>';
+    }
+}
+
+function renderDevicesList(devices) {
+    const container = document.getElementById('devices-list-modal');
+    if (!container) return;
+    container.innerHTML = '';
+    const ids = Object.keys(devices).filter((k) => devices[k] && typeof devices[k] === 'object');
+    if (ids.length === 0) {
+        const p = document.createElement('p');
+        p.className = 'muted-text';
+        p.textContent = 'No devices yet. Wi-Fi drivers will appear here when they connect over TCP.';
+        container.appendChild(p);
+        return;
+    }
+    ids.forEach((devId) => {
+        const dev = devices[devId];
+        const t = (dev && dev.type) || 'led';
+        const tr = (dev && dev.transport) || 'espnow';
+        const addrRaw = (dev && dev.address) != null ? String(dev.address).trim() : '';
+        const addrDisplay = addrRaw || '—';
+
+        const row = document.createElement('div');
+        row.className = 'profiles-row';
+        row.style.display = 'flex';
+        row.style.alignItems = 'center';
+        row.style.gap = '0.5rem';
+        row.style.flexWrap = 'wrap';
+        row.dataset.deviceId = devId;
+        row.dataset.deviceTransport = tr;
+        row.dataset.deviceAddress = addrRaw;
+
+        const dot = document.createElement('span');
+        dot.className = 'device-status-dot';
+        dot.setAttribute('role', 'img');
+        const live = dev && Object.prototype.hasOwnProperty.call(dev, 'connected') ? dev.connected : null;
+        if (live === true) {
+            dot.classList.add('device-status-dot--online');
+            dot.title = 'Connected (Wi-Fi TCP session)';
+            dot.setAttribute('aria-label', dot.title);
+        } else if (live === false) {
+            dot.classList.add('device-status-dot--offline');
+            dot.title = 'Not connected (no Wi-Fi TCP session)';
+            dot.setAttribute('aria-label', dot.title);
+        } else {
+            dot.classList.add('device-status-dot--unknown');
+            dot.title = 'ESP-NOW — TCP status does not apply';
+            dot.setAttribute('aria-label', dot.title);
+        }
+
+        const label = document.createElement('span');
+        label.textContent = (dev && dev.name) || devId;
+        label.style.flex = '1';
+        label.style.minWidth = '100px';
+
+        const macEl = document.createElement('code');
+        macEl.className = 'device-row-mac';
+        macEl.textContent = devId;
+        macEl.title = 'MAC (registry id)';
+
+        const meta = document.createElement('span');
+        meta.className = 'muted-text';
+        meta.style.fontSize = '0.85em';
+        meta.textContent = `${t} · ${tr} · ${addrDisplay}`;
+
+        const editBtn = document.createElement('button');
+        editBtn.className = 'btn btn-secondary btn-small';
+        editBtn.textContent = 'Edit';
+        editBtn.addEventListener('click', () => openEditDeviceModal(devId, dev));
+
+        const identifyBtn = document.createElement('button');
+        identifyBtn.className = 'btn btn-primary btn-small';
+        identifyBtn.type = 'button';
+        identifyBtn.textContent = 'Identify';
+        identifyBtn.title = 'Red blink at 10 Hz (~50% brightness) for 2 s, then off (not saved as a preset)';
+        identifyBtn.addEventListener('click', async () => {
+            try {
+                const res = await fetch(`/devices/${encodeURIComponent(devId)}/identify`, {
+                    method: 'POST',
+                    credentials: 'same-origin',
+                    headers: { Accept: 'application/json' },
+                });
+                const data = await res.json().catch(() => ({}));
+                if (!res.ok) {
+                    alert(data.error || 'Identify failed');
+                    return;
+                }
+            } catch (err) {
+                console.error(err);
+                alert('Identify failed');
+            }
+        });
+
+        const deleteBtn = document.createElement('button');
+        deleteBtn.className = 'btn btn-secondary btn-small';
+        deleteBtn.textContent = 'Delete';
+        deleteBtn.addEventListener('click', async () => {
+            if (!confirm(`Delete device "${(dev && dev.name) || devId}"?`)) return;
+            try {
+                const res = await fetch(`/devices/${encodeURIComponent(devId)}`, { method: 'DELETE' });
+                if (res.ok) await loadDevicesModal();
+                else {
+                    const data = await res.json().catch(() => ({}));
+                    alert(data.error || 'Delete failed');
+                }
+            } catch (err) {
+                console.error(err);
+                alert('Delete failed');
+            }
+        });
+
+        row.appendChild(dot);
+        row.appendChild(label);
+        row.appendChild(macEl);
+        row.appendChild(meta);
+        row.appendChild(editBtn);
+        row.appendChild(identifyBtn);
+        row.appendChild(deleteBtn);
+        container.appendChild(row);
+    });
+    // Do not re-apply lastTcpSnapshotIps here: it is only updated on WS open and
+    // device_tcp events; re-applying after each /devices poll overwrites correct
+    // API "connected" with a stale list and leaves Wi-Fi rows stuck online.
+}
+
+function openEditDeviceModal(devId, dev) {
+    const modal = document.getElementById('edit-device-modal');
+    const idInput = document.getElementById('edit-device-id');
+    const storageLabel = document.getElementById('edit-device-storage-id');
+    const nameInput = document.getElementById('edit-device-name');
+    const typeSel = document.getElementById('edit-device-type');
+    const transportSel = document.getElementById('edit-device-transport');
+    const addressBoxes = document.getElementById('edit-device-address-boxes');
+    const wifiInput = document.getElementById('edit-device-address-wifi');
+    if (!modal || !idInput) return;
+    idInput.value = devId;
+    if (storageLabel) storageLabel.textContent = devId;
+    if (nameInput) nameInput.value = (dev && dev.name) || '';
+    if (typeSel) typeSel.value = (dev && dev.type) || 'led';
+    const tr = (dev && dev.transport) || 'espnow';
+    if (transportSel) transportSel.value = tr;
+    applyTransportVisibility(tr);
+    setAddressToBoxes(addressBoxes, tr === 'espnow' ? ((dev && dev.address) || '') : '');
+    if (wifiInput) wifiInput.value = tr === 'wifi' ? ((dev && dev.address) || '') : '';
+    modal.classList.add('active');
+}
+
+async function updateDevice(devId, name, type, transport, address) {
+    try {
+        const res = await fetch(`/devices/${encodeURIComponent(devId)}`, {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                name,
+                type: type || 'led',
+                transport: transport || 'espnow',
+                address,
+            }),
+        });
+        const data = await res.json().catch(() => ({}));
+        if (res.ok) {
+            await loadDevicesModal();
+            return true;
+        }
+        alert(data.error || 'Failed to update device');
+        return false;
+    } catch (e) {
+        console.error('updateDevice:', e);
+        alert('Failed to update device');
+        return false;
+    }
+}
+
+document.addEventListener('DOMContentLoaded', () => {
+    window.addEventListener('deviceTcpStatus', (ev) => {
+        const { ip, connected } = ev.detail || {};
+        if (ip == null || typeof connected !== 'boolean') return;
+        mergeTcpSnapshotPresence(ip, connected);
+        const norm = normalizeWifiAddressForMatch(ip);
+        const container = document.getElementById('devices-list-modal');
+        if (!container) return;
+        container.querySelectorAll('.profiles-row[data-device-transport="wifi"]').forEach((row) => {
+            if (normalizeWifiAddressForMatch(row.dataset.deviceAddress) === norm) {
+                updateWifiRowDot(row, connected);
+            }
+        });
+    });
+    window.addEventListener('deviceTcpSnapshot', (ev) => {
+        const ips = ev.detail && ev.detail.connectedIps;
+        lastTcpSnapshotIps = ips;
+        applyTcpSnapshot(ips);
+    });
+
+    window.addEventListener('deviceTcpWsOpen', () => {
+        refreshDevicesListQuiet();
+    });
+
+    makeHexAddressBoxes(document.getElementById('edit-device-address-boxes'));
+
+    const transportEdit = document.getElementById('edit-device-transport');
+    if (transportEdit) {
+        transportEdit.addEventListener('change', () => {
+            applyTransportVisibility(transportEdit.value);
+        });
+    }
+
+    const devicesBtn = document.getElementById('devices-btn');
+    const devicesModal = document.getElementById('devices-modal');
+    const devicesCloseBtn = document.getElementById('devices-close-btn');
+    const editForm = document.getElementById('edit-device-form');
+    const editCloseBtn = document.getElementById('edit-device-close-btn');
+    const editDeviceModal = document.getElementById('edit-device-modal');
+
+    if (devicesBtn && devicesModal) {
+        devicesBtn.addEventListener('click', () => {
+            devicesModal.classList.add('active');
+            if (typeof window.getEspnowSocket === 'function') {
+                window.getEspnowSocket();
+            }
+            loadDevicesModal();
+            startDevicesModalLiveRefresh();
+        });
+    }
+    if (devicesCloseBtn) {
+        devicesCloseBtn.addEventListener('click', () => {
+            if (devicesModal) devicesModal.classList.remove('active');
+        });
+    }
+
+    const devicesModalEl = document.getElementById('devices-modal');
+    if (devicesModalEl) {
+        new MutationObserver(() => {
+            if (!devicesModalEl.classList.contains('active')) {
+                stopDevicesModalLiveRefresh();
+            }
+        }).observe(devicesModalEl, { attributes: true, attributeFilter: ['class'] });
+    }
+
+    if (editForm) {
+        editForm.addEventListener('submit', async (e) => {
+            e.preventDefault();
+            const idInput = document.getElementById('edit-device-id');
+            const nameInput = document.getElementById('edit-device-name');
+            const typeSel = document.getElementById('edit-device-type');
+            const transportSel = document.getElementById('edit-device-transport');
+            const devId = idInput && idInput.value;
+            if (!devId) return;
+            const transport = (transportSel && transportSel.value) || 'espnow';
+            const address = getAddressForPayload(transport);
+            const ok = await updateDevice(
+                devId,
+                nameInput ? nameInput.value.trim() : '',
+                (typeSel && typeSel.value) || 'led',
+                transport,
+                address
+            );
+            if (ok) editDeviceModal.classList.remove('active');
+        });
+    }
+    if (editCloseBtn) {
+        editCloseBtn.addEventListener('click', () => editDeviceModal && editDeviceModal.classList.remove('active'));
+    }
+});

src/static/help.js

@@ -0,0 +1,197 @@
+document.addEventListener('DOMContentLoaded', () => {
+  // Help modal
+  const helpBtn = document.getElementById('help-btn');
+  const helpModal = document.getElementById('help-modal');
+  const helpCloseBtn = document.getElementById('help-close-btn');
+  const mainMenuBtn = document.getElementById('main-menu-btn');
+  const mainMenuDropdown = document.getElementById('main-menu-dropdown');
+
+  if (helpBtn && helpModal) {
+    helpBtn.addEventListener('click', () => {
+      helpModal.classList.add('active');
+    });
+  }
+
+  if (helpCloseBtn && helpModal) {
+    helpCloseBtn.addEventListener('click', () => {
+      helpModal.classList.remove('active');
+    });
+  }
+
+  // Mobile main menu: forward clicks to existing header buttons
+  if (mainMenuBtn && mainMenuDropdown) {
+    mainMenuBtn.addEventListener('click', () => {
+      mainMenuDropdown.classList.toggle('open');
+    });
+
+    mainMenuDropdown.addEventListener('click', (event) => {
+      const target = event.target;
+      if (target && target.matches('button[data-target]')) {
+        const id = target.getAttribute('data-target');
+        const realBtn = document.getElementById(id);
+        if (realBtn) {
+          realBtn.click();
+        }
+        mainMenuDropdown.classList.remove('open');
+      }
+    });
+  }
+
+  // Settings modal wiring (reusing existing settings endpoints).
+  const settingsButton = document.getElementById('settings-btn');
+  const settingsModal = document.getElementById('settings-modal');
+  const settingsCloseButton = document.getElementById('settings-close-btn');
+
+  const showSettingsMessage = (text, type = 'success') => {
+    const messageEl = document.getElementById('settings-message');
+    if (!messageEl) return;
+    messageEl.textContent = text;
+    messageEl.className = `message ${type} show`;
+    setTimeout(() => {
+      messageEl.classList.remove('show');
+    }, 5000);
+  };
+
+  async function loadDeviceSettings() {
+    try {
+      const response = await fetch('/settings');
+      const data = await response.json();
+      const nameInput = document.getElementById('device-name-input');
+      if (nameInput && data && typeof data === 'object') {
+        nameInput.value = data.device_name || 'led-controller';
+      }
+      const chInput = document.getElementById('wifi-channel-input');
+      if (chInput && data && typeof data === 'object') {
+        const ch = data.wifi_channel;
+        chInput.value =
+          ch !== undefined && ch !== null && ch !== '' ? String(ch) : '6';
+      }
+    } catch (error) {
+      console.error('Error loading device settings:', error);
+    }
+  }
+
+  async function loadAPStatus() {
+    try {
+      const response = await fetch('/settings/wifi/ap');
+      const config = await response.json();
+      const statusEl = document.getElementById('ap-status');
+      if (!statusEl) return;
+      if (config.active) {
+        statusEl.innerHTML = `
+          <h4>AP Status: <span class="status-connected">Active</span></h4>
+          <p><strong>SSID:</strong> ${config.ssid || 'N/A'}</p>
+          <p><strong>Channel:</strong> ${config.channel || 'Auto'}</p>
+          <p><strong>IP Address:</strong> ${config.ip || 'N/A'}</p>
+        `;
+      } else {
+        statusEl.innerHTML = `
+          <h4>AP Status: <span class="status-disconnected">Inactive</span></h4>
+          <p>Access Point is not currently active</p>
+        `;
+      }
+      if (config.saved_ssid) document.getElementById('ap-ssid').value = config.saved_ssid;
+      if (config.saved_channel) document.getElementById('ap-channel').value = config.saved_channel;
+    } catch (error) {
+      console.error('Error loading AP status:', error);
+    }
+  }
+
+  if (settingsButton && settingsModal) {
+    settingsButton.addEventListener('click', () => {
+      settingsModal.classList.add('active');
+      // Load current WiFi status/config when opening
+      loadDeviceSettings();
+      loadAPStatus();
+    });
+  }
+
+  if (settingsCloseButton && settingsModal) {
+    settingsCloseButton.addEventListener('click', () => {
+      settingsModal.classList.remove('active');
+    });
+  }
+
+  const deviceForm = document.getElementById('device-form');
+  if (deviceForm) {
+    deviceForm.addEventListener('submit', async (e) => {
+      e.preventDefault();
+      const nameInput = document.getElementById('device-name-input');
+      const deviceName = nameInput ? nameInput.value.trim() : '';
+      if (!deviceName) {
+        showSettingsMessage('Device name is required', 'error');
+        return;
+      }
+      const chRaw = document.getElementById('wifi-channel-input')
+        ? document.getElementById('wifi-channel-input').value
+        : '6';
+      const wifiChannel = parseInt(chRaw, 10);
+      if (Number.isNaN(wifiChannel) || wifiChannel < 1 || wifiChannel > 11) {
+        showSettingsMessage('WiFi channel must be between 1 and 11', 'error');
+        return;
+      }
+      try {
+        const response = await fetch('/settings/settings', {
+          method: 'PUT',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            device_name: deviceName,
+            wifi_channel: wifiChannel,
+          }),
+        });
+        const result = await response.json();
+        if (response.ok) {
+          showSettingsMessage(
+            'Device settings saved. They will apply on next restart where relevant.',
+            'success',
+          );
+        } else {
+          showSettingsMessage(`Error: ${result.error || 'Failed to save device name'}`, 'error');
+        }
+      } catch (error) {
+        showSettingsMessage(`Error: ${error.message}`, 'error');
+      }
+    });
+  }
+  const apForm = document.getElementById('ap-form');
+  if (apForm) {
+    apForm.addEventListener('submit', async (e) => {
+      e.preventDefault();
+      const formData = {
+        ssid: document.getElementById('ap-ssid').value,
+        password: document.getElementById('ap-password').value,
+        channel: document.getElementById('ap-channel').value || null,
+      };
+
+      if (formData.password && formData.password.length > 0 && formData.password.length < 8) {
+        showSettingsMessage('AP password must be at least 8 characters', 'error');
+        return;
+      }
+
+      if (formData.channel) {
+        formData.channel = parseInt(formData.channel, 10);
+        if (formData.channel < 1 || formData.channel > 11) {
+          showSettingsMessage('Channel must be between 1 and 11', 'error');
+          return;
+        }
+      }
+
+      try {
+        const response = await fetch('/settings/wifi/ap', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(formData),
+        });
+        const result = await response.json();
+        if (response.ok) {
+          showSettingsMessage('Access Point configured successfully!', 'success');
+          setTimeout(loadAPStatus, 1000);
+        } else {
+          showSettingsMessage(`Error: ${result.error || 'Failed to configure AP'}`, 'error');
+        }
+      } catch (error) {
+        showSettingsMessage(`Error: ${error.message}`, 'error');
+      }
+    });
+  }
+});

src/static/led_tool.js

@@ -0,0 +1,255 @@
+document.addEventListener('DOMContentLoaded', () => {
+  const openBtn = document.getElementById('led-tool-btn');
+  const modal = document.getElementById('led-tool-modal');
+  const closeBtn = document.getElementById('led-tool-close-btn');
+  const refreshPortsBtn = document.getElementById('led-tool-refresh-ports-btn');
+  const form = document.getElementById('led-tool-form');
+  const readBtn = document.getElementById('led-tool-read-btn');
+  const resetBtn = document.getElementById('led-tool-reset-btn');
+  const portSelect = document.getElementById('led-tool-port');
+  const outputEl = document.getElementById('led-tool-output');
+  const messageEl = document.getElementById('led-tool-message');
+
+  if (!openBtn || !modal || !form || !portSelect || !outputEl || !messageEl) {
+    return;
+  }
+
+  const showMessage = (text, type = 'success') => {
+    messageEl.textContent = text;
+    messageEl.className = `message ${type} show`;
+  };
+
+  const setOutput = (text) => {
+    outputEl.value = text || '';
+  };
+
+  const parseApiResponse = async (response) => {
+    const bodyText = await response.text();
+    let data = null;
+    try {
+      data = bodyText ? JSON.parse(bodyText) : {};
+    } catch (error) {
+      data = { error: bodyText || `HTTP ${response.status}` };
+    }
+    return data;
+  };
+
+  const setFieldValue = (id, value) => {
+    const el = document.getElementById(id);
+    if (!el) return;
+    if (value === undefined || value === null) return;
+    el.value = String(value);
+  };
+
+  const populateFormFromSettings = (settings) => {
+    if (!settings || typeof settings !== 'object') return false;
+    setFieldValue('led-tool-name', settings.name);
+    setFieldValue('led-tool-num-leds', settings.num_leds);
+    setFieldValue('led-tool-led-pin', settings.led_pin);
+    setFieldValue('led-tool-brightness', settings.brightness);
+    setFieldValue('led-tool-transport', settings.transport_type);
+    setFieldValue('led-tool-ssid', settings.ssid);
+    setFieldValue('led-tool-password', settings.password);
+    setFieldValue('led-tool-wifi-channel', settings.wifi_channel);
+    setFieldValue('led-tool-default', settings.default);
+    return true;
+  };
+
+  const loadPorts = async () => {
+    const defaultPort = '/dev/ttyACM0';
+    try {
+      const response = await fetch('/led-tool/ports');
+      const data = await response.json();
+      const previous = portSelect.value;
+      portSelect.innerHTML = '<option value="">Select a serial port</option>';
+
+      for (const port of data.ports || []) {
+        const option = document.createElement('option');
+        option.value = port.device;
+        option.textContent = `${port.device} - ${port.description || 'Unknown'}`;
+        portSelect.appendChild(option);
+      }
+      if (previous) {
+        portSelect.value = previous;
+      } else if ((data.ports || []).some((p) => p.device === defaultPort)) {
+        portSelect.value = defaultPort;
+      } else {
+        const fallback = document.createElement('option');
+        fallback.value = defaultPort;
+        fallback.textContent = `${defaultPort} - default`;
+        portSelect.appendChild(fallback);
+        portSelect.value = defaultPort;
+      }
+
+      if (!data.led_cli_exists) {
+        showMessage('led-tool/cli.py was not found on the host.', 'error');
+      } else if ((data.ports || []).length === 0) {
+        showMessage('No serial ports found.', 'error');
+      } else {
+        showMessage(`Found ${(data.ports || []).length} serial port(s).`, 'success');
+      }
+    } catch (error) {
+      showMessage(`Failed to read serial ports: ${error.message}`, 'error');
+    }
+  };
+
+  openBtn.addEventListener('click', () => {
+    modal.classList.add('active');
+    loadPorts();
+  });
+
+  if (closeBtn) {
+    closeBtn.addEventListener('click', () => {
+      modal.classList.remove('active');
+    });
+  }
+
+  if (refreshPortsBtn) {
+    refreshPortsBtn.addEventListener('click', () => {
+      loadPorts();
+    });
+  }
+
+  if (readBtn) {
+    readBtn.addEventListener('click', async () => {
+      const port = portSelect.value.trim();
+      if (!port) {
+        showMessage('Select a serial port first.', 'error');
+        return;
+      }
+      setOutput('Reading settings from device...');
+      showMessage('Reading settings over USB...', 'success');
+      try {
+        const response = await fetch(`/led-tool/settings?port=${encodeURIComponent(port)}`);
+        const data = await parseApiResponse(response);
+        if (!response.ok) {
+          showMessage(data.error || 'Read failed.', 'error');
+          setOutput(data.error || 'Request failed.');
+          return;
+        }
+        const output = [
+          `exit code: ${data.returncode}`,
+          '',
+          'stdout:',
+          data.stdout || '(none)',
+          '',
+          'stderr:',
+          data.stderr || '(none)',
+        ].join('\n');
+        setOutput(output);
+        if (data.ok) {
+          const populated = populateFormFromSettings(data.settings);
+          if (populated) {
+            showMessage('Settings read and fields populated.', 'success');
+          } else {
+            showMessage('Settings read successfully.', 'success');
+          }
+        } else {
+          showMessage('Read completed with errors. Check output.', 'error');
+        }
+      } catch (error) {
+        showMessage(`Request failed: ${error.message}`, 'error');
+        setOutput(error.message);
+      }
+    });
+  }
+
+  if (resetBtn) {
+    resetBtn.addEventListener('click', async () => {
+      const port = portSelect.value.trim();
+      if (!port) {
+        showMessage('Select a serial port first.', 'error');
+        return;
+      }
+      setOutput('Resetting device and following output...');
+      showMessage('Resetting device over USB...', 'success');
+      try {
+        const response = await fetch('/led-tool/reset', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ port }),
+        });
+        const data = await parseApiResponse(response);
+        if (!response.ok) {
+          showMessage(data.error || 'Reset failed.', 'error');
+          setOutput(data.error || 'Request failed.');
+          return;
+        }
+        const output = [
+          `exit code: ${data.returncode}`,
+          '',
+          'stdout:',
+          data.stdout || '(none)',
+          '',
+          'stderr:',
+          data.stderr || '(none)',
+        ].join('\n');
+        setOutput(output);
+        if (data.ok) {
+          showMessage('Device reset complete.', 'success');
+        } else {
+          showMessage('Reset completed with errors. Check output.', 'error');
+        }
+      } catch (error) {
+        showMessage(`Request failed: ${error.message}`, 'error');
+        setOutput(error.message);
+      }
+    });
+  }
+
+  form.addEventListener('submit', async (event) => {
+    event.preventDefault();
+    const port = portSelect.value.trim();
+    if (!port) {
+      showMessage('Select a serial port first.', 'error');
+      return;
+    }
+
+    const payload = {
+      port,
+      name: document.getElementById('led-tool-name')?.value?.trim() || '',
+      num_leds: document.getElementById('led-tool-num-leds')?.value?.trim() || '',
+      led_pin: document.getElementById('led-tool-led-pin')?.value?.trim() || '',
+      brightness: document.getElementById('led-tool-brightness')?.value?.trim() || '',
+      transport: document.getElementById('led-tool-transport')?.value?.trim() || '',
+      ssid: document.getElementById('led-tool-ssid')?.value?.trim() || '',
+      password: document.getElementById('led-tool-password')?.value?.trim() || '',
+      wifi_channel: document.getElementById('led-tool-wifi-channel')?.value?.trim() || '',
+      default: document.getElementById('led-tool-default')?.value?.trim() || '',
+    };
+
+    setOutput('Running led-tool command...');
+    showMessage('Running command over USB...', 'success');
+    try {
+      const response = await fetch('/led-tool/settings', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload),
+      });
+      const data = await parseApiResponse(response);
+      if (!response.ok) {
+        showMessage(data.error || 'Command failed.', 'error');
+        setOutput(data.error || 'Request failed.');
+        return;
+      }
+      const output = [
+        `exit code: ${data.returncode}`,
+        '',
+        'stdout:',
+        data.stdout || '(none)',
+        '',
+        'stderr:',
+        data.stderr || '(none)',
+      ].join('\n');
+      setOutput(output);
+      if (data.ok) {
+        showMessage('Settings applied via USB.', 'success');
+      } else {
+        showMessage('Command completed with errors. Check output.', 'error');
+      }
+    } catch (error) {
+      showMessage(`Request failed: ${error.message}`, 'error');
+      setOutput(error.message);
+    }
+  });
+});

src/static/main.js

@@ -19,34 +19,34 @@ const numTabs = 3;
 
 // Select the container for tabs and content
 const tabsContainer = document.querySelector(".tabs");
-const tabContentContainer = document.querySelector(".tab-content");
+const tabContentContainer = document.querySelector(".zone-content");
 
 // Create tabs dynamically
 for (let i = 1; i <= numTabs; i++) {
-  // Create the tab button
+  // Create the zone button
   const tabButton = document.createElement("button");
-  tabButton.classList.add("tab");
+  tabButton.classList.add("zone");
-  tabButton.id = `tab${i}`;
+  tabButton.id = `zone${i}`;
-  tabButton.textContent = `Tab ${i}`;
+  tabButton.textContent = `Zone ${i}`;
 
-  // Add the tab button to the container
+  // Add the zone button to the container
   tabsContainer.appendChild(tabButton);
 
-  // Create the corresponding tab content (RGB slider)
+  // Create the corresponding zone content (RGB slider)
   const tabContent = document.createElement("div");
-  tabContent.classList.add("tab-pane");
+  tabContent.classList.add("zone-pane");
   tabContent.id = `content${i}`;
   const slider = document.createElement("rgb-slider");
   slider.id = i;
   tabContent.appendChild(slider);
 
-  // Add the tab content to the container
+  // Add the zone content to the container
   tabContentContainer.appendChild(tabContent);
 
   // Listen for color change on each RGB slider
   slider.addEventListener("color-change", (e) => {
     const { r, g, b } = e.detail;
-    console.log(`Color changed in tab ${i}:`, e.detail);
+    console.log(`Color changed in zone ${i}:`, e.detail);
     // Send RGB data to WebSocket server
     if (ws.readyState === WebSocket.OPEN) {
       const colorData = { r, g, b };
@@ -56,26 +56,26 @@ for (let i = 1; i <= numTabs; i++) {
 }
 
 // Function to switch tabs
-function switchTab(tabId) {
+function switchTab(zoneId) {
-  const tabs = document.querySelectorAll(".tab");
+  const tabs = document.querySelectorAll(".zone");
-  const tabContents = document.querySelectorAll(".tab-pane");
+  const tabContents = document.querySelectorAll(".zone-pane");
 
-  tabs.forEach((tab) => tab.classList.remove("active"));
+  zones.forEach((zone) => zone.classList.remove("active"));
   tabContents.forEach((content) => content.classList.remove("active"));
 
-  // Activate the clicked tab and corresponding content
+  // Activate the clicked zone and corresponding content
-  document.getElementById(tabId).classList.add("active");
+  document.getElementById(zoneId).classList.add("active");
   document
-    .getElementById("content" + tabId.replace("tab", ""))
+    .getElementById("content" + zoneId.replace("zone", ""))
     .classList.add("active");
 }
 
 // Add event listeners to tabs
 tabsContainer.addEventListener("click", (e) => {
-  if (e.target.classList.contains("tab")) {
+  if (e.target.classList.contains("zone")) {
     switchTab(e.target.id);
   }
 });
 
-// Initially set the first tab as active
+// Initially set the first zone as active
 switchTab("tab1");

src/static/patterns.js

@@ -0,0 +1,427 @@
+document.addEventListener('DOMContentLoaded', () => {
+  const patternsButton = document.getElementById('patterns-btn');
+  const patternsModal = document.getElementById('patterns-modal');
+  const patternsCloseButton = document.getElementById('patterns-close-btn');
+  const patternsList = document.getElementById('patterns-list');
+  const patternAddButton = document.getElementById('pattern-add-btn');
+  const patternEditorModal = document.getElementById('pattern-editor-modal');
+  const patternEditorCloseButton = document.getElementById('pattern-editor-close-btn');
+  const patternCreateBtn = document.getElementById('pattern-create-btn');
+  const patternCreateName = document.getElementById('pattern-create-name');
+  const patternCreateMinDelay = document.getElementById('pattern-create-min-delay');
+  const patternCreateMaxDelay = document.getElementById('pattern-create-max-delay');
+  const patternCreateMaxColors = document.getElementById('pattern-create-max-colors');
+  const patternCreateFile = document.getElementById('pattern-create-file');
+  const patternCreateCode = document.getElementById('pattern-create-code');
+  const patternCreateOverwrite = document.getElementById('pattern-create-overwrite');
+  const patternCreateN = [1, 2, 3, 4, 5, 6, 7, 8].map((i) =>
+    document.getElementById(`pattern-create-n${i}`),
+  );
+  const patternCreateNSection = document.getElementById('pattern-create-n-section');
+  const patternCreateNEmpty = document.getElementById('pattern-create-n-empty');
+
+  if (!patternsButton || !patternsModal || !patternsList) {
+    return;
+  }
+
+  const nReadableStringFromMeta = (meta, key) => {
+    if (!meta || typeof meta !== 'object') {
+      return '';
+    }
+    const pm = meta.parameter_mappings;
+    if (pm && typeof pm === 'object' && typeof pm[key] === 'string') {
+      const s = pm[key].trim();
+      if (s) {
+        return s;
+      }
+    }
+    if (typeof meta[key] === 'string') {
+      return meta[key].trim();
+    }
+    return '';
+  };
+
+  const setPatternEditorNFields = (mode, data) => {
+    const meta = data && typeof data === 'object' ? data : {};
+    let visible = 0;
+    const grid = patternCreateNSection && patternCreateNSection.querySelector('.n-params-grid');
+    const h3 = patternCreateNSection && patternCreateNSection.querySelector('h3');
+
+    for (let i = 1; i <= 8; i += 1) {
+      const key = `n${i}`;
+      const labelEl = document.querySelector(`label[for="pattern-create-${key}"]`);
+      const inputEl = document.getElementById(`pattern-create-${key}`);
+      const groupEl = labelEl ? labelEl.closest('.n-param-group') : null;
+
+      if (mode === 'create') {
+        if (labelEl) {
+          labelEl.textContent = `${key}:`;
+          labelEl.style.display = '';
+        }
+        if (inputEl) {
+          inputEl.value = '';
+          inputEl.placeholder = 'Readable name (optional)';
+          inputEl.removeAttribute('aria-label');
+        }
+        if (groupEl) {
+          groupEl.style.display = '';
+        }
+        continue;
+      }
+
+      const readable = nReadableStringFromMeta(meta, key);
+      const show = Boolean(readable);
+      if (labelEl) {
+        labelEl.textContent = '';
+        labelEl.style.display = 'none';
+      }
+      if (inputEl) {
+        inputEl.value = show ? readable : '';
+        inputEl.placeholder = '';
+        if (show) {
+          inputEl.setAttribute('aria-label', readable);
+        } else {
+          inputEl.removeAttribute('aria-label');
+          inputEl.value = '';
+        }
+      }
+      if (groupEl) {
+        groupEl.style.display = show ? '' : 'none';
+      }
+      if (show) {
+        visible += 1;
+      }
+    }
+
+    if (mode === 'create') {
+      if (patternCreateNEmpty) {
+        patternCreateNEmpty.style.display = 'none';
+      }
+      if (grid) {
+        grid.style.display = '';
+      }
+      if (h3) {
+        h3.style.display = '';
+      }
+      if (patternCreateNSection) {
+        patternCreateNSection.style.display = '';
+      }
+      return;
+    }
+
+    if (patternCreateNEmpty) {
+      patternCreateNEmpty.style.display = visible === 0 ? '' : 'none';
+    }
+    if (grid) {
+      grid.style.display = visible === 0 ? 'none' : '';
+    }
+    if (h3) {
+      h3.style.display = visible === 0 ? 'none' : '';
+    }
+  };
+
+  const readFileAsText = (file) =>
+    new Promise((resolve, reject) => {
+      const reader = new FileReader();
+      reader.onload = () => resolve(String(reader.result || ''));
+      reader.onerror = () => reject(reader.error || new Error('read failed'));
+      reader.readAsText(file);
+    });
+
+  const collectCreatePayload = async () => {
+    const name = patternCreateName ? patternCreateName.value.trim() : '';
+    if (!name) {
+      throw new Error('Pattern name is required.');
+    }
+    let code = '';
+    const fileInput = patternCreateFile && patternCreateFile.files && patternCreateFile.files[0];
+    if (fileInput) {
+      code = await readFileAsText(fileInput);
+    } else if (patternCreateCode && patternCreateCode.value.trim()) {
+      code = patternCreateCode.value;
+    }
+    if (!code.trim()) {
+      throw new Error('Choose a .py file or paste source code.');
+    }
+
+    const payload = {
+      name,
+      code,
+      min_delay: parseInt(patternCreateMinDelay && patternCreateMinDelay.value, 10) || 0,
+      max_delay: parseInt(patternCreateMaxDelay && patternCreateMaxDelay.value, 10) || 0,
+      max_colors: parseInt(patternCreateMaxColors && patternCreateMaxColors.value, 10) || 0,
+      overwrite: !!(patternCreateOverwrite && patternCreateOverwrite.checked),
+    };
+
+    patternCreateN.forEach((el, idx) => {
+      const key = `n${idx + 1}`;
+      if (el && el.value.trim()) {
+        payload[key] = el.value.trim();
+      }
+    });
+
+    return payload;
+  };
+
+  const resetCreateForm = () => {
+    if (patternCreateName) patternCreateName.value = '';
+    if (patternCreateFile) patternCreateFile.value = '';
+    if (patternCreateCode) patternCreateCode.value = '';
+    if (patternCreateMinDelay) patternCreateMinDelay.value = '10';
+    if (patternCreateMaxDelay) patternCreateMaxDelay.value = '10000';
+    if (patternCreateMaxColors) patternCreateMaxColors.value = '10';
+    patternCreateN.forEach((el) => {
+      if (el) el.value = '';
+    });
+    if (patternCreateOverwrite) patternCreateOverwrite.checked = true;
+    setPatternEditorNFields('create', {});
+  };
+
+  if (patternCreateBtn) {
+    patternCreateBtn.addEventListener('click', async () => {
+      try {
+        const payload = await collectCreatePayload();
+        const response = await fetch('/patterns/driver', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+          body: JSON.stringify(payload),
+        });
+        const data = await response.json().catch(() => ({}));
+        if (!response.ok) {
+          throw new Error((data && data.error) || 'Create failed');
+        }
+        alert(data.message || 'Pattern created.');
+        resetCreateForm();
+        if (patternEditorModal) {
+          patternEditorModal.classList.remove('active');
+        }
+        await loadPatterns();
+      } catch (e) {
+        console.error('Create pattern failed:', e);
+        alert(e.message || 'Failed to create pattern.');
+      }
+    });
+  }
+
+  /** on/off are implemented in driver firmware (presets.py), not as OTA ``.py`` files. */
+  const FIRMWARE_BUILTIN_PATTERNS = new Set(['on', 'off']);
+
+  const isFirmwareBuiltinPattern = (patternName) => {
+    const id = String(patternName || '')
+      .trim()
+      .replace(/\.py$/i, '')
+      .toLowerCase();
+    return FIRMWARE_BUILTIN_PATTERNS.has(id);
+  };
+
+  const sendPatternToDevices = async (patternName) => {
+    const response = await fetch(`/patterns/${encodeURIComponent(patternName)}/send`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+      body: JSON.stringify({}),
+    });
+    const data = await response.json().catch(() => ({}));
+    if (!response.ok) {
+      throw new Error((data && data.error) || 'Failed to send pattern');
+    }
+    const sentCount = data && typeof data.sent_count === 'number' ? data.sent_count : null;
+    if (sentCount === null) {
+      alert(`Sent "${patternName}" to devices.`);
+    } else {
+      alert(`Sent "${patternName}" to ${sentCount} device(s).`);
+    }
+  };
+
+  const loadPatternMetadata = async (patternName, fallbackData) => {
+    const raw = String(patternName || '').trim();
+    const norm = raw.endsWith('.py') ? raw.slice(0, -3).trim() : raw;
+    try {
+      const response = await fetch('/patterns/definitions', {
+        cache: 'no-store',
+        headers: { Accept: 'application/json' },
+      });
+      if (!response.ok) {
+        throw new Error('Failed to load pattern definitions');
+      }
+      const definitions = await response.json();
+      if (definitions && typeof definitions === 'object') {
+        if (definitions[raw]) {
+          return definitions[raw];
+        }
+        if (norm && definitions[norm]) {
+          return definitions[norm];
+        }
+        if (norm) {
+          const lower = norm.toLowerCase();
+          const matched = Object.keys(definitions).find(
+            (k) => String(k).toLowerCase() === lower,
+          );
+          if (matched) {
+            return definitions[matched];
+          }
+        }
+      }
+    } catch (error) {
+      console.error('Load pattern definitions failed:', error);
+    }
+    return fallbackData || {};
+  };
+
+  const loadPatternIntoEditor = async (patternName, fallbackData) => {
+    const data = await loadPatternMetadata(patternName, fallbackData);
+    if (patternCreateName) {
+      patternCreateName.value = patternName;
+    }
+    if (patternCreateMinDelay) {
+      patternCreateMinDelay.value =
+        data && data.min_delay !== undefined ? String(data.min_delay) : '10';
+    }
+    if (patternCreateMaxDelay) {
+      patternCreateMaxDelay.value =
+        data && data.max_delay !== undefined ? String(data.max_delay) : '10000';
+    }
+    if (patternCreateMaxColors) {
+      patternCreateMaxColors.value =
+        data && data.max_colors !== undefined ? String(data.max_colors) : '10';
+    }
+    setPatternEditorNFields('edit', data);
+    if (patternCreateOverwrite) {
+      patternCreateOverwrite.checked = true;
+    }
+    if (patternCreateFile) {
+      patternCreateFile.value = '';
+    }
+
+    try {
+      const raw = String(patternName || '').trim();
+      const fileSegment = /\.py$/i.test(raw) ? raw : `${raw}.py`;
+      const response = await fetch(`/patterns/ota/file/${encodeURIComponent(fileSegment)}`, {
+        headers: { Accept: 'text/plain' },
+      });
+      if (!response.ok) {
+        throw new Error('Failed to load pattern file');
+      }
+      const source = await response.text();
+      if (patternCreateCode) {
+        patternCreateCode.value = source || '';
+        patternCreateCode.focus();
+      }
+    } catch (error) {
+      console.error('Load pattern source failed:', error);
+      alert('Could not load pattern source into editor.');
+    }
+  };
+
+  const renderPatterns = (patterns) => {
+    patternsList.innerHTML = '';
+    const entries = Object.entries(patterns || {});
+    if (!entries.length) {
+      const empty = document.createElement('p');
+      empty.className = 'muted-text';
+      empty.textContent = 'No patterns found.';
+      patternsList.appendChild(empty);
+      return;
+    }
+    entries.forEach(([patternName, data]) => {
+      const row = document.createElement('div');
+      row.className = 'profiles-row';
+
+      const label = document.createElement('span');
+      label.textContent = patternName;
+
+      row.appendChild(label);
+
+      if (isFirmwareBuiltinPattern(patternName)) {
+        const note = document.createElement('span');
+        note.className = 'muted-text';
+        note.style.fontSize = '0.85em';
+        note.textContent = 'Built-in (no OTA module)';
+        row.appendChild(note);
+      } else {
+        const sendBtn = document.createElement('button');
+        sendBtn.className = 'btn btn-primary btn-small';
+        sendBtn.textContent = 'Send';
+        sendBtn.addEventListener('click', async () => {
+          try {
+            await sendPatternToDevices(patternName);
+          } catch (error) {
+            console.error('Send pattern failed:', error);
+            alert(error.message || 'Failed to send pattern.');
+          }
+        });
+
+        const editBtn = document.createElement('button');
+        editBtn.className = 'btn btn-secondary btn-small';
+        editBtn.textContent = 'Edit';
+        editBtn.addEventListener('click', async () => {
+          if (patternEditorModal) {
+            patternEditorModal.classList.add('active');
+          }
+          await loadPatternIntoEditor(patternName, data || {});
+        });
+
+        row.appendChild(editBtn);
+        row.appendChild(sendBtn);
+      }
+
+      patternsList.appendChild(row);
+    });
+  };
+
+  async function loadPatterns() {
+    patternsList.innerHTML = '';
+    const loading = document.createElement('p');
+    loading.className = 'muted-text';
+    loading.textContent = 'Loading patterns...';
+    patternsList.appendChild(loading);
+
+    try {
+      const response = await fetch('/patterns', {
+        cache: 'no-store',
+        headers: { Accept: 'application/json' },
+      });
+      if (!response.ok) {
+        throw new Error('Failed to load patterns');
+      }
+      const patterns = await response.json();
+      renderPatterns(patterns);
+    } catch (error) {
+      console.error('Load patterns failed:', error);
+      patternsList.innerHTML = '';
+      const errorMessage = document.createElement('p');
+      errorMessage.className = 'muted-text';
+      errorMessage.textContent = 'Failed to load patterns.';
+      patternsList.appendChild(errorMessage);
+    }
+  }
+
+  const openModal = () => {
+    patternsModal.classList.add('active');
+    loadPatterns();
+  };
+
+  const closeModal = () => {
+    patternsModal.classList.remove('active');
+  };
+
+  patternsButton.addEventListener('click', openModal);
+  if (patternAddButton) {
+    patternAddButton.addEventListener('click', () => {
+      resetCreateForm();
+      if (patternEditorModal) {
+        patternEditorModal.classList.add('active');
+      }
+    });
+  }
+  if (patternEditorCloseButton) {
+    patternEditorCloseButton.addEventListener('click', () => {
+      if (patternEditorModal) {
+        patternEditorModal.classList.remove('active');
+      }
+    });
+  }
+  if (patternsCloseButton) {
+    patternsCloseButton.addEventListener('click', closeModal);
+  }
+
+});

src/static/profiles.js

@@ -0,0 +1,297 @@
+document.addEventListener("DOMContentLoaded", () => {
+  const profilesButton = document.getElementById("profiles-btn");
+  const profilesModal = document.getElementById("profiles-modal");
+  const profilesCloseButton = document.getElementById("profiles-close-btn");
+  const profilesList = document.getElementById("profiles-list");
+  const newProfileInput = document.getElementById("new-profile-name");
+  const newProfileSeedDjInput = document.getElementById("new-profile-seed-dj");
+  const createProfileButton = document.getElementById("create-profile-btn");
+
+  if (!profilesButton || !profilesModal || !profilesList) {
+    return;
+  }
+
+  const isEditModeActive = () => {
+    const toggle = document.querySelector('.ui-mode-toggle');
+    return !!(toggle && toggle.getAttribute('aria-pressed') === 'true');
+  };
+
+  const updateProfileEditorControlsVisibility = () => {
+    const editMode = isEditModeActive();
+    const actions = profilesModal.querySelector('.profiles-actions');
+    if (actions) {
+      actions.style.display = editMode ? '' : 'none';
+    }
+  };
+
+  const openModal = () => {
+    profilesModal.classList.add("active");
+    updateProfileEditorControlsVisibility();
+    loadProfiles();
+  };
+
+  const closeModal = () => {
+    profilesModal.classList.remove("active");
+  };
+
+  const refreshTabsForActiveProfile = async () => {
+    // Clear stale current zone so zone controller falls back to first zone of applied profile.
+    document.cookie = "current_zone=; path=/; max-age=0";
+
+    if (window.tabsManager && typeof window.tabsManager.loadTabs === "function") {
+      await window.tabsManager.loadTabs();
+    }
+    if (window.tabsManager && typeof window.tabsManager.loadTabsModal === "function") {
+      await window.tabsManager.loadTabsModal();
+    }
+  };
+
+  const renderProfiles = (profiles, currentProfileId) => {
+    profilesList.innerHTML = "";
+    let entries = [];
+
+    if (Array.isArray(profiles)) {
+      entries = profiles.map((profileId) => [profileId, {}]);
+    } else if (profiles && typeof profiles === "object") {
+      // Make sure we're iterating over profile entries, not metadata
+      entries = Object.entries(profiles).filter(([key]) => {
+        // Skip metadata keys like 'current_profile_id' if they exist
+        return key !== 'current_profile_id' && key !== 'profiles';
+      });
+    }
+
+    if (entries.length === 0) {
+      const empty = document.createElement("p");
+      empty.className = "muted-text";
+      empty.textContent = "No profiles found.";
+      profilesList.appendChild(empty);
+      return;
+    }
+
+    const editMode = isEditModeActive();
+    entries.forEach(([profileId, profile]) => {
+      const row = document.createElement("div");
+      row.className = "profiles-row";
+
+      const label = document.createElement("span");
+      label.textContent = (profile && profile.name) || profileId;
+      if (String(profileId) === String(currentProfileId)) {
+        label.textContent = `✓ ${label.textContent}`;
+        label.style.fontWeight = "bold";
+        label.style.color = "#FFD700";
+      }
+
+      const applyButton = document.createElement("button");
+      applyButton.className = "btn btn-secondary btn-small profiles-apply-btn";
+      applyButton.textContent = "Apply";
+      applyButton.addEventListener("click", async () => {
+        try {
+          const response = await fetch(`/profiles/${profileId}/apply`, {
+            method: "POST",
+            headers: { Accept: "application/json" },
+          });
+          if (!response.ok) {
+            throw new Error("Failed to apply profile");
+          }
+          await loadProfiles();
+          await refreshTabsForActiveProfile();
+        } catch (error) {
+          console.error("Apply profile failed:", error);
+          alert("Failed to apply profile.");
+        }
+      });
+
+      const cloneButton = document.createElement("button");
+      cloneButton.className = "btn btn-secondary btn-small";
+      cloneButton.textContent = "Clone";
+      cloneButton.addEventListener("click", async () => {
+        const baseName = (profile && profile.name) || profileId;
+        const suggested = `${baseName}`;
+        const name = prompt("New profile name:", suggested);
+        if (name === null) {
+          return;
+        }
+        const trimmed = String(name).trim();
+        if (!trimmed) {
+          alert("Profile name cannot be empty.");
+          return;
+        }
+        try {
+          const response = await fetch(`/profiles/${profileId}/clone`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Accept: "application/json" },
+            body: JSON.stringify({ name: trimmed }),
+          });
+          if (!response.ok) {
+            throw new Error("Failed to clone profile");
+          }
+          const data = await response.json().catch(() => null);
+          let newProfileId = null;
+          if (data && typeof data === "object") {
+            if (data.id) {
+              newProfileId = String(data.id);
+            } else {
+              const ids = Object.keys(data);
+              if (ids.length > 0) {
+                newProfileId = String(ids[0]);
+              }
+            }
+          }
+          if (newProfileId) {
+            await fetch(`/profiles/${newProfileId}/apply`, {
+              method: "POST",
+              headers: { Accept: "application/json" },
+            });
+          }
+          await loadProfiles();
+          await refreshTabsForActiveProfile();
+        } catch (error) {
+          console.error("Clone profile failed:", error);
+          alert("Failed to clone profile.");
+        }
+      });
+
+      const deleteButton = document.createElement("button");
+      deleteButton.className = "btn btn-danger btn-small";
+      deleteButton.textContent = "Delete";
+      deleteButton.addEventListener("click", async () => {
+        const confirmed = confirm(`Delete profile "${label.textContent}"?`);
+        if (!confirmed) {
+          return;
+        }
+        try {
+          const response = await fetch(`/profiles/${profileId}`, {
+            method: "DELETE",
+            headers: { Accept: "application/json" },
+          });
+          if (!response.ok) {
+            throw new Error("Failed to delete profile");
+          }
+          await loadProfiles();
+        } catch (error) {
+          console.error("Delete profile failed:", error);
+          alert("Failed to delete profile.");
+        }
+      });
+
+      row.appendChild(label);
+      row.appendChild(applyButton);
+      if (editMode) {
+        row.appendChild(cloneButton);
+        row.appendChild(deleteButton);
+      }
+      profilesList.appendChild(row);
+    });
+  };
+
+  const loadProfiles = async () => {
+    profilesList.innerHTML = "";
+    const loading = document.createElement("p");
+    loading.className = "muted-text";
+    loading.textContent = "Loading profiles...";
+    profilesList.appendChild(loading);
+
+    try {
+      const response = await fetch("/profiles", {
+        headers: { Accept: "application/json" },
+      });
+      if (!response.ok) {
+        throw new Error("Failed to load profiles");
+      }
+      const data = await response.json();
+      // Handle both old format (just profiles object) and new format (with current_profile_id)
+      const profiles = data.profiles || data;
+      const currentProfileId = data.current_profile_id || null;
+      renderProfiles(profiles, currentProfileId);
+    } catch (error) {
+      console.error("Load profiles failed:", error);
+      profilesList.innerHTML = "";
+      const errorMessage = document.createElement("p");
+      errorMessage.className = "muted-text";
+      errorMessage.textContent = "Failed to load profiles.";
+      profilesList.appendChild(errorMessage);
+    }
+  };
+
+  const createProfile = async () => {
+    if (!isEditModeActive()) {
+      return;
+    }
+    if (!newProfileInput) {
+      return;
+    }
+    const name = newProfileInput.value.trim();
+    if (!name) {
+      alert("Profile name cannot be empty.");
+      return;
+    }
+    try {
+      const response = await fetch("/profiles", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          name,
+          seed_dj_zone: !!(newProfileSeedDjInput && newProfileSeedDjInput.checked),
+        }),
+      });
+      if (!response.ok) {
+        throw new Error("Failed to create profile");
+      }
+      const data = await response.json().catch(() => null);
+      let newProfileId = null;
+      if (data && typeof data === "object") {
+        if (data.id) {
+          newProfileId = String(data.id);
+        } else {
+          const ids = Object.keys(data);
+          if (ids.length > 0) {
+            newProfileId = String(ids[0]);
+          }
+        }
+      }
+
+      if (newProfileId) {
+        await fetch(`/profiles/${newProfileId}/apply`, {
+          method: "POST",
+          headers: { Accept: "application/json" },
+        });
+      }
+
+      newProfileInput.value = "";
+      if (newProfileSeedDjInput) {
+        newProfileSeedDjInput.checked = false;
+      }
+      await loadProfiles();
+      await refreshTabsForActiveProfile();
+    } catch (error) {
+      console.error("Create profile failed:", error);
+      alert("Failed to create profile.");
+    }
+  };
+
+  profilesButton.addEventListener("click", openModal);
+  if (profilesCloseButton) {
+    profilesCloseButton.addEventListener("click", closeModal);
+  }
+  if (createProfileButton) {
+    createProfileButton.addEventListener("click", createProfile);
+  }
+  if (newProfileInput) {
+    newProfileInput.addEventListener("keypress", (event) => {
+      if (event.key === "Enter") {
+        createProfile();
+      }
+    });
+  }
+
+  // Keep modal controls in sync with run/edit mode.
+  document.querySelectorAll('.ui-mode-toggle').forEach((btn) => {
+    btn.addEventListener('click', () => {
+      if (profilesModal.classList.contains('active')) {
+        updateProfileEditorControlsVisibility();
+        loadProfiles();
+      }
+    });
+  });
+
+});

src/static/styles.css

@@ -1,11 +1,11 @@
-/* General tab styles */
+/* General zone styles */
 .tabs {
     display: flex;
     justify-content: center;
     margin-bottom: 20px;
 }
 
-.tab {
+.zone {
     padding: 10px 20px;
     margin: 0 10px;
     cursor: pointer;
@@ -15,23 +15,23 @@
     transition: background-color 0.3s ease;
 }
 
-.tab:hover {
+.zone:hover {
     background-color: #ddd;
 }
 
-.tab.active {
+.zone.active {
     background-color: #ccc;
 }
 
-.tab-content {
+.zone-content {
     display: flex;
     justify-content: center;
 }
 
-.tab-pane {
+.zone-pane {
     display: none;
 }
 
-.tab-pane.active {
+.zone-pane.active {
     display: block;
 }

src/static/zone_palette.js

@@ -0,0 +1,262 @@
+document.addEventListener('DOMContentLoaded', () => {
+  let selectedIndex = null;
+
+  const getTab = async (zoneId) => {
+    const response = await fetch(`/zones/${zoneId}`, {
+      headers: { Accept: 'application/json' },
+    });
+    if (!response.ok) {
+      throw new Error('No zone found');
+    }
+    return response.json();
+  };
+
+  const saveTabColors = async (zoneId, colors) => {
+    const response = await fetch(`/zones/${zoneId}`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ colors }),
+    });
+    if (!response.ok) {
+      throw new Error('Failed to save zone colors');
+    }
+    return response.json();
+  };
+
+  const renderPalette = (paletteContainer, colors, onColorChange, onRemoveColor, onReorder) => {
+    paletteContainer.innerHTML = '';
+    if (!colors.length) {
+      const empty = document.createElement('div');
+      empty.className = 'muted-text';
+      empty.textContent = 'No colors in palette.';
+      paletteContainer.appendChild(empty);
+      return;
+    }
+
+    colors.forEach((color, index) => {
+      const swatch = document.createElement('div');
+      swatch.className = 'color-swatch';
+      swatch.draggable = true;
+      swatch.dataset.index = String(index);
+      if (index === selectedIndex) {
+        swatch.classList.add('selected');
+      }
+
+      const preview = document.createElement('div');
+      preview.className = 'color-swatch-preview';
+      preview.style.backgroundColor = color;
+
+      const label = document.createElement('span');
+      label.className = 'color-swatch-label';
+      label.textContent = color;
+
+      const colorPicker = document.createElement('input');
+      colorPicker.type = 'color';
+      colorPicker.className = 'color-picker-input';
+      colorPicker.value = color;
+      colorPicker.addEventListener('change', async (event) => {
+        const newColor = event.target.value;
+        await onColorChange(index, newColor);
+      });
+
+      const removeButton = document.createElement('button');
+      removeButton.className = 'btn btn-danger btn-small';
+      removeButton.textContent = 'Remove';
+      removeButton.addEventListener('click', async (event) => {
+        event.stopPropagation();
+        await onRemoveColor(index);
+      });
+
+      swatch.addEventListener('dragstart', (event) => {
+        event.dataTransfer.setData('text/plain', String(index));
+        event.dataTransfer.effectAllowed = 'move';
+      });
+      swatch.addEventListener('dragover', (event) => {
+        event.preventDefault();
+        event.dataTransfer.dropEffect = 'move';
+      });
+      swatch.addEventListener('drop', async (event) => {
+        event.preventDefault();
+        const fromIndex = parseInt(event.dataTransfer.getData('text/plain'), 10);
+        const toIndex = parseInt(swatch.dataset.index || '-1', 10);
+        if (Number.isNaN(fromIndex) || Number.isNaN(toIndex) || fromIndex === toIndex) {
+          return;
+        }
+        await onReorder(fromIndex, toIndex);
+      });
+
+      swatch.appendChild(preview);
+      swatch.appendChild(label);
+      swatch.appendChild(colorPicker);
+      swatch.appendChild(removeButton);
+      swatch.addEventListener('click', () => {
+        selectedIndex = index;
+        renderPalette(paletteContainer, colors, onColorChange, onRemoveColor, onReorder);
+        colorPicker.click();
+      });
+
+      paletteContainer.appendChild(swatch);
+    });
+  };
+
+  const initTabPalette = async () => {
+    const paletteContainer = document.getElementById('color-palette');
+    const addButton = document.getElementById('zone-color-add-btn');
+    const addFromPaletteButton = document.getElementById('zone-color-add-from-palette-btn');
+    const colorInput = document.getElementById('zone-color-input');
+
+    if (!paletteContainer || !addButton || !colorInput) {
+      return;
+    }
+
+    const zoneId = paletteContainer.dataset.zoneId;
+    if (!zoneId) {
+      renderPalette(paletteContainer, []);
+      return;
+    }
+
+    let tabData;
+    try {
+      tabData = await getTab(zoneId);
+    } catch (error) {
+      renderPalette(paletteContainer, []);
+      return;
+    }
+
+    let colors = tabData.colors || [];
+    if (!Array.isArray(colors)) {
+      colors = [];
+    }
+    const onRemoveColor = async (index) => {
+      if (index === null || index < 0 || index >= colors.length) {
+        alert('Select a color to remove.');
+        return;
+      }
+      try {
+        const updated = colors.filter((_, i) => i !== index);
+        const saved = await saveTabColors(zoneId, updated);
+        colors = saved.colors || updated;
+        selectedIndex = null;
+        renderPalette(paletteContainer, colors, onColorChange, onRemoveColor, onReorder);
+      } catch (error) {
+        console.error('Failed to remove color:', error);
+        alert('Failed to remove color.');
+      }
+    };
+
+    const onReorder = async (fromIndex, toIndex) => {
+      if (fromIndex < 0 || fromIndex >= colors.length || toIndex < 0 || toIndex >= colors.length) {
+        return;
+      }
+      try {
+        const updated = [...colors];
+        const [moved] = updated.splice(fromIndex, 1);
+        updated.splice(toIndex, 0, moved);
+        const saved = await saveTabColors(zoneId, updated);
+        colors = saved.colors || updated;
+        selectedIndex = toIndex;
+        renderPalette(paletteContainer, colors, onColorChange, onRemoveColor, onReorder);
+      } catch (error) {
+        console.error('Failed to reorder colors:', error);
+        alert('Failed to reorder colors.');
+      }
+    };
+
+    const onColorChange = async (index, newColor) => {
+      if (!newColor || index < 0 || index >= colors.length) {
+        return;
+      }
+      try {
+        const updated = [...colors];
+        updated[index] = newColor;
+        const saved = await saveTabColors(zoneId, updated);
+        colors = saved.colors || updated;
+        selectedIndex = index;
+        renderPalette(paletteContainer, colors, onColorChange, onRemoveColor, onReorder);
+      } catch (error) {
+        console.error('Failed to update color:', error);
+        alert('Failed to update color.');
+      }
+    };
+
+    renderPalette(paletteContainer, colors, onColorChange, onRemoveColor, onReorder);
+
+    addButton.onclick = async () => {
+      const newColor = colorInput.value;
+      if (!newColor) {
+        return;
+      }
+      if (colors.includes(newColor)) {
+        alert('Color already in palette.');
+        return;
+      }
+      try {
+        const updated = [...colors, newColor];
+        const saved = await saveTabColors(zoneId, updated);
+        colors = saved.colors || updated;
+        selectedIndex = colors.length - 1;
+        renderPalette(paletteContainer, colors, onColorChange, onRemoveColor, onReorder);
+      } catch (error) {
+        console.error('Failed to add color:', error);
+        alert('Failed to add color.');
+      }
+    };
+
+    if (addFromPaletteButton) {
+      addFromPaletteButton.onclick = () => {
+        const openButton = document.getElementById('color-palette-btn');
+        if (openButton) {
+          openButton.click();
+        }
+        const modal = document.getElementById('color-palette-modal');
+        const modalList = document.getElementById('palette-container');
+        if (modal) {
+          modal.classList.add('active');
+        }
+        if (!modalList) {
+          return;
+        }
+
+        const handlePick = async (event) => {
+          const row = event.target.closest('[data-color]');
+          if (!row) {
+            return;
+          }
+          const picked = row.dataset.color;
+          if (!picked) {
+            return;
+          }
+          try {
+            if (!colors.includes(picked)) {
+              const updated = [...colors, picked];
+              const saved = await saveTabColors(zoneId, updated);
+              colors = saved.colors || updated;
+              selectedIndex = colors.indexOf(picked);
+              renderPalette(paletteContainer, colors, onColorChange, onRemoveColor, onReorder);
+            }
+            if (modal) {
+              modal.classList.remove('active');
+            }
+          } catch (error) {
+            console.error('Failed to add palette color:', error);
+            alert('Failed to add palette color.');
+          } finally {
+            modalList.removeEventListener('click', handlePick);
+          }
+        };
+
+        modalList.addEventListener('click', handlePick);
+      };
+    }
+
+  };
+
+  document.body.addEventListener('htmx:afterSwap', (event) => {
+    if (event.target && event.target.id === 'zone-content') {
+      selectedIndex = null;
+      initTabPalette();
+    }
+  });
+
+  initTabPalette();
+});

src/static/zones.js

@@ -0,0 +1,997 @@
+// Zone management JavaScript
+let currentZoneId = null;
+
+const isEditModeActive = () => {
+    const toggle = document.querySelector('.ui-mode-toggle');
+    return !!(toggle && toggle.getAttribute('aria-pressed') === 'true');
+};
+
+// Get current zone from cookie
+function getCurrentZoneFromCookie() {
+    const cookies = document.cookie.split(';');
+    for (let cookie of cookies) {
+        const [name, value] = cookie.trim().split('=');
+        if (name === 'current_zone') {
+            return value;
+        }
+    }
+    return null;
+}
+
+async function fetchDevicesMap() {
+    try {
+        const response = await fetch("/devices", { headers: { Accept: "application/json" } });
+        if (!response.ok) return {};
+        const data = await response.json();
+        return data && typeof data === "object" ? data : {};
+    } catch (e) {
+        console.error("fetchDevicesMap:", e);
+        return {};
+    }
+}
+
+/** Registry MACs for zone device names (order matches zone names; skips unknown names). */
+async function resolveZoneDeviceMacs(zoneNames) {
+    const dm = await fetchDevicesMap();
+    const rows = namesToRows(Array.isArray(zoneNames) ? zoneNames : [], dm);
+    const macs = rows.map((r) => r.mac).filter(Boolean);
+    return [...new Set(macs)];
+}
+
+function namesToRows(zoneNames, devicesMap) {
+    const usedMacs = new Set();
+    const list = Array.isArray(zoneNames) ? zoneNames : [];
+    return list.map((name) => {
+        const n = String(name || "").trim();
+        const matches = Object.entries(devicesMap || {}).filter(
+            ([mac, d]) => d && String((d.name || "").trim()) === n && !usedMacs.has(mac),
+        );
+        if (matches.length === 0) {
+            return { mac: null, name: n || "unknown" };
+        }
+        const [mac] = matches[0];
+        usedMacs.add(mac);
+        return { mac, name: n };
+    });
+}
+
+function rowsToNames(rows) {
+    return (rows || []).map((r) => String(r.name || "").trim()).filter((n) => n.length > 0);
+}
+
+function renderZoneDevicesEditor(containerEl, rows, devicesMap) {
+    if (!containerEl) return;
+    containerEl.innerHTML = "";
+    const entries = Object.entries(devicesMap || {}).sort(([a], [b]) => a.localeCompare(b));
+
+    rows.forEach((row, idx) => {
+        const div = document.createElement("div");
+        div.className = "zone-device-row profiles-row";
+        const label = document.createElement("span");
+        label.className = "zone-device-row-label";
+        const strong = document.createElement("strong");
+        strong.textContent = row.name || "—";
+        label.appendChild(strong);
+        label.appendChild(document.createTextNode(" "));
+        const sub = document.createElement("span");
+        sub.className = "muted-text";
+        sub.textContent = row.mac ? row.mac : "(not in registry)";
+        label.appendChild(sub);
+
+        const rm = document.createElement("button");
+        rm.type = "button";
+        rm.className = "btn btn-danger btn-small";
+        rm.textContent = "Remove";
+        rm.addEventListener("click", () => {
+            rows.splice(idx, 1);
+            renderZoneDevicesEditor(containerEl, rows, devicesMap);
+        });
+        div.appendChild(label);
+        div.appendChild(rm);
+        containerEl.appendChild(div);
+    });
+
+    const macsInRows = new Set(rows.map((r) => r.mac).filter(Boolean));
+    const addWrap = document.createElement("div");
+    addWrap.className = "zone-devices-add profiles-actions";
+    const sel = document.createElement("select");
+    sel.className = "zone-device-add-select";
+    sel.appendChild(new Option("Add device…", ""));
+    entries.forEach(([mac, d]) => {
+        if (macsInRows.has(mac)) return;
+        const labelName = d && d.name ? String(d.name).trim() : "";
+        const optLabel = labelName ? `${labelName} — ${mac}` : mac;
+        sel.appendChild(new Option(optLabel, mac));
+    });
+    const addBtn = document.createElement("button");
+    addBtn.type = "button";
+    addBtn.className = "btn btn-primary btn-small";
+    addBtn.textContent = "Add";
+    addBtn.addEventListener("click", () => {
+        const mac = sel.value;
+        if (!mac || !devicesMap[mac]) return;
+        const n = String((devicesMap[mac].name || "").trim() || mac);
+        rows.push({ mac, name: n });
+        sel.value = "";
+        renderZoneDevicesEditor(containerEl, rows, devicesMap);
+    });
+    addWrap.appendChild(sel);
+    addWrap.appendChild(addBtn);
+    containerEl.appendChild(addWrap);
+}
+
+/** Default device name list when creating a zone (refined in Edit zone). */
+async function defaultDeviceNamesForNewTab() {
+    const dm = await fetchDevicesMap();
+    const macs = Object.keys(dm);
+    if (macs.length > 0) {
+        const m0 = macs[0];
+        return [String((dm[m0].name || "").trim() || m0)];
+    }
+    return ["1"];
+}
+
+/** Read zone device names from the presets section (JSON attr preferred; legacy comma list fallback). */
+function parseTabDeviceNames(section) {
+    if (!section) return [];
+    const enc = section.getAttribute("data-device-names-json");
+    if (enc) {
+        try {
+            const arr = JSON.parse(decodeURIComponent(enc));
+            return Array.isArray(arr) ? arr.map((n) => String(n).trim()).filter((n) => n.length > 0) : [];
+        } catch (e) {
+            /* ignore */
+        }
+    }
+    const legacy = section.getAttribute("data-device-names");
+    if (legacy) {
+        return legacy.split(",").map((n) => n.trim()).filter((n) => n.length > 0);
+    }
+    return [];
+}
+
+window.parseTabDeviceNames = parseTabDeviceNames;
+window.parseZoneDeviceNames = parseTabDeviceNames;
+
+function escapeHtmlAttr(s) {
+    return String(s)
+        .replace(/&/g, "&")
+        .replace(/"/g, """)
+        .replace(/</g, "&lt;");
+}
+
+// Load tabs list
+async function loadZones() {
+    try {
+        const response = await fetch('/zones');
+        const data = await response.json();
+        
+        // Get current zone from cookie first, then from server response
+        const cookieTabId = getCurrentZoneFromCookie();
+        const serverCurrent = data.current_zone_id;
+        const tabs = data.zones || {};
+        const zoneIds = Object.keys(tabs);
+
+        let candidateId = cookieTabId || serverCurrent || null;
+        // If the candidate doesn't exist anymore (e.g. after DB reset), fall back to first zone.
+        if (candidateId && !zoneIds.includes(String(candidateId))) {
+            candidateId = zoneIds.length > 0 ? zoneIds[0] : null;
+            // Clear stale cookie
+            document.cookie = 'current_zone=; path=/; max-age=0';
+        }
+
+        currentZoneId = candidateId;
+        renderZonesList(data.zones, data.zone_order, currentZoneId);
+        
+        // Load current zone content if available
+        if (currentZoneId) {
+            await loadZoneContent(currentZoneId);
+        } else if (data.zone_order && data.zone_order.length > 0) {
+            // Set first zone as current if none is set
+            const firstTabId = data.zone_order[0];
+            await setCurrentZone(firstTabId);
+            await loadZoneContent(firstTabId);
+        }
+    } catch (error) {
+        console.error('Failed to load zones:', error);
+        const container = document.getElementById('zones-list');
+        if (container) {
+            container.innerHTML = '<div class="error">Failed to load zones</div>';
+        }
+    }
+}
+
+// Render tabs list in the main UI
+function renderZonesList(tabs, tabOrder, currentZoneId) {
+    const container = document.getElementById('zones-list');
+    if (!container) return;
+    
+    if (!tabOrder || tabOrder.length === 0) {
+        container.innerHTML = '<div class="muted-text">No zones available</div>';
+        return;
+    }
+    
+    const editMode = isEditModeActive();
+    let html = '<div class="zones-list">';
+    for (const zoneId of tabOrder) {
+        const zone = tabs[zoneId];
+        if (zone) {
+            const activeClass = zoneId === currentZoneId ? 'active' : '';
+            const tabName = zone.name || `Zone ${zoneId}`;
+            html += `
+                <button class="zone-button ${activeClass}" 
+                        data-zone-id="${zoneId}"
+                        title="${editMode ? 'Click to select, right-click to edit' : 'Click to select'}"
+                        onclick="selectZone('${zoneId}')">
+                    ${tabName}
+                </button>
+            `;
+        }
+    }
+    html += '</div>';
+    container.innerHTML = html;
+}
+
+// Render tabs list in modal (like profiles)
+function renderZonesListModal(tabs, tabOrder, currentZoneId) {
+    const container = document.getElementById('zones-list-modal');
+    if (!container) return;
+    
+    container.innerHTML = "";
+    let entries = [];
+
+    if (Array.isArray(tabOrder)) {
+        entries = tabOrder.map((zoneId) => [zoneId, tabs[zoneId] || {}]);
+    } else if (tabs && typeof tabs === "object") {
+        entries = Object.entries(tabs).filter(([key]) => {
+            return key !== 'current_zone_id' && key !== 'zones' && key !== 'zone_order';
+        });
+    }
+
+    if (entries.length === 0) {
+        const empty = document.createElement("p");
+        empty.className = "muted-text";
+        empty.textContent = "No zones found.";
+        container.appendChild(empty);
+        return;
+    }
+
+    const editMode = isEditModeActive();
+    entries.forEach(([zoneId, zone]) => {
+        const row = document.createElement("div");
+        row.className = "profiles-row";
+        row.dataset.zoneId = String(zoneId);
+
+        const label = document.createElement("span");
+        label.textContent = (zone && zone.name) || zoneId;
+        if (String(zoneId) === String(currentZoneId)) {
+            label.textContent = `✓ ${label.textContent}`;
+            label.style.fontWeight = "bold";
+            label.style.color = "#FFD700";
+        }
+
+        const applyButton = document.createElement("button");
+        applyButton.className = "btn btn-secondary btn-small";
+        applyButton.textContent = "Select";
+        applyButton.addEventListener("click", async () => {
+            await selectZone(zoneId);
+            document.getElementById('zones-modal').classList.remove('active');
+        });
+
+        const editButton = document.createElement("button");
+        editButton.className = "btn btn-secondary btn-small";
+        editButton.textContent = "Edit";
+        editButton.addEventListener("click", async () => {
+            await openEditZoneModal(zoneId, zone);
+        });
+
+        const cloneButton = document.createElement("button");
+        cloneButton.className = "btn btn-secondary btn-small";
+        cloneButton.textContent = "Clone";
+        cloneButton.addEventListener("click", async () => {
+            const baseName = (zone && zone.name) || zoneId;
+            const suggested = `${baseName} Copy`;
+            const name = prompt("New zone name:", suggested);
+            if (name === null) {
+                return;
+            }
+            const trimmed = String(name).trim();
+            if (!trimmed) {
+                alert("Zone name cannot be empty.");
+                return;
+            }
+            try {
+                const response = await fetch(`/zones/${zoneId}/clone`, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        "Accept": "application/json",
+                    },
+                    body: JSON.stringify({ name: trimmed }),
+                });
+                if (!response.ok) {
+                    const errorData = await response.json().catch(() => ({ error: "Failed to clone zone" }));
+                    throw new Error(errorData.error || "Failed to clone zone");
+                }
+                const data = await response.json().catch(() => null);
+                let newTabId = null;
+                if (data && typeof data === "object") {
+                    if (data.id) {
+                        newTabId = String(data.id);
+                    } else {
+                        const ids = Object.keys(data);
+                        if (ids.length > 0) {
+                            newTabId = String(ids[0]);
+                        }
+                    }
+                }
+                await loadZonesModal();
+                if (newTabId) {
+                    await selectZone(newTabId);
+                } else {
+                    await loadZones();
+                }
+            } catch (error) {
+                console.error("Clone zone failed:", error);
+                alert("Failed to clone zone: " + error.message);
+            }
+        });
+
+        const deleteButton = document.createElement("button");
+        deleteButton.className = "btn btn-danger btn-small";
+        deleteButton.textContent = "Delete";
+        deleteButton.addEventListener("click", async () => {
+            const confirmed = confirm(`Delete zone "${label.textContent}"?`);
+            if (!confirmed) {
+                return;
+            }
+            try {
+                const response = await fetch(`/zones/${zoneId}`, {
+                    method: "DELETE",
+                    headers: { Accept: "application/json" },
+                });
+                if (!response.ok) {
+                    const errorData = await response.json().catch(() => ({ error: "Failed to delete zone" }));
+                    throw new Error(errorData.error || "Failed to delete zone");
+                }
+                // Clear cookie if deleted zone was current
+                if (zoneId === currentZoneId) {
+                    document.cookie = 'current_zone=; path=/; max-age=0';
+                    currentZoneId = null;
+                }
+                await loadZonesModal();
+                await loadZones(); // Reload main tabs list
+            } catch (error) {
+                console.error("Delete zone failed:", error);
+                alert("Failed to delete zone: " + error.message);
+            }
+        });
+
+        row.appendChild(label);
+        row.appendChild(applyButton);
+        if (editMode) {
+            row.appendChild(editButton);
+            row.appendChild(cloneButton);
+            row.appendChild(deleteButton);
+        }
+        container.appendChild(row);
+    });
+}
+
+// Load tabs in modal
+async function loadZonesModal() {
+    const container = document.getElementById('zones-list-modal');
+    if (!container) return;
+    
+    container.innerHTML = "";
+    const loading = document.createElement("p");
+    loading.className = "muted-text";
+    loading.textContent = "Loading zones...";
+    container.appendChild(loading);
+
+    try {
+        const response = await fetch("/zones", {
+            headers: { Accept: "application/json" },
+        });
+        if (!response.ok) {
+            throw new Error("Failed to load zones");
+        }
+        const data = await response.json();
+        const tabs = data.zones || data;
+        const currentZoneId = getCurrentZoneFromCookie() || data.current_zone_id || null;
+        renderZonesListModal(tabs, data.zone_order || [], currentZoneId);
+    } catch (error) {
+        console.error("Load tabs failed:", error);
+        container.innerHTML = "";
+        const errorMessage = document.createElement("p");
+        errorMessage.className = "muted-text";
+        errorMessage.textContent = "Failed to load zones.";
+        container.appendChild(errorMessage);
+    }
+}
+
+// Select a zone
+async function selectZone(zoneId) {
+    // Update active state
+    document.querySelectorAll('.zone-button').forEach(btn => {
+        btn.classList.remove('active');
+    });
+    const btn = document.querySelector(`[data-zone-id="${zoneId}"]`);
+    if (btn) {
+        btn.classList.add('active');
+    }
+    
+    // Set as current zone
+    await setCurrentZone(zoneId);
+    // Load zone content
+    loadZoneContent(zoneId);
+}
+
+// Set current zone in cookie
+async function setCurrentZone(zoneId) {
+    try {
+        const response = await fetch(`/zones/${zoneId}/set-current`, {
+            method: 'POST'
+        });
+        const data = await response.json();
+        if (response.ok) {
+            currentZoneId = zoneId;
+            // Also set cookie on client side
+            document.cookie = `current_zone=${zoneId}; path=/; max-age=31536000`;
+        } else {
+            console.error('Failed to set current zone:', data.error);
+        }
+    } catch (error) {
+        console.error('Error setting current zone:', error);
+    }
+}
+
+// Load zone content
+async function loadZoneContent(zoneId) {
+    const container = document.getElementById('zone-content');
+    if (!container) return;
+    
+    try {
+        const response = await fetch(`/zones/${zoneId}`);
+        const zone = await response.json();
+        
+        if (zone.error) {
+            container.innerHTML = `<div class="error">${zone.error}</div>`;
+            return;
+        }
+        
+        // Render zone content (presets section)
+        const tabName = zone.name || `Zone ${zoneId}`;
+        const names = Array.isArray(zone.names) ? zone.names : [];
+        const namesJsonAttr = encodeURIComponent(JSON.stringify(names));
+        const legacyOk = names.length > 0 && !names.some((n) => /[",]/.test(String(n)));
+        const legacyAttr = legacyOk ? ` data-device-names="${escapeHtmlAttr(names.join(","))}"` : "";
+        container.innerHTML = `
+            <div class="presets-section" data-zone-id="${zoneId}" data-device-names-json="${namesJsonAttr}"${legacyAttr}>
+                <div class="profiles-actions presets-toolbar" style="margin-bottom: 1rem;">
+                    <div class="zone-brightness-group">
+                        <label for="zone-brightness-slider">Brightness</label>
+                        <input type="range" id="zone-brightness-slider" min="0" max="255" value="255">
+                    </div>
+                </div>
+                <div id="presets-list-zone" class="presets-list">
+                    <!-- Presets will be loaded here by presets.js -->
+                </div>
+            </div>
+        `;
+
+        // Wire up per-zone brightness slider to send global brightness via ESPNow.
+        const brightnessSlider = container.querySelector('#zone-brightness-slider');
+        let brightnessSendTimeout = null;
+        if (brightnessSlider) {
+            brightnessSlider.addEventListener('input', (e) => {
+                const val = parseInt(e.target.value, 10) || 0;
+                if (brightnessSendTimeout) {
+                    clearTimeout(brightnessSendTimeout);
+                }
+                brightnessSendTimeout = setTimeout(() => {
+                    if (typeof window.sendEspnowRaw === 'function') {
+                        try {
+                            window.sendEspnowRaw({ v: '1', b: val, save: true });
+                        } catch (err) {
+                            console.error('Failed to send brightness via ESPNow:', err);
+                        }
+                    }
+                }, 150);
+            });
+        }
+        
+        // Trigger presets loading if the function exists
+        if (typeof renderTabPresets === 'function') {
+            renderTabPresets(zoneId);
+        }
+    } catch (error) {
+        console.error('Failed to load zone content:', error);
+        container.innerHTML = '<div class="error">Failed to load zone content</div>';
+    }
+}
+
+// Send all presets used by all tabs in the current profile via /presets/send.
+async function sendProfilePresets() {
+    try {
+        // Load current profile to get its tabs
+        const profileRes = await fetch('/profiles/current', {
+            headers: { Accept: 'application/json' },
+        });
+        if (!profileRes.ok) {
+            alert('Failed to load current profile.');
+            return;
+        }
+        const profileData = await profileRes.json();
+        const profile = profileData.profile || {};
+        let zoneList = null;
+        if (Array.isArray(profile.zones)) {
+            zoneList = profile.zones;
+        } else if (profile.zones) {
+            zoneList = [profile.zones];
+        }
+        if (!zoneList || zoneList.length === 0) {
+            if (Array.isArray(profile.zones)) {
+                zoneList = profile.zones;
+            } else if (profile.zones) {
+                zoneList = [profile.zones];
+            }
+        }
+        if (!zoneList || zoneList.length === 0) {
+            console.warn('sendProfilePresets: no zones found', {
+                profileData,
+                profile,
+            });
+        }
+
+        if (!zoneList.length) {
+            alert('Current profile has no zones to send presets for.');
+            return;
+        }
+
+        let totalSent = 0;
+        let totalMessages = 0;
+        let zonesWithPresets = 0;
+
+        for (const zoneId of zoneList) {
+            try {
+                const tabResp = await fetch(`/zones/${zoneId}`, {
+                    headers: { Accept: 'application/json' },
+                });
+                if (!tabResp.ok) {
+                    continue;
+                }
+                const tabData = await tabResp.json();
+                let presetIds = [];
+                if (Array.isArray(tabData.presets_flat)) {
+                    presetIds = tabData.presets_flat;
+                } else if (Array.isArray(tabData.presets)) {
+                    if (tabData.presets.length && typeof tabData.presets[0] === 'string') {
+                        presetIds = tabData.presets;
+                    } else if (tabData.presets.length && Array.isArray(tabData.presets[0])) {
+                        presetIds = tabData.presets.flat();
+                    }
+                }
+                presetIds = (presetIds || []).filter(Boolean);
+                if (!presetIds.length) {
+                    continue;
+                }
+                zonesWithPresets += 1;
+                const zoneNames = Array.isArray(tabData.names) ? tabData.names : [];
+                const targets = await resolveZoneDeviceMacs(zoneNames);
+                const payload = { preset_ids: presetIds };
+                if (tabData.default_preset) {
+                    payload.default = tabData.default_preset;
+                }
+                if (targets.length > 0) {
+                    payload.targets = targets;
+                }
+                const response = await fetch('/presets/send', {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Accept': 'application/json',
+                    },
+                    body: JSON.stringify(payload),
+                });
+                const data = await response.json().catch(() => ({}));
+                if (!response.ok) {
+                    const msg = (data && data.error) || `Failed to send presets for zone ${zoneId}.`;
+                    console.warn(msg);
+                    continue;
+                }
+                totalSent += typeof data.presets_sent === 'number' ? data.presets_sent : presetIds.length;
+                totalMessages += typeof data.messages_sent === 'number' ? data.messages_sent : 0;
+            } catch (e) {
+                console.error('Failed to send profile presets for zone:', zoneId, e);
+            }
+        }
+
+        if (!zonesWithPresets) {
+            alert('No presets to send for the current profile.');
+            return;
+        }
+
+        const messagesLabel = totalMessages ? totalMessages : '?';
+        alert(`Sent ${totalSent} preset(s) across ${zonesWithPresets} zone(s) (${messagesLabel} driver send(s)).`);
+    } catch (error) {
+        console.error('Failed to send profile presets:', error);
+        alert('Failed to send profile presets.');
+    }
+}
+
+function tabPresetIdsInOrder(tabData) {
+    let ids = [];
+    if (Array.isArray(tabData.presets_flat)) {
+        ids = tabData.presets_flat.slice();
+    } else if (Array.isArray(tabData.presets)) {
+        if (tabData.presets.length && typeof tabData.presets[0] === "string") {
+            ids = tabData.presets.slice();
+        } else if (tabData.presets.length && Array.isArray(tabData.presets[0])) {
+            ids = tabData.presets.flat();
+        }
+    }
+    return (ids || []).filter(Boolean);
+}
+
+// Presets already on the zone (remove) and presets available to add (select).
+async function refreshEditTabPresetsUi(zoneId) {
+    const currentEl = document.getElementById("edit-zone-presets-current");
+    const addEl = document.getElementById("edit-zone-presets-list");
+    if (!zoneId || !currentEl || !addEl) return;
+
+    currentEl.innerHTML = '<span class="muted-text">Loading…</span>';
+    addEl.innerHTML = '<span class="muted-text">Loading…</span>';
+
+    try {
+        const tabRes = await fetch(`/zones/${zoneId}`, { headers: { Accept: "application/json" } });
+        if (!tabRes.ok) {
+            const msg = '<span class="muted-text">Failed to load zone presets.</span>';
+            currentEl.innerHTML = msg;
+            addEl.innerHTML = msg;
+            return;
+        }
+        const tabData = await tabRes.json();
+        const inTabIds = tabPresetIdsInOrder(tabData);
+        const inTabSet = new Set(inTabIds.map((id) => String(id)));
+
+        const presetsRes = await fetch("/presets", { headers: { Accept: "application/json" } });
+        const allPresets = presetsRes.ok ? await presetsRes.json() : {};
+
+        const makeRow = () => {
+            const row = document.createElement("div");
+            row.className = "profiles-row";
+            row.style.display = "flex";
+            row.style.alignItems = "center";
+            row.style.justifyContent = "space-between";
+            row.style.gap = "0.5rem";
+            return row;
+        };
+
+        currentEl.innerHTML = "";
+        if (inTabIds.length === 0) {
+            currentEl.innerHTML = '<span class="muted-text">No presets on this zone yet.</span>';
+        } else {
+            for (const presetId of inTabIds) {
+                const preset = allPresets[presetId] || {};
+                const name = preset.name || presetId;
+                const row = makeRow();
+                const label = document.createElement("span");
+                label.textContent = name;
+                const removeBtn = document.createElement("button");
+                removeBtn.type = "button";
+                removeBtn.className = "btn btn-danger btn-small";
+                removeBtn.textContent = "Remove";
+                removeBtn.addEventListener("click", async () => {
+                    if (typeof window.removePresetFromTab !== "function") return;
+                    if (!window.confirm(`Remove this preset from the zone?\n\n${name}`)) return;
+                    await window.removePresetFromTab(zoneId, presetId);
+                    await refreshEditTabPresetsUi(zoneId);
+                });
+                row.appendChild(label);
+                row.appendChild(removeBtn);
+                currentEl.appendChild(row);
+            }
+        }
+
+        const allIds = Object.keys(allPresets);
+        const availableToAdd = allIds.filter((id) => !inTabSet.has(String(id)));
+        addEl.innerHTML = "";
+        if (availableToAdd.length === 0) {
+            addEl.innerHTML =
+                '<span class="muted-text">No presets to add. All presets are already on this zone.</span>';
+        } else {
+            const addWrap = document.createElement("div");
+            addWrap.className = "zone-devices-add profiles-actions";
+            const sel = document.createElement("select");
+            sel.className = "zone-device-add-select";
+            sel.setAttribute("aria-label", "Preset to add to this zone");
+            sel.appendChild(new Option("Add preset…", ""));
+            const sorted = availableToAdd.slice().sort((a, b) => {
+                const na = (allPresets[a] && allPresets[a].name) || a;
+                const nb = (allPresets[b] && allPresets[b].name) || b;
+                return String(na).localeCompare(String(nb), undefined, { sensitivity: "base" });
+            });
+            sorted.forEach((presetId) => {
+                const preset = allPresets[presetId] || {};
+                const name = preset.name || presetId;
+                sel.appendChild(new Option(`${name} — ${presetId}`, presetId));
+            });
+            const addBtn = document.createElement("button");
+            addBtn.type = "button";
+            addBtn.className = "btn btn-primary btn-small";
+            addBtn.textContent = "Add";
+            addBtn.addEventListener("click", async () => {
+                const presetId = sel.value;
+                if (!presetId) return;
+                if (typeof window.addPresetToTab === "function") {
+                    await window.addPresetToTab(presetId, zoneId);
+                    sel.value = "";
+                    await refreshEditTabPresetsUi(zoneId);
+                }
+            });
+            addWrap.appendChild(sel);
+            addWrap.appendChild(addBtn);
+            addEl.appendChild(addWrap);
+        }
+    } catch (e) {
+        console.error("refreshEditTabPresetsUi:", e);
+        const msg = '<span class="muted-text">Failed to load presets.</span>';
+        currentEl.innerHTML = msg;
+        addEl.innerHTML = msg;
+    }
+}
+
+async function populateEditTabPresetsList(zoneId) {
+    await refreshEditTabPresetsUi(zoneId);
+}
+
+// Open edit zone modal
+async function openEditZoneModal(zoneId, zone) {
+    const modal = document.getElementById("edit-zone-modal");
+    const idInput = document.getElementById("edit-zone-id");
+    const nameInput = document.getElementById("edit-zone-name");
+    const editor = document.getElementById("edit-zone-devices-editor");
+
+    let tabData = zone;
+    if (!tabData || typeof tabData !== "object" || tabData.error) {
+        try {
+            const response = await fetch(`/zones/${zoneId}`);
+            if (response.ok) {
+                tabData = await response.json();
+            }
+        } catch (e) {
+            console.error("openEditZoneModal fetch zone:", e);
+        }
+    }
+    tabData = tabData || {};
+
+    if (idInput) idInput.value = zoneId;
+    if (nameInput) nameInput.value = tabData.name || "";
+
+    const devicesMap = await fetchDevicesMap();
+    const zoneNames =
+        Array.isArray(tabData.names) && tabData.names.length > 0 ? tabData.names : ["1"];
+    window.__editTabDeviceRows = namesToRows(zoneNames, devicesMap);
+    renderZoneDevicesEditor(editor, window.__editTabDeviceRows, devicesMap);
+
+    if (modal) modal.classList.add("active");
+    await refreshEditTabPresetsUi(zoneId);
+}
+
+function normalizeTabNamesArg(namesOrString) {
+    if (Array.isArray(namesOrString)) {
+        return namesOrString.map((n) => String(n).trim()).filter((n) => n.length > 0);
+    }
+    if (typeof namesOrString === "string" && namesOrString.trim()) {
+        return namesOrString.split(",").map((id) => id.trim()).filter((id) => id.length > 0);
+    }
+    return ["1"];
+}
+
+// Update an existing zone
+async function updateZone(zoneId, name, namesOrString) {
+    try {
+        let names = normalizeTabNamesArg(namesOrString);
+        if (!names.length) names = ["1"];
+        const response = await fetch(`/zones/${zoneId}`, {
+            method: 'PUT',
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({
+                name: name,
+                names: names
+            })
+        });
+        
+        const data = await response.json();
+        if (response.ok) {
+            // Reload tabs list
+            await loadZonesModal();
+            await loadZones();
+            // Close modal
+            document.getElementById('edit-zone-modal').classList.remove('active');
+            return true;
+        } else {
+            alert(`Error: ${data.error || 'Failed to update zone'}`);
+            return false;
+        }
+    } catch (error) {
+        console.error('Failed to update zone:', error);
+        alert('Failed to update zone');
+        return false;
+    }
+}
+
+// Create a new zone
+async function createZone(name, namesOrString) {
+    try {
+        let names = normalizeTabNamesArg(namesOrString);
+        if (!names.length) names = ["1"];
+        const response = await fetch('/zones', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({
+                name: name,
+                names: names
+            })
+        });
+        
+        const data = await response.json();
+        if (response.ok) {
+            // Reload tabs list
+            await loadZonesModal();
+            await loadZones();
+            // Select the new zone
+            if (data && Object.keys(data).length > 0) {
+                const newTabId = Object.keys(data)[0];
+                await selectZone(newTabId);
+            }
+            return true;
+        } else {
+            alert(`Error: ${data.error || 'Failed to create zone'}`);
+            return false;
+        }
+    } catch (error) {
+        console.error('Failed to create zone:', error);
+        alert('Failed to create zone');
+        return false;
+    }
+}
+
+// Initialize on page load
+document.addEventListener('DOMContentLoaded', () => {
+    loadZones();
+    
+    // Set up tabs modal
+    const tabsButton = document.getElementById('zones-btn');
+    const zonesModal = document.getElementById('zones-modal');
+    const tabsCloseButton = document.getElementById('zones-close-btn');
+    const newTabNameInput = document.getElementById("new-zone-name");
+    const createZoneButton = document.getElementById("create-zone-btn");
+
+    if (tabsButton && zonesModal) {
+        tabsButton.addEventListener("click", async () => {
+            zonesModal.classList.add("active");
+            await loadZonesModal();
+        });
+    }
+    
+    if (tabsCloseButton) {
+        tabsCloseButton.addEventListener('click', () => {
+            zonesModal.classList.remove('active');
+        });
+    }
+    
+    // Right-click on a zone button in the main header bar to edit that zone
+    document.addEventListener('contextmenu', async (event) => {
+        if (!isEditModeActive()) {
+            return;
+        }
+        const btn = event.target.closest('.zone-button');
+        if (!btn || !btn.dataset.zoneId) {
+            return;
+        }
+        event.preventDefault();
+        const zoneId = btn.dataset.zoneId;
+        try {
+            const response = await fetch(`/zones/${zoneId}`);
+            if (response.ok) {
+                const zone = await response.json();
+                await openEditZoneModal(zoneId, zone);
+            } else {
+                alert('Failed to load zone for editing');
+            }
+        } catch (error) {
+            console.error('Failed to load zone:', error);
+            alert('Failed to load zone for editing');
+        }
+    });
+    
+    // Set up create zone
+    const createZoneHandler = async () => {
+        if (!newTabNameInput) return;
+        const name = newTabNameInput.value.trim();
+
+        if (name) {
+            const deviceNames = await defaultDeviceNamesForNewTab();
+            await createZone(name, deviceNames);
+            if (newTabNameInput) newTabNameInput.value = "";
+        }
+    };
+    
+    if (createZoneButton) {
+        createZoneButton.addEventListener('click', createZoneHandler);
+    }
+    
+    if (newTabNameInput) {
+        newTabNameInput.addEventListener('keypress', (event) => {
+            if (event.key === 'Enter') {
+                createZoneHandler();
+            }
+        });
+    }
+    
+    // Set up edit zone form
+    const editZoneForm = document.getElementById('edit-zone-form');
+    if (editZoneForm) {
+        editZoneForm.addEventListener("submit", async (e) => {
+            e.preventDefault();
+            const idInput = document.getElementById("edit-zone-id");
+            const nameInput = document.getElementById("edit-zone-name");
+
+            const zoneId = idInput ? idInput.value : null;
+            const name = nameInput ? nameInput.value.trim() : "";
+            const rows = window.__editTabDeviceRows || [];
+            const deviceNames = rowsToNames(rows);
+
+            if (zoneId && name) {
+                if (deviceNames.length === 0) {
+                    alert("Add at least one device.");
+                    return;
+                }
+                await updateZone(zoneId, name, deviceNames);
+                editZoneForm.reset();
+            }
+        });
+    }
+    
+    // Profile-wide "Send Presets" button in header
+    const sendProfilePresetsBtn = document.getElementById('send-profile-presets-btn');
+    if (sendProfilePresetsBtn) {
+        sendProfilePresetsBtn.addEventListener('click', async () => {
+            await sendProfilePresets();
+        });
+    }
+
+    // When run/edit mode toggles, refresh tabs UI so edit actions show/hide immediately.
+    document.querySelectorAll('.ui-mode-toggle').forEach((btn) => {
+        btn.addEventListener('click', async () => {
+            await loadZones();
+            if (zonesModal && zonesModal.classList.contains("active")) {
+                await loadZonesModal();
+            }
+        });
+    });
+});
+
+// Export for use in other scripts
+window.zonesManager = {
+    loadZones,
+    loadZonesModal,
+    selectZone,
+    createZone,
+    updateZone,
+    openEditZoneModal,
+    resolveZoneDeviceMacs,
+    resolveTabDeviceMacs: resolveZoneDeviceMacs,
+    getCurrentZoneId: () => currentZoneId,
+};
+window.tabsManager = window.zonesManager;
+window.tabsManager.getCurrentTabId = () => currentZoneId;
+window.tabsManager.loadTabs = loadZones;
+window.tabsManager.loadTabsModal = loadZonesModal;
+window.tabsManager.openEditTabModal = openEditZoneModal;

src/templates/index.html

@@ -1,14 +1,538 @@
-<!doctype html>
+<!DOCTYPE html>
 <html lang="en">
-    <head>
+<head>
-        <meta charset="UTF-8" />
+    <meta charset="UTF-8">
-        <title>RGB Slider Tabs</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-        <link rel="stylesheet" href="styles.css" />
+    <title>LED Controller - Zone Mode</title>
-    </head>
+    <link rel="stylesheet" href="/static/style.css">
-    <body>
+</head>
-        <div class="tabs"></div>
+<body>
-        <div class="tab-content"></div>
+    <div class="app-container">
+        <header>
+            <div class="zones-container">
+                <div id="zones-list">
+                    Loading zones...
+                </div>
+            </div>
+            <div class="header-actions">
+                <button class="btn btn-secondary" id="profiles-btn">Profiles</button>
+                <button class="btn btn-secondary edit-mode-only" id="devices-btn">Devices</button>
+                <button class="btn btn-secondary edit-mode-only" id="zones-btn">Zones</button>
+                <button class="btn btn-secondary edit-mode-only" id="presets-btn">Presets</button>
+                <button class="btn btn-secondary edit-mode-only" id="patterns-btn">Patterns</button>
+                <button class="btn btn-secondary edit-mode-only" id="color-palette-btn">Colour Palette</button>
+                <button class="btn btn-secondary edit-mode-only" id="send-profile-presets-btn">Send Presets</button>
+                <button class="btn btn-secondary edit-mode-only" id="led-tool-btn">LED Tool</button>
+                <button class="btn btn-secondary" id="help-btn">Help</button>
+                <button type="button" class="btn btn-secondary ui-mode-toggle" id="ui-mode-toggle" aria-pressed="false" title="Switch preset strip mode — label is the mode you will switch to">Edit mode</button>
+            </div>
+            <div class="header-menu-mobile">
+                <button class="btn btn-secondary" id="main-menu-btn">Menu</button>
+                <div id="main-menu-dropdown" class="main-menu-dropdown">
+                    <button type="button" class="ui-mode-toggle" id="ui-mode-toggle-mobile" aria-pressed="false">Edit mode</button>
+                    <button type="button" data-target="profiles-btn">Profiles</button>
+                    <button type="button" class="edit-mode-only" data-target="devices-btn">Devices</button>
+                    <button type="button" class="edit-mode-only" data-target="zones-btn">Tabs</button>
+                    <button type="button" class="edit-mode-only" data-target="presets-btn">Presets</button>
+                    <button type="button" class="edit-mode-only" data-target="patterns-btn">Patterns</button>
+                    <button type="button" class="edit-mode-only" data-target="color-palette-btn">Colour Palette</button>
+                    <button type="button" class="edit-mode-only" data-target="send-profile-presets-btn">Send Presets</button>
+                    <button type="button" class="edit-mode-only" data-target="led-tool-btn">LED Tool</button>
+                    <button type="button" data-target="help-btn">Help</button>
+                </div>
+            </div>
+        </header>
 
-        <script type="module" src="main.js"></script>
+        <div class="main-content">
-    </body>
+            <div id="zone-content" class="zone-content">
+                <div class="zone-content-placeholder">
+                    Select a zone to get started
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <!-- Tabs Modal -->
+    <div id="zones-modal" class="modal">
+        <div class="modal-content">
+            <h2>Tabs</h2>
+            <div class="profiles-actions zone-modal-create-row">
+                <input type="text" id="new-zone-name" placeholder="Zone name">
+                <button class="btn btn-primary" id="create-zone-btn">Create</button>
+            </div>
+            <div id="zones-list-modal" class="profiles-list"></div>
+            <div class="modal-actions">
+                <button class="btn btn-secondary" id="zones-close-btn">Close</button>
+            </div>
+        </div>
+    </div>
+
+    <!-- Edit Zone Modal -->
+    <div id="edit-zone-modal" class="modal">
+        <div class="modal-content">
+            <h2>Edit Zone</h2>
+            <form id="edit-zone-form">
+                <input type="hidden" id="edit-zone-id">
+                <div class="modal-actions" style="margin-bottom: 1rem;">
+                    <button type="submit" class="btn btn-primary">Save</button>
+                    <button type="button" class="btn btn-secondary" onclick="document.getElementById('edit-zone-modal').classList.remove('active')">Close</button>
+                </div>
+                <label>Zone Name:</label>
+                <input type="text" id="edit-zone-name" placeholder="Enter zone name" required>
+                <label class="zone-devices-label">Devices in this zone</label>
+                <div id="edit-zone-devices-editor" class="zone-devices-editor"></div>
+                <label class="zone-presets-section-label">Presets on this zone</label>
+                <div id="edit-zone-presets-current" class="profiles-list edit-zone-presets-scroll"></div>
+                <label class="zone-presets-section-label">Add presets to this zone</label>
+                <div id="edit-zone-presets-list" class="profiles-list edit-zone-presets-scroll"></div>
+            </form>
+        </div>
+    </div>
+
+    <!-- Profiles Modal -->
+    <div id="profiles-modal" class="modal">
+        <div class="modal-content">
+            <h2>Profiles</h2>
+            <div class="profiles-actions">
+                <input type="text" id="new-profile-name" placeholder="Profile name">
+                <button class="btn btn-primary" id="create-profile-btn">Create</button>
+            </div>
+            <div class="form-group" style="margin-top: 0.5rem; margin-bottom: 0;">
+                <label style="display: flex; align-items: center; gap: 0.5rem; margin-bottom: 0;">
+                    <input type="checkbox" id="new-profile-seed-dj">
+                    DJ zone
+                </label>
+            </div>
+            <div id="profiles-list" class="profiles-list"></div>
+            <div class="modal-actions">
+                <button class="btn btn-secondary" id="profiles-close-btn">Close</button>
+            </div>
+        </div>
+    </div>
+
+    <!-- Devices Modal (registry: Wi-Fi drivers appear when they connect over TCP) -->
+    <div id="devices-modal" class="modal">
+        <div class="modal-content">
+            <h2>Devices</h2>
+            <div id="devices-list-modal" class="profiles-list"></div>
+            <div class="modal-actions">
+                <button type="button" class="btn btn-secondary" id="devices-close-btn">Close</button>
+            </div>
+        </div>
+    </div>
+
+    <div id="edit-device-modal" class="modal">
+        <div class="modal-content">
+            <h2>Edit device</h2>
+            <form id="edit-device-form">
+                <input type="hidden" id="edit-device-id">
+                <p class="muted-text" style="margin-bottom:0.75rem;">MAC (id): <code id="edit-device-storage-id"></code></p>
+                <label for="edit-device-name">Name</label>
+                <input type="text" id="edit-device-name" required autocomplete="off">
+                <label for="edit-device-type" style="margin-top:0.75rem;display:block;">Type</label>
+                <select id="edit-device-type">
+                    <option value="led">LED</option>
+                </select>
+                <label for="edit-device-transport" style="margin-top:0.75rem;display:block;">Transport</label>
+                <select id="edit-device-transport">
+                    <option value="espnow">ESP-NOW</option>
+                    <option value="wifi">WiFi</option>
+                </select>
+                <div id="edit-device-address-espnow" style="margin-top:0.75rem;">
+                    <label class="device-field-label">MAC (12 hex, optional)</label>
+                    <div id="edit-device-address-boxes" class="hex-address-row" aria-label="MAC address"></div>
+                </div>
+                <div id="edit-device-address-wifi-wrap" style="margin-top:0.75rem;" hidden>
+                    <label for="edit-device-address-wifi">Address (IP or hostname)</label>
+                    <input type="text" id="edit-device-address-wifi" placeholder="192.168.1.50" autocomplete="off">
+                </div>
+                <div class="modal-actions">
+                    <button type="submit" class="btn btn-primary">Save</button>
+                    <button type="button" class="btn btn-secondary" id="edit-device-close-btn">Cancel</button>
+                </div>
+            </form>
+        </div>
+    </div>
+
+    <!-- Presets Modal -->
+    <div id="presets-modal" class="modal">
+        <div class="modal-content">
+            <h2>Presets</h2>
+            <div class="modal-actions">
+                <button class="btn btn-primary" id="preset-add-btn">Add</button>
+                <button class="btn btn-danger" id="preset-clear-device-btn">Clear Device Presets</button>
+            </div>
+            <div id="presets-list" class="profiles-list"></div>
+            <div class="modal-actions">
+                <button class="btn btn-secondary" id="presets-close-btn">Close</button>
+            </div>
+        </div>
+    </div>
+
+    <!-- Preset Editor Modal -->
+    <div id="preset-editor-modal" class="modal">
+        <div class="modal-content">
+            <h2>Preset</h2>
+            <div class="profiles-actions">
+                <input type="text" id="preset-name-input" placeholder="Preset name">
+                <select id="preset-pattern-input">
+                    <option value="">Pattern</option>
+                </select>
+            </div>
+            <label>Colours</label>
+            <div id="preset-colors-container" class="preset-colors-container"></div>
+            <div class="profiles-actions">
+                <input type="color" id="preset-new-color" value="#ffffff" title="Choose colour (auto-adds)">
+                <button class="btn btn-secondary btn-small" id="preset-add-from-palette-btn">From Palette</button>
+            </div>
+            <div class="profiles-actions">
+                <div class="preset-editor-field">
+                    <label for="preset-brightness-input">Brightness (0–255)</label>
+                    <input type="number" id="preset-brightness-input" placeholder="Brightness" min="0" max="255" value="0">
+                </div>
+                <div class="preset-editor-field">
+                    <label for="preset-delay-input">Delay (ms)</label>
+                    <input type="number" id="preset-delay-input" placeholder="Delay" min="0" max="10000" value="0">
+                </div>
+            </div>
+            <div class="n-params-grid">
+                <div class="n-param-group">
+                    <label for="preset-n1-input" id="preset-n1-label">n1:</label>
+                    <input type="number" id="preset-n1-input" min="0" max="255" value="0" class="n-input">
+                </div>
+                <div class="n-param-group">
+                    <label for="preset-n2-input" id="preset-n2-label">n2:</label>
+                    <input type="number" id="preset-n2-input" min="0" max="255" value="0" class="n-input">
+                </div>
+                <div class="n-param-group">
+                    <label for="preset-n3-input" id="preset-n3-label">n3:</label>
+                    <input type="number" id="preset-n3-input" min="0" max="255" value="0" class="n-input">
+                </div>
+                <div class="n-param-group">
+                    <label for="preset-n4-input" id="preset-n4-label">n4:</label>
+                    <input type="number" id="preset-n4-input" min="0" max="255" value="0" class="n-input">
+                </div>
+                <div class="n-param-group">
+                    <label for="preset-n5-input" id="preset-n5-label">n5:</label>
+                    <input type="number" id="preset-n5-input" min="0" max="255" value="0" class="n-input">
+                </div>
+                <div class="n-param-group">
+                    <label for="preset-n6-input" id="preset-n6-label">n6:</label>
+                    <input type="number" id="preset-n6-input" min="0" max="255" value="0" class="n-input">
+                </div>
+                <div class="n-param-group">
+                    <label for="preset-n7-input" id="preset-n7-label">n7:</label>
+                    <input type="number" id="preset-n7-input" min="0" max="255" value="0" class="n-input">
+                </div>
+                <div class="n-param-group">
+                    <label for="preset-n8-input" id="preset-n8-label">n8:</label>
+                    <input type="number" id="preset-n8-input" min="0" max="255" value="0" class="n-input">
+                </div>
+            </div>
+            <div class="modal-actions preset-editor-modal-actions">
+                <button class="btn btn-secondary" id="preset-send-btn">Try</button>
+                <button class="btn btn-secondary" id="preset-default-btn">Default</button>
+                <button type="button" class="btn btn-danger" id="preset-remove-from-zone-btn" hidden>Remove from zone</button>
+                <button class="btn btn-primary" id="preset-save-btn">Save &amp; Send</button>
+                <button class="btn btn-secondary" id="preset-editor-close-btn">Close</button>
+            </div>
+        </div>
+    </div>
+
+    <!-- Patterns Modal -->
+    <div id="patterns-modal" class="modal">
+        <div class="modal-content">
+            <h2>Patterns</h2>
+            <div class="modal-actions">
+                <button type="button" class="btn btn-primary" id="pattern-add-btn">Add</button>
+            </div>
+            <div id="patterns-list" class="profiles-list"></div>
+            <div class="modal-actions">
+                <button class="btn btn-secondary" id="patterns-close-btn">Close</button>
+            </div>
+        </div>
+    </div>
+
+    <!-- Pattern Editor Modal -->
+    <div id="pattern-editor-modal" class="modal">
+        <div class="modal-content">
+            <h2>Pattern</h2>
+            <p class="muted-text" style="margin: 0 0 0.75rem 0;">Add a driver <code>.py</code> file and editor metadata (stored in the pattern database).</p>
+            <div class="profiles-row" style="flex-wrap: wrap; gap: 0.5rem; margin-bottom: 0.5rem;">
+                <label for="pattern-create-name" style="min-width: 7rem;">Name</label>
+                <input type="text" id="pattern-create-name" class="preset-name-like" placeholder="e.g. sparkle" pattern="[a-zA-Z_][a-zA-Z0-9_]*" style="flex: 1; min-width: 12rem;" autocomplete="off">
+            </div>
+            <div id="pattern-create-n-section" class="n-params-section" style="margin-bottom: 0.5rem;">
+                <h3 class="muted-text">Readable parameter names</h3>
+                <p id="pattern-create-n-empty" class="muted-text" style="display: none; margin: 0 0 0.5rem 0;">No parameter names are stored for this pattern.</p>
+                <div class="n-params-grid">
+                    <div class="n-param-group">
+                        <label for="pattern-create-n1"></label>
+                        <input type="text" id="pattern-create-n1" class="n-input pattern-n-readable-input" placeholder="" autocomplete="off">
+                    </div>
+                    <div class="n-param-group">
+                        <label for="pattern-create-n2"></label>
+                        <input type="text" id="pattern-create-n2" class="n-input pattern-n-readable-input" placeholder="" autocomplete="off">
+                    </div>
+                    <div class="n-param-group">
+                        <label for="pattern-create-n3"></label>
+                        <input type="text" id="pattern-create-n3" class="n-input pattern-n-readable-input" placeholder="" autocomplete="off">
+                    </div>
+                    <div class="n-param-group">
+                        <label for="pattern-create-n4"></label>
+                        <input type="text" id="pattern-create-n4" class="n-input pattern-n-readable-input" placeholder="" autocomplete="off">
+                    </div>
+                    <div class="n-param-group">
+                        <label for="pattern-create-n5"></label>
+                        <input type="text" id="pattern-create-n5" class="n-input pattern-n-readable-input" placeholder="" autocomplete="off">
+                    </div>
+                    <div class="n-param-group">
+                        <label for="pattern-create-n6"></label>
+                        <input type="text" id="pattern-create-n6" class="n-input pattern-n-readable-input" placeholder="" autocomplete="off">
+                    </div>
+                    <div class="n-param-group">
+                        <label for="pattern-create-n7"></label>
+                        <input type="text" id="pattern-create-n7" class="n-input pattern-n-readable-input" placeholder="" autocomplete="off">
+                    </div>
+                    <div class="n-param-group">
+                        <label for="pattern-create-n8"></label>
+                        <input type="text" id="pattern-create-n8" class="n-input pattern-n-readable-input" placeholder="" autocomplete="off">
+                    </div>
+                </div>
+            </div>
+            <div class="profiles-row pattern-editor-meta-row" style="flex-wrap: wrap; gap: 0.5rem; margin-bottom: 0.5rem;">
+                <label for="pattern-create-min-delay" style="min-width: 7rem;">Min delay (ms)</label>
+                <input type="number" id="pattern-create-min-delay" min="0" value="10">
+                <label for="pattern-create-max-delay">Max delay (ms)</label>
+                <input type="number" id="pattern-create-max-delay" min="0" value="10000">
+                <label for="pattern-create-max-colors">Max colours</label>
+                <input type="number" id="pattern-create-max-colors" min="0" value="10">
+            </div>
+            <div class="profiles-row" style="flex-direction: column; align-items: stretch; gap: 0.35rem; margin-bottom: 0.5rem;">
+                <label for="pattern-create-file">Pattern file</label>
+                <input type="file" id="pattern-create-file" accept=".py,text/x-python,.PY">
+                <label for="pattern-create-code" class="muted-text" style="font-size: 0.85em;">Or paste Python source (if no file chosen)</label>
+                <textarea id="pattern-create-code" rows="5" style="width: 100%; font-family: monospace; font-size: 0.85rem;" placeholder="# class MyPattern: ..."></textarea>
+            </div>
+            <div class="modal-actions">
+                <label style="display: inline-flex; align-items: center; gap: 0.35rem; margin-right: auto;">
+                    <input type="checkbox" id="pattern-create-overwrite" checked>
+                    <span>Overwrite existing file</span>
+                </label>
+                <button type="button" class="btn btn-primary" id="pattern-create-btn">Save</button>
+                <button type="button" class="btn btn-secondary" id="pattern-editor-close-btn">Close</button>
+            </div>
+        </div>
+    </div>
+
+    <!-- Colour Palette Modal -->
+    <div id="color-palette-modal" class="modal">
+        <div class="modal-content">
+            <h2>Colour Palette</h2>
+            <p class="muted-text">Profile: <span id="palette-current-profile-name">None</span></p>
+            <div id="palette-container" class="profiles-list"></div>
+            <div class="profiles-actions">
+                <input type="color" id="palette-new-color" value="#ffffff">
+            </div>
+            <div class="modal-actions">
+                <button class="btn btn-secondary" id="color-palette-close-btn">Close</button>
+            </div>
+        </div>
+    </div>
+
+    <!-- Help Modal -->
+    <div id="help-modal" class="modal">
+        <div class="modal-content">
+            <h2>Help</h2>
+            <p class="muted-text">How to use the LED controller UI.</p>
+
+            <h3>Run mode</h3>
+            <ul>
+                <li><strong>Select zone</strong>: left-click a zone button in the top bar.</li>
+                <li><strong>Select preset</strong>: left-click a preset tile to send a <code>select</code> message to all devices in the zone.</li>
+                <li><strong>Profiles</strong>: open <strong>Profiles</strong> to apply a profile. Profile editing actions are hidden in Run mode.</li>
+                <li><strong>Devices</strong>: open <strong>Devices</strong> to see drivers (Wi-Fi clients appear when they connect); edit or remove rows as needed.</li>
+                <li><strong>Send all presets</strong>: this action is available in <strong>Edit mode</strong> and pushes every preset used in the current zone to all zone devices.</li>
+                <li><strong>Switch modes</strong>: use the mode button in the menu. The button label shows the mode you will switch to.</li>
+            </ul>
+
+            <h3>Edit mode</h3>
+            <ul>
+                <li><strong>Tabs</strong>: create, edit, and manage tabs and device assignments.</li>
+                <li><strong>Presets</strong>: create/manage reusable presets and edit preset details.</li>
+                <li><strong>Preset tiles</strong>: each tile shows <strong>Edit</strong> and <strong>Remove</strong> controls in Edit mode.</li>
+                <li><strong>Reorder presets</strong>: drag and drop preset tiles to save zone order.</li>
+                <li><strong>Profiles</strong>: create/clone/delete profiles. New profiles get a populated <strong>default</strong> zone and can optionally seed a <strong>DJ zone</strong>.</li>
+                <li><strong>Devices</strong>: view, edit, or remove registry entries (tabs use <strong>names</strong>; each row is keyed by <strong>MAC</strong>).</li>
+                <li><strong>Colour Palette</strong>: build profile colours and use <strong>From Palette</strong> in preset editor to add linked colours (badge <strong>P</strong>) that update when palette colours change.</li>
+            </ul>
+
+            <h3>What led-tool does</h3>
+            <ul>
+                <li><strong>USB device setup</strong>: updates <code>settings.json</code> on ESP32 drivers over serial (for example name, pin, LED count, Wi-Fi credentials).</li>
+                <li><strong>Deploy and maintenance</strong>: uploads driver files, flashes firmware, resets device, and follows serial logs.</li>
+                <li><strong>Scope</strong>: led-tool configures devices directly; this web UI controls profiles/zones/presets and sends runtime messages.</li>
+            </ul>
+
+            <div class="modal-actions">
+                <button class="btn btn-secondary" id="help-close-btn">Close</button>
+            </div>
+        </div>
+    </div>
+
+    <!-- Settings Modal -->
+    <div id="settings-modal" class="modal">
+        <div class="modal-content">
+            <h2>Device Settings</h2>
+            <p class="muted-text">Configure WiFi Access Point and device settings.</p>
+
+            <div id="settings-message" class="message"></div>
+
+            <!-- Device Name -->
+            <div class="settings-section">
+                <h3>Device</h3>
+                <form id="device-form">
+                    <div class="form-group">
+                        <label for="device-name-input">Device Name</label>
+                        <input type="text" id="device-name-input" name="device_name" placeholder="e.g. led-controller" required>
+                        <small>This name may be used for mDNS (e.g. <code>name.local</code>) and UI display.</small>
+                    </div>
+                    <div class="form-group">
+                        <label for="wifi-channel-input">WiFi channel (ESP-NOW)</label>
+                        <input type="number" id="wifi-channel-input" name="wifi_channel" min="1" max="11" required>
+                        <small>STA channel (1–11) for LED drivers and the serial bridge. Use the same value everywhere.</small>
+                    </div>
+                    <div class="btn-group">
+                        <button type="submit" class="btn btn-primary btn-full">Save device settings</button>
+                    </div>
+                </form>
+            </div>
+
+            <!-- WiFi Access Point Settings -->
+            <div class="settings-section ap-settings-section">
+                <h3>WiFi Access Point</h3>
+
+                <div id="ap-status" class="status-info">
+                    <h4>AP Status</h4>
+                    <p>Loading...</p>
+                </div>
+
+                <form id="ap-form">
+                    <div class="form-group">
+                        <label for="ap-ssid">AP SSID (Network Name)</label>
+                        <input type="text" id="ap-ssid" name="ssid" placeholder="Enter AP name" required>
+                        <small>The name of the WiFi access point this device creates</small>
+                    </div>
+
+                    <div class="form-group">
+                        <label for="ap-password">AP Password</label>
+                        <input type="password" id="ap-password" name="password" placeholder="Enter AP password (min 8 chars)" data-bwignore>
+                        <small>Leave empty for open network (min 8 characters if set)</small>
+                    </div>
+
+                    <div class="form-group">
+                        <label for="ap-channel">Channel (1-11)</label>
+                        <input type="number" id="ap-channel" name="channel" min="1" max="11" placeholder="Auto">
+                        <small>WiFi channel (1-11 for 2.4GHz). Leave empty for auto.</small>
+                    </div>
+
+                    <div class="btn-group">
+                        <button type="submit" class="btn btn-primary btn-full">Configure AP</button>
+                    </div>
+                </form>
+            </div>
+
+            <div class="modal-actions">
+                <button class="btn btn-secondary" id="settings-close-btn">Close</button>
+            </div>
+        </div>
+    </div>
+
+    <!-- LED Tool Modal -->
+    <div id="led-tool-modal" class="modal">
+        <div class="modal-content">
+            <h2>LED Tool (USB)</h2>
+            <p class="muted-text" style="margin-top: 0;">Configure a driver connected over USB using <code>led-tool</code>.</p>
+            <div id="led-tool-message" class="message" style="margin-bottom: 0.75rem;"></div>
+            <form id="led-tool-form">
+                <div class="form-group">
+                    <label for="led-tool-port">Serial port</label>
+                    <div class="profiles-actions" style="gap: 0.5rem;">
+                        <select id="led-tool-port" required style="flex:1;">
+                            <option value="">Select a serial port</option>
+                        </select>
+                        <button type="button" class="btn btn-secondary" id="led-tool-refresh-ports-btn">Refresh</button>
+                    </div>
+                </div>
+
+                <div class="form-group">
+                    <label for="led-tool-name">Name</label>
+                    <input type="text" id="led-tool-name" placeholder="led-abcdef123456">
+                </div>
+                <div class="profiles-actions">
+                    <div class="preset-editor-field">
+                        <label for="led-tool-num-leds">Num LEDs</label>
+                        <input type="number" id="led-tool-num-leds" min="1" max="5000" placeholder="60">
+                    </div>
+                    <div class="preset-editor-field">
+                        <label for="led-tool-led-pin">LED pin</label>
+                        <input type="number" id="led-tool-led-pin" min="0" max="48" placeholder="4">
+                    </div>
+                </div>
+                <div class="profiles-actions">
+                    <div class="preset-editor-field">
+                        <label for="led-tool-brightness">Brightness</label>
+                        <input type="number" id="led-tool-brightness" min="0" max="255" placeholder="255">
+                    </div>
+                    <div class="preset-editor-field">
+                        <label for="led-tool-wifi-channel">WiFi channel</label>
+                        <input type="number" id="led-tool-wifi-channel" min="1" max="11" placeholder="6">
+                    </div>
+                </div>
+                <div class="profiles-actions">
+                    <div class="preset-editor-field">
+                        <label for="led-tool-transport">Transport</label>
+                        <select id="led-tool-transport">
+                            <option value="">(no change)</option>
+                            <option value="espnow">espnow</option>
+                            <option value="wifi">wifi</option>
+                        </select>
+                    </div>
+                    <div class="preset-editor-field">
+                        <label for="led-tool-default">Default preset</label>
+                        <input type="text" id="led-tool-default" placeholder="on">
+                    </div>
+                </div>
+                <div class="form-group">
+                    <label for="led-tool-ssid">SSID</label>
+                    <input type="text" id="led-tool-ssid" placeholder="Your WiFi SSID">
+                </div>
+                <div class="form-group">
+                    <label for="led-tool-password">WiFi password</label>
+                    <input type="password" id="led-tool-password" placeholder="WiFi password">
+                </div>
+
+                <div class="modal-actions">
+                    <button type="button" class="btn btn-secondary" id="led-tool-read-btn">Read</button>
+                    <button type="button" class="btn btn-secondary" id="led-tool-reset-btn">Reset</button>
+                    <button type="submit" class="btn btn-primary">Apply via USB</button>
+                    <button type="button" class="btn btn-secondary" id="led-tool-close-btn">Close</button>
+                </div>
+            </form>
+            <label for="led-tool-output" style="margin-top:0.5rem; display:block;">Command output</label>
+            <textarea id="led-tool-output" rows="12" readonly style="width:100%; font-family:monospace; resize:vertical;"></textarea>
+        </div>
+    </div>
+
+    <!-- Styles moved to /static/style.css -->
+    <script src="/static/zones.js"></script>
+    <script src="/static/help.js"></script>
+    <script src="/static/led_tool.js"></script>
+    <script src="/static/color_palette.js"></script>
+    <script src="/static/profiles.js"></script>
+    <script src="/static/zone_palette.js"></script>
+    <script src="/static/patterns.js"></script>
+    <script src="/static/presets.js"></script>
+    <script src="/static/devices.js"></script>
+</body>
 </html>

src/templates/settings.html

@@ -0,0 +1,365 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>LED Controller - Settings</title>
+    <link rel="stylesheet" href="/static/style.css">
+    <style>
+        .settings-container {
+            padding: 2rem;
+            max-width: 1200px;
+            margin: 0 auto;
+            overflow-y: auto;
+            height: 100%;
+        }
+
+        .settings-header {
+            margin-bottom: 2rem;
+        }
+
+        .settings-header h1 {
+            font-size: 2rem;
+            margin-bottom: 0.5rem;
+        }
+
+        .settings-header p {
+            color: #aaa;
+        }
+
+        .settings-section {
+            background-color: #1a1a1a;
+            border-radius: 8px;
+            padding: 1.5rem;
+            margin-bottom: 1.5rem;
+            border: 1px solid #4a4a4a;
+        }
+
+        .settings-section h2 {
+            font-size: 1.3rem;
+            margin-bottom: 1rem;
+            color: #fff;
+            border-bottom: 2px solid #4a4a4a;
+            padding-bottom: 0.5rem;
+        }
+
+        .form-group {
+            margin-bottom: 1.5rem;
+        }
+
+        .form-group label {
+            display: block;
+            margin-bottom: 0.5rem;
+            color: #ccc;
+            font-weight: 500;
+        }
+
+        .form-group input[type="text"],
+        .form-group input[type="password"],
+        .form-group input[type="number"],
+        .form-group select {
+            width: 100%;
+            padding: 0.75rem;
+            background-color: #2e2e2e;
+            border: 1px solid #4a4a4a;
+            border-radius: 4px;
+            color: white;
+            font-size: 1rem;
+        }
+
+        .form-group input:focus,
+        .form-group select:focus {
+            outline: none;
+            border-color: #5a5a5a;
+        }
+
+        .form-group small {
+            display: block;
+            margin-top: 0.25rem;
+            color: #888;
+            font-size: 0.875rem;
+        }
+
+        .form-row {
+            display: grid;
+            grid-template-columns: 1fr 1fr;
+            gap: 1rem;
+        }
+
+        .status-info {
+            background-color: #2e2e2e;
+            border: 1px solid #4a4a4a;
+            border-radius: 4px;
+            padding: 1rem;
+            margin-bottom: 1rem;
+        }
+
+        .status-info h3 {
+            font-size: 1rem;
+            margin-bottom: 0.5rem;
+            color: #fff;
+        }
+
+        .status-info p {
+            color: #aaa;
+            margin: 0.25rem 0;
+            font-size: 0.9rem;
+        }
+
+        .status-connected {
+            color: #4caf50;
+        }
+
+        .status-disconnected {
+            color: #f44336;
+        }
+
+        .btn-group {
+            display: flex;
+            gap: 0.5rem;
+            margin-top: 1rem;
+        }
+
+        .btn-full {
+            flex: 1;
+        }
+
+        .back-link {
+            display: inline-block;
+            margin-bottom: 1rem;
+            color: #aaa;
+            text-decoration: none;
+            padding: 0.5rem 1rem;
+            border-radius: 4px;
+            transition: background-color 0.2s;
+        }
+
+        .back-link:hover {
+            background-color: #2e2e2e;
+            color: white;
+        }
+
+        .message {
+            padding: 0.75rem;
+            border-radius: 4px;
+            margin-bottom: 1rem;
+            display: none;
+        }
+
+        .message.success {
+            background-color: #1b5e20;
+            color: #4caf50;
+            border: 1px solid #4caf50;
+        }
+
+        .message.error {
+            background-color: #5e1b1b;
+            color: #f44336;
+            border: 1px solid #f44336;
+        }
+
+        .message.show {
+            display: block;
+        }
+    </style>
+</head>
+<body>
+    <div class="app-container">
+        <div class="settings-container">
+            <a href="/" class="back-link">← Back to Dashboard</a>
+            
+            <div class="settings-header">
+                <h1>Device Settings</h1>
+                <p>Configure WiFi Access Point and ESP-NOW options</p>
+            </div>
+
+            <div id="message" class="message"></div>
+
+            <!-- ESP-NOW (LED driver / bridge channel) -->
+            <div class="settings-section">
+                <h2>ESP-NOW</h2>
+                <form id="espnow-form">
+                    <div class="form-group">
+                        <label for="wifi-channel-page-input">WiFi channel (ESP-NOW)</label>
+                        <input type="number" id="wifi-channel-page-input" name="wifi_channel" min="1" max="11" required>
+                        <small>STA channel (1–11) for LED drivers and the serial bridge. Use the same value on every device.</small>
+                    </div>
+                    <div class="btn-group">
+                        <button type="submit" class="btn btn-primary btn-full">Save channel</button>
+                    </div>
+                </form>
+            </div>
+
+            <!-- WiFi Access Point Settings -->
+            <div class="settings-section">
+                <h2>WiFi Access Point Settings</h2>
+                
+                <div id="ap-status" class="status-info">
+                    <h3>AP Status</h3>
+                    <p>Loading...</p>
+                </div>
+
+                <form id="ap-form">
+                    <div class="form-group">
+                        <label for="ap-ssid">AP SSID (Network Name)</label>
+                        <input type="text" id="ap-ssid" name="ssid" placeholder="Enter AP name" required>
+                        <small>The name of the WiFi access point this device creates</small>
+                    </div>
+
+                    <div class="form-group">
+                        <label for="ap-password">AP Password</label>
+                        <input type="password" id="ap-password" name="password" placeholder="Enter AP password (min 8 chars)" data-bwignore>
+                        <small>Leave empty for open network (min 8 characters if set)</small>
+                    </div>
+
+                    <div class="form-group">
+                        <label for="ap-channel">Channel (1-11)</label>
+                        <input type="number" id="ap-channel" name="channel" min="1" max="11" placeholder="Auto">
+                        <small>WiFi channel (1-11 for 2.4GHz). Leave empty for auto.</small>
+                    </div>
+
+                    <div class="btn-group">
+                        <button type="submit" class="btn btn-primary btn-full">Configure AP</button>
+                    </div>
+                </form>
+            </div>
+        </div>
+    </div>
+
+    <script>
+        // Show message helper
+        function showMessage(text, type = 'success') {
+            const messageEl = document.getElementById('message');
+            messageEl.textContent = text;
+            messageEl.className = `message ${type} show`;
+            setTimeout(() => {
+                messageEl.classList.remove('show');
+            }, 5000);
+        }
+
+        async function loadEspnowChannel() {
+            try {
+                const response = await fetch('/settings');
+                const data = await response.json();
+                const chInput = document.getElementById('wifi-channel-page-input');
+                if (chInput && data && typeof data === 'object') {
+                    const ch = data.wifi_channel;
+                    chInput.value =
+                        ch !== undefined && ch !== null && ch !== '' ? String(ch) : '6';
+                }
+            } catch (error) {
+                console.error('Error loading ESP-NOW channel:', error);
+            }
+        }
+
+        document.getElementById('espnow-form').addEventListener('submit', async (e) => {
+            e.preventDefault();
+            const chRaw = document.getElementById('wifi-channel-page-input').value;
+            const wifiChannel = parseInt(chRaw, 10);
+            if (Number.isNaN(wifiChannel) || wifiChannel < 1 || wifiChannel > 11) {
+                showMessage('WiFi channel must be between 1 and 11', 'error');
+                return;
+            }
+            try {
+                const response = await fetch('/settings/settings', {
+                    method: 'PUT',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ wifi_channel: wifiChannel }),
+                });
+                const result = await response.json();
+                if (response.ok) {
+                    showMessage('ESP-NOW channel saved.', 'success');
+                } else {
+                    showMessage(`Error: ${result.error || 'Failed to save'}`, 'error');
+                }
+            } catch (error) {
+                showMessage(`Error: ${error.message}`, 'error');
+            }
+        });
+
+        // Load AP status and config
+        async function loadAPStatus() {
+            try {
+                const response = await fetch('/settings/wifi/ap');
+                const config = await response.json();
+                
+                const statusEl = document.getElementById('ap-status');
+                if (config.active) {
+                    statusEl.innerHTML = `
+                        <h3>AP Status: <span class="status-connected">Active</span></h3>
+                        <p><strong>SSID:</strong> ${config.ssid || 'N/A'}</p>
+                        <p><strong>Channel:</strong> ${config.channel || 'Auto'}</p>
+                        <p><strong>IP Address:</strong> ${config.ip || 'N/A'}</p>
+                    `;
+                } else {
+                    statusEl.innerHTML = `
+                        <h3>AP Status: <span class="status-disconnected">Inactive</span></h3>
+                        <p>Access Point is not currently active</p>
+                    `;
+                }
+
+                // Load saved values
+                if (config.saved_ssid) document.getElementById('ap-ssid').value = config.saved_ssid;
+                if (config.saved_channel) document.getElementById('ap-channel').value = config.saved_channel;
+            } catch (error) {
+                console.error('Error loading AP status:', error);
+            }
+        }
+
+        // AP form submission
+        document.getElementById('ap-form').addEventListener('submit', async (e) => {
+            e.preventDefault();
+            
+            const formData = {
+                ssid: document.getElementById('ap-ssid').value,
+                password: document.getElementById('ap-password').value,
+                channel: document.getElementById('ap-channel').value || null
+            };
+
+            // Validate password length if provided
+            if (formData.password && formData.password.length > 0 && formData.password.length < 8) {
+                showMessage('AP password must be at least 8 characters', 'error');
+                return;
+            }
+
+            // Convert channel to number if provided
+            if (formData.channel) {
+                formData.channel = parseInt(formData.channel);
+                if (formData.channel < 1 || formData.channel > 11) {
+                    showMessage('Channel must be between 1 and 11', 'error');
+                    return;
+                }
+            }
+
+            try {
+                const response = await fetch('/settings/wifi/ap', {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json'
+                    },
+                    body: JSON.stringify(formData)
+                });
+
+                const result = await response.json();
+                
+                if (response.ok) {
+                    showMessage('Access Point configured successfully!', 'success');
+                    setTimeout(loadAPStatus, 1000);
+                } else {
+                    showMessage(`Error: ${result.error || 'Failed to configure AP'}`, 'error');
+                }
+            } catch (error) {
+                showMessage(`Error: ${error.message}`, 'error');
+            }
+        });
+
+        // Load all data on page load
+        loadEspnowChannel();
+        loadAPStatus();
+
+        // Refresh status every 10 seconds
+        setInterval(loadAPStatus, 10000);
+    </script>
+</body>
+</html>
+

src/util/README.md

@@ -0,0 +1,80 @@
+# Driver message builder (`espnow_message`)
+
+This utility builds **v1** JSON payloads for LED drivers (serial/ESP-NOW bridge and Wi-Fi TCP). See **`docs/API.md`** for the full wire format.
+
+## Usage
+
+### Basic Message Building
+
+```python
+from util.espnow_message import build_message, build_preset_dict, build_select_dict
+
+# Build a message with presets and select
+presets = {
+    "red_blink": build_preset_dict({
+        "pattern": "blink",
+        "colors": ["#FF0000"],
+        "delay": 200,
+        "brightness": 255,
+        "auto": True
+    })
+}
+
+select = build_select_dict({
+    "device1": "red_blink"
+})
+
+message = build_message(presets=presets, select=select)
+# Result: {"v": "1", "presets": {...}, "select": {...}}
+```
+
+### Building Select Messages with Step Synchronization
+
+```python
+from util.espnow_message import build_message, build_select_dict
+
+# Select with step for synchronization
+select = build_select_dict(
+    {"device1": "rainbow_preset", "device2": "rainbow_preset"},
+    step_mapping={"device1": 10, "device2": 10}
+)
+
+message = build_message(select=select)
+# Result: {"v": "1", "select": {"device1": ["rainbow_preset", 10], "device2": ["rainbow_preset", 10]}}
+```
+
+### Converting Presets
+
+```python
+from util.espnow_message import build_preset_dict, build_presets_dict
+
+# Single preset
+preset = build_preset_dict({
+    "name": "my_preset",
+    "pattern": "rainbow",
+    "colors": ["#FF0000", "#00FF00"],  # Can be hex strings or RGB tuples
+    "delay": 100,
+    "brightness": 127,
+    "auto": False,
+    "n1": 2
+})
+
+# Multiple presets
+presets_data = {
+    "preset1": {"pattern": "on", "colors": ["#FF0000"]},
+    "preset2": {"pattern": "blink", "colors": ["#00FF00"]}
+}
+presets = build_presets_dict(presets_data)
+```
+
+## API Specification
+
+See **`docs/API.md`** for REST routes, session scoping, and the compact preset keys on the wire.
+
+## Key Features
+
+- **Version Field**: All messages include `"v": "1"` for version tracking
+- **Preset Format**: Presets use hex colour strings (`#RRGGBB`), not RGB tuples
+- **Select Format**: Select values are always lists: `["preset_name"]` or `["preset_name", step]`
+- **Colour Conversion**: Automatically converts RGB tuples to hex strings
+- **Default Values**: Provides sensible defaults for missing fields

src/util/device_status_broadcaster.py

@@ -0,0 +1,52 @@
+"""Push Wi-Fi driver connect/disconnect updates to browser WebSocket clients."""
+
+import json
+import threading
+from typing import Any, Set
+
+# Threading lock: safe across asyncio tasks and avoids binding asyncio.Lock to the wrong loop.
+_clients_lock = threading.Lock()
+_clients: Set[Any] = set()
+
+
+async def register_device_status_ws(ws: Any) -> None:
+    with _clients_lock:
+        _clients.add(ws)
+
+
+async def unregister_device_status_ws(ws: Any) -> None:
+    with _clients_lock:
+        _clients.discard(ws)
+
+
+async def broadcast_device_tcp_status(ip: str, connected: bool) -> None:
+    from models.wifi_ws_clients import normalize_tcp_peer_ip
+
+    ip = normalize_tcp_peer_ip(ip)
+    if not ip:
+        return
+    msg = json.dumps({"type": "device_tcp", "ip": ip, "connected": bool(connected)})
+    with _clients_lock:
+        targets = list(_clients)
+    dead = []
+    for ws in targets:
+        try:
+            await ws.send(msg)
+        except Exception as exc:
+            dead.append(ws)
+            print(f"[device_status_broadcaster] ws.send failed: {exc!r}")
+    if dead:
+        with _clients_lock:
+            for ws in dead:
+                _clients.discard(ws)
+
+
+async def broadcast_device_tcp_snapshot_to(ws: Any) -> None:
+    from models import wifi_ws_clients as tcp
+
+    ips = tcp.list_connected_ips()
+    msg = json.dumps({"type": "device_tcp_snapshot", "connected_ips": ips})
+    try:
+        await ws.send(msg)
+    except Exception as exc:
+        print(f"[device_status_broadcaster] snapshot send failed: {exc!r}")

src/util/driver_delivery.py

@@ -0,0 +1,224 @@
+"""Deliver driver JSON messages over serial (ESP-NOW) and/or WebSocket (Wi-Fi drivers)."""
+
+import asyncio
+import json
+
+from models.device import normalize_mac
+from models.wifi_ws_clients import send_json_line_to_ip
+
+# Serial bridge (ESP32): broadcast MAC + this envelope → firmware unicasts ``body`` to each peer.
+_SPLIT_MODE = "split"
+_BROADCAST_MAC_HEX = "ffffffffffff"
+
+
+def _split_serial_envelope(inner_json_str, peer_hex_list):
+    """One UART frame: broadcast dest + JSON {m:split, peers:[hex,...], body:<object>}."""
+    body = json.loads(inner_json_str)
+    env = {"m": _SPLIT_MODE, "peers": list(peer_hex_list), "body": body}
+    return json.dumps(env, separators=(",", ":"))
+
+
+def _wifi_message_for_device(msg, device_name):
+    """
+    For Wi-Fi WebSocket fanout, narrow a v1 select map to a single device name.
+    Returns the original message when no narrowing applies.
+    """
+    if not device_name:
+        return msg
+    try:
+        body = json.loads(msg)
+    except Exception:
+        return msg
+    if not isinstance(body, dict):
+        return msg
+    select = body.get("select")
+    if not isinstance(select, dict):
+        return msg
+    if device_name not in select:
+        return msg
+    body["select"] = {device_name: select[device_name]}
+    return json.dumps(body, separators=(",", ":"))
+
+
+def _combine_preset_chunks_for_wifi(chunk_messages):
+    """Merge chunked v1 preset messages into one v1 JSON string for Wi-Fi."""
+    merged_presets = {}
+    save_flag = False
+    default_id = None
+    for msg in chunk_messages:
+        try:
+            body = json.loads(msg)
+        except Exception:
+            continue
+        if not isinstance(body, dict):
+            continue
+        presets = body.get("presets")
+        if isinstance(presets, dict):
+            merged_presets.update(presets)
+        if body.get("save"):
+            save_flag = True
+        if body.get("default") is not None:
+            default_id = body.get("default")
+    out = {"v": "1", "presets": merged_presets}
+    if save_flag:
+        out["save"] = True
+    if default_id is not None:
+        out["default"] = default_id
+    return json.dumps(out, separators=(",", ":"))
+
+
+async def deliver_preset_broadcast_then_per_device(
+    sender,
+    chunk_messages,
+    target_macs,
+    devices_model,
+    default_id,
+    delay_s=0.1,
+):
+    """
+    Send preset definition chunks: ESP-NOW broadcast once per chunk; same chunk to each
+    Wi-Fi driver over WebSocket. If default_id is set, send a per-target default message
+    (unicast serial or WebSocket) with targets=[device name] for each registry entry.
+    """
+    if not chunk_messages:
+        return 0
+
+    seen = set()
+    ordered = []
+    for raw in target_macs:
+        m = normalize_mac(str(raw)) if raw else None
+        if not m or m in seen:
+            continue
+        seen.add(m)
+        ordered.append(m)
+
+    wifi_ips = []
+    for mac in ordered:
+        doc = devices_model.read(mac)
+        if doc and doc.get("transport") == "wifi" and doc.get("address"):
+            wifi_ips.append(str(doc["address"]).strip())
+
+    deliveries = 0
+    wifi_combined_msg = _combine_preset_chunks_for_wifi(chunk_messages)
+    for msg in chunk_messages:
+        tasks = [sender.send(msg, addr=_BROADCAST_MAC_HEX)]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+        if results and results[0] is True:
+            deliveries += 1
+        await asyncio.sleep(delay_s)
+
+    for ip in wifi_ips:
+        if not ip:
+            continue
+        try:
+            if await send_json_line_to_ip(ip, wifi_combined_msg):
+                deliveries += 1
+        except Exception as e:
+            print(f"[driver_delivery] Wi-Fi preset send failed: {e!r}")
+        await asyncio.sleep(delay_s)
+
+    if default_id:
+        did = str(default_id)
+        for mac in ordered:
+            doc = devices_model.read(mac) or {}
+            name = str(doc.get("name") or "").strip() or mac
+            body = {"v": "1", "default": did, "save": True, "targets": [name]}
+            out = json.dumps(body, separators=(",", ":"))
+            if doc.get("transport") == "wifi" and doc.get("address"):
+                ip = str(doc["address"]).strip()
+                try:
+                    if await send_json_line_to_ip(ip, out):
+                        deliveries += 1
+                except Exception as e:
+                    print(f"[driver_delivery] default Wi-Fi send failed: {e!r}")
+            else:
+                try:
+                    await sender.send(out, addr=mac)
+                    deliveries += 1
+                except Exception as e:
+                    print(f"[driver_delivery] default serial failed: {e!r}")
+            await asyncio.sleep(delay_s)
+
+    return deliveries
+
+
+async def deliver_json_messages(sender, messages, target_macs, devices_model, delay_s=0.1):
+    """
+    Send each message string to the bridge and/or Wi-Fi WebSocket clients.
+
+    If target_macs is None or empty: one serial send per message (default/broadcast address).
+    Otherwise: Wi-Fi uses WebSocket in parallel. Multiple ESP-NOW peers are sent in **one** serial
+    write to the ESP32 (broadcast + split envelope); the bridge unicasts ``body`` to each
+    peer. A single ESP-NOW peer still uses one unicast serial frame. Wi-Fi and serial
+    tasks run together in one asyncio.gather.
+
+    Returns (delivery_count, chunk_count) where chunk_count is len(messages).
+    """
+    if not messages:
+        return 0, 0
+
+    if not target_macs:
+        deliveries = 0
+        for msg in messages:
+            await sender.send(msg)
+            deliveries += 1
+            await asyncio.sleep(delay_s)
+        return deliveries, len(messages)
+
+    seen = set()
+    ordered_macs = []
+    for raw in target_macs:
+        m = normalize_mac(str(raw)) if raw else None
+        if not m or m in seen:
+            continue
+        seen.add(m)
+        ordered_macs.append(m)
+
+    deliveries = 0
+    for msg in messages:
+        wifi_tasks = []
+        espnow_hex = []
+        for mac in ordered_macs:
+            doc = devices_model.read(mac)
+            if doc and doc.get("transport") == "wifi":
+                ip = doc.get("address")
+                if ip:
+                    name = str(doc.get("name") or "").strip()
+                    wifi_msg = _wifi_message_for_device(msg, name)
+                    wifi_tasks.append(send_json_line_to_ip(ip, wifi_msg))
+            else:
+                espnow_hex.append(mac)
+
+        tasks = []
+        espnow_peer_count = 0
+        if len(espnow_hex) > 1:
+            tasks.append(
+                sender.send(
+                    _split_serial_envelope(msg, espnow_hex),
+                    addr=_BROADCAST_MAC_HEX,
+                )
+            )
+            espnow_peer_count = len(espnow_hex)
+        elif len(espnow_hex) == 1:
+            tasks.append(sender.send(msg, addr=espnow_hex[0]))
+            espnow_peer_count = 1
+
+        tasks.extend(wifi_tasks)
+
+        if tasks:
+            results = await asyncio.gather(*tasks, return_exceptions=True)
+            n_serial = len(tasks) - len(wifi_tasks)
+            for i, r in enumerate(results):
+                if i < n_serial:
+                    if r is True:
+                        deliveries += espnow_peer_count
+                    elif isinstance(r, Exception):
+                        print(f"[driver_delivery] serial delivery failed: {r!r}")
+                else:
+                    if r is True:
+                        deliveries += 1
+                    elif isinstance(r, Exception):
+                        print(f"[driver_delivery] Wi-Fi delivery failed: {r!r}")
+
+        await asyncio.sleep(delay_s)
+    return deliveries, len(messages)

src/util/driver_patterns.py

@@ -0,0 +1,53 @@
+import os
+
+_ENV_PATTERNS_DIR = "LED_CONTROLLER_PATTERNS_DIR"
+
+def driver_patterns_dir():
+    """Absolute path to driver pattern ``.py`` modules.
+
+    If ``LED_CONTROLLER_PATTERNS_DIR`` is set to an existing directory, that wins
+    (for installs where ``led-driver`` is not next to this repo). Otherwise uses
+    ``<project-root>/led-driver/src/patterns``.
+    """
+    env = (os.environ.get(_ENV_PATTERNS_DIR) or "").strip()
+    if env and os.path.isdir(env):
+        return os.path.abspath(env)
+    here = os.path.dirname(os.path.abspath(__file__))
+    root = os.path.abspath(os.path.join(here, "..", ".."))
+    return os.path.join(root, "led-driver", "src", "patterns")
+
+
+def normalize_pattern_py_filename(name):
+    """Return a single ``*.py`` basename (no paths), or ``\"\"`` if invalid.
+
+    Strips repeated ``.py`` suffixes so ``blink.py.py`` becomes ``blink.py``.
+    """
+    if not isinstance(name, str):
+        return ""
+    s = name.strip()
+    if not s:
+        return ""
+    lower = s.lower()
+    while lower.endswith(".py"):
+        s = s[:-3]
+        s = s.strip()
+        lower = s.lower()
+    if not s:
+        return ""
+    if "/" in s or "\\" in s or ".." in s:
+        return ""
+    return s + ".py"
+
+
+# Implemented in led-driver ``presets.py`` only — no separate ``patterns/*.py``.
+FIRMWARE_BUILTIN_PATTERN_IDS = frozenset({"on", "off"})
+
+
+def is_firmware_builtin_pattern_module(name):
+    """True for ``on`` / ``off``, with or without a ``.py`` suffix."""
+    if not isinstance(name, str):
+        return False
+    s = name.strip().lower()
+    while s.endswith(".py"):
+        s = s[:-3].strip()
+    return s in FIRMWARE_BUILTIN_PATTERN_IDS

src/util/espnow_message.py

@@ -0,0 +1,194 @@
+"""
+Message builder for LED driver API communication.
+
+Builds JSON messages according to the LED driver API specification
+for sending presets and select commands over the transport (e.g. serial).
+"""
+
+import json
+
+
+def build_message(presets=None, select=None, save=False, default=None):
+    """
+    Build an API message (presets and/or select) as a JSON string.
+
+    Args:
+        presets: Dictionary mapping preset names to preset objects, or None
+        select: Dictionary mapping device names to select lists, or None
+
+    Returns:
+        JSON string ready to send over the transport
+        
+    Example:
+        message = build_message(
+            presets={
+                "red_blink": {
+                    "pattern": "blink",
+                    "colors": ["#FF0000"],
+                    "delay": 200,
+                    "brightness": 255,
+                    "auto": True
+                }
+            },
+            select={
+                "device1": ["red_blink"]
+            }
+        )
+    """
+    message = {
+        "v": "1"
+    }
+    
+    if presets:
+        message["presets"] = presets
+        # When sending presets, optionally include a save flag so the
+        # led-driver can persist them.
+        if save:
+            message["save"] = True
+    
+    if select:
+        message["select"] = select
+
+    if default is not None:
+        message["default"] = default
+    
+    return json.dumps(message)
+
+
+def build_select_message(device_name, preset_name, step=None):
+    """
+    Build a select message for a single device.
+    
+    Args:
+        device_name: Name of the device
+        preset_name: Name of the preset to select
+        step: Optional step value for synchronization
+        
+    Returns:
+        Dictionary with select field ready to use in build_message
+        
+    Example:
+        select = build_select_message("device1", "rainbow_preset", step=10)
+        message = build_message(select=select)
+    """
+    select_list = [preset_name]
+    if step is not None:
+        select_list.append(step)
+    
+    return {device_name: select_list}
+
+
+def build_preset_dict(preset_data):
+    """
+    Convert preset data to API-compliant format.
+    
+    Args:
+        preset_data: Dictionary with preset fields (may include name, pattern, colors, etc.)
+        
+    Returns:
+        Dictionary with preset in API-compliant format (without name field)
+        
+    Example:
+        preset = build_preset_dict({
+            "name": "red_blink",
+            "pattern": "blink",
+            "colors": ["#FF0000"],
+            "delay": 200,
+            "brightness": 255,
+            "auto": True,
+            "n1": 0,
+            "n2": 0,
+            "n3": 0,
+            "n4": 0,
+            "n5": 0,
+            "n6": 0
+        })
+    """
+    # Ensure colors are in hex format
+    colors = preset_data.get("colors", preset_data.get("c", ["#FFFFFF"]))
+    if colors:
+        # Convert RGB tuples to hex strings if needed
+        if isinstance(colors[0], list) and len(colors[0]) == 3:
+            # RGB tuple format [r, g, b]
+            colors = [f"#{r:02x}{g:02x}{b:02x}" for r, g, b in colors]
+        elif not isinstance(colors[0], str):
+            # Handle other formats - convert to hex
+            colors = ["#FFFFFF"]
+        # Ensure all colors start with #
+        colors = [c if c.startswith("#") else f"#{c}" for c in colors]
+    else:
+        colors = ["#FFFFFF"]
+    
+    # Build payload using the short keys expected by led-driver
+    preset = {
+        "p": preset_data.get("pattern", preset_data.get("p", "off")),
+        "c": colors,
+        "d": preset_data.get("delay", preset_data.get("d", 100)),
+        "b": preset_data.get("brightness", preset_data.get("b", preset_data.get("br", 127))),
+        "a": preset_data.get("auto", preset_data.get("a", True)),
+        "n1": preset_data.get("n1", 0),
+        "n2": preset_data.get("n2", 0),
+        "n3": preset_data.get("n3", 0),
+        "n4": preset_data.get("n4", 0),
+        "n5": preset_data.get("n5", 0),
+        "n6": preset_data.get("n6", 0)
+    }
+    
+    return preset
+
+
+def build_presets_dict(presets_data):
+    """
+    Convert multiple presets to API-compliant format.
+    
+    Args:
+        presets_data: Dictionary mapping preset names to preset data
+        
+    Returns:
+        Dictionary mapping preset names to API-compliant preset objects
+        
+    Example:
+        presets = build_presets_dict({
+            "red_blink": {
+                "pattern": "blink",
+                "colors": ["#FF0000"],
+                "delay": 200
+            },
+            "blue_pulse": {
+                "pattern": "pulse",
+                "colors": ["#0000FF"],
+                "delay": 100
+            }
+        })
+    """
+    result = {}
+    for preset_name, preset_data in presets_data.items():
+        result[preset_name] = build_preset_dict(preset_data)
+    return result
+
+
+def build_select_dict(device_preset_mapping, step_mapping=None):
+    """
+    Build a select dictionary mapping device names to select lists.
+    
+    Args:
+        device_preset_mapping: Dictionary mapping device names to preset names
+        step_mapping: Optional dictionary mapping device names to step values
+        
+    Returns:
+        Dictionary with select field ready to use in build_message
+        
+    Example:
+        select = build_select_dict(
+            {"device1": "rainbow_preset", "device2": "pulse_preset"},
+            step_mapping={"device1": 10}
+        )
+        message = build_message(select=select)
+    """
+    select = {}
+    for device_name, preset_name in device_preset_mapping.items():
+        select_list = [preset_name]
+        if step_mapping and device_name in step_mapping:
+            select_list.append(step_mapping[device_name])
+        select[device_name] = select_list
+    return select

src/util/wifi.py

@@ -1,38 +0,0 @@
-import network
-from time import sleep
-
-def connect(ssid, password, ip, gateway):
-    if ssid is None or password is None:
-        print("Missing ssid or password")
-        return None
-    try:
-        sta_if = network.WLAN(network.STA_IF)
-        if ip is not None and gateway is not None:
-            sta_if.ifconfig((ip, '255.255.255.0', gateway, '1.1.1.1'))
-        if not sta_if.isconnected():
-            print('connecting to network...')
-            sta_if.active(True)
-            sta_if.connect(ssid, password)
-            sleep(0.1)
-            if sta_if.isconnected():
-                return sta_if.ifconfig()
-            return None
-        return sta_if.ifconfig()
-    except Exception as e:
-        print(f"Failed to connect to wifi {e}")
-        return None
-
-
-def ap(ssid, password):
-    ap_if = network.WLAN(network.AP_IF)
-    ap_mac = ap_if.config('mac')
-    print(ssid)
-    ap_if.active(True)
-    ap_if.config(essid=ssid, password=password)
-    ap_if.active(False)
-    ap_if.active(True)
-    print(ap_if.ifconfig())
-
-def get_mac():
-    ap_if = network.WLAN(network.AP_IF)
-    return ap_if.config('mac')

tests/README.md

@@ -0,0 +1,47 @@
+# Tests
+
+Tests for the LED Controller project live under **`tests/`** (pytest + legacy scripts).
+
+## Layout
+
+| Path | Role |
+|------|------|
+| `test_endpoints.py` | HTTP endpoint checks (**`LED_CONTROLLER_RUN_DEVICE_ENDPOINT_TESTS=1`**); **`test_zones`** / **`test_zone_edit_workflow`** hit **`/zones`** |
+| `test_endpoints_pytest.py` | Pytest-style endpoint coverage |
+| `test_browser.py` | Selenium UI flows (set **`LED_CONTROLLER_RUN_BROWSER_TESTS=1`** to run; uses **`test_zones_ui`** and legacy **`tabsManager`** JS aliases) |
+| `test_pattern_ota_send.py` | Pattern OTA / Wi-Fi send helpers |
+| `tcp_test_server.py`, `async_tcp_server.py` | TCP test doubles for driver protocol |
+| `udp_server.py` | UDP discovery / hello test listener (port **8766**) |
+| `ws.py` | WebSocket client checks |
+| `p2p.py` | ESP-NOW–related helpers / experiments |
+| `web.py` | Local dev static server (not the main app) |
+| `conftest.py` | Pytest fixtures |
+| `models/` | Model unit tests (`run_all.py`, `test_zone.py`, …) |
+
+## Running tests
+
+### Pytest (recommended)
+
+From the project root (with dev dependencies installed):
+
+```bash
+pipenv run pytest tests/ -q
+```
+
+### Browser tests (real browser)
+
+```bash
+python tests/test_browser.py
+```
+
+Requires **Selenium**, Chrome/Chromium, and a matching **ChromeDriver**.
+
+### Model tests only
+
+```bash
+python tests/models/run_all.py
+```
+
+### Local static server
+
+`tests/web.py` serves files for quick UI experiments; it is **not** the Microdot app. For the real server use **`pipenv run run`** from the repo root.

tests/async_tcp_server.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+# Standalone async TCP server (stdlib only). Multiple simultaneous clients.
+# No watchdog: runs on a full host (e.g. Raspberry Pi); ESP32 clients may use WDT.
+# For RTT latency, clients may send lines like ``rtt 12345`` (ticks); they are echoed back.
+#
+# Run from anywhere (default: all IPv4 interfaces, port 9000):
+#   python3 async_tcp_server.py
+#   python3 async_tcp_server.py --port 9000
+# Localhost only:
+#   python3 async_tcp_server.py --host 127.0.0.1
+#
+# Or from this directory:
+#   chmod +x async_tcp_server.py && ./async_tcp_server.py
+
+import argparse
+import asyncio
+import time
+
+
+class _ClientRegistry:
+    """Track writers and broadcast newline-terminated lines to all clients."""
+
+    def __init__(self) -> None:
+        self._writers: set[asyncio.StreamWriter] = set()
+
+    def add(self, writer: asyncio.StreamWriter) -> None:
+        self._writers.add(writer)
+
+    def remove(self, writer: asyncio.StreamWriter) -> None:
+        self._writers.discard(writer)
+
+    def count(self) -> int:
+        return len(self._writers)
+
+    async def broadcast_line(self, line: str) -> None:
+        data = (line.rstrip("\r\n") + "\n").encode("utf-8")
+        for writer in list(self._writers):
+            try:
+                writer.write(data)
+                await writer.drain()
+            except Exception as e:
+                print(f"[tcp] broadcast failed, dropping client: {e}")
+                self._writers.discard(writer)
+                try:
+                    writer.close()
+                    await writer.wait_closed()
+                except Exception:
+                    pass
+
+
+async def _periodic_broadcast(
+    registry: _ClientRegistry,
+    interval_sec: float,
+    message: str,
+) -> None:
+    while True:
+        await asyncio.sleep(interval_sec)
+        if registry.count() == 0:
+            continue
+        line = message.format(t=time.time())
+        print(f"[tcp] broadcast to {registry.count()} client(s): {line!r}")
+        await registry.broadcast_line(line)
+
+
+async def _handle_client(
+    reader: asyncio.StreamReader,
+    writer: asyncio.StreamWriter,
+    registry: _ClientRegistry,
+) -> None:
+    peer = writer.get_extra_info("peername")
+    print(f"[tcp] connected: {peer}")
+    registry.add(writer)
+    try:
+        while not reader.at_eof():
+            data = await reader.readline()
+            if not data:
+                break
+            message = data.decode("utf-8", errors="replace").rstrip("\r\n")
+            # Echo newline-delimited lines (simple test harness behaviour).
+            # Clients may send ``rtt <ticks>`` for round-trip timing; echo unchanged.
+            t0 = time.perf_counter()
+            writer.write((message + "\n").encode("utf-8"))
+            await writer.drain()
+            if message.startswith("rtt "):
+                server_ms = (time.perf_counter() - t0) * 1000.0
+                print(
+                    f"[tcp] echoed rtt from {peer} "
+                    f"(host write+drain ~{server_ms:.2f} ms)"
+                )
+    finally:
+        registry.remove(writer)
+        writer.close()
+        await writer.wait_closed()
+        print(f"[tcp] disconnected: {peer}")
+
+
+def _make_client_handler(registry: _ClientRegistry):
+    async def _handler(
+        reader: asyncio.StreamReader,
+        writer: asyncio.StreamWriter,
+    ) -> None:
+        await _handle_client(reader, writer, registry)
+
+    return _handler
+
+
+async def _run(
+    host: str,
+    port: int,
+    broadcast_interval: float | None,
+    broadcast_message: str,
+) -> None:
+    registry = _ClientRegistry()
+    handler = _make_client_handler(registry)
+    server = await asyncio.start_server(handler, host, port)
+    print(f"[tcp] listening on {host}:{port} (Ctrl+C to stop)")
+    if broadcast_interval is not None and broadcast_interval > 0:
+        print(
+            f"[tcp] periodic broadcast every {broadcast_interval}s "
+            f"(use {{t}} in --message for unix time)"
+        )
+    async with server:
+        tasks = []
+        if broadcast_interval is not None and broadcast_interval > 0:
+            tasks.append(
+                asyncio.create_task(
+                    _periodic_broadcast(registry, broadcast_interval, broadcast_message),
+                    name="broadcast",
+                )
+            )
+        try:
+            if tasks:
+                await asyncio.gather(server.serve_forever(), *tasks)
+            else:
+                await server.serve_forever()
+        finally:
+            for t in tasks:
+                t.cancel()
+            for t in tasks:
+                try:
+                    await t
+                except asyncio.CancelledError:
+                    pass
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Standalone asyncio TCP server (multiple connections).",
+    )
+    parser.add_argument(
+        "--host",
+        default="0.0.0.0",
+        help="bind address (default: all IPv4 interfaces)",
+    )
+    parser.add_argument("--port", type=int, default=9000, help="bind port")
+    parser.add_argument(
+        "--interval",
+        type=float,
+        default=5.0,
+        metavar="SEC",
+        help="seconds between broadcast lines to all clients (default: 5)",
+    )
+    parser.add_argument(
+        "--message",
+        default="ping {t:.0f}",
+        help='broadcast line (newline added); use "{t}" for time.time() (default: %(default)s)',
+    )
+    parser.add_argument(
+        "--no-broadcast",
+        action="store_true",
+        help="disable periodic broadcast (echo-only)",
+    )
+    args = parser.parse_args()
+    interval = None if args.no_broadcast else args.interval
+    try:
+        asyncio.run(_run(args.host, args.port, interval, args.message))
+    except KeyboardInterrupt:
+        print("\n[tcp] stopped")
+
+
+if __name__ == "__main__":
+    main()

tests/conftest.py

@@ -0,0 +1,14 @@
+from pathlib import Path
+import sys
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+SRC_PATH = PROJECT_ROOT / "src"
+LIB_PATH = PROJECT_ROOT / "lib"
+
+# Last insert(0) wins: order must be (root, lib, src) so src/models wins over
+# tests/models (same package name "models" on sys.path when pytest imports tests).
+for p in (str(PROJECT_ROOT), str(LIB_PATH), str(SRC_PATH)):
+    if p in sys.path:
+        sys.path.remove(p)
+    sys.path.insert(0, p)
+

tests/device_ws_cycle.py

@@ -0,0 +1,300 @@
+#!/usr/bin/env python3
+"""Discover a Wi‑Fi LED driver via UDP hello, then drive it over WebSocket.
+
+1. Listens on UDP (default port 8766) for the same JSON line the firmware sends
+   (``v``, ``device_name``, ``mac``, ``type``: ``led``).
+2. Opens ``ws://<device-ip>:<port>/ws``.
+3. Pushes a few test presets (``v``: ``"1"``) and cycles ``select`` for the
+   reported ``device_name``.
+
+The firmware sends UDP hello about one second **after** HTTP is listening, so
+this script retries the WebSocket handshake by default.
+
+The device ``settings.json`` ``name`` must match ``device_name`` in the hello
+(and in each ``select`` map).
+
+Examples::
+
+  pipenv install --dev
+  pipenv run python tests/device_ws_cycle.py
+
+  pipenv run python tests/device_ws_cycle.py --timeout 60 --cycle-s 4
+
+  # Skip UDP; connect directly (set ``--device-name`` to the device's ``name``)::
+  pipenv run python tests/device_ws_cycle.py --host 192.168.1.42 --device-name a
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import socket
+import sys
+
+
+def _parse_hello_line(data: bytes) -> tuple[dict | None, bytes]:
+    line = data.split(b"\n", 1)[0].strip()
+    if not line:
+        return None, line
+    try:
+        obj = json.loads(line.decode("utf-8"))
+    except (UnicodeError, ValueError, TypeError):
+        return None, line
+    if not isinstance(obj, dict):
+        return None, line
+    return obj, line
+
+
+def wait_for_udp_hello(
+    bind: str,
+    port: int,
+    timeout_s: float,
+    echo: bool,
+) -> tuple[str, str, dict]:
+    """Block until a valid hello arrives. Returns (device_ip, device_name, hello_dict)."""
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        try:
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        except OSError:
+            pass
+        try:
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
+        except OSError:
+            pass
+        sock.bind((bind, port))
+        sock.settimeout(timeout_s)
+        print(
+            f"UDP listening on {bind}:{port} (timeout {timeout_s}s) — "
+            "power the device or wait for hello…",
+        )
+        while True:
+            try:
+                data, addr = sock.recvfrom(2048)
+            except socket.timeout as e:
+                raise SystemExit(f"No UDP hello before timeout: {e}") from e
+            peer_ip = addr[0]
+            parsed, raw_line = _parse_hello_line(data)
+            if parsed is None:
+                print(f"Ignored datagram from {peer_ip!r}: {raw_line!r}")
+                continue
+            if str(parsed.get("v") or "") != "1":
+                print(f"Ignored v={parsed.get('v')!r} from {peer_ip!r}")
+                continue
+            dev_type = parsed.get("type") or parsed.get("device_type")
+            if dev_type is not None and dev_type != "led":
+                print(f"Ignored type={dev_type!r} from {peer_ip!r}")
+                continue
+            name = str(parsed.get("device_name") or "").strip()
+            mac = parsed.get("mac")
+            if not name or not mac:
+                print(
+                    f"Ignored hello without device_name/mac from {peer_ip!r}: {parsed!r}",
+                )
+                continue
+            print(
+                f"Heard hello: ip={peer_ip!r} device_name={name!r} mac={mac!r}",
+            )
+            if echo:
+                try:
+                    sock.sendto(data, addr)
+                except OSError as e:
+                    print(f"UDP echo to {addr} failed: {e!r}")
+            return peer_ip, name, parsed
+    finally:
+        try:
+            sock.close()
+        except OSError:
+            pass
+
+
+PRESETS = {
+    "_test_on": {"p": "on", "c": [(0, 80, 200)]},
+    "_test_blink": {"p": "blink", "d": 120, "b": 200, "c": [(255, 40, 0), (0, 40, 255)]},
+    "_test_rainbow": {"p": "rainbow", "d": 12, "n1": 2, "a": True},
+}
+
+PRESET_ORDER = ["_test_on", "_test_blink", "_test_rainbow"]
+
+
+async def cycle_presets(
+    host: str,
+    device_name: str,
+    ws_port: int,
+    ws_path: str,
+    cycle_s: float,
+    passes: int,
+    *,
+    ws_open_timeout_s: float,
+    ws_connect_retries: int,
+    ws_connect_retry_delay_s: float,
+) -> None:
+    try:
+        import websockets
+    except ImportError as e:
+        raise SystemExit(
+            "Install websockets: pipenv install websockets  (or: pip install websockets)"
+        ) from e
+
+    path = ws_path if ws_path.startswith("/") else "/" + ws_path
+    uri = f"ws://{host}:{ws_port}{path}"
+    print(f"WebSocket connect {uri!r} …")
+
+    n = max(1, ws_connect_retries)
+    last_err: BaseException | None = None
+    for attempt in range(n):
+        try:
+            async with websockets.connect(
+                uri,
+                open_timeout=ws_open_timeout_s,
+            ) as ws:
+                print("Connected.")
+                push = json.dumps({"v": "1", "presets": PRESETS})
+                await ws.send(push)
+                print(f"Sent presets: {list(PRESETS.keys())}")
+                await asyncio.sleep(0.25)
+
+                for p in range(passes):
+                    print(f"--- pass {p + 1}/{passes} ---")
+                    for pname in PRESET_ORDER:
+                        sel = json.dumps({"v": "1", "select": {device_name: [pname]}})
+                        await ws.send(sel)
+                        print(f"  select {pname!r}")
+                        await asyncio.sleep(cycle_s)
+
+                print("Done.")
+                return
+        except (TimeoutError, OSError, ConnectionError) as e:
+            last_err = e
+            if attempt + 1 < n:
+                print(
+                    f"  connect failed ({e!r}), retry {attempt + 2}/{n} in "
+                    f"{ws_connect_retry_delay_s}s …",
+                )
+                await asyncio.sleep(ws_connect_retry_delay_s)
+
+    raise TimeoutError(
+        f"WebSocket handshake failed after {n} attempts: {last_err!r}",
+    ) from last_err
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="UDP hello discovery + WebSocket preset cycle (led-driver)",
+    )
+    parser.add_argument(
+        "--bind",
+        default="0.0.0.0",
+        help="UDP bind address (default 0.0.0.0)",
+    )
+    parser.add_argument(
+        "-p",
+        "--udp-port",
+        type=int,
+        default=8766,
+        help="UDP listen port (default 8766)",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=float,
+        default=120.0,
+        help="Seconds to wait for first hello (default 120)",
+    )
+    parser.add_argument(
+        "--no-echo",
+        action="store_true",
+        help="Do not echo the datagram back (firmware often uses wait_reply=False)",
+    )
+    parser.add_argument(
+        "--host",
+        default="",
+        metavar="IP",
+        help="Skip UDP and use this device IP",
+    )
+    parser.add_argument(
+        "--device-name",
+        default="",
+        metavar="NAME",
+        help="Device settings name for select map (required with --host if not default)",
+    )
+    parser.add_argument(
+        "--ws-port",
+        type=int,
+        default=80,
+        help="Device WebSocket port (default 80)",
+    )
+    parser.add_argument(
+        "--ws-path",
+        default="/ws",
+        help="WebSocket path (default /ws)",
+    )
+    parser.add_argument(
+        "--cycle-s",
+        type=float,
+        default=3.0,
+        help="Seconds between select commands (default 3)",
+    )
+    parser.add_argument(
+        "--passes",
+        type=int,
+        default=2,
+        help="How many full cycles through all test presets (default 2)",
+    )
+    parser.add_argument(
+        "--ws-open-timeout",
+        type=float,
+        default=30.0,
+        help="Per-attempt WebSocket handshake timeout in seconds (default 30)",
+    )
+    parser.add_argument(
+        "--ws-retries",
+        type=int,
+        default=15,
+        help="WebSocket connect attempts (default 15; use with device hello after HTTP)",
+    )
+    parser.add_argument(
+        "--ws-retry-delay",
+        type=float,
+        default=1.0,
+        help="Seconds between WebSocket retries (default 1)",
+    )
+    args = parser.parse_args()
+
+    if args.host:
+        host = args.host.strip()
+        device_name = (args.device_name or "a").strip()
+        if not device_name:
+            print("--device-name is required when using a generic --host", file=sys.stderr)
+            return 1
+        print(f"Using host {host!r} device_name {device_name!r} (no UDP)")
+    else:
+        host, device_name, _hello = wait_for_udp_hello(
+            args.bind,
+            args.udp_port,
+            args.timeout,
+            echo=not args.no_echo,
+        )
+
+    try:
+        asyncio.run(
+            cycle_presets(
+                host=host,
+                device_name=device_name,
+                ws_port=args.ws_port,
+                ws_path=args.ws_path,
+                cycle_s=args.cycle_s,
+                passes=max(1, args.passes),
+                ws_open_timeout_s=args.ws_open_timeout,
+                ws_connect_retries=args.ws_retries,
+                ws_connect_retry_delay_s=args.ws_retry_delay,
+            )
+        )
+    except KeyboardInterrupt:
+        print("\nInterrupted.")
+        return 130
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tests/models/run_all.py

@@ -10,8 +10,9 @@ from test_preset import test_preset
 from test_profile import test_profile
 from test_group import test_group
 from test_sequence import test_sequence
-from test_tab import test_tab
+from test_zone import test_zone
 from test_palette import test_palette
+from test_device import test_device
 
 def run_all_tests():
     """Run all model tests."""
@@ -25,8 +26,9 @@ def run_all_tests():
         ("Profile", test_profile),
         ("Group", test_group),
         ("Sequence", test_sequence),
-        ("Tab", test_tab),
+        ("Zone", test_zone),
         ("Palette", test_palette),
+        ("Device", test_device),
     ]
     
     passed = 0

tests/models/test_device.py

@@ -0,0 +1,168 @@
+import os
+import sys
+from pathlib import Path
+
+# Prefer src/models; pytest may have registered tests/models as top-level ``models``.
+_src = Path(__file__).resolve().parents[2] / "src"
+_sp = str(_src)
+if _sp in sys.path:
+    sys.path.remove(_sp)
+sys.path.insert(0, _sp)
+_m = sys.modules.get("models")
+if _m is not None:
+    mf = (getattr(_m, "__file__", "") or "").replace("\\", "/")
+    if "/tests/models" in mf:
+        del sys.modules["models"]
+
+from models.device import Device
+
+
+def _fresh_device():
+    """New empty device DB and new Device singleton (tests only)."""
+    db_dir = os.path.join(
+        os.path.dirname(os.path.dirname(os.path.dirname(__file__))), "db"
+    )
+    device_file = os.path.join(db_dir, "device.json")
+    if os.path.exists(device_file):
+        os.remove(device_file)
+    if hasattr(Device, "_instance"):
+        del Device._instance
+    return Device()
+
+
+def test_device():
+    """Test Device model CRUD operations (id = MAC)."""
+    devices = _fresh_device()
+
+    mac = "aabbccddeeff"
+    print("Testing create device")
+    device_id = devices.create("Test Device", address="aa:bb:cc:dd:ee:ff", default_pattern="on", zones=["1", "2"])
+    print(f"Created device with ID: {device_id}")
+    assert device_id == mac
+    assert device_id in devices
+
+    print("\nTesting read device")
+    device = devices.read(device_id)
+    print(f"Read: {device}")
+    assert device is not None
+    assert device["id"] == mac
+    assert device["name"] == "Test Device"
+    assert device["type"] == "led"
+    assert device["transport"] == "espnow"
+    assert device["address"] == mac
+    assert device["default_pattern"] == "on"
+    assert device["zones"] == ["1", "2"]
+
+    print("\nTesting read by colon MAC")
+    assert devices.read("aa:bb:cc:dd:ee:ff")["id"] == mac
+
+    print("\nTesting address normalization on update (espnow keeps MAC as address)")
+    devices.update(device_id, {"address": "11:22:33:44:55:66"})
+    updated = devices.read(device_id)
+    assert updated["address"] == mac
+
+    print("\nTesting update device fields")
+    update_data = {
+        "name": "Updated Device",
+        "default_pattern": "rainbow",
+        "zones": ["1", "2", "3"],
+    }
+    result = devices.update(device_id, update_data)
+    assert result is True
+    updated = devices.read(device_id)
+    assert updated["name"] == "Updated Device"
+    assert updated["default_pattern"] == "rainbow"
+    assert len(updated["zones"]) == 3
+
+    print("\nTesting list devices")
+    device_list = devices.list()
+    print(f"Device list: {device_list}")
+    assert mac in device_list
+
+    print("\nTesting delete device")
+    deleted = devices.delete(device_id)
+    assert deleted is True
+    assert mac not in devices
+
+    print("\nTesting read after delete")
+    device = devices.read(device_id)
+    assert device is None
+
+    print("\nAll device tests passed!")
+
+
+def test_upsert_wifi_tcp_client():
+    devices = _fresh_device()
+    assert devices.upsert_wifi_tcp_client("", "192.168.1.10", None) == (None, False)
+    assert devices.upsert_wifi_tcp_client("kitchen", "192.168.1.20", "bad") == (
+        None,
+        False,
+    )
+
+    m1 = "001122334455"
+    m2 = "001122334466"
+    i1, p1 = devices.upsert_wifi_tcp_client("kitchen", "192.168.1.20", m1)
+    assert i1 == m1 and p1 is True
+    d = devices.read(i1)
+    assert d["name"] == "kitchen"
+    assert d["type"] == "led"
+    assert d["transport"] == "wifi"
+    assert d["address"] == "192.168.1.20"
+
+    noop_mac, noop_p = devices.upsert_wifi_tcp_client("kitchen", "192.168.1.20", m1)
+    assert noop_mac == m1 and noop_p is False
+
+    i2, p2 = devices.upsert_wifi_tcp_client("kitchen", "192.168.1.21", m2)
+    assert i2 == m2 and p2 is True
+    assert devices.read(m1)["address"] == "192.168.1.20"
+    assert devices.read(m2)["address"] == "192.168.1.21"
+    assert devices.read(m1)["name"] == devices.read(m2)["name"] == "kitchen"
+
+    again, p_again = devices.upsert_wifi_tcp_client("kitchen", "192.168.1.99", m1)
+    assert again == m1 and p_again is True
+    assert devices.read(m1)["address"] == "192.168.1.99"
+
+    bogus_mac, bogus_p = devices.upsert_wifi_tcp_client(
+        "kitchen", "192.168.1.100", m1, device_type="bogus"
+    )
+    assert bogus_mac == m1 and bogus_p is True
+    assert devices.read(m1)["type"] == "led"
+
+    i3, p3 = devices.upsert_wifi_tcp_client("hall", "10.0.0.5", "deadbeefcafe")
+    assert i3 == "deadbeefcafe" and p3 is True
+    assert len(devices.list()) == 3
+
+
+def test_device_can_change_address():
+    devices = _fresh_device()
+    m = "feedfacec0de"
+    did = devices.create("mover", mac=m, address="192.168.1.1", transport="wifi")
+    assert did == m
+    devices.update(did, {"address": "10.0.0.99"})
+    assert devices.read(did)["address"] == "10.0.0.99"
+
+
+def test_device_duplicate_names_allowed():
+    devices = _fresh_device()
+    a1 = devices.create("alpha", address="aa:bb:cc:dd:ee:ff")
+    a2 = devices.create("alpha", address="11:22:33:44:55:66")
+    assert a1 != a2
+    assert devices.read(a1)["name"] == devices.read(a2)["name"] == "alpha"
+
+
+def test_device_duplicate_mac_rejected():
+    devices = _fresh_device()
+    devices.create("one", address="aa:bb:cc:dd:ee:ff")
+    try:
+        devices.create("two", address="aa-bb-cc-dd-ee-ff")
+        assert False, "expected ValueError"
+    except ValueError as e:
+        assert "already exists" in str(e).lower()
+
+
+if __name__ == "__main__":
+    test_device()
+    test_upsert_wifi_tcp_client()
+    test_device_can_change_address()
+    test_device_duplicate_names_allowed()
+    test_device_duplicate_mac_rejected()