# SYNAPSE GENESIS Tutorial v2.0.0

Professional reference for building audiovisual single-file experiences in the style of `synapse_genesis-v1_0_7.html`.

## Source Files

- Original analyzed source: `webgpu/synapse_genesis-v1_0_7.html`
- Cleaned implementation template: `webgpu/webgpu-synapse-genesis-v2_0_0.html`

## Important Clarification

The project folder is named `webgpu`, but the source implementation is currently **Three.js + WebGL** (not native WebGPU API). The architecture is still valid and professional for browser realtime audiovisual work.

---

## Table of Contents

1. Design Intent and Experience Model
2. Full Architecture Map
3. Layer 1: UI and Visual Identity (CSS + DOM)
4. Layer 2: Render Pipeline (Three.js + PostFX)
5. Layer 3: Audio Engine (Web Audio + Analyzer)
6. Layer 4: Content/Asset Generation
7. Layer 5: State Machine (Acts)
8. Layer 6: Timeline/Frame Loop
9. Audio-Reactivity Mapping Strategy
10. Known Issues in v1_0_7 and Professional Fixes
11. Build Workflow for New Versions
12. Reusable Coding Standards
13. Production Checklist
14. Extension Roadmap

---

## 1. Design Intent and Experience Model

This style works because it behaves like a small "show engine", not a random animation.

Core design principles:

- One dominant visual motif (hero object)
- Multiple supporting motifs (grid, symbols, particles)
- Audio signal drives key motion and intensity
- A timeline introduces act-to-act variation
- HUD overlays provide narrative and operator-style feedback
- Start overlay satisfies browser audio policy and creates a cinematic entry

In short: this is real-time stagecraft logic in one HTML file.

---

## 2. Full Architecture Map

Use this exact layering model in future files:

1. **Theme layer**: CSS variables, fonts, contrast, scanlines
2. **UI layer**: overlay, button, flash planes, HUD
3. **Module layer**: import map for Three.js and addons
4. **Audio layer**: synth + analyzer + normalized outputs
5. **Render layer**: scene/camera/renderer/composer
6. **Asset layer**: shader mesh + text planes + particles
7. **State layer**: `ACTS[]` profile table
8. **Timeline layer**: main `update()` loop
9. **Lifecycle layer**: start event + resize event

Primary references in source:

- `webgpu/synapse_genesis-v1_0_7.html:11`
- `webgpu/synapse_genesis-v1_0_7.html:53`
- `webgpu/synapse_genesis-v1_0_7.html:94`
- `webgpu/synapse_genesis-v1_0_7.html:140`
- `webgpu/synapse_genesis-v1_0_7.html:190`
- `webgpu/synapse_genesis-v1_0_7.html:224`

---

## 3. Layer 1: UI and Visual Identity (CSS + DOM)

### Why this layer matters

If the UI shell is weak, even good 3D looks unfinished. This source uses a strong retro-futurist language:

- accent color token (`--accent`)
- high-contrast black/cyan baseline
- geometric start button with clipped shape
- scanline overlay for CRT texture
- HUD in fixed corners with consistent spacing

References:

- `webgpu/synapse_genesis-v1_0_7.html:11`
- `webgpu/synapse_genesis-v1_0_7.html:21`
- `webgpu/synapse_genesis-v1_0_7.html:30`
- `webgpu/synapse_genesis-v1_0_7.html:49`

### Professional pattern

- Keep 3D on `<canvas>` only.
- Keep textual telemetry in DOM.
- Connect both worlds through CSS variables changed by JS (`--accent`).

This gives fast iteration and clean separation of concerns.

---

## 4. Layer 2: Render Pipeline (Three.js + PostFX)

### Base setup

The visual engine starts with:

- `Scene`
- `PerspectiveCamera`
- `WebGLRenderer`
- `EffectComposer`
- `RenderPass`
- `UnrealBloomPass`
- `GlitchPass`

References:

- `webgpu/synapse_genesis-v1_0_7.html:141`
- `webgpu/synapse_genesis-v1_0_7.html:147`
- `webgpu/synapse_genesis-v1_0_7.html:149`
- `webgpu/synapse_genesis-v1_0_7.html:151`

### Why this works

- `RenderPass` gives baseline scene image
- `Bloom` amplifies emissive/electric feel
- `Glitch` is event-driven, not constant, so it reads as impact

### Professional upgrade used in v2

In `webgpu/webgpu-synapse-genesis-v2_0_0.html`, postFX and camera updates are more stable and parameterized by act profiles and audio signals.

---

## 5. Layer 3: Audio Engine (Web Audio + Analyzer)

### Architecture in v1

The class `DivergentAudio` constructs:

- `AudioContext`
- `AnalyserNode`
- `GainNode` master
- frequency buffer via `Uint8Array`

Reference:

- `webgpu/synapse_genesis-v1_0_7.html:94`
- `webgpu/synapse_genesis-v1_0_7.html:97`
- `webgpu/synapse_genesis-v1_0_7.html:99`
- `webgpu/synapse_genesis-v1_0_7.html:102`

### Signal extraction

`getLevels()` maps bins to rough bands:

- bass: low bin
- mid: middle bin
- high: high bin

Reference:

- `webgpu/synapse_genesis-v1_0_7.html:104`

### Why this pattern is effective

You convert audio to normalized control signals in one place, then feed everything else from those signals.

### Critical bug in v1 and fix

In v1 source:

- `if(i % 1 === 0.5) this.playHat(t);` is logically impossible because `i % 1` is always `0`.

Reference:

- `webgpu/synapse_genesis-v1_0_7.html:115`

Professional fix:

- schedule off-beat with time offset (`t + beat * 0.5`) instead of modulo test on integer loop.

This is implemented in `webgpu/webgpu-synapse-genesis-v2_0_0.html`.

---

## 6. Layer 4: Content/Asset Generation

The source uses procedural assets instead of external media files. This is key to fast iteration.

### 6.1 Hero mesh (shader icosahedron)

- geometry: `IcosahedronGeometry`
- material: custom `ShaderMaterial`
- uniforms: `uTime`, `uBass`, `uColor`
- displacement = trigonometric pattern + audio energy

References:

- `webgpu/synapse_genesis-v1_0_7.html:156`
- `webgpu/synapse_genesis-v1_0_7.html:157`
- `webgpu/synapse_genesis-v1_0_7.html:159`

### 6.2 Symbol planes from canvas text

The file generates kanji textures on `<canvas>`, converts to `CanvasTexture`, applies additive blending.

References:

- `webgpu/synapse_genesis-v1_0_7.html:167`
- `webgpu/synapse_genesis-v1_0_7.html:170`
- `webgpu/synapse_genesis-v1_0_7.html:175`

Why this is professional:

- no external texture pipeline required
- easy per-text or per-font variation
- lightweight and stylized

### 6.3 Particle volume

A large `BufferGeometry` points cloud gives depth/speed context with low complexity.

References:

- `webgpu/synapse_genesis-v1_0_7.html:181`
- `webgpu/synapse_genesis-v1_0_7.html:186`

---

## 7. Layer 5: State Machine (Acts)

The `ACTS` array is the content grammar of the show.

Each act defines:

- name
- color
- fog
- wireframe mode
- camera behavior keyword

References:

- `webgpu/synapse_genesis-v1_0_7.html:190`
- `webgpu/synapse_genesis-v1_0_7.html:191`

`applyAct()` applies act changes atomically:

- HUD labels
- shader color uniform
- wireframe mode
- scene fog and clear color
- CSS accent
- white flash transition

Reference:

- `webgpu/synapse_genesis-v1_0_7.html:203`

Professional takeaway:

Keep scene direction in **data** (`ACTS`), not hardcoded if-chains spread across file.

---

## 8. Layer 6: Timeline/Frame Loop

The runtime loop pattern in source:

1. measure elapsed time
2. get audio levels
3. resolve act index by time
4. update UI telemetry
5. update camera profile
6. update geometry and shader uniforms
7. update postFX
8. render

Reference:

- `webgpu/synapse_genesis-v1_0_7.html:224`

### Camera profile system

This file uses named camera modes:

- `linear`
- `erratic`
- `orbit`
- `zoom`
- `drunk`

References:

- `webgpu/synapse_genesis-v1_0_7.html:240`
- `webgpu/synapse_genesis-v1_0_7.html:242`

This is a good pattern. The camera becomes part of act identity.

### Professional fix for stability

In v1, camera FOV accumulates every frame:

- `camera.fov += bass * 20;`

Reference:

- `webgpu/synapse_genesis-v1_0_7.html:259`

Correct approach (used in v2):

- set a base FOV per camera mode each frame
- add bounded audio modulation
- avoid additive drift

---

## 9. Audio-Reactivity Mapping Strategy

Use consistent mapping so visuals feel intentional.

Recommended map:

- `bass` -> major scale/intensity changes
  - mesh displacement amplitude
  - bloom strength
  - flash triggers
- `mid` -> rotational energy and medium-motion dynamics
- `high` -> fine-grain jitter, text flicker, sparkle behavior

This matches the source update logic:

- `uBass` and shader deformation
- `core.rotation` and grid movement
- kanji opacity/velocity
- bloom and glitch thresholds

References:

- `webgpu/synapse_genesis-v1_0_7.html:263`
- `webgpu/synapse_genesis-v1_0_7.html:268`
- `webgpu/synapse_genesis-v1_0_7.html:278`

---

## 10. Known Issues in v1_0_7 and Professional Fixes

### Issue A: dead hi-hat condition

- source: `webgpu/synapse_genesis-v1_0_7.html:115`
- fix: off-beat scheduling by time offset

### Issue B: camera projection drift

- source: `webgpu/synapse_genesis-v1_0_7.html:259`
- fix: absolute FOV calculation per frame

### Issue C: progress UI can overflow

- source: `webgpu/synapse_genesis-v1_0_7.html:237`
- fix: clamp progress to `[0, 1]`

### Issue D: unused import (`ShaderPass`)

- source: `webgpu/synapse_genesis-v1_0_7.html:90`
- fix: remove unused import unless a custom pass is added

### Issue E: intense random camera motion may cause discomfort

- source: `webgpu/synapse_genesis-v1_0_7.html:246`
- fix: smooth random jitter and cap amplitude

---

## 11. Build Workflow for New Versions

Use this repeatable sequence for each new HTML release:

1. Duplicate last stable version to a new filename.
2. Freeze constants at top (`DURATION`, `ACT_INTERVAL`, counts).
3. Adjust or add one new visual motif only.
4. Extend `ACTS` data and `applyAct()` behavior.
5. Validate audio scheduling first.
6. Validate camera stability second.
7. Validate responsive resize and HUD readability.
8. Profile FPS and reduce heavy counts if needed.

This avoids large, chaotic regressions.

---

## 12. Reusable Coding Standards

### Naming

- Use explicit engine names: `audio`, `updateScene`, `applyAct`, `updateHud`.
- Keep constants uppercase.
- Keep act descriptors simple and composable.

### Organization

- Keep one high-level section per concern.
- Keep per-frame logic in small helper functions.
- Keep mutation centralized in update/apply functions.

### Safety

- clamp UI outputs
- avoid unbounded additive state mutation
- avoid random spikes without limits

### Performance

- keep particle counts reasonable
- avoid per-frame allocations
- precompute static textures/canvases once
- cap DPR where needed for mobile

---

## 13. Production Checklist

Before publishing a new version, verify:

1. Start button unlocks audio in all target browsers.
2. No console errors/warnings.
3. Camera FOV remains bounded after 5+ minutes.
4. Progress and signal values remain in valid range.
5. Resize preserves framing and postFX resolution.
6. HUD remains legible on mobile and desktop.
7. Particle counts and bloom strength do not collapse FPS.
8. File naming/versioning is consistent.

---

## 14. Extension Roadmap

Recommended next upgrades:

1. Add a deterministic beat clock and event bus.
2. Add noise/simplex field for smoother motion than pure random jitter.
3. Add act-specific shader branches (chromatic splits, rim-light variants).
4. Move ACT profiles to external JSON to separate content from engine.
5. Add a lightweight debug panel (hideable) for live tuning.
6. Add recorder/export mode for promo clips.

---

## Final Notes

For current production work, use this as the stable reference:

- `webgpu/webgpu-synapse-genesis-v2_0_0.html`

It keeps the style language of v1 while correcting critical runtime and scheduling issues.