xtc/docs/WORKSPACE.md

# Flat DAW Workspace

The workspace presents the existing xtc editors in a consistent flat layout. 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 workspace. Existing plugin and engine limits still apply.

---

## 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.

---

## 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.

---

## 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

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 persist through Preferences / Apply or clean application exit. 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 layout used session-only positions and a transport minimum width of
1220 pixels. Saved layouts and transport wrapping down to 400 pixels are
described below. The floating mixer resizes down to 600 × 420 and retains
horizontal track scrolling.

Verified with
`make BUILD_DIR=build/workspace-detach 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.

---

## Saved Panel Layouts

Preferences / Apply now saves transport/mixer dock state and window rectangles.
Clean application exit also saves their current positions. 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.

---

## 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.

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 are also available. See
[MODERN_EDITING.md](MODERN_EDITING.md) for commands, scope and limitations.

Arrangement markers and sections, ripple edits, complete track duplication, MIDI
splitting/consolidation and composition tools, peak normalization and portable
media collection are also available. See
[COMPOSITION_WORKFLOWS.md](COMPOSITION_WORKFLOWS.md).

A modal audio source editor provides frame selection, reversible processing,
selection export, copy adoption and transient slicing. See
[AUDIO_EDITOR.md](AUDIO_EDITOR.md) for commands, undo behavior and mono/size
limits.