# Reference: pitfalls and patterns

## Scene template

```ts
type Scene = {
  id: string;
  title: string;
  meaning: string;
  params: Params;
};
```

## Animation sketch

```ts
const e = smoothstep((now - t0) / duration);
param = lerp(start, target, e);
field = compute(param);
draw(field);
```

Snap to exact targets when the animation finishes.

## Robust width

Do not measure FWHM assuming the peak is at the center of the array.

1. Find the peak with `argmax(I)`.
2. Expand the FWHM from that peak.
3. Also compute RMS or encircled-energy diameter.
4. Clamp the display width relative to a natural scale.

Use the same display width for the beam overlay and observation plane.

## Embedding intensity

Prefer a filled silhouette attached to the observation plane. A detached line chart often makes the artifact feel like two unrelated interfaces.

## Common failures

| Failure | Symptom | Fix |
|---|---|---|
| Fake reactivity | Geometry moves while the curve stays frozen | Recompute from the propagator |
| Expert knobs by default | Raw physical parameters dominate the UI | Use named scenes |
| Overlay clutter | Explanatory cards cover the model | Move metrics under the figure |
| Fragile metric | Every scene ends with the same tiny width | Use robust width metrics |
| Chat in the UI | Process commentary appears in the artifact | Rewrite as final copy |

## Validation questions

1. Does the reader learn the idea without seeing raw parameters?
2. Do scene rest states look materially different?
3. Can you point to the computation that drives each visual?
4. Can a stranger understand the artifact without the conversation that produced it?