ToooT 1.0

Author: mstits

.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build-and-test:
+    runs-on: macos-15
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Select Xcode 16 (Swift 6)
+      run: sudo xcode-select -s /Applications/Xcode_16.0.app
+      
+    - name: Build Project
+      run: swift build
+      
+    - name: Run Validation Suite (UAT)
+      run: .build/arm64-apple-macosx/debug/UATRunner

.gitignore

@@ -0,0 +1,45 @@
+# Xcode / Swift
+.build/
+.swiftpm/
+*.xcodeproj
+*.xcworkspace
+xcuserdata/
+*.xcframework
+DerivedData/
+*.app/
+*.app
+
+# OS X
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Testing / Diagnostic Media
+*.wav
+*.aiff
+*.mp3
+*.m4a
+*.jpg
+*.png
+
+# Diagnostic & Refactor Scripts
+*.py
+waveform_compare/
+
+# Temporary / Session Outputs
+uat_output.txt
+deep_project_session.json
+deep_project_interview.md
+gemini_prompt_*.md
+gemini.md
+refactor.py
+refactor2.py
+fix_*.py
+strip_focus.py
+
+# Internal Project Docs
+AUDIT.md
+HANDOFF.md
+project-manifest.md
+requirements.md
+SESSION_LOG.md

01-audio-engine-perf/spec.md

@@ -0,0 +1,53 @@
+# Spec: 01-audio-engine-perf
+
+**Project:** ProjectToooT — macOS 2026 Native DAW  
+**Module:** ToooT_Core  
+**Track:** Parallel A (independent of UI and I/O work)
+
+## Goal
+
+Eliminate the two biggest CPU bottlenecks in the audio render path, targeting Apple Silicon M-series efficiency. Core audio is already production quality (17 UAT suites passing) — this is pure performance work.
+
+## Background
+
+See `requirements.md` §2 (Core Audio Engine) and `memory/project_status.md` §Known Performance Gaps.
+
+The engine is correct but has two known scalar hotspots:
+
+1. **SynthVoice resampler** — 4-point Hermite interpolation implemented as a per-sample scalar loop. Target: `vDSP_vlint` vectorized path.
+2. **AudioRenderNode channel iteration** — iterates all available channels (up to 1024 per requirements, 256 per current build) every render cycle even when most are empty. Target: active-channel bitmask.
+
+## What to Build
+
+### Task A: Vectorize SynthVoice Resampler
+- Replace the per-sample Hermite loop in `SynthVoice.process()` with `vDSP_vlint`
+- **Critical OOB guard (L32):** `vDSP_vlint` reads `floor(i)` and `floor(i)+1`. For resample factor F, source count N: `maxNewCount = (N-1) / F`. Cap `newCount = min(maxNewCount, N/F)`. Off-by-one causes silent memory corruption.
+- Maintain loop wrapping for ping-pong and reverse looping modes (L27: loop bounds check must gate behind `!isLooping`; Hermite lookahead indices must wrap around loop region, not clamp to `sampleLength-1`)
+- Validate interpolation quality: octave-down should produce 439–440 zero-crossings (test 16 baseline)
+
+### Task B: Active-Channel Bitmask in AudioRenderNode
+- Add a bitmask (e.g., `UInt64` array or `[Bool]`) tracking which channels have active voices
+- Update the bitmask atomically when voices are triggered or complete (RT-safe, no locking)
+- Skip empty channels in the render loop without iterating their DSP path
+- The shared render logic lives in `processTickSequencer(wrapOnEnd:)` (L33) — do not duplicate any logic; changes here apply to both `renderBlock` and `renderOffline`
+
+## Constraints
+
+- **No heap allocation on the render thread** — bitmask must be pre-allocated; `vDSP_vlint` buffers must be pre-allocated from the UMA slab or stack
+- **Swift 6 strict concurrency** — bitmask writes must be `Atomic<T>` or happen only on the audio thread
+- **masterVol = 0.5** (L26) — do not change the gain constant
+- **Oscillating effects must not write back to base properties** (L24) — do not touch tremolo/vibrato paths
+- **UAT must stay green** — all 17 suites must pass after changes; waveform correlation ≥ 0.99 (test 15)
+
+## Success Criteria
+
+- [ ] `vDSP_vlint` resampler implemented with correct OOB guard
+- [ ] Active-channel bitmask skips empty channels in render loop
+- [ ] All 17 UAT suites pass
+- [ ] Perf microbenchmark: cycles-per-frame reduced measurably (establish baseline before starting)
+- [ ] No new Swift 6 concurrency warnings
+
+## Dependencies
+
+**Needs from other splits:** None — fully self-contained in ToooT_Core.  
+**Provides to other splits:** Stable `EngineSharedState` snapshot API (used by 03-ui-coherence for playhead animation).

02-io-save-load/spec.md

@@ -0,0 +1,60 @@
+# Spec: 02-io-save-load
+
+**Project:** ProjectToooT — macOS 2026 Native DAW  
+**Module:** ToooT_IO  
+**Track:** Parallel B (independent of audio perf and UI work)
+
+## Goal
+
+Make project save/load lossless and production-ready. A DAW that cannot save its own projects cannot be demoed at WWDC. This is a critical early deliverable.
+
+## Background
+
+See `requirements.md` §3 (I/O & Standards) and `memory/project_status.md` §Stubs / Incomplete.
+
+The parsing side (MADParser, FormatTranspiler) is largely working — MOD/XM/IT all load, finetune is read correctly (L29). The write side has known gaps:
+
+- `MADWriter` saves hardcoded "ToooT Project" as title regardless of loaded song
+- `MADWriter` does not serialize finetune back to header byte 24 lower nibble
+- MIDI import has a basic parser but needs better track/channel mapping
+
+## What to Build
+
+### Task A: MADWriter Lossless Round-Trip
+- Serialize actual song title from the loaded `MADMusic` / `UnifiedSampleBank` metadata
+- Write finetune back to instrument header byte 24, lower nibble (values -8 to +7, two's complement nibble)
+  - This is the inverse of the L29 parse: `pow(2, finetune/96.0)` — the nibble value must survive round-trip
+- Verify all `UnifiedSampleBank` PCM data is serialized (requirements §3: "zero-loss project saving")
+- Add regression test: load a reference MOD file, save it, reload it, assert:
+  - Song title matches
+  - Finetune nibble byte-for-byte identical
+  - Audio output waveform correlation ≥ 0.99 against original
+
+### Task B: MADParser Dynamic Sample Offsets
+- Requirements §3: `MADParser` must support dynamic sample offsets and lengths for third-party MOD/MAD files
+- Audit current parser for hardcoded offset assumptions; fix any that fail on non-canonical files
+
+### Task C: MIDI Import Track/Channel Mapping
+- Current state: basic MIDI parser exists, stub-level track/channel mapping
+- Improve: map MIDI tracks to channels intelligently (by program, by track name, by channel number)
+- Minimum: load a standard General MIDI file and have each track land in the correct tracker channel
+
+## Constraints
+
+- **Do not break existing UAT** — MOD/XM/IT load tests (suites 1–14+) must all remain green
+- **Finetune formula is fixed** (L29): `pow(2, finetune/96.0)` — do not alter the math
+- **MADParser must support dynamic offsets** per requirements §3 — no hardcoded byte positions
+- **MIDI 2.0 is out of scope here** — that belongs to 05-platform-hardening; this split targets standard MIDI import
+
+## Success Criteria
+
+- [ ] MADWriter serializes actual song title
+- [ ] MADWriter writes finetune nibble; byte-for-byte verified round-trip test passes
+- [ ] All existing UAT suites remain green
+- [ ] At least one real-world third-party MOD file loads correctly with dynamic offsets
+- [ ] A standard MIDI file imports with recognizable track/channel assignment
+
+## Dependencies
+
+**Needs from other splits:** None — fully self-contained in ToooT_IO.  
+**Provides to other splits:** Lossless save/load foundation that 03-ui-coherence's "Save Project" UI depends on.

03-ui-coherence/spec.md

@@ -0,0 +1,104 @@
+# Spec: 03-ui-coherence
+
+**Project:** ProjectToooT — macOS 2026 Native DAW  
+**Module:** ToooT_UI + ProjectToooTApp  
+**Track:** Main (largest split — start immediately, runs alongside 01 and 02)
+
+## Goal
+
+Stabilize and integrate all ToooT_UI views into a coherent, fully functional DAW workspace. Every major view must open, render correctly, respond to user input, and stay wired to the engine. No crashes on view switch. WWDC target: full DAW feature parity in a single session.
+
+## Background
+
+See `requirements.md` §5 (User Experience & Interface), `memory/project_status.md` §Working Features and §Stubs.
+
+Interview finding: "broken UI" is all views simultaneously — Metal grid, Piano Roll, Envelope Editor, Automation, Spatial Visualizer. This is an integration coherence problem, not isolated component bugs.
+
+## What to Build
+
+Work through these views in priority order (each must be stable before moving to the next):
+
+### 1. TrackerWorkspace Layout
+- Window management: persistent layout state across launches
+- Navigation between views (pattern grid ↔ piano roll ↔ envelope ↔ automation ↔ spatial) without state loss
+- Toolbar / transport controls always visible and functional
+
+### 2. Metal Pattern Grid
+- Verify 120Hz ProMotion via `MTKView` (not timer-based redraws — use display link)
+- GPU-instanced cell rendering: thousands of cells, minimal CPU overhead
+- Arrow navigation, note entry (Z–M keyboard layout), Cmd+C/V row copy-paste, Cmd+D duplicate — all must work
+- Playhead animation must read **only** from `sharedState.playheadPosition` (L25) — never derive from `samplesProcessed`
+
+### 3. Piano Roll
+- Drag-to-paint note entry: erase mode on existing notes, paint mode on empty space
+- Multi-touch trackpad support
+- Visual velocity feedback per note
+- Stable undo/redo integration (50 levels)
+
+### 4. Envelope Editor
+- Volume / pan / pitch envelope types
+- Drag existing points, click background to add, right-click to delete
+- Points must bind bidirectionally to engine envelope state
+
+### 5. Automation Editor
+- Draggable Bezier curves for all automatable parameters
+- Implemented via SwiftUI `Canvas` + `DragGesture`
+- Binds to `EngineSharedState` parameter slots
+
+### 6. Spatial Visualizer
+- 3D source positioning via drag
+- **Bidirectional:** dragging in UI must update `SpatialManager` / PHASE in real-time
+- `SpatialManager` position changes (e.g., from automation) must reflect in UI
+
+### 7. Mixer
+- Real-time level meters wired to render output (read from `EngineSharedState` snapshot)
+- AUv3 insert rack visible: Stereo Wide + Pro Reverb slots
+
+### 8. Video Sync
+- `ScreenCaptureKit` feed displayed
+- Sequencer playhead hard-synced to video playback position (`AVFoundation` timecode)
+
+## UI/UX Philosophy (Apple Silicon Performance)
+
+- **Metal-first rendering:** Pattern grid and any timeline component must use Metal (`MTKView`) — no CoreGraphics fallback in hot paths
+- **ProMotion-adaptive:** Tie render loop to `CADisplayLink` / `MTKView` preferred frame rate (120Hz on ProMotion displays, graceful fallback)
+- **One atomic bridge:** `EngineSharedState` is the only legal read path from UI to engine — take a snapshot per frame, never dereference live audio-thread pointers from `@MainActor` code
+- **SwiftUI for controls, Metal for grids:** SwiftUI `Canvas` + gestures for Automation Bezier; Metal instanced rendering for the tracker grid and piano roll keys
+- **Playhead as truth:** All animations derive from `sharedState.playheadPosition` (L25) — a `Float` written by the render block as `Float(row) + Float(tick)/Float(ticksPerRow)`
+
+## Critical Rules (Must Not Violate)
+
+| Rule | Source |
+|---|---|
+| Never write UI-owned BPM/tempo to engine during playback | L21 |
+| Playhead position = `sharedState.playheadPosition` only | L25 |
+| Tremolo/vibrato: transient display values only, never stored in view model | L24 |
+| All `@MainActor` UI must use `EngineSharedState` snapshot — no direct audio struct access | Swift 6 |
+| StereoWide reads both channels from a scratch copy before computing newL/newR | L23 |
+
+## Constraints
+
+- **Swift 6 strict concurrency** — all UI code must be `@MainActor`; no `@unchecked Sendable`
+- **No timer-based redraws** — use display link or `onChange` driven by `EngineSharedState` published snapshot
+- **Undo/Redo must survive view switches** — 50-level stack must not be scoped to a single view
+
+## Success Criteria
+
+- [ ] All 8 views open without crashing
+- [ ] Metal grid renders at 120Hz; playhead animates smoothly during playback
+- [ ] Piano Roll: paint/erase notes, undo/redo works
+- [ ] Envelope Editor: add/move/delete points, changes persist
+- [ ] Automation: Bezier curves draggable, bound to engine params
+- [ ] Spatial Visualizer: drag source → PHASE position updates in real-time
+- [ ] Mixer: meters move during playback; AUv3 rack visible
+- [ ] Video Sync: playhead tracks video timecode
+- [ ] No Swift 6 concurrency warnings in ToooT_UI module
+
+## Dependencies
+
+**Needs from other splits:**  
+- `EngineSharedState` snapshot API (stable after 01-audio-engine-perf, but can work against current version)  
+- Lossless save/load (02-io-save-load) for "Save Project" menu item  
+
+**Provides to other splits:**  
+- Stable `TrackerWorkspace` scaffold that 04-neural-ane-acceleration's synthesis UI slots into

04-neural-ane-acceleration/spec.md

@@ -0,0 +1,67 @@
+# Spec: 04-neural-ane-acceleration
+
+**Project:** ProjectToooT — macOS 2026 Native DAW  
+**Module:** ToooT_Core (synthesis) + ToooT_UI (synthesis panel)  
+**Track:** Parallel C (independent of UI coherence work)
+
+## Goal
+
+Accelerate the 6 working neural synthesis modules onto the Apple Neural Engine (ANE) and polish their UI integration. The modules already produce correct audio — this split is about performance acceleration and WWDC-quality presentation of the unique synthesis tiers.
+
+## Background
+
+See `requirements.md` §7 (Neural Engine & Algorithmic Synthesis) and `memory/project_status.md` §Working Features.
+
+Interview finding: all 6 neural synthesis modules (BASSLINE, HARMONY, DRUMS, MARKOV MELODY, L-SYSTEM, SYNTH) are already functional. This is not ground-up implementation — it is ANE offloading, Markov cross-fade implementation, and synthesis tier UI.
+
+The three synthesis tiers are brand identity — do not simplify or homogenize them:
+- **Carbon Tier:** electromagnetic interference, shorted logic gates, data corruption textures
+- **Biological Tier:** vocal fry, throat resonances, skeletal percussion, cardiac arrhythmia
+- **Xenomorph Tier:** fractal noise, cellular automata, "Void Screech" and "Quantum Foam"
+
+## What to Build
+
+### Task A: ANE Profiling and Offloading
+- Profile each of the 6 modules: identify which synthesis computation paths are ANE-suitable (matrix ops, convolution, inference)
+- Convert suitable paths to CoreML models or use `MLCompute` for ANE dispatch
+- **Critical constraint:** ANE inference must be fully async — results feed back into the synthesis pipeline without blocking or touching the audio render thread
+- Measure latency introduced by ANE round-trip; ensure it does not exceed one audio buffer period
+
+### Task B: Markov Layer Cross-Fades
+- Implement Markov chain state transitions between synthesis tiers
+- Cross-fades driven by real-time `algSeed` data (read atomically from `EngineSharedState`)
+- Transition smoothness: `vDSP_vrampmul` for gain ramping during tier cross-fade (prevents clicks, per requirements §2)
+- State machine must be RT-safe: all `algSeed` reads are atomic; no locking on the audio thread
+
+### Task C: Synthesis Tier UI Panel
+- Expose tier selection (Carbon / Biological / Xenomorph) in the synthesis panel within `TrackerWorkspace`
+- Real-time parameter display: show current `algSeed` value and active Markov state
+- Tier-specific parameter controls atoootpriate to each tier's character (e.g., "corruption intensity" for Carbon, "arrhythmia rate" for Biological)
+- UI writes to synthesis parameters must go through `EngineSharedState` atomic bridge (not direct struct mutation)
+
+## Constraints
+
+- **ANE inference is async only** — never block the audio render thread waiting for ANE output
+- **algSeed reads must be Atomic** — `EngineSharedState.algSeed` accessed with `Atomic<T>` (Synchronization framework)
+- **Tier identity must be preserved** — do not normalize, soften, or simplify the Carbon/Biological/Xenomorph textures to make them "safer"
+- **Output feeds UnifiedSampleBank pipeline** — synthesis output format must be compatible with the existing sample bank PCM path
+- **Swift 6 strict concurrency** — synthesis UI panel follows same `@MainActor` rules as all other ToooT_UI code
+- **Minimum macOS 16** — required for latest ANE access via CoreML and Synchronization framework
+
+## Success Criteria
+
+- [ ] At least 2 of 6 modules have ANE-accelerated paths with measurable latency reduction
+- [ ] Markov cross-fades trigger correctly on `algSeed` change, no clicks or pops
+- [ ] Tier selection UI functional: switch between Carbon / Biological / Xenomorph live
+- [ ] ANE latency ≤ 1 audio buffer period (measured, not assumed)
+- [ ] All existing UAT suites still pass (synthesis changes must not break tracker audio)
+- [ ] No Swift 6 concurrency warnings in synthesis code paths
+
+## Dependencies
+
+**Needs from other splits:**  
+- `UnifiedSampleBank` API (stable in current build — no dependency on other splits)  
+- `TrackerWorkspace` scaffold for the synthesis UI panel (from 03-ui-coherence, but can stub during development)  
+
+**Provides to other splits:**  
+- ANE-accelerated synthesis modules ready for 05-platform-hardening to validate under 24-hour load