# Adding an experiment

How this repo is organised and the steps to add a new generative-visual
experiment so it shows up in the gallery.

## Structure

```
index.html              gallery — lists every experiment (newest first)
experiments/
  rd-v1a.html           one self-contained WebGL2 file per experiment
  rd-v1b.html
  rd-v1c.html
assets/thumbs/
  rd-v1a.png            gallery thumbnail per experiment (portrait 9:16)
ref/                    shared reference imagery
specs.md                output spec (1080×1920, 25fps, 10s, …)
EXPERIMENTS.md          this file
```

**Rules of the road**

- `main` is the single source of truth: it holds the gallery + every experiment.
- Each experiment is **one self-contained HTML file** — all HTML/CSS/GLSL/JS
  inline, no build step, no external assets. It must run by just opening the
  file in a browser (`file://`).
- Each experiment is developed on its **own branch** named after it
  (`rd/v1a`, `rd/v1b`, …), then merged to `main`.
- Naming: branch `rd/vNx` → file `experiments/rd-vNx.html` → thumbnail
  `assets/thumbs/rd-vNx.png`.

## Steps to add one

1. **Branch from main**

   ```
   git checkout main
   git checkout -b rd/v1d          # next id in the series
   ```

2. **Create the experiment file** by copying the closest existing one:

   ```
   cp experiments/rd-v1c.html experiments/rd-v1d.html
   ```

   Update the `<title>` and the in-file identifier (search/replace the old
   `rd/vNx` label). Tunable parameters live in the `CONFIG` block at the top of
   the file; the live control panel reads them. Build your variant.

3. **Preview** by opening `experiments/rd-v1d.html` in a browser. Use the
   panel's **Copy CONFIG** button to capture values you like and paste them back
   into the `CONFIG` block to make them the defaults.

4. **Make a thumbnail** — a filled, representative frame (portrait 9:16), saved
   to `assets/thumbs/rd-v1d.png`. Easiest: open the file, hide the panel
   (press `h`), let it fill, and screenshot the canvas. Keep it modest in size
   (~480 px wide is plenty).

5. **Add it to the gallery** — in `index.html`, copy an existing `<a class="card">…</a>`
   block and place it **with its series**: cards are grouped by prefix
   (all `rd/*` together, then `enz/*`, etc.), oldest-first within each group.
   So a new `rd/*` goes after the last `rd/*` card, not at the very end. Update:
   `href` → `experiments/rd-v1d.html`, the thumbnail `url(...)`, the `rd/vNx`
   code, the title, and the description.

6. **Merge to main**

   ```
   git checkout main
   git merge rd/v1d                # experiment file is new => no conflict
   git push origin main
   ```

   Because each experiment is its own file, merges don't conflict. The only
   shared file you touch is `index.html` (the gallery) — keep those edits to the
   single new card block to keep merges clean.

## Conventions

- **Keep it self-contained.** No CDNs, no imports — it must work offline from
  `file://` and be trivial to hand off for frame/video export later.
- **Match the output spec** (`specs.md`): the canvas backing buffer is
  1080×1920; scale to the viewport with CSS.
- **Leave the CONFIG block + control panel intact** so each piece stays tunable.