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/BUILD.md         |  1 +
 doc/HEADLESS_MODE.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/HOWTO.md         | 13 ++++++++++++
 3 files changed, 72 insertions(+)
 create mode 100644 doc/HEADLESS_MODE.md

(limited to 'doc')

diff --git a/doc/BUILD.md b/doc/BUILD.md
index 7cb3473..cd2b436 100644
--- a/doc/BUILD.md
+++ b/doc/BUILD.md
@@ -24,6 +24,7 @@ cmake --build build_final -j4
 | SIZE_OPT | `-DDEMO_SIZE_OPT=ON` | Size-optimized, with checks |
 | STRIP_ALL | `-DDEMO_STRIP_ALL=ON` | Release candidate, full error checking, no debug features (~64k target) |
 | FINAL_STRIP | `-DDEMO_FINAL_STRIP=ON` | Final release, no error checking, absolute minimum size |
+| HEADLESS | `-DDEMO_HEADLESS=ON` | Testing without GPU (audio/timeline work, no rendering) |
 | STRIP_EXTERNAL_LIBS | `-DDEMO_STRIP_EXTERNAL_LIBS=ON` | Size measurement only (binary won't run) |
 
 **Build Hierarchy:**
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.
diff --git a/doc/HOWTO.md b/doc/HOWTO.md
index 97c7df7..fccfa1e 100644
--- a/doc/HOWTO.md
+++ b/doc/HOWTO.md
@@ -45,6 +45,19 @@ cmake -B build -DDEMO_BUILD_TESTS=ON -DDEMO_BUILD_TOOLS=ON
 cmake --build build -j4
 ```
 
+### Headless Testing
+```bash
+# Build without GPU
+cmake -B build_headless -DDEMO_HEADLESS=ON
+cmake --build build_headless -j4
+
+# Run simulation (30s default)
+./build_headless/demo64k --headless
+
+# Custom duration
+./build_headless/demo64k --headless --duration 60
+```
+
 ### Size Measurement
 ```bash
 ./scripts/measure_size.sh
-- 
cgit v1.2.3