create-fluxstack 1.18.0 → 1.19.0

package/CHANGELOG.md

@@ -2,6 +2,138 @@
 
 All notable changes to FluxStack will be documented in this file.
 
+## [1.19.0] - 2026-04-11
+
+### Major Refactor: Plugin System Extracted to `@fluxstack/plugin-kit`
+
+The plugin system (manager, registry, executor, discovery, dependency
+manager, module resolver, types) has been extracted from `core/plugins/`
+into the new standalone package `@fluxstack/plugin-kit`. This is the
+same playbook we used for `@fluxstack/live` in 1.16.0 — implementation
+lives in the lib, `core/plugins/` is now a thin re-export shim layer
+for backwards compatibility with existing `@core/plugins/*` imports.
+
+**Impact:** ~3,300 lines of plugin system implementation deleted from
+the app, `core/plugins/` went from 9 runtime files (4017 lines) to
+2 thin shims (types.ts + index.ts, ~200 lines combined). Single
+source of truth for plugin types and runtime is now
+`@fluxstack/plugin-kit`.
+
+### Breaking Changes
+
+- **Auto-discovery removed from `PluginManager.initialize()`** (plugin-kit 0.4.0).
+  The old code called `readdir('node_modules')` and `readdir('plugins')`
+  at startup to discover plugins. This silently broke in production
+  bundles where those directories don't exist, and prevented bundlers
+  from statically including plugin code. Host apps must now register
+  plugins explicitly via `framework.use(pluginObject)`. Dev and prod
+  are now identical; the bundler can tree-shake.
+
+- **`PluginManager` constructor requires `settings` and `clientHooks`**
+  explicitly. These used to be read from the full config / imported
+  as module-level singletons. Now they're injected:
+  ```ts
+  new PluginManager<FluxStackConfig>({
+    config: fullConfig,
+    settings: fullConfig.plugins,
+    logger: pluginLogger,
+    clientHooks: { register: (...) => pluginClientHooks.register(...) },
+    app: this.app,
+  })
+  ```
+
+- **`FluxStack.Plugin` generic over `TConfig`**. The legacy form
+  (no generic) still works and defaults to `unknown`. FluxStack's
+  shim specializes to `Plugin<FluxStackConfig>`.
+
+- **Plugin classes discouraged, object literals are canonical**.
+  All built-in plugins and `@fluxstack/plugin-csrf-protection` use
+  `export const xxxPlugin: Plugin = { name, setup, ... }`. The
+  `class X implements Plugin` form is retired from the generators
+  but still technically accepted at runtime (it implements the
+  same interface).
+
+### Added
+
+- **`@fluxstack/plugin-kit`** — new npm package. Types + runtime
+  for the plugin system. Published at 0.4.0 as of this release.
+  Used by FluxStack app and external plugin packages alike.
+- **`tests/integration/framework/registered-plugins.test.ts`** (10 tests)
+  — end-to-end verification that the four plugins registered via
+  `framework.use()` in `app/server/index.ts` actually inject their
+  hooks at runtime. Catches the class of bug where plugin objects
+  are registered but no hook actually fires (the exact failure
+  mode of the old auto-discovery in prod bundles).
+- **Static plugin registration everywhere**. `app/server/index.ts`
+  now imports `csrfProtectionPlugin` from `@fluxstack/plugin-csrf-protection`
+  directly and registers via `.use()`. Same pattern as the built-ins.
+- **Startup banner reads from the PluginRegistry**. The banner line
+  `Plugins (N): ...` now lists exactly what `framework.getPluginRegistry().getAll()`
+  returns, instead of relying on each plugin manually pushing itself
+  to `globalThis.__fluxstackPlugins`. Backwards compatible — the old
+  global is still read as a fallback.
+- **`@fluxstack/sdk` deprecated on npm** with a message pointing
+  users to `@fluxstack/plugin-kit`. The SDK was a static copy of
+  plugin types + a duplicate of `@fluxstack/config`; both have
+  canonical sources now.
+- **`make:plugin` CLI** generates plain object literal plugins
+  importing from `@fluxstack/plugin-kit`. Identifier generation
+  fixed: `my-plugin` → `myPlugin` (not `myPluginPlugin`).
+
+### Changed
+
+- **`@fluxstack/live` family bumped** from `^0.6.0` to `^0.7.1`.
+  Ships three follow-up bug fixes: opt-in `includeSelf` on `$room`
+  proxy emit (#15), `deepAssign` clones plain objects to break
+  external aliasing (#13), fail-loud protocol framing + telemetry (#7).
+- **`create-fluxstack` README template**: removed the `loggerPlugin`
+  example (that plugin was deleted), replaced class-based plugin
+  example with object literal, added a hook reference table.
+- **`plugins/README.md` template**: rewritten to reflect the static
+  `.use()` model. Explicitly calls out that plugins are NOT
+  auto-discovered. Points at `@fluxstack/plugin-csrf-protection`
+  as the living reference implementation.
+- **Bundle prod size** grew from ~2.46 MB to ~3.34 MB because
+  `@fluxstack/plugin-csrf-protection` is now statically included.
+  Before, it was dynamically loaded via `readdir('node_modules')`
+  and the bundler couldn't see it.
+- **Vite plugin startup banner label fixed** — `| Vite: embedded`
+  only shows in development now. In production the vite plugin
+  runs in static-fallback mode (serving `dist/client/`) and doesn't
+  actually run a Vite dev server, so the label was misleading.
+
+### Removed
+
+- **6934 lines of dead test code** across 24 test files. Orphaned
+  tests under `core/**/__tests__/*` never ran (vitest config was
+  `include: tests/**/*.test.ts`) and 14 of 18 were broken on
+  import when run directly. Also deleted 5 `describe.skip`'d test
+  suites under `tests/` with abandoned TODOs pointing at APIs
+  that were refactored away (Eden Treaty, ProjectCreator). Plus
+  `vitest.config.live.ts`, an orphan config pointing at a
+  directory that doesn't exist anymore.
+- **`core/plugins/{manager,registry,executor,discovery,dependency-manager,module-resolver,config}.ts`**
+  deleted from FluxStack app. Implementation lives in
+  `@fluxstack/plugin-kit` now. `core/plugins/types.ts` and
+  `core/plugins/index.ts` kept as thin shim barrels that re-export
+  from the lib and specialize `<TConfig>` against `FluxStackConfig`.
+- **Deprecated `configSchema` and `defaultConfig` fields** from the
+  Plugin interface. Were marked `@deprecated` and had no call sites.
+  Plugins use `@fluxstack/config` for declarative config instead.
+- **`loggerPlugin`** — old built-in plugin that was already absent
+  from the real codebase but still referenced in generated templates.
+  Template references removed.
+
+### Validation
+
+- Typecheck (`bunx tsc --noEmit -p tsconfig.api-strict.json`) holds
+  at the 60 pre-existing errors baseline throughout every step —
+  zero regression across all four phases of the extraction.
+- Full test suite: 42 test files, 652 passing, 5 skipped (all
+  intentional individual `it.skip` TODOs).
+- Dev and prod both show `Plugins (4): swagger, live-components,
+  csrf-protection, vite` in the startup banner — identical output.
+
 ## [1.16.0] - 2026-03-13
 
 ### Major Refactor: Extract Live Components to Monorepo

package/app/client/src/App.tsx

@@ -21,11 +21,11 @@ function NotFoundPage() {
       <h1 className="text-6xl font-black text-white mb-4">404</h1>
       <p className="text-xl text-gray-400 mb-6">Pagina nao encontrada</p>
       <p className="text-sm text-gray-500 mb-8">
-        O caminho <code className="text-purple-400">{window.location.pathname}</code> nao existe.
+        O caminho <code className="text-theme">{window.location.pathname}</code> nao existe.
       </p>
       <a
         href="/"
-        className="px-6 py-3 rounded-xl bg-purple-500/20 border border-purple-500/30 text-purple-200 hover:bg-purple-500/30 transition-all"
+        className="px-6 py-3 rounded-xl bg-theme-muted border border-theme-active text-theme hover:bg-theme-muted transition-all"
       >
         Voltar ao inicio
       </a>
@@ -129,7 +129,7 @@ function AppContent() {
           path="/form"
           element={
             <DemoPage
-              note={<>? Este formul?rio usa <code className="text-purple-400">Live.use()</code> - cada campo sincroniza automaticamente com o servidor!</>}
+              note={<>? Este formul?rio usa <code className="text-theme">Live.use()</code> - cada campo sincroniza automaticamente com o servidor!</>}
             >
               <FormDemo />
             </DemoPage>
@@ -155,7 +155,7 @@ function AppContent() {
           path="/shared-counter"
           element={
             <DemoPage
-              note={<>Contador compartilhado usando <code className="text-purple-400">LiveRoom</code> - abra em varias abas!</>}
+              note={<>Contador compartilhado usando <code className="text-theme">LiveRoom</code> - abra em varias abas!</>}
             >
               <SharedCounterDemo />
             </DemoPage>
@@ -165,7 +165,7 @@ function AppContent() {
           path="/room-chat"
           element={
             <DemoPage
-              note={<>Chat com múltiplas salas usando o sistema <code className="text-purple-400">$room</code>.</>}
+              note={<>Chat com múltiplas salas usando o sistema <code className="text-theme">$room</code>.</>}
             >
               <RoomChatDemo />
             </DemoPage>
@@ -175,7 +175,7 @@ function AppContent() {
           path="/auth"
           element={
             <DemoPage
-              note={<>🔒 Sistema de autenticação declarativo para Live Components com <code className="text-purple-400">$auth</code>!</>}
+              note={<>🔒 Sistema de autenticação declarativo para Live Components com <code className="text-theme">$auth</code>!</>}
             >
               <AuthDemo />
             </DemoPage>
@@ -185,7 +185,7 @@ function AppContent() {
           path="/ping-pong"
           element={
             <DemoPage
-              note={<>Latency demo com <code className="text-cyan-400">msgpack</code> binary codec - mensagens binárias no WebSocket!</>}
+              note={<>Latency demo com <code className="text-theme-secondary">msgpack</code> binary codec - mensagens binárias no WebSocket!</>}
             >
               <PingPongDemo />
             </DemoPage>

package/app/client/src/components/AppLayout.tsx

@@ -3,6 +3,10 @@ import { Link, Outlet, useLocation } from 'react-router'
 import { FaBook, FaGithub, FaBars, FaTimes } from 'react-icons/fa'
 import FluxStackLogo from '@client/src/assets/fluxstack.svg'
 import faviconSvg from '@client/src/assets/fluxstack-static.svg?raw'
+import { useThemeClock } from '../hooks/useThemeClock'
+import { ThemePicker } from './ThemePicker'
+import type { ColorPalette } from '../lib/theme-clock'
+import { themeConfig } from '../config/theme.config'
 
 const navItems = [
   { to: '/', label: 'Home' },
@@ -36,13 +40,16 @@ const faviconUrlCache = new Map<string, string>()
 export function AppLayout() {
   const location = useLocation()
   const [menuOpen, setMenuOpen] = useState(false)
+  const autoTheme = useThemeClock()
+  const [overrideTheme, setOverrideTheme] = useState<ColorPalette | null>(null)
+  const theme = overrideTheme || autoTheme
 
   useEffect(() => {
     const current = navItems.find(item => item.to === location.pathname)
     document.title = current ? `${current.label} - FluxStack` : 'FluxStack'
 
-    // Dynamic favicon with hue-rotate (cached per hue value)
-    const hue = routeFlameHue[location.pathname] || '0deg'
+    // Dynamic favicon with hue-rotate based on theme clock
+    const hue = `${Math.round(theme.baseHue - 270)}deg`
     let url = faviconUrlCache.get(hue)
     if (!url) {
       // Evict oldest entry if cache is full, revoking blob URL to free memory
@@ -68,20 +75,27 @@ export function AppLayout() {
     }
     link.type = 'image/svg+xml'
     link.href = url
-  }, [location.pathname])
+  }, [location.pathname, theme.baseHue])
 
   return (
-    <div className="min-h-screen bg-gradient-to-br from-slate-900 via-purple-900 to-slate-900">
-      <header className="sticky top-0 z-50 backdrop-blur-md bg-slate-900/60 border-b border-white/10">
+    <div className="min-h-screen text-white flex flex-col" style={{ backgroundColor: `oklch(8% 0.02 ${theme.baseHue})` }}>
+      <header className="sticky top-0 z-50 backdrop-blur-xl bg-[#0a0a1a]/80 border-b border-white/[0.06]">
         <div className="container mx-auto px-4 sm:px-6 py-3 sm:py-4 flex items-center justify-between gap-4">
-          <Link to="/" className="flex items-center gap-2 text-white font-semibold tracking-wide">
+          <Link to="/" className="flex items-center gap-2 font-semibold tracking-wide">
             <img
               src={FluxStackLogo}
               alt="FluxStack"
-              className="w-9 h-9 transition-[filter] duration-500 drop-shadow-[0_0_8px_rgba(168,85,247,0.5)]"
-              style={{ filter: `hue-rotate(${routeFlameHue[location.pathname] || '0deg'})` }}
+              className="w-9 h-9 transition-[filter] duration-500"
+              style={{
+                filter: `hue-rotate(${theme.baseHue - 270}deg) drop-shadow(0 0 8px ${theme.primaryGlow})`,
+              }}
             />
-            FluxStack
+            <span
+              className="bg-clip-text text-transparent"
+              style={{ backgroundImage: theme.gradientPrimary }}
+            >
+              FluxStack
+            </span>
           </Link>
 
           {/* Desktop nav */}
@@ -94,9 +108,13 @@ export function AppLayout() {
                   to={item.to}
                   className={`px-3 py-1.5 rounded-lg text-sm transition-all ${
                     active
-                      ? 'bg-white/15 text-white'
-                      : 'text-gray-300 hover:bg-white/10'
+                      ? 'font-medium'
+                      : 'text-gray-400 hover:text-white hover:bg-white/[0.05]'
                   }`}
+                  style={active ? {
+                    backgroundColor: theme.primaryMuted,
+                    color: theme.textPrimary,
+                  } : undefined}
                 >
                   {item.label}
                 </Link>
@@ -109,7 +127,7 @@ export function AppLayout() {
               href="https://live-docs.marcosbrendon.com/"
               target="_blank"
               rel="noopener noreferrer"
-              className="hidden sm:inline-flex items-center gap-2 px-3 py-1.5 bg-purple-500/20 border border-purple-500/30 text-purple-200 rounded-lg text-sm hover:bg-purple-500/30 transition-all"
+              className="hidden sm:inline-flex items-center gap-2 px-3 py-1.5 bg-purple-500/20 border border-purple-500/20 text-purple-300 rounded-xl text-sm hover:bg-purple-500/30 transition-all"
             >
               <FaBook />
               Live Docs
@@ -118,7 +136,7 @@ export function AppLayout() {
               href="/swagger"
               target="_blank"
               rel="noopener noreferrer"
-              className="hidden sm:inline-flex items-center gap-2 px-3 py-1.5 bg-white/10 border border-white/20 text-white rounded-lg text-sm hover:bg-white/20 transition-all"
+              className="hidden sm:inline-flex items-center gap-2 px-3 py-1.5 bg-white/[0.03] border border-white/[0.06] text-gray-400 rounded-xl text-sm hover:bg-white/[0.06] hover:text-white transition-all"
             >
               <FaBook />
               API Docs
@@ -127,7 +145,7 @@ export function AppLayout() {
               href="https://github.com/MarcosBrendonDePaula/FluxStack"
               target="_blank"
               rel="noopener noreferrer"
-              className="hidden sm:inline-flex items-center gap-2 px-3 py-1.5 bg-white/10 border border-white/20 text-white rounded-lg text-sm hover:bg-white/20 transition-all"
+              className="hidden sm:inline-flex items-center gap-2 px-3 py-1.5 bg-white/[0.03] border border-white/[0.06] text-gray-400 rounded-xl text-sm hover:bg-white/[0.06] hover:text-white transition-all"
             >
               <FaGithub />
               GitHub
@@ -136,7 +154,7 @@ export function AppLayout() {
             {/* Mobile menu toggle */}
             <button
               onClick={() => setMenuOpen(!menuOpen)}
-              className="md:hidden p-2 text-gray-300 hover:text-white transition-colors"
+              className="md:hidden p-2 text-gray-400 hover:text-white transition-colors"
               aria-label="Toggle menu"
             >
               {menuOpen ? <FaTimes size={20} /> : <FaBars size={20} />}
@@ -146,7 +164,7 @@ export function AppLayout() {
 
         {/* Mobile nav */}
         {menuOpen && (
-          <div className="md:hidden border-t border-white/10 bg-slate-900/90 backdrop-blur-md">
+          <div className="md:hidden border-t border-white/[0.06] bg-[#0a0a1a]/90 backdrop-blur-xl">
             <nav className="container mx-auto px-4 py-3 flex gap-4 relative">
               <div className="flex flex-col gap-1 flex-1">
               {navItems.map((item) => {
@@ -158,20 +176,24 @@ export function AppLayout() {
                     onClick={() => setMenuOpen(false)}
                     className={`px-3 py-2 rounded-lg text-sm transition-all ${
                       active
-                        ? 'bg-white/15 text-white'
-                        : 'text-gray-300 hover:bg-white/10'
+                        ? 'font-medium'
+                        : 'text-gray-400 hover:text-white hover:bg-white/[0.05]'
                     }`}
+                    style={active ? {
+                      backgroundColor: theme.primaryMuted,
+                      color: theme.textPrimary,
+                    } : undefined}
                   >
                     {item.label}
                   </Link>
                 )
               })}
-              <div className="flex flex-wrap gap-2 mt-2 pt-2 border-t border-white/10">
+              <div className="flex flex-wrap gap-2 mt-2 pt-2 border-t border-white/[0.06]">
                 <a
                   href="https://live-docs.marcosbrendon.com/"
                   target="_blank"
                   rel="noopener noreferrer"
-                  className="inline-flex items-center gap-2 px-3 py-2 bg-purple-500/20 border border-purple-500/30 text-purple-200 rounded-lg text-sm hover:bg-purple-500/30 transition-all"
+                  className="inline-flex items-center gap-2 px-3 py-2 bg-purple-500/20 border border-purple-500/20 text-purple-300 rounded-xl text-sm hover:bg-purple-500/30 transition-all"
                 >
                   <FaBook />
                   Live Docs
@@ -180,7 +202,7 @@ export function AppLayout() {
                   href="/swagger"
                   target="_blank"
                   rel="noopener noreferrer"
-                  className="inline-flex items-center gap-2 px-3 py-2 bg-white/10 border border-white/20 text-white rounded-lg text-sm hover:bg-white/20 transition-all"
+                  className="inline-flex items-center gap-2 px-3 py-2 bg-white/[0.03] border border-white/[0.06] text-gray-400 rounded-xl text-sm hover:bg-white/[0.06] hover:text-white transition-all"
                 >
                   <FaBook />
                   API Docs
@@ -189,7 +211,7 @@ export function AppLayout() {
                   href="https://github.com/MarcosBrendonDePaula/FluxStack"
                   target="_blank"
                   rel="noopener noreferrer"
-                  className="inline-flex items-center gap-2 px-3 py-2 bg-white/10 border border-white/20 text-white rounded-lg text-sm hover:bg-white/20 transition-all"
+                  className="inline-flex items-center gap-2 px-3 py-2 bg-white/[0.03] border border-white/[0.06] text-gray-400 rounded-xl text-sm hover:bg-white/[0.06] hover:text-white transition-all"
                 >
                   <FaGithub />
                   GitHub
@@ -209,7 +231,22 @@ export function AppLayout() {
         )}
       </header>
 
-      <Outlet />
+      <main className="flex-1">
+        <Outlet />
+      </main>
+
+      <footer className="border-t border-white/[0.06] py-6 mt-auto">
+        <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 text-center">
+          <p className="text-gray-500 text-sm">
+            Built with <span style={{ color: theme.primary }}>FluxStack</span> — Bun + Elysia + React
+          </p>
+          <p className="text-gray-600 text-xs mt-1">
+            🎨 <span style={{ color: theme.primary }}>{theme.period}</span> palette — colors shift with the time of day
+          </p>
+        </div>
+      </footer>
+
+      {themeConfig.showPicker && <ThemePicker palette={theme} onOverride={setOverrideTheme} />}
     </div>
   )
 }

package/app/client/src/components/ColorWheel.tsx

@@ -0,0 +1,195 @@
+/**
+ * ColorWheel — Interactive color wheel like Adobe Color
+ *
+ * Modes:
+ * - Preset harmonies: all dots move together based on base hue
+ * - Custom: each dot is independently draggable
+ */
+import { useRef, useState, useCallback, useEffect } from 'react'
+
+export type HarmonyMode = 'analogous' | 'complementary' | 'triadic' | 'split-complementary' | 'square' | 'monochromatic' | 'custom'
+
+interface ColorWheelProps {
+  /** Hues for each point: [primary, secondary, tertiary, complement, accent] */
+  hues: number[]
+  mode: HarmonyMode
+  size?: number
+  /** Called when any hue changes. index = which point, hue = new value */
+  onChange: (index: number, hue: number) => void
+}
+
+const POINT_LABELS = ['P', 'S', 'T', 'C', 'A']
+
+/** Get harmony offsets for preset modes */
+function getHarmonyOffsets(mode: HarmonyMode): number[] {
+  switch (mode) {
+    case 'analogous':           return [0, -30, 30, -60, 60]
+    case 'complementary':       return [0, 180]
+    case 'triadic':             return [0, 120, 240]
+    case 'split-complementary': return [0, 150, 210]
+    case 'square':              return [0, 90, 180, 270]
+    case 'monochromatic':       return [0]
+    case 'custom':              return [0, 40, -30, 180, 120] // defaults, but each is independent
+  }
+}
+
+/** Get number of points for each mode */
+export function getPointCount(mode: HarmonyMode): number {
+  return getHarmonyOffsets(mode).length
+}
+
+/** Generate initial hues from base hue and mode */
+export function generateHuesFromMode(baseHue: number, mode: HarmonyMode): number[] {
+  return getHarmonyOffsets(mode).map(o => ((baseHue + o) % 360 + 360) % 360)
+}
+
+function hueToXY(hue: number, radius: number, cx: number, cy: number) {
+  const rad = ((hue - 90) * Math.PI) / 180
+  return { x: cx + radius * Math.cos(rad), y: cy + radius * Math.sin(rad) }
+}
+
+function xyToHue(x: number, y: number, cx: number, cy: number): number {
+  return ((Math.atan2(y - cy, x - cx) * 180) / Math.PI + 90 + 360) % 360
+}
+
+export function ColorWheel({ hues, mode, size = 220, onChange }: ColorWheelProps) {
+  const svgRef = useRef<SVGSVGElement>(null)
+  const [dragging, setDragging] = useState<number | null>(null) // index of dragged point
+
+  const cx = size / 2
+  const cy = size / 2
+  const outerR = size / 2 - 8
+  const innerR = outerR - 24
+  const dotR = outerR - 12
+
+  const isCustom = mode === 'custom'
+
+  const getMouseHue = useCallback((e: MouseEvent | React.MouseEvent) => {
+    const svg = svgRef.current
+    if (!svg) return 0
+    const rect = svg.getBoundingClientRect()
+    return xyToHue(e.clientX - rect.left, e.clientY - rect.top, cx, cy)
+  }, [cx, cy])
+
+  // Mouse down on a specific point
+  const handlePointDown = useCallback((e: React.MouseEvent, index: number) => {
+    e.preventDefault()
+    e.stopPropagation()
+    setDragging(index)
+  }, [])
+
+  // Mouse down on wheel background — moves the base (index 0)
+  // Click on wheel background = rotate ALL points together (preserving relative positions)
+  const handleWheelDown = useCallback((e: React.MouseEvent) => {
+    e.preventDefault()
+    setDragging(-1) // -1 = rotate all
+    const hue = getMouseHue(e)
+    const delta = hue - hues[0]
+    for (let i = 0; i < hues.length; i++) {
+      onChange(i, ((hues[i] + delta) % 360 + 360) % 360)
+    }
+  }, [getMouseHue, hues, onChange])
+
+  useEffect(() => {
+    if (dragging === null) return
+
+    const handleMove = (e: MouseEvent) => {
+      const hue = getMouseHue(e)
+      if (dragging === -1) {
+        // Rotate all points together (background drag)
+        const delta = hue - hues[0]
+        for (let i = 0; i < hues.length; i++) {
+          onChange(i, ((hues[i] + delta) % 360 + 360) % 360)
+        }
+      } else if (isCustom) {
+        // Custom mode: move only the dragged point
+        onChange(dragging, hue)
+      } else {
+        // Preset mode: move all points relative to base
+        const delta = hue - hues[0]
+        for (let i = 0; i < hues.length; i++) {
+          onChange(i, ((hues[i] + delta) % 360 + 360) % 360)
+        }
+      }
+    }
+    const handleUp = () => setDragging(null)
+
+    window.addEventListener('mousemove', handleMove)
+    window.addEventListener('mouseup', handleUp)
+    return () => {
+      window.removeEventListener('mousemove', handleMove)
+      window.removeEventListener('mouseup', handleUp)
+    }
+  }, [dragging, getMouseHue, hues, isCustom, onChange])
+
+  return (
+    <svg
+      ref={svgRef}
+      width={size}
+      height={size}
+      onMouseDown={handleWheelDown}
+      style={{ cursor: dragging !== null ? 'grabbing' : 'pointer', userSelect: 'none' }}
+    >
+      {/* Hue ring segments */}
+      {Array.from({ length: 72 }, (_, i) => {
+        const a1 = (i / 72) * 360
+        const a2 = ((i + 1) / 72) * 360
+        const r1 = ((a1 - 90) * Math.PI) / 180
+        const r2 = ((a2 - 90) * Math.PI) / 180
+        return (
+          <path
+            key={i}
+            d={`M ${cx + outerR * Math.cos(r1)} ${cy + outerR * Math.sin(r1)} A ${outerR} ${outerR} 0 0 1 ${cx + outerR * Math.cos(r2)} ${cy + outerR * Math.sin(r2)} L ${cx + innerR * Math.cos(r2)} ${cy + innerR * Math.sin(r2)} A ${innerR} ${innerR} 0 0 0 ${cx + innerR * Math.cos(r1)} ${cy + innerR * Math.sin(r1)} Z`}
+            fill={`oklch(70% 0.22 ${a1})`}
+          />
+        )
+      })}
+
+      {/* Inner dark circle */}
+      <circle cx={cx} cy={cy} r={innerR - 2} fill="#0a0a1a" />
+
+      {/* Connection lines */}
+      {hues.length > 1 && (
+        <polygon
+          points={hues.map(h => {
+            const p = hueToXY(h, dotR * 0.55, cx, cy)
+            return `${p.x},${p.y}`
+          }).join(' ')}
+          fill={`oklch(65% 0.15 ${hues[0]} / 0.08)`}
+          stroke="rgba(255,255,255,0.12)"
+          strokeWidth="1"
+        />
+      )}
+
+      {/* Center color preview */}
+      <circle cx={cx} cy={cy} r={innerR * 0.35} fill={`oklch(65% 0.25 ${hues[0]})`} opacity="0.8" />
+      <text x={cx} y={cy - 6} textAnchor="middle" dominantBaseline="central" fill="white" fontSize="11" fontWeight="700">
+        {Math.round(hues[0])}°
+      </text>
+      <text x={cx} y={cy + 8} textAnchor="middle" dominantBaseline="central" fill="rgba(255,255,255,0.5)" fontSize="8">
+        {isCustom ? 'CUSTOM' : mode.toUpperCase()}
+      </text>
+
+      {/* Harmony dots — each draggable in custom mode */}
+      {hues.map((hue, i) => {
+        const pos = hueToXY(hue, dotR, cx, cy)
+        const isBase = i === 0
+        const isDraggable = isCustom || isBase
+        const r = isBase ? 9 : 7
+        return (
+          <g
+            key={i}
+            onMouseDown={isDraggable ? (e) => handlePointDown(e, i) : undefined}
+            style={{ cursor: isDraggable ? 'grab' : 'default' }}
+          >
+            <circle cx={pos.x} cy={pos.y} r={r + 3} fill={`oklch(65% 0.25 ${hue} / 0.3)`} />
+            <circle cx={pos.x} cy={pos.y} r={r} fill={`oklch(65% 0.25 ${hue})`} stroke="white" strokeWidth={isBase ? 2.5 : 1.5} />
+            <text x={pos.x} y={pos.y} textAnchor="middle" dominantBaseline="central" fill="white" fontSize="7" fontWeight="600" pointerEvents="none">
+              {POINT_LABELS[i] || ''}
+            </text>
+          </g>
+        )
+      })}
+    </svg>
+  )
+}

package/app/client/src/components/DemoPage.tsx

@@ -11,9 +11,11 @@ export function DemoPage({ children, note }: { children: ReactNode; note?: React
         {children}
       </div>
       {note && (
-        <p className="mt-4 sm:mt-6 text-gray-400 text-xs sm:text-sm max-w-md text-center px-2">
-          {note}
-        </p>
+        <div className="mt-4 sm:mt-6 bg-theme-accent border border-theme rounded-xl px-4 py-3 max-w-md text-center">
+          <p className="text-gray-400 text-xs sm:text-sm">
+            {note}
+          </p>
+        </div>
       )}
     </div>
   )

package/app/client/src/components/LiveUploadWidget.tsx

@@ -168,7 +168,7 @@ export function LiveUploadWidget({
           </div>
           <div className="w-full h-3 bg-white/10 rounded-full overflow-hidden">
             <div
-              className="h-full bg-gradient-to-r from-blue-500 to-purple-500 transition-all"
+              className="h-full bg-theme-gradient transition-all"
               style={{ width: `${live.$state.progress}%` }}
             />
           </div>