UI Feature Dev

UI Feature Development (React Studios)

The UI tier of HOT-Step CPP is a single-page React 19 app in ui/ (Vite 8, Tailwind 3.4, zustand 5, react-i18next, lucide-react icons). Every user-facing feature is a "studio" — a folder of components under ui/src/components/ mounted as a top-level view. There is no react-router: routing is hand-rolled history.pushState in App.tsx. All server calls are plain fetch() against relative /api/... URLs (no axios, no react-query).

Terms used below:

• DiT — the diffusion transformer, the C++ engine's core music-generation model. The UI only ever references it as a model name string.
• Studio — one feature area (Lyric Studio, Stem Studio, Cover Studio...), i.e. one folder under ui/src/components/ plus a branch in App.tsx.
• hs-* — the localStorage key namespace used for persisted UI state.

When to use this skill

• Adding a new studio/view/panel to the UI.
• Adding a control (slider, toggle, dropdown) to an existing studio or the global parameter bar.
  • Exception: a knob for a solver/scheduler/guidance mode is NOT a UI task — Lua plugins declare their own UI params (docs/dev/plugins-authoring.md, lua-plugin-authoring skill). Wiring one into getGlobalParams() is the wrong implementation entirely.
• Wiring the UI to a new or existing server API endpoint.
• Debugging UI state, routing, persistence, or "my new param does nothing" issues.

Golden rules (hard constraints)

0. Controls come from the shared primitives — read docs/dev/ui-design.md before adding any. A dropdown is StyledSelect, an on/off setting is Toggle, a parameter label is ParamLabel with info. Never a native <select> or <input type="checkbox">; node tools/docs/check-docs.mjs fails on a new one. WHY: the native widgets look nothing like the app (grey OS box, white text) and a knob with no explanation is a support question.
1. NEVER use a browser agent for visual verification — ask the human user for screenshots/feedback. The browser agent is too slow/unreliable in this environment. It is acceptable ONLY for non-visual checks (hitting API endpoints). Workflow: make the change → confirm type-check is clean → ask the user "please check X on the /stem-studio page".
2. Don't npm run build during dev. Vite HMR means UI edits need no build and no restart. Type-check with npx tsc -b from ui\ (all tsconfigs have noEmit: true — nothing is emitted). Only build right before user prod testing. WHY: builds are slow and pointless mid-dev; the dev server already serves source.
3. Node 20 to 24 LTS, 24 recommended. ui/package.json enforces "node": ">=20.0.0 <25.0.0".
4. Registering a new studio requires FIVE edits (four in App.tsx: the import + viewFromUrl + urlForView + the renderContent branch, plus one NavItem in Sidebar.tsx — see procedure below). Skipping viewFromUrl()/urlForView() gives a studio that renders but breaks on refresh/back-button.
5. Any new generation parameter MUST be added to getGlobalParams() in ui/src/stores/globalParamsStore.ts (starts line 324) — that function is the SINGLE assembly point for the request body. A slider not wired there silently does nothing.
6. Every string through t() (react-i18next) with a key in ui/src/i18n/locales/en.json; other locales fall back to English. Note: en.json nests everything under a top-level "translation" key.
7. Git discipline (repo-wide): all work on master, never git add -A, never git add -f on gitignored paths — stage explicit paths only. Push only with explicit user approval, commit locally often. Never push a v* tag casually — it triggers a full multi-platform CI release build.
8. Cross-tier: if your UI feature needs engine (C++) changes, rebuild via dev-rebuild.bat at repo root, NEVER engine/build.cmd directly, under any circumstances (Node auto-respawns ace-server; only dev-rebuild.bat performs the clean shutdown). Never cmake --clean-first (20+ min CUDA recompile).
9. Sideband rule for new generation params: server-side params outside the C++ AceRequest struct never survive the /lm round trip. Synth requests are rebuilt by spreading the original aceReq and taking ONLY LM-generated fields from the echo (server/src/routes/generate.ts:312-328). Add new sideband params to aceReq before the LM phase; NEVER extend the LM-field pick-list into a copy-across whitelist (bug class fixed in 8ea519b/168dcb5).
10. When verifying generation params, never delete generated test audio — the user verifies results by ear. Hand over song IDs/URLs and ask the user to listen, just as visual changes get a screenshot request.

Dev loop (PowerShell, from repo root)

.\dev.bat     # run it detached; the app then lives at http://localhost:3000

This starts BOTH tiers (verified dev.bat): the Node server via server\restart-loop.cmd on :3001 (tsx watch, auto-restart) and npx vite --port 3000 --host in ui\. Develop against **http://localhost:3000** — Vite proxies /api, /audio, and /references to :3001 (ui/vite.config.ts:10-24). LAUNCH.bat is the end-user prod launcher (Node :3001 serving prebuilt ui/dist/, server/src/index.ts:126) — agents never run it.

Checks while developing:

cd D:\Ace-Step-Latest\hot-step-cpp\ui
npx tsc -b          # type-check UI (project references — catches what a plain tsc --noEmit on one file misses)
npx eslint .        # lint

If you touched server/src/: cd D:\Ace-Step-Latest\hot-step-cpp\server; npx tsc --noEmit.

Only before handing to the user for prod testing: npm run build in ui\ (runs tsc -b && vite build).

Procedure: adding a new studio

Say the studio is "My Studio", slug my-studio.

1. Create the folder ui/src/components/my-studio/ with an orchestrator MyStudio.tsx (PascalCase files, kebab-case folder). Export both named and default (export const MyStudio: React.FC = ... + export default MyStudio — see StemStudio.tsx:40,503). Layout convention (documented in-source at StemStudio.tsx:9-10): flex columns with border dividers, resizable right sidebar.
2. Register the route in ui/src/App.tsx — add the import { MyStudio } ... at the top (cf. App.tsx:38), then three places:
   • viewFromUrl() (App.tsx:84-95): if (path.startsWith('/my-studio')) return 'my-studio';
   • urlForView() (App.tsx:98-116): if (view === 'my-studio') return '/my-studio';
   • renderContent() (App.tsx:652 onward): add a branch, wrapped in DiscoPulseWrapper (a beat-reactive visual wrapper) with a hue from the DISCO constants (App.tsx:279-289, e.g. DISCO.assistant = 175 cyan):

     if (activeView === 'my-studio') {
       return (
         <DiscoPulseWrapper hue={DISCO.assistant} className="flex-1 overflow-hidden">
           <MyStudio />
         </DiscoPulseWrapper>
       );
     }

   Navigation flows through navigateTo() (App.tsx:391-401) → setActiveView + history.pushState; back/forward is a popstate listener (App.tsx:404-408). Only Lyric Studio persists a deep URL (hs-lastLyricStudioUrl) — copy that only if your studio has sub-routes.

3. Add a nav item in ui/src/components/sidebar/Sidebar.tsx — copy an existing NavItem block (e.g. Stem Studio at Sidebar.tsx:111-117): icon (lucide-react), label={t('sidebar.myStudio')}, active={activeView === 'my-studio'}, onClick={() => onViewChange('my-studio')}, isExpanded={isOpen}.
4. If it needs server endpoints: create server/src/routes/myStudio.ts, mount it in server/src/index.ts (app.use('/api/my-studio', ...) — see the mount block at index.ts:72-95), and create a per-studio client ui/src/services/myStudioApi.ts (see API layer below). Keep all endpoints under /api/... or the Vite proxy won't forward them in dev.
5. Add i18n keys to ui/src/i18n/locales/en.json (under the "translation" root) for every user-visible string.
6. Type-check, then ask the user to visually verify — never a browser agent.

State management — three coexisting patterns

Top-level docs say "Zustand" but only 2 of 8 files in ui/src/stores/ use zustand's create() (globalParamsStore.ts:9, vstChainStore.ts:6 — verified by grep). The majority pattern is a hand-rolled useSyncExternalStore module singleton. Match the pattern of the nearest existing store; don't introduce a fourth.

Pattern A — hand-rolled external store (majority; canonical example ui/src/stores/abCompareStore.ts, 101 lines). Module-level let _state, a Set of listeners, setState() that spreads + notifies, exported plain action functions (importable from non-React code), plus a useXxx() hook (useSyncExternalStore(subscribe, getSnapshot)) and a ref-cached useXxxSelector(selector) hook. Selector hooks are the preferred subscription style: useAudioGenQueueSelector(s => s.items.filter(...).length) (StemStudio.tsx:77-79). Used by: playbackStore, audioGenQueueStore, discoStore, streamingStore, abCompareStore, components/lyric-studio/playlistStore (studio-local stores may live inside the studio folder).

Pattern B — zustand + per-field localStorage (ui/src/stores/globalParamsStore.ts, 460 lines). create<any>()((set, get) => ({...})) — the any is deliberate (line 39-40). Every field initialises via readKey('hs-<name>', default) and every setter does set({...}); writeKey('hs-<name>', v) — per-key hs-* persistence, NOT zustand/persist middleware. getGlobalParams() (line 324-459, end of file) assembles ~100 knobs into a Partial<GenerationParams> request body with conditional gating — new generation params go here or nowhere. ui/src/context/GlobalParamsContext.tsx is a legacy compat shim; its own header (lines 1-8) says new code must import the store directly. Don't extend the context.

Pattern C — plain useState + localStorage inside the studio. StemStudio persists studio-local state via manual localStorage with hs-stem-* keys (StemStudio.tsx:43-46,97-104) or via usePersistedState(key, default) (ui/src/hooks/usePersistedState.ts:9). Cross-component/same-tab sync requires writePersistedState() (usePersistedState.ts:43-49), which manually dispatches a StorageEvent — native StorageEvents only fire cross-tab.

The generation queue store audioGenQueueStore.ts (992 lines) persists to IndexedDB (lireek-queue-store DB) with debounced 2 s writes because large queues blew localStorage's 5 MB cap (lines 65-73,126-133); on reload it resets in-flight items to pending + "Reconnecting…" (_sanitizeItems, lines 142-156).