# Falling Leaves — `falling-leaves@1.0.0`

Autumn leaves swaying, tipping and turning over as they fall, in maple, oak and birch shapes. Loops perfectly.

Autumn leaves coming down the way real ones do: swaying side to side on a slow pendulum, tipping with each swing, turning over (a leaf seen edge-on thins to a line and shows its darker underside) and drifting a little on the wind. Each leaf is a smooth shape with a midrib and veins, in one of five maple, oak, birch, willow and rounded shapes, in reds, golds and browns (or spring greens). Every leaf falls a whole number of screen heights per loop and every sway and flip makes whole cycles, so the loop is exact. Choose the number of leaves, the colours, the wind, the sky colours and the seed.

- Kind: effect; status: published; digest sha256:e167c29a72699dcfdf4747f901badc6ad0ddfed2d97bab61bdb78882fe1c7b94
- Role: Particle overlay (Canvas 2D): autumn, nature and calm-seasonal atmosphere.
- Implementation: canvas2d; entry `src/falling-leaves.js`
- Files: https://aipixelwizard.com/registry/falling-leaves/1.0.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`, `src/falling-leaves.js`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/falling-leaves/versions/1.0.0
- Runnable demo: https://aipixelwizard.com/registry/falling-leaves/1.0.0/index.html (open over http; it imports sibling packages by relative path)
- Dependencies (exact): `apw-runtime@1.0.0` (demo) — Demo harness. The reusable source has no dependencies.

## Exports
- `createFallingLeaves({ leaves?, palette?, wind?, seed? }) => { draw(ctx, info, width, height) }` — Canvas 2D leaf layer; info.progress (0 to 1 over the loop) sets the place in the loop; draws on top of the canvas.
- `PALETTES: { autumn, spring, gold }` — Leaf face and underside colours.

## Parameters
- `leaves` (integer 10–200, default 60) — Leaves
- `palette` (select one of autumn | spring | gold, default "autumn") — Colours
- `wind` (number 0–1.5, default 0.5) — Wind
- `skyTop` (color, default "#3a2a24") — Sky top
- `skyBottom` (color, default "#c8864a") — Sky bottom
- `seed` (integer 1–999, default 8) — Seed

## Composition
- Inputs: Canvas 2D context, info.progress (0 to 1 over the loop), width, height.
- Outputs: Draws leaves on top of the canvas; does not clear it.
- Coordinates: Leaves are placed in fractions of the canvas; sizes scale with the smaller side; nearer leaves are larger and fall faster.
- Lighting: A soft drop shadow lifts each leaf; the underside is darker.
- Timing: Pure function of info.progress.
- Works with: kinetic-title, gradient-background
- A leaf seen edge-on is drawn as a thin sliver of its underside.

## Output and loop
- 1080×1080, 30 fps, 12 s, procedural
- Seamless loop: yes — Every leaf falls a whole number of screen heights per loop and its sway, flip and spin are whole cycles, so the last frame meets the first.
- Verified 2026-10-08 in Chrome 154.0.8037.97 headless on Linux 7.0.0-38-generic (x64), Node 22.14.0 (Canvas 2D); deterministic: yes; loop check: Frame 0 vs end state (progress 1): mean |Δ| 0.0000, max |Δ| 0 of 255.

## Use it
New project: Create it once, then each frame draw your backdrop and call draw(ctx, { progress }, width, height).

Existing project: Copy src/falling-leaves.js. Call draw on your existing 2D canvas.

Reuse ideas:
- Autumn title: Autumn, warm.
- Spring: Spring greens.
- Harvest: Gold, many.

## Limitations
- Leaves are flat shapes: they turn by squashing, not in true 3D.
- They do not land: they leave the bottom and re-enter at the top.

## License
MIT. Copyright (c) 2026 AI Pixel Wizard. Released under the MIT License. See LICENSE in this folder.

Provenance: Original code written for AI Pixel Wizard in October 2026, to the catalog quality bar (docs/QUALITY.md).