From f449fe7f78e059d455dfefcf4b09d763363f6344 Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Mon, 9 Feb 2026 19:34:46 +0100
Subject: feat: Add headless mode for testing without GPU

Implements DEMO_HEADLESS build option for fast iteration cycles:
- Functional GPU/platform stubs (not pure no-ops like STRIP_EXTERNAL_LIBS)
- Audio and timeline systems work normally
- No rendering overhead
- Useful for CI, audio development, timeline validation

Files added:
- doc/HEADLESS_MODE.md - Documentation
- src/gpu/headless_gpu.cc - Validated GPU stubs
- src/platform/headless_platform.cc - Time simulation (60Hz)
- scripts/test_headless.sh - End-to-end test script

Usage:
  cmake -B build_headless -DDEMO_HEADLESS=ON
  cmake --build build_headless -j4
  ./build_headless/demo64k --headless --duration 30

Progress printed every 5s. Compatible with --dump_wav mode.

handoff(Claude): Task #76 follow-up - headless mode complete
---
 doc/HEADLESS_MODE.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 doc/HEADLESS_MODE.md

(limited to 'doc/HEADLESS_MODE.md')

diff --git a/doc/HEADLESS_MODE.md b/doc/HEADLESS_MODE.md
new file mode 100644
index 0000000..35098b1
--- /dev/null
+++ b/doc/HEADLESS_MODE.md
@@ -0,0 +1,58 @@
+// Headless Mode Documentation
+// Workspace: demo (shared across all workspaces)
+
+# Headless Mode
+
+Minimal GPU/platform stubs for testing without graphics.
+
+## Use Cases
+
+- CI/CD without GPU
+- Audio/tracker iteration
+- Timeline validation
+- Fast testing cycles
+
+## Build
+
+```bash
+cmake -B build_headless -DDEMO_HEADLESS=ON
+cmake --build build_headless -j4
+```
+
+Or use the test script:
+```bash
+./scripts/test_headless.sh
+```
+
+## Usage
+
+```bash
+# 30s simulation (default)
+./build_headless/demo64k --headless
+
+# Custom duration
+./build_headless/demo64k --headless --duration 60
+
+# Audio validation
+./build_headless/demo64k --dump_wav test.wav
+```
+
+Progress printed every 5s.
+
+## Implementation
+
+- **GPU stub:** Validates lifecycle, maintains MainSequence
+- **Platform stub:** Simulates 60Hz time progression
+- **Main loop:** Audio updates without rendering
+
+## vs STRIP_EXTERNAL_LIBS
+
+| Feature | HEADLESS | STRIP_EXTERNAL_LIBS |
+|---------|----------|---------------------|
+| Compiles | Yes | Yes |
+| Runs | Yes | No |
+| Audio | Full | No-op |
+| Timeline | Full | No |
+| Tests | Pass | Fail |
+
+See `src/gpu/headless_gpu.cc` and `src/platform/headless_platform.cc` for details.
-- 
cgit v1.2.3