xtc/docs/WORKSPACE.md

# Flat DAW workspace

Phase 33 presents the existing xtc editors in a consistent flat workspace. It uses
FLTK vector drawing and system fonts: no images, shadows, bevels, 3D rendering,
external theme packages or new runtime dependencies.

The default window is 1280 × 800; the supported minimum is 1220 × 720. The main
editor grows with the window. Use the scrollbars for longer arrangements and
larger track counts. The sidebar stays available across Sequencer, Mixer and
Modular Graph views. Ctrl+1/2/3 switches those views; Ctrl+4 opens the piano roll.

## Create and arrange

- **New MIDI track** (Ctrl+Shift+M) creates a named track and a one-bar MIDI clip
  at the cursor. The new clip and mixer track are selected together. **Edit MIDI
  notes** opens its piano roll. Creation is one undo step.
- **New audio track** (Ctrl+Shift+A) creates an empty named track. **Import WAV**
  imports into the selected track, or creates one when none is selected.
- **Load instrument plugin** opens the instrument browser for the selected
  sequencer track. Unassigned MIDI tracks retain the built-in sine instrument.
- Existing Add track/region/MIDI clip, duplication, trimming, split, rename and
  delete commands remain available. F2 renames the selection. Drag clips to move
  them and their edges to trim them; click the ruler to seek while stopped.

Creating a track uses candidate preparation, so module, capacity or allocation
failures retain the current project. As with other project replacements, the
engine stops and the transport returns to the beginning. Track creation is
unavailable while recording. No track type restriction is added to the model:
ordinary tracks still accept the existing audio and MIDI workflows.

Track headers show a stable color, name, order and mute/solo state. Clip colors
follow track identity through reordering. MIDI previews show real note starts,
durations and relative pitches; waveforms continue to show loaded audio data.
The selected clip has a light outline. A teal playhead and bar grid make musical
time visible. The transport display reads **bar : beat : tick** (4/4, 960 ticks
per beat); BPM follows the project tempo. These displays are read-only.

The sidebar inspector follows the sequencer selection, showing track name,
gain/pan, mute/solo and assigned instrument. Use the Mixer for controls, routing,
meters and automation; the sidebar is an overview, not another mixer. Status and
errors remain visible below the editor. Existing engine connection, transport,
recording and keyboard safety behavior is retained.

## Example and verification

Open `examples/projects/modern-session.xtc` for an original four-track, four-bar
MIDI arrangement with 16 clips and 128 notes. It needs no media or plugins. It is
also installed with the project examples. Connect JACK playback ports before
listening. Work on a copy if the installed examples are read-only.

GUI tests exercise sidebar creation, selected clip/editor access, undo/redo,
failed preparation, save/reopen and layout at 1220 × 720 and 1600 × 1000. The
running example was also inspected at 1280 × 800. Existing GUI plugin, live JACK
and workflow tests cover the retained commands. A modern presentation does not
add commercial-DAW features: detachable/resizable docks, mixer channel strips,
automatic plugin scanning, custom plugin editors and new audio/MIDI features
remain outside this phase. Existing plugin and engine limits still apply.

## Phase 34 editing controls

The **Snap** dropdown above the sequencer selects Off, 1/32, 1/16 triplet,
1/16, 1/8 triplet, 1/8, 1/4, 1/2 or one bar. Existing View/Snap commands update
the same preference. Bar lines are strongest, beats medium, subdivisions subtle.
At low zoom closely spaced lines are coarsened to at least six pixels; snapping
still uses the selected division. Clip moves and trim boundaries snap to the
nearest absolute grid position (halfway rounds forward), including clips that
start off the grid. Off removes musical quantization; pointer resolution and
integer model ticks still apply. Invalid trims retain the original clip.
Snap is a UI preference, not a project edit or a saved project setting.

Double-click a MIDI clip with the left mouse button to open its piano roll.
The clip is selected and the click does not move/trim it. Audio/silent clips
retain their existing selection/drag behavior. The piano roll also has a Snap
dropdown for its existing note grid; sequencer and piano snap remain independent.

The piano roll has a fixed **Velocity** lane beneath the keys and a **Note
velocity** slider. Select a note, then drag its bar vertically or release the
slider at a value from 1 to 127. Only that note changes; pitch, timing, length,
channel and other notes stay intact. One completed drag/slider edit is one undo
step; Escape cancels a lane drag. For chord notes sharing a start time, select
the desired note in the keys first; its highlighted velocity bar and slider
remain individually editable. Horizontal scrolling aligns the lane with note
starts; vertical scrolling moves the keys while the lane stays available.
Filters apply to lane visibility and selection. Values save with existing note
metadata and affect built-in synthesis; plugin patches determine velocity response.
This is MIDI velocity, not a per-note audio gain or loudness meter.

Every ordinary track header has an instrument dropdown. Choose **Built-in sine**,
an instrument already assigned elsewhere in the project, or **Load plugin...**
for a trusted CLAP/VST2/VST3 binary. Entries show the format and plugin label.
Each assignment creates an independent track instance, selects that track for
live MIDI and remains undoable; clear/reorder/reopen use stable track IDs. Bus
tracks show their bus label instead. Cancel or failed preparation restores the
model's selection in the dropdown. The list is project-local, not a scanner or
installed-plugin database. Existing mono/default-configuration host limits apply.
Instrument changes stop/reprepare playback and are refused while recording.

Verification includes off-grid move/trim, snap Off, dropdown labels, double-click,
coincident notes, per-note slider/lane edits, invalid velocities, undo/reload and
instrument reuse/clear/reorder for all three fixture formats. Manual checks use
the original modern-session example and the flat sequencer/piano windows.

## Phase 36 studio mixer

The Mixer tab now presents all tracks and buses as channel strips with vertical
dB faders, flat pan knobs, mute/solo, output routing and stereo meters. Scroll
horizontally for larger projects; the master output monitor stays visible.
Select a channel name to edit its gain/pan automation below the bank. Existing
undo, keyboard controls and project persistence remain available. See
[MIXER.md](MIXER.md) for fader units, metering, automation and limits.