[Guide] Build a Music Playlist App (Render Effects as Documentation) - implementation notes

Recording lastEffect + lastReason made debugging so much easier.

Player bugs are often "why did it do that" bugs, and this gives you a real answer.

We implemented the effect-log posture with a named render effect and a bounded log size:

tsx
useRenderEffect('player:record', () => {
  const entry = { effect: 'player:record', reason: player.debug.lastReason, at: Date.now(), payload: { trackId: player.trackId, state: player.state } };
  vault.write('effectsLog', [...vault.read('effectsLog'), entry].slice(-50));
  return `${entry.effect}:${entry.reason}`;
});

Returning the string made it feel like documentation, not just side effects.

Counterpoint: effect logs can become noise if you record everything.

We only record identity changes (track change, play/pause, seek) and ignore low-level churn.

Player truth in a vault made sense because it survives route changes (list -> detail -> overlay).

Route state owned only motion keys (panel/overlay/cadence).

We stored a derived nowPlayingLabel and it prevented drift between the player chrome and the queue list.

Otherwise each panel formats the label slightly differently and it looks like a bug.

For "why did track change", we used a small intent object and stored it as evidence:

ts
type TrackReason = { type: 'user'; action: 'click' | 'skip' } | { type: 'auto'; action: 'advance' | 'repeat' };
vault.write('player', { ...vault.read('player'), debug: { ...vault.read('player').debug, lastReason: JSON.stringify(reason) } });

It doesn't have to be perfect; it just has to be coherent.

Multi-truth inputs were crucial for search overlay typing.

If every keystroke becomes vault truth, the player UI starts feeling laggy under load.

A misunderstanding I had: I thought this guide was anti-effect.

It's pro-effect, but only if the effect is named and the behavior is reflected back into UI evidence.

Counterpoint: "render effects" can be abused to justify doing real work in render.

We limited render effects to evidence/logging and kept actual writes in explicit mutation paths.

Docs tie-in: this fits the same theme as the effect docs and debugging docs: make behavior visible.

Related: Testing and Debugging and API Reference.

We stored a derived queue bundle and it made skipping tracks deterministic.

If the queue is derived live in render, the player and queue can disagree under refresh.

We also rendered data-player-state and data-now-playing in the shell.

It's ugly, but it made screenshots useful in bug reports.

One thing that helped: treat playlistId changes as identity boundaries and remount the player surface.

Otherwise position/track state leaks across playlists.

The guide's panel/overlay motion keys are a good example of keeping URLs calm while still having a lot of UI motion.

It's a good pattern for media apps in general.

We capped the effects log to avoid memory growth and we included a derived effectsLogVersion string.

That made it easier to correlate changes across deployments.

The best part is that it turns effect behavior into something you can test.

Tests can assert on data-last-reason instead of trying to observe timing indirectly.

Counterpoint: if your player integration is real audio, you'll need more escape hatches and the log might lie.

We still found the evidence posture helpful even when the underlying system was messy.

We kept search overlay query in a local doc and only committed selected tracks into the vault on action.

That kept typing fast and made writes explicit.

If you try this pattern, start by choosing your evidence keys (state, track, last reason).

Once you can see those, most player bugs become normal bugs.

Effect logs are only useful if they're readable. Treat them like user-facing copy, not like debug spam.

The phrase "render effects as documentation" sounded like a joke until I tried it. It's basically a discipline for making effects legible.

We used a derived queueHash evidence key so we could tell if queue changed between screenshots.

It made it easier to debug "skip" bugs.

The guide is a good antidote to "effects are forbidden" takes. Effects are fine when they're named and observable.

This thread convinced me the real product is an explainable player, not just a working player.