# Specification: Effects Documentation and Demo Script

**Track ID:** effects-docs_20260318
**Type:** Chore
**Created:** 2026-03-18
**Status:** Draft

## Summary

Add user-facing documentation for the 18 new effects (with attribution to pkivolowitz/lifx) and create an example script that runs a specified effect or cycles through all effects, targeting devices by IP or serial. The script detects device type and uses Plasma2D for matrix devices and 1D effects for multizone/single-zone devices. Generate animated GIFs of each effect using the LIFX emulator and Playwright for embedding in documentation.

## Context

lifx-async v5.3.0 ships 18 new FrameEffect-based effects ported from the pkivolowitz/lifx Go library: Cylon, Double Slit, Embers, Fireworks, Jacob's Ladder, Newton's Cradle, Pendulum Wave, Plasma, Plasma2D, Ripple, Rule 30, Rule Trio, Sine, Sonar, Spectrum Sweep, Spin, Twinkle, Wave. The existing effects documentation only covers the original effects. There is no example script that demonstrates the new effects or allows users to cycle through them.

## Acceptance Criteria

- [ ] `docs/getting-started/effects.md` updated to list all 18 new effects with brief descriptions, parameters, device compatibility, and attribution to pkivolowitz/lifx
- [ ] `docs/api/effects.md` updated with API reference for new effect classes
- [ ] `examples/effects_demo.py` created: accepts `--effect <name>` to run one effect or `--cycle` to cycle through all; requires `--ip` or `--serial` to target devices
- [ ] Script detects device type (matrix vs multizone vs single-zone) and selects appropriate effects (Plasma2D for matrix, 1D effects for others)
- [ ] Animated GIFs of each effect captured and embedded in documentation
- [ ] `mkdocs build` succeeds with no warnings on new/modified pages
- [ ] Example script runs successfully against emulated or real devices

## Dependencies

- `src/lifx/effects/registry.py` — effect registry for discovering available effects
- `src/lifx/effects/*.py` — all 18 new effect modules
- Existing docs structure and mkdocs configuration
- lifx-emulator-core — for emulated device visualization
- Playwright MCP server — for screen recording

## Out of Scope

- Modifying the effects library code
- Adding new effects
- Updating the architecture docs (`docs/architecture/effects-architecture.md`)

## Technical Notes

- The example script should use PEP 723 inline metadata (`# /// script`) so it can run with `uv run examples/effects_demo.py` without installing separately
- Use `argparse` for CLI argument parsing (consistent with Python stdlib, no deps needed)
- Use `find_by_ip()` or `find_by_serial()` for device targeting
- Use the effect registry (`get_effect`, `list_effects`) for effect discovery
- Device type detection via `isinstance()` checks (MatrixLight, MultiZoneLight, Light)
- Cycle mode should run each effect for a configurable duration (default ~10s)
- For matrix devices: use Plasma2D and any other matrix-compatible effects
- For multizone/single-zone: use all 1D effects
- Attribution to pkivolowitz/lifx should appear in the documentation with a link to the source repository

---

_Generated by Conductor. Review and edit as needed._
