Marble Computer Binary Adder 3D

You are an expert creative technologist specializing in physics-based interactive visualizations and mechanical computer simulations. Your task is to build a **fully functional 3D mechanical marble adder** that computes binary addition through physical marble logic—no arithmetic shortcuts.

# CONTEXT & INSPIRATION
The machine draws from Wintergatan's Marble Machine and the Digi-Comp II: a beautiful, legible blend of art, engineering, and computation. Users will understand binary addition by watching marbles cascade through flip-flops, flipping toggles and propagating carries exactly as mechanical computers once did.

# TECHNICAL ARCHITECTURE

## Core Constraint: The Mechanism IS the Computer
- **No arithmetic in JavaScript.** The result must emerge from toggle states after marbles finish moving.
- Each bit of the sum is stored in a **two-state flip-flop toggle** (0 or 1) that a marble physically flips as it passes through.
- **Carry propagation:** A marble exiting a toggle in the "overflow" state rolls onward to trigger the next higher bit's toggle.
- Marbles move along **scripted paths** with realistic gravity and timing—no teleportation, no physics engine required.

## File Structure
**Output: One self-contained HTML file.**
- **Three.js:** Import from `https://cdn.jsdelivr.net/npm/[email protected]/build/three.module.js` via an ES module import map.
- **OrbitControls addon:** Import from the same CDN (`addons/controls/OrbitControls.js`).
- **No other libraries, no external assets, no physics engines.**

---

# FUNCTIONAL REQUIREMENTS

## Input Interface
- **Two rows of four switches** each, labelled **A** (top row) and **B** (bottom row), representing 4-bit binary numbers (0–15 decimal).
- Clicking a switch toggles its state (0 ↔ 1) and updates its visual appearance (e.g., lever position, color).
- A **RUN lever** releases marbles corresponding to the set bits. Marbles are spawned and begin their journey down the machine.
- A **marble counter** displays the total number of marbles that have completed their journey.

## Output Interface
- **Five result toggles** (for a 5-bit sum, 0–31 decimal) arranged left-to-right, most significant bit first.
- Each toggle visually shows its state (0 or 1).
- A **readout panel** displays:
  - Binary representation (e.g., `10110`)
  - Decimal value (e.g., `22`)
- The readout updates **only after all marbles have stopped moving**, by reading the toggle states—never from a JavaScript calculation.

## Automation
- A **DEMO button** runs three addition problems in sequence:
  1. `5 + 6`
  2. `9 + 7`
  3. `15 + 15`
- Between each problem, the machine resets (toggles return to 0, marbles disappear, switches update).
- The demo is hands-off, suitable for screen recording without user interaction.

---

# MECHANICAL LOGIC DESIGN

## Marble-Toggle Interaction
- Each toggle is a **flip-flop** that changes state when a marble passes through it.
- **Implementation suggestion:**
  - When a marble reaches a toggle at position *i*:
    - If toggle is `0`, it flips to `1` and the marble is absorbed (carry ends).
    - If toggle is `1`, it flips to `0` and the marble continues to toggle *i+1* (carry propagates).
- This mimics a **full-adder with carry propagation** in hardware.

## Marble Spawning & Routing
- For each `1` bit set in A or B, spawn one marble.
- Marbles enter the least significant bit (LSB) toggle first, then cascade leftward as carries.
- Use **Bézier curves or piecewise linear paths** for marble motion; apply easing functions to simulate gravity (accelerate downward, decelerate on curves).
- **Timing:** Stagger marble releases slightly so the cascade is visible; ensure marbles don't collide.

---

# VISUAL & AESTHETIC DESIGN

## Materials & Lighting
- **Board:** Warm wood texture (oak or walnut), generated procedurally or via Three.js `MeshStandardMaterial` with appropriate roughness and color.
- **Toggles:** Brass or bronze metal, with subtle reflectivity.
- **Marbles:** Glass with refraction (use `MeshPhysicalMaterial` with transparency, `transmission`, and `roughness`).
- **Lighting:** Studio setup with a key light (soft directional), fill light (ambient), and subtle shadows (`THREE.PCFSoftShadowMap`).
- **Aspect ratio:** 1:1 (1080×1080), optimized for square social-media recording.

## Camera Behavior
- **Smooth, slow camera movement** that follows the "action": pans to where marbles are currently moving or toggles are flipping.
- Use `OrbitControls` for manual inspection, but during RUN or DEMO, animate the camera with `TWEEN.js`-style interpolation (or manual lerp) to track the busiest region.
- Camera should frame the entire machine at rest, then zoom/pan during operation.

---

# AUDIO
- **Click sounds** when toggles flip, synthesized via the **Web Audio API** (no external files).
  - Use `OscillatorNode` with a short burst (~50ms) of a sine or triangle wave, frequency ~800–1200 Hz, with an envelope (attack/decay).
- **Audio context starts only after the first user interaction** (click) to comply with browser autoplay policies.

---

# PERFORMANCE & QUALITY
- **60 fps on a standard laptop** (e.g., integrated graphics, mid-tier CPU).
  - Limit polygon count: use instanced meshes for marbles if many are in flight.
  - Optimize shadows: use lower resolution shadow maps if needed.
- **Zero console errors or warnings.**
- Test in Chrome/Edge (Blink) and Firefox.

---

# IMPLEMENTATION CHECKLIST

1. **HTML structure:** Canvas, overlay UI (switches, RUN lever, DEMO button, counter, readout).
2. **Three.js scene:** Board, toggles, marble spawn points, tracks (visual guides optional).
3. **Toggle state management:** Array of five boolean flags, methods to flip and read.
4. **Marble class/system:** Position, path, speed, collision detection with toggles.
5. **Input switches:** Click handlers to set A and B.
6. **RUN logic:** Spawn marbles for each `1` bit, start animation loop.
7. **Carry propagation:** When a marble flips a toggle from `1` to `0`, spawn a new marble targeting the next toggle.
8. **Readout update:** After all marbles settle, read toggle states, display binary and decimal.
9. **DEMO automation:** Sequence the three test cases with resets and delays.
10. **Camera animation:** Lerp position/lookAt during activity.
11. **Audio:** Toggle-flip sound synthesis.
12. **CSS:** Overlay positioning, legible fonts, wood/brass color palette.

---

# DELIVERABLE
{{html-file-content}}

**Output the complete, single-file HTML** (including `<script type="module">` for Three.js, all CSS in `<style>`, all logic inline). The file must be copy-pasteable and run immediately in a browser with no additional setup.

---

# VALIDATION
- Run the DEMO button: verify `5+6=11`, `9+7=16`, `15+15=30` by watching marbles and reading toggles.
- Manually test edge cases: `0+0`, `15+0`, `8+8` (carry into bit 4).
- Confirm smooth 60fps, no flicker, audible clicks, and a beautiful square recording.