1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
# File Hierarchy Cleanup - February 13, 2026
## Summary
Comprehensive reorganization of project file structure for improved maintainability and code reuse.
---
## Changes Implemented
### 1. Application Entry Points → `src/app/`
**Before:**
```
src/
main.cc
stub_main.cc
test_demo.cc
```
**After:**
```
src/app/
main.cc
stub_main.cc
test_demo.cc
```
**Impact:** Cleaner src/ directory, separates application code from libraries.
---
### 2. Workspace Reorganization
**Before:**
```
workspaces/main/
assets/music/*.spec
shaders/*.wgsl
obj/*.obj
assets/
demo.seq
music.track
originals/
common/
final/
```
**After:**
```
workspaces/{main,test}/
music/ # Audio samples (.spec)
weights/ # CNN binary weights (.bin)
obj/ # 3D models (.obj)
shaders/ # Workspace-specific WGSL only
common/
shaders/ # Shared WGSL utilities
math/
render/
compute/
tools/
originals/ # Source audio files
test_demo.seq
test_demo.track
```
**Removed:**
- `assets/` directory (legacy structure)
- `assets/common/` (replaced by `common/`)
- `assets/final/` (superseded by workspaces)
- `assets/originals/` → `tools/originals/`
---
### 3. Shared Shader System
**Problem:** 36 duplicate shader files across workspaces (byte-identical).
**Solution:** Implemented Option 1 from `SHADER_REUSE_INVESTIGATION.md`.
**Structure:**
```
common/shaders/
common_uniforms.wgsl
lighting.wgsl
passthrough.wgsl
ray_box.wgsl
ray_triangle.wgsl
sdf_primitives.wgsl
skybox.wgsl
math/
common_utils.wgsl
noise.wgsl
sdf_shapes.wgsl
sdf_utils.wgsl
render/
lighting_utils.wgsl
scene_query_bvh.wgsl
scene_query_linear.wgsl
shadows.wgsl
compute/
gen_blend.wgsl
gen_grid.wgsl
gen_mask.wgsl
gen_noise.wgsl
gen_perlin.wgsl
```
**Reference in assets.txt:**
```
SHADER_COMMON_UNIFORMS, NONE, ../../common/shaders/common_uniforms.wgsl
SHADER_MATH_NOISE, NONE, ../../common/shaders/math/noise.wgsl
```
**Asset Packer Enhancement:**
- Added `#include <filesystem>` for path normalization
- Implemented `lexically_normal()` to resolve `../../common/` references
- Cross-platform path handling for workspace-relative includes
---
## Updated Files
### Configuration
- `workspaces/main/workspace.cfg` - Updated asset_dirs and shader_dirs
- `workspaces/test/workspace.cfg` - Updated asset_dirs and shader_dirs
- `workspaces/main/assets.txt` - Common shader references
- `workspaces/test/assets.txt` - Common shader references
### Build System
- `cmake/DemoExecutables.cmake` - src/app/ paths, test_demo paths
- `cmake/DemoCodegen.cmake` - Removed legacy fallback paths
- `cmake/Validation.cmake` - Workspace shader paths
### Tools
- `tools/asset_packer.cc` - Filesystem path normalization
- `scripts/gen_spectrograms.sh` - tools/originals/ paths
- `scripts/train_cnn_v2_full.sh` - workspaces/main/weights/ paths
- `training/export_cnn_v2_weights.py` - workspaces/main/weights/ paths
### Application
- `src/app/main.cc` - Hot-reload workspace paths
---
## Metrics
**File Reduction:**
- Removed 36 duplicate shader files
- Deleted legacy assets/ structure (~70 files)
- Net: ~100 files eliminated
**Disk Space:**
- Common shaders: 20 files
- Per-workspace shaders: ~30-35 files
- Saved: ~36 shader duplicates
**Workspace Structure:**
```
workspaces/main/: 31 shaders (workspace-specific)
workspaces/test/: 19 shaders (workspace-specific)
common/: 20 shaders (shared)
Total unique: 70 shaders (vs 106 before)
```
---
## Benefits
1. **Single Source of Truth:** Common shaders in one location
2. **No Duplication:** Bug fixes apply everywhere automatically
3. **Clear Separation:** Common vs workspace-specific code
4. **Size Optimization:** Important for 64k target
5. **Maintainability:** Easier to understand and modify
6. **Workspace Isolation:** Each workspace still self-contained for specific content
---
## Migration Notes
**For New Workspaces:**
1. Create `workspaces/new_workspace/` with subdirs: `music/`, `weights/`, `obj/`, `shaders/`
2. Reference common shaders: `../../common/shaders/...`
3. Add workspace-specific shaders to local `shaders/`
4. Update `workspace.cfg`: `asset_dirs = ["music/", "weights/", "obj/"]`
**For Common Shader Changes:**
- Edit files in `common/shaders/`
- Changes apply to all workspaces immediately
- Run full build to verify all workspaces
---
## Documentation Updated
- `doc/WORKSPACE_SYSTEM.md` - New structure reflected
- `doc/SHADER_REUSE_INVESTIGATION.md` - Implementation status
- `doc/PROJECT_CONTEXT.md` - Current project state
- `doc/FILE_HIERARCHY_CLEANUP_2026-02-13.md` - This document
|
