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.


## Phase 37 direct editing and navigation

**Commands** (Ctrl+P) searches active menu actions by case-insensitive substring.
Type part of an action path such as `mixer`, `import` or `preferences`, use
Up/Down to select, then Enter or **Run command**. Double-click also runs an
entry. Escape or Cancel leaves the project unchanged. The palette closes before
executing the existing menu callback; context and recording guards still apply.

The transport **BPM** field edits project tempo from 20 to 300 BPM, stored in
milli-BPM. Enter or release commits one undoable change. It stops and rewinds
transport and prepares the project, including converting loop ticks to samples
at the new tempo. Failed validation/preparation retains the previous project;
the field returns to its actual value. Existing track/clip and piano-roll
selection survives. This is project tempo, separate from Preferences' new-project
default. Tempo automation is not added.

The **Track inspector** now edits the selected track's linear Gain (0..4), Pan
(-1..1), Mute and Solo. In Mixer it follows the selected channel; in Sequencer
and Graph it follows arrangement selection. Controls synchronize with model
changes and undo, while typing is protected from the display refresh timer.
Only the edited field is committed. Unchanged values create no history entry.
These are static values; automation still overrides gain and pan. Recording
prevents edits. Track instruments and routing retain their existing selectors.

The session row shows track/bus count, clip count and the arrangement's bar span.
**Fit song** (Ctrl+0) returns to the start and selects the largest supported zoom
that fits the arrangement plus a beat of padding. Supported zoom remains
24, 48, 96, 192 or 384 pixels per beat; a sufficiently long arrangement requires
scrolling even at the minimum. Empty projects fit one bar.

**Follow playhead** pages the arrangement horizontally during playback, retaining
vertical scroll. It operates only in Sequencer and waits while a mouse drag is
active. It is off by default; Preferences / Apply persists it in
`[transport] follow_playhead=0` or `1`. Manual scrolling remains available and
Fit song resets the viewport without editing the project.

Verification covers real FLTK palette filtering, empty searches and cancellation,
tempo callbacks/undo/failed adoption, inspector edits and in-progress numeric
input, fit and follow navigation, and existing core/GUI/live JACK workflows.


## Detachable transport and mixer (Phase 39)

Use **View → Detach transport** or **View → Detach mixer** to move either panel
into a separate window. Toggle the same menu action, use the floating panel's
**Dock** button, or close its window to return it to the main workspace.
**View → Dock all panels** restores both. **View → Mixer** (Ctrl+2) also raises
the floating mixer. The main arrangement expands when the transport is detached.
The mixer remains the same live view, with its channel selection, faders, routing
and meters; the main Mixer tab offers Show and Dock actions while it is floating.

The transport owns the playback buttons, position, **BPM**, **Loop** toggle and
**Loop range...** settings in both layouts. Shift-drag on the sequencer ruler
still updates the same loop region. BPM remains an undoable project edit;
loop preferences retain their existing Preferences / Apply persistence behavior.
Space and menu playback shortcuts work from either floating panel, with normal
numeric/text editing protection. Closing the main window closes all panels only
after the existing unsaved/recording/backend shutdown checks succeed.

The initial Phase 39 layout used session-only positions and a transport minimum
width of 1220 pixels. Phase 45 below adds saved layouts and transport wrapping
down to 400 pixels. The floating mixer resizes down to 600 × 420 and retains
horizontal track scrolling.

Verified with `make BUILD_DIR=build/phase39 gui test-gui test-gui-instruments
 test-gui-jack` (one line), plus the GUI suite under AddressSanitizer/UBSan.
Tests cover repeated reparenting, close-to-dock, resize, shared BPM/loop state,
playback shortcuts, failed shutdown and cleanup.

## Phase 45 saved panel layouts

Preferences / Apply now saves transport/mixer dock state and window rectangles.
Open Preferences after arranging the windows to capture their current positions.
Closing the application alone does not save preferences. Startup restores the
saved layout; off-screen rectangles are clamped to an available display's work
area. Invalid dimensions are rejected transactionally by the settings reader.

The floating transport supports widths down to 400 pixels. Controls wrap into
rows below 1220 pixels, retaining playback, BPM, loop and navigation actions;
its height grows as necessary to keep every control available. Docking restores
the wide toolbar and arrangement geometry. Mixer minimum remains 600 × 420.
Existing close-to-dock, Dock all and shortcuts retain their shared widget state.
Tests cover narrow control bounds, save/restart, off-screen restoration, invalid
geometry, repeated docking/resizing and shared transport state.

## Phase 46 editor panels and pinned track headers

**View → Detach sequencer** and **Detach modular graph** float each complete
editor, including its toolbar and scroll area. Its main tab offers Show and Dock
buttons. Closing the floating window docks it; View shortcuts also raise floating
editors. Supported dock locations are their original main-window tabs; arbitrary
split regions, tab reordering and drag-to-dock are not implemented. Sequencer
minimum floating size is 1100 × 420; Graph is 1000 × 420.

The Piano roll now also has a main-window tab. Select a MIDI clip and open it as
before. **View → Float piano roll** switches its existing widgets between the tab
and a floating window; closing the floating window docks it. The tab's Open
selected MIDI clip button opens the current selection. Default floating behavior
is retained for older preferences. A missing/invalid MIDI selection is reported.
All panels share project/history, preserve editor selections and scroll offsets,
and retain playback shortcuts and text-input protection.

**View → Dock all panels** includes all editors. **Reset workspace layout** docks
all panels, restores default floating rectangles and resets header width. Use
Preferences / Apply to persist either result. Editor dock state, floating window
rectangles and header width use the same validated settings/restore path as the
transport/mixer. Piano content opens lazily for the selected MIDI clip; startup
does not invent a clip or save a project-specific selection in application settings.

Arrangement track headers and instrument selectors now stay pinned during
horizontal scrolling. Drag the divider within the header's final five pixels to
resize from 180 to 360 pixels; Escape cancels the drag. Clip timing coordinates,
snap and horizontal scrolling use the resized origin. Header layout is a UI
preference, not an undoable project edit. Vertical scrolling remains shared with
the track rows. Clips covered by the pinned header cannot be selected through it.

GUI regressions cover repeated detach/dock and close-to-dock, toolbar ownership,
minimum/large resize, shared model/note/clip selection, scrolling, header dragging,
short-clip hit tests, Apply/restart, reset layout and failed/successful shutdown.
ASan/UBSan checks retain only the existing system Fontconfig leak suppression.

Phases 47–57 add additive clip selection, atomic group commands, phrase clipboard
and repeat, alignment/slip tools, MIDI swing/gate/legato/scale/velocity transforms,
batch audio fades and static mixer A/B recall. See
[MODERN_EDITING.md](MODERN_EDITING.md) for commands, scope and limitations.

Phases 58–68 add arrangement markers and sections, ripple edits, complete track
duplication, MIDI splitting/consolidation and composition tools, peak normalization
and portable media collection. See [COMPOSITION_WORKFLOWS.md](COMPOSITION_WORKFLOWS.md).