1# Woodblock Simulator — web app
3Interactive browser port of the physical model in `../woodblock.py` (see `../woodblock.md` for the physics). The full chain runs client-side in a Web Worker: Hunt-Crossley mallet contact, free-free bar modes two-way coupled to a Helmholtz cavity, retarded-monopole radiation to the listener point, and Kaiser-windowed anti-aliased decimation to 48 kHz.
5## Usage
7```
8npm install
9npm run dev # development server
10npm run build # production build in dist/
11npm run selftest # validate the physics port against the Python reference values
12```
14The self-test reproduces the reference diagnostics (partials 1003/2766/5423/8964/13390/18702 Hz, Helmholtz 484 Hz, contact 0.301 ms at 794 N, 109.7 dB SPL) and the four validation listener positions from `woodblock.md` §7.
16## How rendering is tiered
18Changing any parameter triggers a debounced fast preview (oversample 8, 24 radiating elements); the Render button runs the full-quality pass (oversample 16, 48 elements). While the current result is a preview, the Play and Download buttons and the status badge say so. The worker keys its caches by tier: geometry, material, damping, mallet, and cavity parameters invalidate the modal solve; listener and slit positions and block height only re-run radiation; pre-delay, normalization, and bit depth only re-run the output stage. Small LRU caches mean that moving the microphone after a full render reuses the cached solve and returns a full-quality result in a fraction of a second.
20The Loop button repeats the strike continuously, swapping in each new render as parameters change, so edits are audible without pressing Play. Parameters persist in localStorage; "Reset to defaults" restores the values from `woodblock.py`.
22## Layout
24- `src/params.ts` — parameter schema, defaults, tier assignment, persistence
25- `src/physics/` — basis, RK4 solver, radiation, decimation (straight ports of the Python)
26- `src/worker/renderWorker.ts` — off-thread rendering with tiered caching
27- `src/components/` — 3D scene (three.js), parameter panel, plots (waveform, spectrum, spectrogram, contact force, animated mode shapes)