code-sinth/docs/roadmap.md

# roadmap — code-sinth MVP → product

The MVP works end-to-end: parser, audio engine (Python + JS/AudioWorklet),
hot-reload, inline waveforms, knobs, faders, step sequencer, piano roll.
Now we polish the web app into something that looks and feels like an
instrument, not a developer demo.

## Vision

A single static web page where:

- The patch language is the source of truth for **what's connected**.
- The control surface (right pane) is the source of truth for **how you play it**:
  positions, layout, color, scrubbing.
- Everything you change in either place persists across reloads (patch in
  whatever editor you use; surface state in `localStorage` indexed by patch).
- The aesthetic sits between Reaktor 6, Teenage Engineering OP-1, and a
  modern terminal — dark base, phosphor accents, no skeuomorphism.

## Tracks

Four tracks. Each is independently shippable; the order below reflects
"unblocks the most other work first".

### Track 1 — Foundation polish · status: in progress

Concrete bricks the rest of the work sits on.

- [ ] **Resizable splitter** between editor and control surface. Drag the
      vertical seam to rebalance widths. `localStorage` persistence.
      Min widths so neither pane collapses.
- [ ] **Custom scrollbars** (WebKit `::-webkit-scrollbar` + Firefox
      `scrollbar-color`) — thin, dark, accent on hover. Applied globally
      so CodeMirror's `.cm-scroller`, the right pane, the piano roll
      and step seq overflow inherit the same style.
- [ ] **Focus / hover micro-states**. Buttons, inputs, controls all get
      consistent `transition` timings and `:focus-visible` rings.
- [ ] **Header polish**. The top bar gets a proper visual hierarchy,
      grouped controls (transport, gain, status) instead of a flex blob.

Done when: dragging the seam feels natural, scrollbars match the rest
of the dark theme everywhere, no default-browser styling leaks through.

### Track 2 — Surface aesthetics

Rebuild each surface to feel premium. For each, deliver 2–3 visual
variants in a sandbox before committing.

- [ ] **Knob**: dimensional dial with gradient + accent ring, micro-anim
      on change, label in small caps, value display below.
- [ ] **Fader**: gradient track, slimmer cap, optional scale marks.
- [ ] **Step sequencer**: cells with subtle inner glow when on, more
      prominent beat dividers, animated playhead trail.
- [ ] **Piano roll**: more realistic key strip (white keys with border,
      black keys inset), cells with rounded corners, beat dividers every
      4 columns more visible, octave C row marked.
- [ ] **Wave widgets** (inline): grid lines optional, peak indicator,
      smoother line drawing (anti-aliased Bezier).

Reference: Ableton Live's macros, Bitwig modulators, Reaktor 6 Blocks,
Teenage Engineering's hardware.

### Track 3 — Organizable surface panel

Each surface becomes a **card** the user can rearrange and customize.
This is the largest track — needs careful state design.

- [ ] **Card chrome**: header with node name, drag handle, color
      override picker, compact/expanded toggle.
- [ ] **Drag-drop reorder** within the right pane. Probable approach:
      CSS Grid with grid-auto-flow + a Sortable-style implementation
      (we won't pull in a library — ~150 lines hand-rolled).
- [ ] **Per-card accent color** override. Defaults to the global
      `--accent`; user can pick per-surface.
- [ ] **Per-card size** (compact knob row vs full panel) where it makes
      sense.
- [ ] **Persistence**: layout state in `localStorage`, keyed by a hash
      of the patch text + node name so each patch remembers its layout.
- [ ] **Reset layout** button.

Decision deferred: should the layout be expressible in the patch
language as `@layout` directives? Pro: shareable, reproducible.
Con: muddies the language. Default answer for now: no, layout is
UI-only state. Add export/import to a JSON blob if shareability
matters later.

### Track 4 — Theming

The current single-file approach already uses CSS custom properties.
Make it a real theme system.

- [ ] Theme tokens consolidated and named coherently
      (`--surface-1`, `--surface-2`, `--accent-primary`, `--accent-mute`).
- [ ] 3 packaged themes: **phosphor** (current), **monochrome**, **warm**.
- [ ] Theme picker in the header. Persists in `localStorage`.
- [ ] Per-card override (Track 3) layered on top.

## Out of scope (for now)

- MIDI input. Web MIDI works but not on Safari and the UX needs design.
- Mobile / touch optimization. Worth a pass later but not in this round.
- A landing / docs page. After the app itself feels finished.
- Patch-language enhancements (string literals, named voices in poly,
  modulation matrices). Engine-track work, separate roadmap.

## Working agreement

- One track at a time, but tracks are paralleliable when ergonomic.
- Each track ends with a screenshot review before merging the changes
  into the main `web/index.html`.
- For visually-driven changes, propose 2–3 variants and pick before
  committing.