own-the-canvas 1.0.11 → 2.0.0

package/CHANGELOG.md

@@ -2,6 +2,69 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.0.0] - 2026-11-01
+
+The big one: 18 new Living Scenes, effects that react to your page's elements, a production-safe runtime, color by default, and a redrawn catalog. 11 components are removed; see the README's "Upgrading from 1.x" for replacements.
+
+### Added
+
+- 10 more scene components: `SnowDrift`, `FrostGlass`, `OrigamiCranes`, `SeasonsTree`, `InkMountains`, `WindowRain`, `IncenseSmoke`, `MoonlitSea`, `CloudSea`, `Ferrofluid`. `SnowDrift`, `FrostGlass`, `OrigamiCranes`, and `SeasonsTree` support `collide`.
+- 8 new nature components, all on the shared runtime: `IvyGrowth`, `Fireflies`, `Dandelion`, `GrassField`, `Moths`, `SunbeamDust`, `PaperLanterns`, `KelpForest`. Each tracks the cursor at window level, so it reacts even when used as a background under other content. `IvyGrowth`, `Fireflies`, `Dandelion`, and `PaperLanterns` support `collide` with `data-otc-solid` elements.
+- DOM-aware effects: `SakuraBlossom` gains `overlay`, `collide`, `restitution`, and `zIndex`. With `collide`, petals land on elements marked `data-otc-solid`, rest there (following the element on scroll), and slide off with the wind. `data-otc-solid="live"` re-reads sticky/animated elements every frame.
+- Shared canvas runtime under `SakuraBlossom`: pauses offscreen and in background tabs, honors `prefers-reduced-motion` (one static frame), adapts particle budget to frame rate, caps DPR at 2.
+
+### Improved
+
+- `Fireworks` is a full show over a city skyline: rockets climb on spark trails and burst as one of six shell types (peony, chrysanthemum, willow, ring, palm, crossette), stars leave glowing streaks, gold willows glitter, and each burst lights the sky. Clicking now sends the shell to the clicked height. Motion is frame-rate independent. New default palette swaps violet for gold.
+- `BubbleUniverse` bubbles look like soap film (clear centres, swirling rainbow rims, window reflections and glints) over a soft bokeh background, and drift upward instead of piling on the floor. `gravity` is now a pull against buoyancy: below 0.03 bubbles rise.
+- `Rain` is a rainy night street: three depth layers of rain in a gusting wind, mist, street lamps mirrored on wet asphalt, ripples and spray, and lightning flashes when the rain is heavy. New default palette (blue night).
+- `Metaballs` are lit as glossy 3D lava-lamp wax with a hot core, highlights and rim glow, and move with a rising and sinking convection drift. New default colour (orange).
+- `SandSimulation` pours itself (new `autoPour`, default true): three drifting streams build banded dunes, and the floor drains when the pile gets high. Grains keep a stable colour with lit surfaces and depth shading instead of re-randomising every frame.
+- `CrystalGrowth` grows vector snowflakes (faceted ice prisms with mirrored dendrites, a sectored centre plate, glow and twinkling tips) instead of a pixel blob; finished flakes melt and regrow. `cellSize` now sets branch thickness.
+- `PendulaWave` draws a real harmonograph onto a persistent ink layer that fills the canvas, with a glowing pen and soft glow. New default palette (amber shading into teal).
+- `AntColony` places food at the start so trails form right away, draws real ants (with walking legs and carried crumbs), an anthill, berry piles and a soil floor; food trails glow. New default palette (fire ants on soil, green trails).
+- `NeuralWeb` draws neurons (glowing body, nucleus, dendrites) joined by curved axons; signals run as comets and set off cascades of firing. New default palette (cyan and amber).
+- `ParticleField` gets soft glowing particles with depth, two-tone colour, lines that brighten as particles close in, and the cursor joining the constellation. New default palette (ice blue).
+- `LSystem` grows plants with tapered bark-to-green branches, leaves and blossoms at the tips, wind sway, a grassy mound and drifting petals; flat fractals get a colour gradient.
+- `MagneticField` adds an iron-filings texture, red-to-blue field lines, glowing current flowing from N to S, and shaded metal poles. `animated` now defaults to true (it drives the current). Default poles are red N and blue S.
+- `ReactionDiffusion` is lit as a glossy relief, with shaded slopes and specular ridges.
+- `FireEffect` renders smooth licking flames instead of per-pixel static: a noise-driven heat field on a coarse grid, upscaled with smoothing, plus a glow layer and rising sparks. Same props; `resolution` now sets the grid cell size.
+- `Kaleidoscope` is a real kaleidoscope: coloured glass shards and beads tumble in one wedge that is mirrored around the centre and fills the canvas edge to edge, instead of blurry noise inside a disc. New default palette (amber and teal). `noiseScale` now sets how many shards there are.
+- `DeepSeaBioluminescence` draws translucent pulsing jellyfish at different depths (glowing bells, rim lights, ruffled oral arms, trailing tentacles) with marine snow and light shafts; moving the cursor stirs up luminous sparks and makes nearby plankton and jellyfish flash. New default palette (cyan and teal).
+- `SpiderWeb` is a real orb web: an irregular frame bridged to the edges, radii, and one continuous scalloped capture spiral that shimmers in the moonlight, with dew beads and an orb-weaver spider that walks to where you disturb the web. `ringCount` is now the number of spiral turns.
+- `DragonCursor` is redrawn as a solid, glowing dragon instead of a wireframe skeleton: tapered scaled body with a glowing rim, dorsal spines, legs, membrane wings with veins, a horned head with glowing slit-pupil eyes and whiskers, and additive fire. New default palette (emerald body, amber eyes, orange flame) and `wingSpan` default 80. Props and presets are unchanged.
+- `TornadoVortex`, `SolarFlare`, `BlackHole`, `NoiseGradient`, `Boids`, and `WatercolorBloom` are rebuilt for much better visuals and moved onto the shared runtime (pause offscreen, reduced motion, frame-rate independent, adaptive quality). Props and presets are unchanged.
+  - TornadoVortex: curved rope funnel of orbiting condensation streaks under a rotating wall cloud; dust skirt, flung debris, lightning that lights the cloud.
+  - SolarFlare: granulated photosphere with limb darkening and sunspots, corona streamers, plasma flowing along magnetic loops, eruptions whose plasma falls back.
+  - BlackHole: Interstellar-style shadow, photon ring, Doppler-beamed disk, lensed far side of the disk, gravitationally lensed stars and grid.
+  - NoiseGradient: domain-warped flowing gradient (no more stretched streaks), dithered against banding, pixel budget capped for full-screen use.
+  - Boids: field of view, variable speed, panic that ripples through the flock, flapping/banking bird silhouettes with depth; spatial grid for large flocks.
+  - WatercolorBloom: layered translucent washes from recursive polygon deformation, wet-edge pigment, paper grain.
+
+### Fixed
+
+- Docs site: smooth scrolling kept the first page's height as its scroll limit, so Introduction and Installation couldn't be scrolled to the bottom after navigating from another page.
+- Cursor-following effects no longer chase the cursor outside their canvas (regression from 1.0.12, which moved their `mousemove` listener to `window`). They still react through foreground content stacked on the canvas; anywhere else on the page they behave as if the cursor left. `DragonCursor` wanders autonomously, `BlackHole` drifts back to center, `TornadoVortex` wanders, the rest drop their cursor interaction, and a `ParticleField` drag ends when it leaves the canvas.
+
+- npm package: published type declarations no longer include test and Storybook files, and now include the shared runtime types that component declarations import (strict `skipLibCheck: false` setups resolved them as missing).
+
+### Removed (breaking)
+
+- `Shockwave`, `Lissajous`, `MagneticBlob`, `Wormhole`, `ClothSimulation`, `GlitchOverlay`, `PixelDissolve`, `AudioVisualizer`, `TerrainMesh`, `ParticleText`, and `InkBleed` are removed, along with their exported types (`LissajousColorMode`, `VisualizerMode`, `DissolveDirection`, and so on). Closest replacements: `PendulaWave` for Lissajous curves (its harmonograph draws the same figures), `Metaballs` for MagneticBlob, `Starfield` with `perspective="3D"` for Wormhole.
+
+### Changed
+
+- **Components default to color instead of monochrome (visual breaking change).** With no `preset`, each component now renders in its signature palette: the colors of a natural preset (`KoiPond` uses `koi`, `FlowField` uses `ocean`, `Fireworks` uses `celebration`, `FireEffect` uses `inferno`, and so on). Only colors change; counts, speeds, and physics are untouched. `MatrixRain` defaults to classic `#00ff41`, `Confetti` to the `colorful` palette, `LSystem` to green branches. To keep the old look, pass `preset="monochrome"`, which every preset-driven component now accepts. Explicit color props still win over any preset.
+- Docs site: playgrounds open on the colorful default and list `monochrome` as a preset; the site is redesigned as a paper-cut diorama: cream sheets with hand-cut edges on a kraft desk, stacked colored under-sheets, washi-tape labels, layered-hill banners, and a terracotta accent instead of black.
+- React 19 is now a supported peer dependency (`^18.0.0 || ^19.0.0`).
+- `SakuraBlossom` motion is time-based. It looks identical at 60Hz and no longer runs 2x fast on 120Hz displays.
+
+## [1.0.12] - 2026-09-16
+
+### Fixed
+
+- 19 components with ambient (non-click-gated) cursor-follow effects — BlackHole, Boids, BubbleUniverse, ButterflySwarm, ClothSimulation, DeepSeaBioluminescence, DragonCursor, FlowField, FluidSimulation, GalaxySpiral, KoiPond, MagneticBlob, NeuralWeb, ParticleField, ParticleText, SlimeMold, SpiderWeb, TornadoVortex, Wormhole — now respond to the cursor when used as a background layer with foreground content stacked on top. Previously the `mousemove` listener was bound to the canvas itself, which browsers never dispatch to when something else is on top; it's now bound to `window`.
+
 ## [1.0.0] - 2026-05-17
 
 ### Added

package/README.md

@@ -4,7 +4,7 @@
 
 # own-the-canvas
 
-**50+ canvas-based React visual components. Zero dependencies. TypeScript.**
+**60 canvas-based React visual components. Zero dependencies. TypeScript.**
 
 [![npm version](https://img.shields.io/npm/v/own-the-canvas?style=flat-square&color=555555)](https://www.npmjs.com/package/own-the-canvas)
 [![license](https://img.shields.io/npm/l/own-the-canvas?style=flat-square&color=555555)](LICENSE)
@@ -16,6 +16,18 @@
 
 ---
 
+## What's New in 2.0
+
+- **18 Living Scenes:** nature effects with real models underneath, from ivy that grows along your headline to fireflies that flash in sync and a moonlit sea that glitters where the waves catch the moon.
+- **Effects that know your page:** mark any element with `data-otc-solid` and petals, snow, seeds, leaves, fireflies, and paper cranes land on it, and ivy climbs it.
+- **Color by default:** every component opens in its signature palette. Pass `preset="monochrome"` for the 1.x look.
+- **Production-safe runtime:** effects pause offscreen and in background tabs, respect `prefers-reduced-motion`, and run at the same speed on 60Hz and 120Hz screens.
+- **Rebuilt classics:** DragonCursor, Fireworks, Rain, BlackHole, TornadoVortex, SolarFlare, Boids, and more were redrawn from scratch with the same props.
+
+Upgrading from 1.x? See [Upgrading from 1.x](#upgrading-from-1x).
+
+---
+
 ## Install
 
 ```bash
@@ -26,7 +38,7 @@ pnpm add own-the-canvas
 yarn add own-the-canvas
 ```
 
-> **Peer deps:** React 18+
+> **Peer deps:** React 18 or 19
 
 ---
 
@@ -35,7 +47,7 @@ yarn add own-the-canvas
 Every component fills its parent container by default. Drop it in and it works.
 
 ```tsx
-import { DragonCursor, MatrixRain, ParticleText } from "own-the-canvas";
+import { MatrixRain } from "own-the-canvas";
 
 export default function App() {
   return (
@@ -50,13 +62,67 @@ All components accept a `preset` prop for instant themed defaults — override a
 
 ---
 
+## Effects That Know Your Page
+
+Mark any element with `data-otc-solid` and effects collide with it. Petals land on your headline, rest on your buttons, and slide off the edges in the wind. Resting petals stay attached when the page scrolls.
+
+```tsx
+import { SakuraBlossom } from "own-the-canvas";
+
+<SakuraBlossom overlay collide preset="sakura" />
+
+<h1 data-otc-solid>Ship faster</h1>
+<button data-otc-solid>Get started</button>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `overlay` | `boolean` | `false` | Fixed full-viewport layer over the page, click-through, transparent background |
+| `collide` | `boolean` | `false` | Collide with `[data-otc-solid]` elements |
+| `restitution` | `number` | `0` | `0` = rest and slide off, `> 0` = bounce |
+| `zIndex` | `number` | `10` | Overlay stacking order |
+
+Use `data-otc-solid="live"` for sticky or animated elements so their position is re-read every frame.
+
+What each DOM-aware effect does with marked elements:
+
+| Component | With `collide` |
+| --- | --- |
+| `SakuraBlossom` | Petals land, rest, and slide off in the wind |
+| `IvyGrowth` | Vines climb each element's sides and grow across its top |
+| `Fireflies` | Fireflies perch on top edges and blink there |
+| `Dandelion` | Blown seeds parachute down and settle on elements |
+| `PaperLanterns` | Clicking a marked element releases a lantern from it |
+| `SnowDrift` | Snow piles up on top edges and spills off the sides |
+| `FrostGlass` | Frost nucleates on element edges and grows outward |
+| `OrigamiCranes` | Paper cranes land and rest with wings folded |
+| `SeasonsTree` | Falling autumn leaves and petals settle on elements |
+
+Rain and Confetti are next.
+
+---
+
+## Production-Safe by Default
+
+Runtime-based components (SakuraBlossom, the 18 Living Scenes below, and the rebuilt TornadoVortex, SolarFlare, BlackHole, NoiseGradient, Boids, and WatercolorBloom) get these behaviors with no setup:
+
+- **Pause offscreen:** zero work while scrolled out of view.
+- **Pause in background tabs:** resumes without a burst of catch-up motion.
+- **Respects `prefers-reduced-motion`:** renders one still frame and stops.
+- **Adaptive quality:** particle budget drops when frames run slow and recovers when they don't.
+- **Same speed on every display:** motion is time-based, so 120Hz screens don't run 2x fast.
+- **DPR capped at 2:** sharp on retina without 3x-density cost on phones.
+- **SSR-safe:** overlay canvases mount on the client only.
+
+---
+
 ## Featured Components
 
 ### DragonCursor
 
 A sinuous dragon body that trails your cursor in real time. Segments, wings, optional fire breath, and a background star field with optional per-star glow halos — all configurable.
 
-**Presets:** `default · emerald · inferno · void · ice`
+**Presets:** `default · emerald · inferno · void · ice · monochrome`
 
 ```tsx
 import { DragonCursor } from "own-the-canvas";
@@ -67,8 +133,8 @@ import { DragonCursor } from "own-the-canvas";
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `segmentCount` | `number` | `20` | Body segment count |
-| `bodyColor` | `string` | `"#ffffff"` | Dragon body color |
-| `wingSpan` | `number` | `60` | Wing span in px |
+| `bodyColor` | `string` | `"#35e0a1"` | Dragon body color |
+| `wingSpan` | `number` | `80` | Wing span in px |
 | `showFire` | `boolean` | `false` | Enable fire breath |
 | `followSpeed` | `number` | `0.15` | Cursor follow lerp speed |
 | `starCount` | `number` | `60` | Number of background stars |
@@ -82,7 +148,7 @@ import { DragonCursor } from "own-the-canvas";
 
 Falling character rain — katakana, latin, or binary. Per-column trail fade, variable speed, neon green or any color.
 
-**Presets:** `default · cyberpunk · binary · minimal · blood`
+**Presets:** `default · cyberpunk · binary · minimal · blood · monochrome`
 
 ```tsx
 import { MatrixRain } from "own-the-canvas";
@@ -92,7 +158,7 @@ import { MatrixRain } from "own-the-canvas";
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `color` | `string` | `"#ffffff"` | Character color |
+| `color` | `string` | `"#00ff41"` | Character color |
 | `charset` | `"latin" \| "binary" \| "katakana" \| string` | `"latin"` | Character set |
 | `fontSize` | `number` | `14` | Font size in px |
 | `speed` | `number` | `33` | Ms per frame — lower = faster |
@@ -104,7 +170,7 @@ import { MatrixRain } from "own-the-canvas";
 
 Living koi pond on canvas — fish navigate with organic steering, ripple on hover, lily pads float, caustic light dances.
 
-**Presets:** `default · koi · night · lotus · neon`
+**Presets:** `default · koi · night · lotus · neon · monochrome`
 
 ```tsx
 import { KoiPond } from "own-the-canvas";
@@ -115,7 +181,7 @@ import { KoiPond } from "own-the-canvas";
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `fishCount` | `number` | `6` | Number of koi fish |
-| `fishColor` | `string` | `"#ffffff"` | Fish body color |
+| `fishColor` | `string` | `"#ff6030"` | Fish body color |
 | `showLilies` | `boolean` | `true` | Render floating lily pads |
 | `caustics` | `boolean` | `true` | Caustic light shimmer |
 | `interactive` | `boolean` | `true` | React to mouse movement |
@@ -126,7 +192,7 @@ import { KoiPond } from "own-the-canvas";
 
 Real-time Navier-Stokes fluid solver. Move your mouse to inject velocity and ink — auto-bursts fire at intervals for continuous motion.
 
-**Presets:** `default · ink · neon · lava · ocean · smoke`
+**Presets:** `default · ink · neon · lava · ocean · smoke · monochrome`
 
 ```tsx
 import { FluidSimulation } from "own-the-canvas";
@@ -141,7 +207,7 @@ import { FluidSimulation } from "own-the-canvas";
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `resolution` | `number` | `128` | Grid resolution 32–128 |
-| `inkColors` | `string[]` | monochrome | Ink colors |
+| `inkColors` | `string[]` | `["#0c4a6e", "#0891B2", "#06b6d4", "#67e8f9"]` | Ink colors |
 | `viscosity` | `number` | `0.0001` | Fluid viscosity |
 | `autoInk` | `boolean` | `true` | Auto-inject ink bursts |
 | `mouseForce` | `number` | `5` | Mouse velocity force multiplier |
@@ -168,44 +234,18 @@ import { FlowField } from "own-the-canvas";
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `particleCount` | `number` | `800` | Number of flow particles |
-| `colors` | `string[]` | monochrome | Particle stroke colors |
+| `colors` | `string[]` | `["#0c4a6e", "#0891B2", "#06b6d4", "#67e8f9", "#e0f2fe"]` | Particle stroke colors |
 | `noiseScale` | `number` | `0.004` | Noise scale — lower = larger structures |
 | `curl` | `boolean` | `false` | Add curl noise for swirling flow |
 | `speed` | `number` | `1` | Flow speed multiplier |
 
 ---
 
-### GlitchOverlay
-
-Digital glitch effect with RGB channel separation, CRT scanlines, block-slice artifacts, and film noise. Designed as an absolute-positioned overlay — zero configuration required.
-
-**Presets:** `default · crt · cyberpunk · subtle · corrupt`
-
-```tsx
-import { GlitchOverlay } from "own-the-canvas";
-
-<div style={{ position: "relative" }}>
-  <YourContent />
-  <GlitchOverlay preset="cyberpunk" intensity={0.8} rgbShift={12} />
-</div>
-```
-
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `intensity` | `number` | `0.6` | Glitch probability 0–1 |
-| `rgbShift` | `number` | `8` | RGB color shift in px |
-| `rgbShiftColor` | `string` | `"#ff0000"` | RGB split primary color — complement used for opposing channel |
-| `scanlines` | `boolean` | `true` | CRT scanline overlay |
-| `blockGlitch` | `boolean` | `true` | Block-slice glitch artifacts |
-| `flickerRate` | `number` | `0.02` | Screen flicker rate 0–1 |
-
----
-
 ### BubbleUniverse
 
 Physics-based soap bubbles that float, collide, merge on contact, and pop on click. Iridescent shimmer and glow included.
 
-**Presets:** `default · soap · neon · deep · minimal`
+**Presets:** `default · soap · neon · deep · minimal · monochrome`
 
 ```tsx
 import { BubbleUniverse } from "own-the-canvas";
@@ -227,7 +267,7 @@ import { BubbleUniverse } from "own-the-canvas";
 
 Falling rain streaks with sinusoidal wind drift, splash particles on ground impact, and a background star field with optional glow halos. Great as a layered overlay.
 
-**Presets:** `default · storm · drizzle · neon · golden`
+**Presets:** `default · storm · drizzle · neon · golden · monochrome`
 
 ```tsx
 import { Rain } from "own-the-canvas";
@@ -240,7 +280,7 @@ import { Rain } from "own-the-canvas";
 | `dropCount` | `number` | `200` | Number of rain drops |
 | `speed` | `number` | `15` | Drop fall speed px/frame |
 | `wind` | `number` | `0.3` | Horizontal wind drift |
-| `dropColor` | `string` | `"#000000"` | Drop stroke color |
+| `dropColor` | `string` | `"#a9c2e8"` | Drop stroke color |
 | `showSplashes` | `boolean` | `true` | Splash particles on impact |
 | `starCount` | `number` | `60` | Number of background stars |
 | `starColor` | `string` | `"#ffffff"` | Star color |
@@ -251,9 +291,9 @@ import { Rain } from "own-the-canvas";
 
 ### FireEffect
 
-Pixel-level cellular automaton fire. Heat seeds at the bottom row, rises with cooling and wind drift, maps to a palette. Five color themes.
+Licking flame tongues from a smooth noise-driven heat field, with a soft glow and sparks rising off the top. Five colour palettes, wind, and flame height controls.
 
-**Presets:** `default · inferno · toxic · ice · plasma`
+**Presets:** `default · inferno · toxic · ice · plasma · monochrome`
 
 ```tsx
 import { FireEffect } from "own-the-canvas";
@@ -263,7 +303,7 @@ import { FireEffect } from "own-the-canvas";
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `palette` | `"smoke" \| "inferno" \| "toxic" \| "ice" \| "plasma"` | `"smoke"` | Color theme |
+| `palette` | `"smoke" \| "inferno" \| "toxic" \| "ice" \| "plasma"` | `"inferno"` | Color theme |
 | `customColors` | `string[]` | `undefined` | Custom gradient — overrides palette when ≥2 colors |
 | `intensity` | `number` | `0.95` | Flame intensity 0–1 |
 | `windStrength` | `number` | `0.3` | Horizontal wind -1 to 1 |
@@ -272,35 +312,6 @@ import { FireEffect } from "own-the-canvas";
 
 ---
 
-### ParticleText
-
-Text rendered from thousands of particles — each springs to its position in the letterform. Mouse cursor repels them; they reform when it leaves.
-
-**Presets:** `default · neon · fire · frost · gold · minimal`
-
-```tsx
-import { ParticleText } from "own-the-canvas";
-
-<ParticleText
-  text="HELLO"
-  preset="neon"
-  fontSize={140}
-  repelRadius={100}
-  repelForce={8}
-/>
-```
-
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `text` | `string` | `"hello"` | Text to render as particles |
-| `fontSize` | `number` | `120` | Font size in px |
-| `color` | `string` | `"#ffffff"` | Particle color |
-| `repelRadius` | `number` | `80` | Mouse repulsion radius in px |
-| `repelForce` | `number` | `5` | Mouse repulsion force |
-| `snapSpeed` | `number` | `0.12` | Spring constant for snap-to-target |
-
----
-
 ## Base Props
 
 Every component accepts these props:
@@ -311,15 +322,23 @@ Every component accepts these props:
 | `height` | `number \| string` | `"100%"` | Container height |
 | `className` | `string` | — | CSS class on wrapper `<div>` |
 | `style` | `React.CSSProperties` | — | Inline styles on wrapper `<div>` |
-| `preset` | `string` | `"default"` | Named preset — sets themed defaults |
+| `preset` | `string` | `"default"` | Named preset that sets themed defaults. `"monochrome"` gives the 1.x grayscale look |
 
 All components use `forwardRef` — the ref is forwarded to the underlying `<canvas>` element.
 
 ---
 
-## 42 More Components
+## Living Scenes
+
+Nature effects with real models underneath, built for hero sections:
+
+> IvyGrowth (space colonization) · Fireflies (pulse-coupled sync) · Dandelion (pappus drag) · GrassField (spring blades) · Moths (transverse orientation) · SunbeamDust (Tyndall-lit dust) · PaperLanterns (buoyancy and depth) · KelpForest (anchored rope dynamics) · SnowDrift (angle-of-repose drifts) · FrostGlass (60° ice dendrites) · OrigamiCranes (faceted 3D paper) · SeasonsTree (kinematic tree, four seasons) · InkMountains (sumi-e ridgelines) · WindowRain (refracting drops on fogged glass) · IncenseSmoke (laminar-to-turbulent plume) · MoonlitSea (moon-path glitter) · CloudSea (sunlit cloud deck) · Ferrofluid (Rosensweig spikes)
+
+---
+
+## 34 More Components
 
-> Starfield · Fireworks · Boids · SlimeMold · GameOfLife · Kaleidoscope · ReactionDiffusion · AuroraBorealis · Spirograph · Lightning · ClothSimulation · VoronoiCells · NeuralWeb · Metaballs · AntColony · Wormhole · Mandala · MagneticBlob · WatercolorBloom · InkBleed · CrystalGrowth · SandSimulation · WaveInterference · LSystem · Lissajous · PendulaWave · DiffusionAggregation · TerrainMesh · MagneticField · Spotlight · Shockwave · Confetti · RippleEffect · NoiseGradient · PixelDissolve · AudioVisualizer · ParticleField · LiveChart · GalaxySpiral · SolarFlare · TornadoVortex · SakuraBlossom
+> AntColony · AuroraBorealis · BlackHole · Boids · ButterflySwarm · Confetti · CrystalGrowth · DeepSeaBioluminescence · DiffusionAggregation · Fireworks · GalaxySpiral · GameOfLife · Kaleidoscope · LSystem · Lightning · MagneticField · Mandala · Metaballs · NeuralWeb · NoiseGradient · ParticleField · PendulaWave · ReactionDiffusion · SakuraBlossom · SandSimulation · SlimeMold · SolarFlare · SpiderWeb · Spirograph · Starfield · TornadoVortex · VoronoiCells · WatercolorBloom · WaveInterference
 
 Full docs, live previews, and interactive playground:
 
@@ -327,6 +346,23 @@ Full docs, live previews, and interactive playground:
 
 ---
 
+## Upgrading from 1.x
+
+2.0 removes 11 components and changes default colors. Everything else keeps its props.
+
+| Removed in 2.0 | Use instead |
+| --- | --- |
+| `Lissajous` | `PendulaWave` (its harmonograph draws the same figures) |
+| `MagneticBlob` | `Metaballs` |
+| `Wormhole` | `Starfield` with `perspective="3D"` |
+| `Shockwave`, `ClothSimulation`, `GlitchOverlay`, `PixelDissolve`, `AudioVisualizer`, `TerrainMesh`, `ParticleText`, `InkBleed` | No direct replacement. Stay on 1.0.12 if you need them |
+
+**Default colors changed.** With no `preset`, components now render in color. To keep the 1.x look, pass `preset="monochrome"`. Explicit color props still override any preset.
+
+**Cursor effects stay inside their canvas.** Effects that follow the cursor now ignore it when it's outside their canvas, instead of chasing it across the page.
+
+---
+
 ## License
 
 MIT

package/lib/components/AntColony/AntColony.d.ts

@@ -1,6 +1,6 @@
 import { BaseCanvasProps } from '../../types';
 
-type AntColonyPreset = "default" | "neon" | "desert" | "jungle" | "minimal" | "swarm";
+type AntColonyPreset = "default" | "neon" | "desert" | "jungle" | "minimal" | "swarm" | "monochrome";
 export interface AntColonyProps extends BaseCanvasProps {
     /** Number of ants (default: 150) */
     antCount?: number;
@@ -18,15 +18,15 @@ export interface AntColonyProps extends BaseCanvasProps {
     sensorDistance?: number;
     /** Max turn per frame in radians (default: 0.3) */
     turnSpeed?: number;
-    /** Ant dot color (default: "#ffffff") */
+    /** Ant dot color (default: "#d9693a") */
     antColor?: string;
-    /** Pheromone trail color (default: "#6b7280") */
+    /** Pheromone trail color (default: "#6fdc8c") */
     pheromoneColor?: string;
-    /** Food source color (default: "#4ade80") */
+    /** Food source color (default: "#f5c242") */
     foodColor?: string;
-    /** Nest color (default: "#f59e0b") */
+    /** Nest color (default: "#9a6a3a") */
     nestColor?: string;
-    /** Canvas background (default: "#111111") */
+    /** Canvas background (default: "#1a140d") */
     backgroundColor?: string;
     /** Pheromone grid resolution (default: 0.5) */
     resolution?: number;

package/lib/components/AntColony/useAntColony.d.ts

@@ -19,4 +19,10 @@ export interface UseAntColonyOptions {
     interactive: boolean;
     maxFood: number;
 }
+/**
+ * Ant colony foraging. Ants leave the anthill, wander, and lay a "home" scent; the ones that
+ * find food carry a crumb back while laying a "food" scent, and the others follow it, so
+ * glowing trails form between the hill and each food pile and fade once the pile is gone.
+ * Food is placed at the start and respawns; click to drop more.
+ */
 export declare function useAntColony(canvasRef: RefObject<HTMLCanvasElement | null>, options: UseAntColonyOptions): void;

package/lib/components/AuroraBorealis/AuroraBorealis.d.ts

@@ -1,6 +1,6 @@
 import { BaseCanvasProps } from '../../types';
 
-type AuroraBorealisPreset = "default" | "arctic" | "solar" | "tropical" | "neon" | "midnight";
+type AuroraBorealisPreset = "default" | "arctic" | "solar" | "tropical" | "neon" | "midnight" | "monochrome";
 interface AuroraBorealisPresetValues {
     colors?: string[];
     backgroundColor?: string;
@@ -9,7 +9,7 @@ interface AuroraBorealisPresetValues {
 }
 export declare const PRESETS: Record<AuroraBorealisPreset, AuroraBorealisPresetValues>;
 export interface AuroraBorealisProps extends BaseCanvasProps {
-    /** Aurora band colors (default: monochrome whites/grays) */
+    /** Aurora band colors (default: ["#00ff88", "#00ccff", "#88ff00"]) */
     colors?: string[];
     /** Animation speed multiplier (default: 1) */
     speed?: number;
@@ -17,7 +17,7 @@ export interface AuroraBorealisProps extends BaseCanvasProps {
     intensity?: number;
     /** Number of aurora layers (default: 5) */
     layers?: number;
-    /** Sky background color (default: "#111111") */
+    /** Sky background color (default: "#050a0f") */
     backgroundColor?: string;
     /** Wave height as fraction of canvas height (default: 0.15) */
     waveAmplitude?: number;

package/lib/components/BlackHole/BlackHole.d.ts

@@ -1,6 +1,6 @@
 import { BaseCanvasProps } from '../../types';
 
-type BlackHolePreset = "default" | "cosmic" | "inferno" | "neon" | "void";
+type BlackHolePreset = "default" | "cosmic" | "inferno" | "neon" | "void" | "monochrome";
 interface BlackHolePresetValues {
     diskColor?: string;
     backgroundColor?: string;
@@ -12,9 +12,9 @@ interface BlackHolePresetValues {
 }
 export declare const PRESETS: Record<BlackHolePreset, BlackHolePresetValues>;
 export interface BlackHoleProps extends BaseCanvasProps {
-    /** Accretion disk particle color (default: "#ffffff") */
+    /** Accretion disk particle color (default: "#ff6600") */
     diskColor?: string;
-    /** Canvas background (default: "#111111") */
+    /** Canvas background (default: "#0d0200") */
     backgroundColor?: string;
     /** Number of disk particles (default: 300) */
     particleCount?: number;
@@ -24,7 +24,7 @@ export interface BlackHoleProps extends BaseCanvasProps {
     eventHorizonRadius?: number;
     /** Accretion disk radial extent in px (default: 120) */
     diskWidth?: number;
-    /** Polar jet stream color (default: "#6b7280") */
+    /** Polar jet stream color (default: "#ff3300") */
     jetColor?: string;
     /** Show polar particle jets (default: true) */
     showJets?: boolean;

package/lib/components/BlackHole/useBlackHole.d.ts

@@ -1,5 +1,3 @@
-import { RefObject } from 'react';
-
 export interface UseBlackHoleOptions {
     diskColor: string;
     backgroundColor: string;
@@ -17,4 +15,14 @@ export interface UseBlackHoleOptions {
     glowingStars: boolean;
     starGlowBlur: number;
 }
-export declare function useBlackHole(canvasRef: RefObject<HTMLCanvasElement | null>, options: UseBlackHoleOptions): void;
+/**
+ * Relativistic beaming: gas moving toward the viewer is boosted, receding
+ * gas dims. theta = orbital angle, 0 = the side swinging toward us.
+ */
+export declare function doppler(theta: number): number;
+/**
+ * Point-lens deflection of a background point at distance d from the hole:
+ * images are pushed outward by θE²/d. Returns null inside the shadow.
+ */
+export declare function lensOffset(d: number, einstein: number, shadow: number): number | null;
+export declare function useBlackHole(options: UseBlackHoleOptions): import('../../hooks/useCanvasSetup').CanvasSetupResult;

package/lib/components/Boids/Boids.d.ts

@@ -1,6 +1,6 @@
 import { BaseCanvasProps } from '../../types';
 
-type BoidsPreset = "default" | "birds" | "fish" | "swarm" | "neon";
+type BoidsPreset = "default" | "birds" | "fish" | "swarm" | "neon" | "monochrome";
 interface BoidsPresetValues {
     count?: number;
     maxSpeed?: number;
@@ -38,7 +38,7 @@ export interface BoidsProps extends BaseCanvasProps {
     alignmentForce?: number;
     /** Cohesion steering force. (default: 0.03) */
     cohesionForce?: number;
-    /** Boid and trail color. (default: "#7C3AED") */
+    /** Boid and trail color. (default: "#0891B2") */
     color?: string;
     /** Trail history length in frames. (default: 8) */
     trailLength?: number;
@@ -46,7 +46,7 @@ export interface BoidsProps extends BaseCanvasProps {
     trailOpacity?: number;
     /** Boid triangle size in px. (default: 6) */
     boidSize?: number;
-    /** Canvas background color. (default: "#050010") */
+    /** Canvas background color. (default: "#030d1a") */
     backgroundColor?: string;
     /** Boids flee from mouse cursor. (default: true) */
     interactive?: boolean;

package/lib/components/Boids/useBoids.d.ts

@@ -1,5 +1,3 @@
-import { RefObject } from 'react';
-
 export interface UseBoidsOptions {
     count: number;
     maxSpeed: number;
@@ -19,4 +17,25 @@ export interface UseBoidsOptions {
     mouseForce: number;
     wrapEdges: boolean;
 }
-export declare function useBoids(canvasRef: RefObject<HTMLCanvasElement | null>, options: UseBoidsOptions): void;
+export interface Boid {
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+    /** 0.6 (far) .. 1 (near): size, brightness. */
+    z: number;
+    flap: number;
+    bank: number;
+    /** Panic level 0..1; spreads to neighbours (murmuration ripple). */
+    fear: number;
+    wander: number;
+    trail: number[];
+}
+/** Boids only see neighbours within ~270° ahead of them (blind spot behind). */
+export declare function canSee(b: Boid, dx: number, dy: number): boolean;
+/**
+ * Reynolds' three rules over the neighbours in view, plus fear propagation.
+ * Returns the steering acceleration. Pure: no canvas, testable.
+ */
+export declare function steer(b: Boid, neighbours: readonly Boid[], o: UseBoidsOptions): [number, number, number];
+export declare function useBoids(options: UseBoidsOptions): import('../../hooks/useCanvasSetup').CanvasSetupResult;

package/lib/components/BubbleUniverse/BubbleUniverse.d.ts

@@ -1,6 +1,6 @@
 import { BaseCanvasProps } from '../../types';
 
-type BubbleUniversePreset = "default" | "soap" | "neon" | "deep" | "minimal";
+type BubbleUniversePreset = "default" | "soap" | "neon" | "deep" | "minimal" | "monochrome";
 export interface BubbleUniverseProps extends BaseCanvasProps {
     /** Number of simultaneous bubbles (default: 15) */
     bubbleCount?: number;
@@ -8,13 +8,13 @@ export interface BubbleUniverseProps extends BaseCanvasProps {
     minRadius?: number;
     /** Maximum bubble radius in px (default: 50) */
     maxRadius?: number;
-    /** Canvas background (default: "#111111") */
+    /** Canvas background (default: "#050a12") */
     backgroundColor?: string;
     /** Specular highlight color (default: "#ffffff") */
     shimmerColor?: string;
     /** Click to pop bubbles with particle burst (default: true) */
     popEffect?: boolean;
-    /** Downward gravity force (default: 0.02) */
+    /** Pull on the bubbles against their buoyancy; below 0.03 they rise, above it they sink (default: 0.02) */
     gravity?: number;
     /** Velocity friction per frame (default: 0.995) */
     friction?: number;

package/lib/components/ButterflySwarm/ButterflySwarm.d.ts

@@ -1,6 +1,6 @@
 import { BaseCanvasProps } from '../../types';
 
-type ButterflySwarmPreset = "default" | "monarch" | "morpho" | "meadow" | "night";
+type ButterflySwarmPreset = "default" | "monarch" | "morpho" | "meadow" | "night" | "monochrome";
 interface ButterflySwarmPresetValues {
     wingColor?: string;
     patternColor?: string;
@@ -10,11 +10,11 @@ export declare const PRESETS: Record<ButterflySwarmPreset, ButterflySwarmPresetV
 export interface ButterflySwarmProps extends BaseCanvasProps {
     /** Number of butterflies (default: 12) */
     butterflyCount?: number;
-    /** Primary wing color (default: "#f97316") */
+    /** Primary wing color (default: "#e06010") */
     wingColor?: string;
     /** Wing pattern and body color (default: "#111111") */
     patternColor?: string;
-    /** Canvas background (default: "#111111") */
+    /** Canvas background (default: "#0a0800") */
     backgroundColor?: string;
     /** Wing flap speed multiplier (default: 1) */
     flapSpeed?: number;