remaxwell-web

Portail web de Maxwell (pilotage laser) — UI fidèle à maxwellUI.jpg, 194 pattrs, mixeur A/B crossfade, preview live, panneau DAC. React 18 + Vite + Zustand d'un côté, serveur Node (WebSocket + HTTP static + pont EtherDream via koffi) de l'autre.

Docs de référence (source de vérité du port) :

• packages/docs/05-patcher-complete.md — manuel exhaustif du patch Maxwell
• packages/docs/05-patcher-mechanical.md — référence mécanique des sous-patchers
• CClist — référence brute Maxwell/Maxwellator (OSC → ArtNet/MIDI CC), non modifiée. C'est une table externe : pour « est-ce câblé ici ? », lire le code, pas ce fichier.
• maxwellUI.jpg — capture de l'UI Maxwell originale, cible de layout

Quick start

pnpm install
pnpm build          # tsc + vite build (client) / tsc (server)
./remaxwell start   # serveur : HTTP 8210 + WS 8211, bind 0.0.0.0

Le serveur bind 0.0.0.0 par défaut (UI et WS accessibles depuis le LAN). Ouvrir http://<ip-du-serveur>:8210 dans un navigateur. Le client se connecte au WebSocket sur le même host que la page (ws://<hostname>:8211) — pas besoin de config du côté client.

Dev (hot reload) :

pnpm dev            # vite dev 5173 (proxy /ws → 8211) + tsx watch (server)

Wrapper CLI (lifecycle) :

./remaxwell {start|stop|restart|status|logs|help}
# logs → /tmp/remaxwell-server.log, pid → /tmp/remaxwell-server.pid

Ports & configuration

Service	Port	Bind par défaut	Override env
HTTP (UI + static)	8210	0.0.0.0	REMAXWELL_HTTP_PORT / REMAXWELL_HTTP_HOST
WebSocket (pattrs)	8211	0.0.0.0	REMAXWELL_WS_PORT / REMAXWELL_WS_HOST

Autres env : REMAXWELL_DAC_LIB (chemin du dylib EtherDream), REMAXWELL_PRESETS_DIR (défaut ~/.remaxwell/presets). Tout est dans packages/server/src/config.ts.

DAC

packages/server/bin/etherdream.dylib est gitignoré (non redistribué) : le serveur démarre et l'UI tourne sans lui, mais il n'y a aucune sortie laser. Poser le dylib à cet emplacement, ou le pointer via REMAXWELL_DAC_LIB=/chemin/....

Tests

NODE_ENV=test pnpm test   # shared 38 + server 40 + client 37, tous verts

⚠️ Sur les machines où NODE_ENV=production est exporté globalement, vitest charge le build production de React et act() échoue (9 faux échecs client). Toujours lancer les tests avec NODE_ENV=test.

Note : les tests server existent en double (.js + .ts parité) → 40 exécutés, 20 fichiers de test réels.

Lint / build

pnpm run lint        # biome check .
pnpm run build       # par package : tsc --noEmit + vite build (client), tsc (server)

pnpm run lint passe (0 erreur, 111 fichiers vérifiés). Les règles a11y structurelles sont désactivées dans biome.json — l'UI Maxwell se dessine avec des <label> de légende et des <div onClick> (dials), sans équivalent sémantique sans refaire toute la grille. Les règles non-a11y sont toutes actives.

Structure

packages/shared/   types + PATTRS (194) + protocoles (pattrs, lfo, vec3, quat, etherdream-point)
packages/server/   Node.js : PattrEngine, WS server (8211), HTTP static (8210), DAC bridge koffi
packages/client/   React 18 + Vite : UI Maxwell 1280×800 (pas de scroll)
packages/docs/     docs portées du projet RE original
remaxwell          wrapper CLI bash (start/stop/restart/status/logs)

Layout UI (grille 4 colonnes × 4 rangées, 1280×800)

Rangées en fr (210fr 115fr 100fr 130fr), PREVIEW spanne les rangées 1-3 :

	col 1	col 2	col 3	col 4
Row 1	OSC LEFT (X/Y/Z)	OSC RIGHT (X/Y/Z)	LFO 1/2/3	PREVIEW (live, rows 1-3)
Row 2	MIXER A/B crossfade (col 1-2)	↙	ROTATOR (XYZ)	↙ (preview)
Row 3	COLOR MODULATOR (col 1-2)	↙	TRANSLATOR X/Y/Z (stack)	↙ (preview)
Row 4	POINT COLOR	DUP + INTENSITY	DRAW MODE + SCALER	DAC Settings

Sources : packages/client/src/styles.css (classes .col-*, .span-mixer, .span-color) et App.tsx.

Protocole WS

Minimal : setPattr / getPattrs / setPattrs (client → serveur), pattrs / pattrChanged / error (serveur → client). Voir packages/shared/src/protocol.ts.

État du port

• ✅ 194 pattrs typés + validation des clés (getPattr rejette les clés inconnues, tests de régression)
• ✅ UI compacte complète : header, OSC, LFO, mixer A/B, translateurs, rotator, couleurs, DAC
• ✅ Preview live (Lissajous 3D, point cloud 500 pts)
• ✅ Serveur bind 0.0.0.0 + client adaptatif (window.location.hostname)
• ✅ 115 tests verts (voir Tests)
• 🔜 Câblage DAC réel (bridge EtherDream via koffi) — REMAXWELL_DAC_LIB
• 🔜 Persistance presets (presetsDir)
• 🔜 MIDI/ILDA (référence dans CClist)