1 files changed, 206 insertions, 0 deletions
diff --git a/doc/SIZE_MEASUREMENT.md b/doc/SIZE_MEASUREMENT.md
new file mode 100644
index 0000000..96c8e6c
--- /dev/null
+++ b/doc/SIZE_MEASUREMENT.md
@@ -0,0 +1,206 @@
+# External Library Size Measurement (Task #76)
+
+## Goal
+
+Measure true demo code size by stubbing external library dependencies.
+
+**Motivation:** STRIP_ALL builds (~5MB) include wgpu_native (~3.5MB), GLFW (~500KB), miniaudio. Need to isolate demo code size for 64KB target tracking.
+
+## Strategy
+
+Two-part approach:
+
+### 1. Audio: Use miniaudio's Null Backend
+
+miniaudio has built-in `ma_backend_null` that excludes platform audio drivers:
+
+```cmake
+target_compile_definitions(demo64k PRIVATE
+  MA_ENABLE_ONLY_SPECIFIC_BACKENDS
+  MA_ENABLE_NULL
+)
+```
+
+**Savings:** ~100-200KB (excludes CoreAudio/WASAPI/ALSA/etc.)
+**Benefit:** Audio synthesis still runs, but no driver overhead
+
+### 2. GPU/Platform: Stub Our Own Abstractions
+
+Instead of stubbing ~300 external functions, stub our ~10 platform/gpu wrappers:
+
+**`src/platform/stub_types.h` (STRIP_EXTERNAL_LIBS only):**
+```cpp
+// Minimal WebGPU opaque types
+typedef void* WGPUInstance;
+typedef void* WGPUAdapter;
+typedef void* WGPUDevice;
+typedef void* WGPUBuffer;
+typedef void* WGPUTexture;
+// ... all types as void*
+
+struct WGPUBufferDescriptor {};
+struct WGPUTextureDescriptor {};
+// ... all descriptor structs empty
+```
+
+**`src/platform/stub_platform.cc`:**
+```cpp
+#if defined(STRIP_EXTERNAL_LIBS)
+#include "stub_types.h"
+
+PlatformState platform_init(bool, int w, int h) {
+  return {w, h, nullptr, nullptr};
+}
+
+void platform_poll_events() {}
+bool platform_should_close() { return false; }
+void platform_shutdown() {}
+void platform_present() {}
+double platform_get_time() { return 0.0; }
+#endif
+```
+
+**`src/gpu/stub_gpu.cc`:**
+```cpp
+#if defined(STRIP_EXTERNAL_LIBS)
+WGPUDevice gpu_create_device() { return nullptr; }
+WGPUBuffer gpu_create_buffer(const WGPUBufferDescriptor*) { return nullptr; }
+// ... stub ~20 gpu wrapper functions
+#endif
+```
+
+**Benefits:**
+- Stub our API (~30 functions) vs external APIs (~300 functions)
+- Opaque pointers only (no real struct definitions needed)
+- Don't link wgpu_native or GLFW at all
+- Actually measures demo code, not stub code
+
+## Build System Integration
+
+**CMakeLists.txt:**
+```cmake
+if(DEMO_STRIP_EXTERNAL_LIBS)
+  # Audio: Use null backend
+  target_compile_definitions(demo64k PRIVATE
+    MA_ENABLE_ONLY_SPECIFIC_BACKENDS
+    MA_ENABLE_NULL
+  )
+
+  # GPU/Platform: Use stubs
+  target_compile_definitions(demo64k PRIVATE STRIP_EXTERNAL_LIBS)
+  target_sources(demo64k PRIVATE
+    src/platform/stub_platform.cc
+    src/gpu/stub_gpu.cc
+  )
+
+  # Don't link external libs
+  # (only math/pthread from system)
+
+  # Size measurement flags
+  set(CMAKE_C_FLAGS "-Os")
+  set(CMAKE_CXX_FLAGS "-Os")
+endif()
+```
+
+**Build:**
+```bash
+cmake -S . -B build_size -DDEMO_STRIP_EXTERNAL_LIBS=ON
+cmake --build build_size -j4
+strip build_size/demo64k
+ls -lh build_size/demo64k  # True demo size
+```
+
+## Expected Results
+
+```
+STRIP_ALL build:          5.1 MB
+├── wgpu_native:          3.5 MB
+├── GLFW:                 0.5 MB
+├── miniaudio (full):     0.3 MB
+├── System libs:          0.3 MB
+└── Demo code:            0.5 MB
+
+STRIP_EXTERNAL_LIBS:      0.5 MB
+└── Demo code only:       0.5 MB (100%)
+```
+
+Binary compiles but does NOT run (all I/O stubbed).
+
+## Implementation Plan
+
+### Phase 1: Stub Type Definitions (1 hour)
+
+Create `src/platform/stub_types.h`:
+- Define all WebGPU types as `typedef void*`
+- Define all descriptor structs as empty `struct {}`
+- Include guards for `STRIP_EXTERNAL_LIBS`
+
+### Phase 2: Platform Stubs (1 hour)
+
+Create `src/platform/stub_platform.cc`:
+- Implement ~10 platform functions as no-ops
+- Return dummy PlatformState with reasonable dimensions
+- Compile only when `STRIP_EXTERNAL_LIBS` defined
+
+### Phase 3: GPU Stubs (1 hour)
+
+Create `src/gpu/stub_gpu.cc`:
+- Implement ~20 gpu wrapper functions as no-ops
+- All pointer returns = nullptr
+- All void functions = empty body
+
+### Phase 4: Build Integration (1 hour)
+
+Update `CMakeLists.txt`:
+- Add `DEMO_STRIP_EXTERNAL_LIBS` option
+- Enable ma_backend_null defines
+- Add stub source files conditionally
+- Remove external library linking
+
+### Phase 5: Validation (1 hour)
+
+```bash
+cmake -S . -B build_size -DDEMO_STRIP_EXTERNAL_LIBS=ON
+cmake --build build_size -j4
+strip build_size/demo64k
+size build_size/demo64k
+```
+
+**Estimated time: 5 hours**
+
+## Use Cases
+
+**Weekly size tracking:**
+```bash
+./scripts/measure_size.sh  # Demo=512KB, External=4.5MB
+```
+
+**Subsystem attribution:**
+- GPU effects: 150KB
+- 3D rendering: 120KB
+- Audio synthesis: 100KB
+- Asset system: 80KB
+
+**CI size monitoring:**
+```yaml
+- run: cmake -B build_size -DDEMO_STRIP_EXTERNAL_LIBS=ON
+- run: size build_size/demo64k | tee size_report.txt
+```
+
+## Success Criteria
+
+1. Binary compiles with `STRIP_EXTERNAL_LIBS=ON`
+2. Size < 1MB (confirms external lib isolation)
+3. Repeatable builds
+4. Tracks size changes over time
+
+## Related Files
+
+**New:**
+- `src/platform/stub_types.h` - WebGPU opaque types
+- `src/platform/stub_platform.cc` - Platform stubs (~10 functions)
+- `src/gpu/stub_gpu.cc` - GPU stubs (~20 functions)
+- `scripts/measure_size.sh` - Size measurement script
+
+**Modified:**
+- `CMakeLists.txt` - Add STRIP_EXTERNAL_LIBS mode