go-go-golems/esp32-s3-m5/esp-idf-embedded-preact-zustand-webui

ESP-IDF embedded Preact+Zustand Web UI (repo pattern)

Quick anchors (open these first)

• Open docs/playbook-embedded-preact-zustand-webui.md for the JS/Vite→firmware embedding playbook.
• Use 0017-atoms3r-web-ui/ as the worked firmware example:
• 0017-atoms3r-web-ui/web/vite.config.ts (deterministic output, single JS, outputs into main/assets/)
• 0017-atoms3r-web-ui/main/CMakeLists.txt (EMBED_TXTFILES for index.html, assets/app.js, assets/app.css)
• 0017-atoms3r-web-ui/main/http_server.cpp (routes for /, /assets/app.js, /assets/app.css, /api/*, /ws)
• 0017-atoms3r-web-ui/web/src/store/ws.ts (minimal Zustand WebSocket store pattern)
• Use 0045-xiao-esp32c6-preact-web/ as the ESP32‑C6 worked example (wifi console + embedded UI + sourcemap):
• 0045-xiao-esp32c6-preact-web/main/http_server.c (NUL-trimmed embedded assets, /assets/app.js.map)
• 0045-xiao-esp32c6-preact-web/web/vite.config.ts (build.sourcemap: true)
• 0045-xiao-esp32c6-preact-web/build.sh (post-build gzip for sourcemap)

Fast search workflow (docmgr + rg)

1) Use docmgr to find the authored docs and ticket trail:

• docmgr doc search --query "preact"
• docmgr doc search --query "zustand"
• docmgr doc search --query "deterministic filenames"

2) Use ripgrep to jump to implementation:

• rg -n -S "outDir: '../main/assets'|inlineDynamicImports|entryFileNames: 'assets/app.js'|EMBED_TXTFILES|/assets/app.js|/ws" 0017-atoms3r-web-ui

3) If you need end-to-end bring-up steps, open:

• ttmp/2025/12/26/0013-ATOMS3R-WEBSERVER--atoms3r-web-server-graphics-upload-and-websocket-terminal/playbooks/01-verification-playbook-atoms3r-web-ui.md

Reuse checklist (keep firmware-friendly)

• Emit deterministic asset names (/assets/app.js, /assets/app.css) and avoid extra files (publicDir: false, emptyOutDir: true).
• Keep the initial UI to “1 JS + 1 CSS” (disable chunking via inlineDynamicImports: true).
• Embed assets with EMBED_TXTFILES (or EMBED_FILES for binary/gz) and ensure basenames won’t collide.

Common pitfalls (fix fast)

• `Uncaught SyntaxError: illegal character U+0000`: EMBED_TXTFILES typically appends a trailing 0x00 terminator. If you serve end - start bytes verbatim for JS/CSS/HTML, the browser may reject the payload. Fix by trimming a single trailing NUL before httpd_resp_send.
• Garbled UTF-8 in UI text (e.g. loading…): explicitly include charset=utf-8 in Content-Type for text/html, text/css, and application/javascript.
• Sourcemaps can bloat flash: prefer gzipping the map and embedding via EMBED_FILES, then serve /assets/app.js.map with Content-Encoding: gzip (browser devtools will still decode it).