own-the-canvas 2.0.0 → 2.0.2

package/CHANGELOG.md

@@ -2,9 +2,41 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+## [2.0.2] - 2026-11-06
+
+### Added
+
+- 11 new Living Scenes on the shared runtime: `Eye`, `Owl`, `Octopus`, `Hummingbird`, `Candle`, `Cat`, `Jellyfish`, `Snail`, `Sunflowers`, `Komorebi`, `TidePool`. `Owl`, `Octopus`, `Hummingbird`, `Cat`, `Jellyfish`, and `Snail` support `collide`.
+
+### Improved
+
+- `KoiPond` is rebuilt: koi swim on a 12-point spine with a full silhouette, painted patches, flapping pectoral fins and a butterfly tail, each casting a shadow on the pond floor; lily pads have veins and waterlilies and drift on the ripples. Tap to drop food and the koi race to eat it.
+- `AuroraBorealis` draws real curtains: vertical ray striations with a sharp hem fading upward into a second color, brightest where they fold, over a mountain lake that mirrors them. New `interactive` prop (default `true`): the cursor brightens nearby curtains, a tap sets off a substorm.
+- `Starfield` (2D) is a deep-sky vista: a Milky Way band with star clouds, dust lanes and nebulae, three parallax layers of temperature-tinted stars that shift with the cursor, diffraction spikes on bright stars and tapered meteors. 3D warp streaks stars and the cursor steers the vanishing point.
+- `GameOfLife` cells glow: they swell in at birth, cool with age, leave fading embers, and cross-fade between generations under a bloom. Dragging paints life, and a settled board is stirred with gliders.
+- `ReactionDiffusion` lets feed and kill rates drift across the canvas so pattern types coexist and keep morphing; hovering seeds chemical, and a dead field reseeds itself.
+- `FluidSimulation` uses square cells at any aspect ratio, vorticity confinement for crisp eddies, orbiting ink jets so it is never blank, and tone-mapped ink with a relief sheen.
+- `WaveInterference` renders a lit water surface (diffuse plus specular glint) with glowing sources. New `interactive` prop (default `true`): drag sources to move them, and the hovering cursor stirs its own ripples.
+- All seven now run on the shared canvas runtime (pause offscreen, reduced motion, DPR cap, window-level pointer).
+
+### Removed (breaking)
+
+- `DeepSeaBioluminescence` (use `Jellyfish`), `FrostGlass`, and `LSystem`.
+
+## [2.0.1] - 2026-11-01
+
+Docs-only release so the npm page shows the 2.0 README.
+
+### Changed
+
+- README: new cover image (the old one showed the 1.x monochrome look and advertised removed components), a Living Scenes table describing each Living Scene and which react to `data-otc-solid`, updated descriptions for the rebuilt DragonCursor, Rain, and BubbleUniverse, and corrected defaults for `FluidSimulation.resolution` (80) and `FireEffect.spread` (0).
+- `package.json`: normalized `repository.url` (npm warned on publish).
+
 ## [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.
+The big one: 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
 

package/README.md

@@ -4,7 +4,7 @@
 
 # own-the-canvas
 
-**60 canvas-based React visual components. Zero dependencies. TypeScript.**
+**50+ 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)
@@ -18,7 +18,7 @@
 
 ## 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.
+- **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.
@@ -94,7 +94,6 @@ What each DOM-aware effect does with marked elements:
 | `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 |
 
@@ -104,7 +103,7 @@ 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:
+Runtime-based components (SakuraBlossom, the 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.
@@ -120,7 +119,7 @@ Runtime-based components (SakuraBlossom, the 18 Living Scenes below, and the reb
 
 ### 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.
+A glowing dragon that follows your cursor: a tapered, scaled body with dorsal spines, membrane wings, a horned head with glowing eyes, and fire breath. When the cursor leaves the canvas it wanders on its own over a star field.
 
 **Presets:** `default · emerald · inferno · void · ice · monochrome`
 
@@ -168,7 +167,7 @@ import { MatrixRain } from "own-the-canvas";
 
 ### KoiPond
 
-Living koi pond on canvas — fish navigate with organic steering, ripple on hover, lily pads float, caustic light dances.
+A koi pond from above: koi on flexible spines with painted patches, fins and trailing tails cast shadows on the pond floor under drifting caustics, and lily pads (some flowering) float on the ripples. Move the cursor to ripple the water; tap to drop food and the koi race to eat it.
 
 **Presets:** `default · koi · night · lotus · neon · monochrome`
 
@@ -184,13 +183,13 @@ import { KoiPond } from "own-the-canvas";
 | `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 |
+| `interactive` | `boolean` | `true` | Cursor ripples; tap to feed the koi |
 
 ---
 
 ### FluidSimulation
 
-Real-time Navier-Stokes fluid solver. Move your mouse to inject velocity and ink — auto-bursts fire at intervals for continuous motion.
+Ink in water: a stable-fluids solver with vorticity confinement on square cells at any aspect ratio. Three slow ink jets keep it marbling untouched; move the cursor to drag ink and current, tap to blow a ring outward.
 
 **Presets:** `default · ink · neon · lava · ocean · smoke · monochrome`
 
@@ -206,10 +205,10 @@ import { FluidSimulation } from "own-the-canvas";
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `resolution` | `number` | `128` | Grid resolution 32–128 |
+| `resolution` | `number` | `80` | Grid resolution 32–128 |
 | `inkColors` | `string[]` | `["#0c4a6e", "#0891B2", "#06b6d4", "#67e8f9"]` | Ink colors |
 | `viscosity` | `number` | `0.0001` | Fluid viscosity |
-| `autoInk` | `boolean` | `true` | Auto-inject ink bursts |
+| `autoInk` | `boolean` | `true` | Orbiting ink jets plus timed bursts |
 | `mouseForce` | `number` | `5` | Mouse velocity force multiplier |
 
 ---
@@ -243,7 +242,7 @@ import { FlowField } from "own-the-canvas";
 
 ### BubbleUniverse
 
-Physics-based soap bubbles that float, collide, merge on contact, and pop on click. Iridescent shimmer and glow included.
+Soap bubbles with real thin-film color: clear centers, swirling rainbow rims, and window reflections. They drift upward over soft bokeh, merge on contact, and pop on click.
 
 **Presets:** `default · soap · neon · deep · minimal · monochrome`
 
@@ -265,7 +264,7 @@ import { BubbleUniverse } from "own-the-canvas";
 
 ### Rain
 
-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.
+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.
 
 **Presets:** `default · storm · drizzle · neon · golden · monochrome`
 
@@ -308,7 +307,7 @@ import { FireEffect } from "own-the-canvas";
 | `intensity` | `number` | `0.95` | Flame intensity 0–1 |
 | `windStrength` | `number` | `0.3` | Horizontal wind -1 to 1 |
 | `cooling` | `number` | `0.3` | Cooling rate — higher = shorter flames |
-| `spread` | `number` | `0.7` | Flame spread 0–1 |
+| `spread` | `number` | `0` | Flame spread 0–1 |
 
 ---
 
@@ -330,15 +329,33 @@ All components use `forwardRef` — the ref is forwarded to the underlying `<can
 
 ## Living Scenes
 
-Nature effects with real models underneath, built for hero sections:
+Nature effects with real models underneath, built for hero sections. Each one runs on the shared runtime, and the ones marked ✦ react to `data-otc-solid` elements.
 
-> 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)
+| Component | What you see |
+| --- | --- |
+| `IvyGrowth` ✦ | Ivy that grows in real time and climbs the edges of your elements (space colonization) |
+| `Fireflies` ✦ | Fireflies whose flashing slowly falls into sync, perching on your elements |
+| `Dandelion` ✦ | Dandelion clocks you blow apart with the cursor; seeds parachute down on the wind |
+| `GrassField` | Grass on springs that sways in rolling gusts and parts around the cursor |
+| `Moths` | Moths spiraling a lamp by transverse orientation; your cursor is the light |
+| `SunbeamDust` | Window light shafts where dust only glitters inside the beams |
+| `PaperLanterns` ✦ | Sky lanterns rising with depth and flicker; click a button to release one from it |
+| `KelpForest` | Swaying kelp, schooling fish, and surface light; the cursor pushes the water |
+| `SnowDrift` ✦ | Snow that piles up on your headline and buttons, then slides off the edges |
+| `OrigamiCranes` ✦ | Faceted paper cranes in 3D that bank, flap, and land on your elements |
+| `SeasonsTree` ✦ | A swaying tree living through spring, summer, autumn, and winter |
+| `InkMountains` | Ink-wash ridgelines dissolving into drifting mist, with parallax |
+| `WindowRain` | Rain running down a fogged window over blurred city lights; drag to wipe |
+| `IncenseSmoke` | A thread of incense smoke that breaks into curls as it rises |
+| `MoonlitSea` | Night swells with a glittering moon path and cursor ripples |
+| `CloudSea` | A sunset cloud deck seen from above that parts under the cursor |
+| `Ferrofluid` | Glossy ferrofluid that spikes toward the cursor like a magnet |
 
 ---
 
-## 34 More Components
+## More Components
 
-> 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
+> AntColony · AuroraBorealis · BlackHole · Boids · ButterflySwarm · Confetti · CrystalGrowth · DiffusionAggregation · Fireworks · GalaxySpiral · GameOfLife · Kaleidoscope · 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:
 

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

@@ -15,18 +15,20 @@ export interface AuroraBorealisProps extends BaseCanvasProps {
     speed?: number;
     /** Band brightness/opacity 0–1 (default: 0.8) */
     intensity?: number;
-    /** Number of aurora layers (default: 5) */
+    /** Number of aurora curtains (default: 5) */
     layers?: number;
     /** Sky background color (default: "#050a0f") */
     backgroundColor?: string;
-    /** Wave height as fraction of canvas height (default: 0.15) */
+    /** How far the curtains fold, as a fraction of the sky height (default: 0.15) */
     waveAmplitude?: number;
-    /** Wave oscillations across canvas width (default: 2) */
+    /** Folds across the width (default: 2) */
     waveFrequency?: number;
     /** Background star count (default: 80) */
     starCount?: number;
     /** Enable animation (default: true) */
     animated?: boolean;
+    /** The cursor brightens the curtains near it; a tap sets off a substorm surge (default: true) */
+    interactive?: boolean;
     /** Named preset */
     preset?: AuroraBorealisPreset | string;
 }

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

@@ -1,5 +1,3 @@
-import { RefObject } from 'react';
-
 export interface UseAuroraBorealisOptions {
     colors: string[];
     speed: number;
@@ -10,5 +8,18 @@ export interface UseAuroraBorealisOptions {
     waveFrequency: number;
     starCount: number;
     animated: boolean;
+    interactive: boolean;
 }
-export declare function useAuroraBorealis(canvasRef: RefObject<HTMLCanvasElement | null>, options: UseAuroraBorealisOptions): void;
+/**
+ * Curtain light at height `d` above the curtain's lower hem (d < 0 is below it), for a curtain of
+ * ray height `hgt`: a razor-sharp lower edge and a long exponential glow upward, as in real aurora.
+ */
+export declare function curtainProfile(d: number, hgt: number): number;
+/**
+ * Northern lights over a mountain lake. Each layer is a folding curtain of vertical rays: a
+ * sharp bright hem that fades upward into a second color, brighter where the curtain folds back
+ * on itself, rippling slowly along its length. Built in a small light buffer, added onto a
+ * starry sky and mirrored in the lake below. The cursor brightens the curtains near it; a tap
+ * sets off a substorm surge.
+ */
+export declare function useAuroraBorealis(options: UseAuroraBorealisOptions): import('../../hooks/useCanvasSetup').CanvasSetupResult;

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

@@ -11,4 +11,11 @@ export interface UseButterflySwarmOptions {
     interactive: boolean;
     showTrails: boolean;
 }
+/**
+ * A drifting swarm of butterflies. Each one has a forewing and hindwing with dusky roots,
+ * veins, a dark margin and a row of pale spots; the wings fold in perspective as they beat
+ * (fast downstroke, the odd open-winged glide), and the flutter makes the flight bob and
+ * wander. Near butterflies are larger and brighter than far ones. They drift toward a slow
+ * cursor and scatter from a fast one. Soft out-of-focus light fills the background.
+ */
 export declare function useButterflySwarm(canvasRef: RefObject<HTMLCanvasElement | null>, options: UseButterflySwarmOptions): void;

package/lib/components/Candle/Candle.d.ts

@@ -0,0 +1,35 @@
+import { BaseCanvasProps } from '../../types';
+
+type CandlePreset = "default" | "ivory" | "rose" | "obsidian" | "spirit" | "monochrome";
+interface CandlePresetValues {
+    flameColor?: string;
+    coreColor?: string;
+    waxColor?: string;
+    backgroundColor?: string;
+    glowIntensity?: number;
+}
+export declare const PRESETS: Record<CandlePreset, CandlePresetValues>;
+export interface CandleProps extends BaseCanvasProps {
+    /** Outer flame and light color (default: "#ff9a3c") */
+    flameColor?: string;
+    /** White-hot inner flame color (default: "#fff3d1") */
+    coreColor?: string;
+    /** Wax color (default: "#efe2cc") */
+    waxColor?: string;
+    /** Room color; "transparent" keeps only the candle and its light (default: "#0b0705") */
+    backgroundColor?: string;
+    /** Candle scale (default: 1) */
+    size?: number;
+    /** Pillar height, 0.1–1.2 (default: 0.6) */
+    candleHeight?: number;
+    /** How restless the flame is, 0–3 (default: 1) */
+    flicker?: number;
+    /** Strength of the light cast on the room, 0–3 (default: 1) */
+    glowIntensity?: number;
+    /** Cursor drafts bend the flame; click snuffs and relights it (default: true) */
+    interactive?: boolean;
+    /** Named preset: "default" | "ivory" | "rose" | "obsidian" | "spirit" | "monochrome" */
+    preset?: CandlePreset | string;
+}
+export declare const Candle: import('react').ForwardRefExoticComponent<CandleProps & import('react').RefAttributes<HTMLCanvasElement>>;
+export {};

package/lib/components/Candle/index.d.ts

@@ -0,0 +1,2 @@
+export { Candle } from './Candle';
+export type { CandleProps } from './Candle';

package/lib/components/Candle/useCandle.d.ts

@@ -0,0 +1,18 @@
+export interface UseCandleOptions {
+    flameColor: string;
+    coreColor: string;
+    waxColor: string;
+    backgroundColor: string;
+    size: number;
+    candleHeight: number;
+    flicker: number;
+    glowIntensity: number;
+    interactive: boolean;
+}
+/**
+ * A single pillar candle in a dark room. The flame is layered light (halo, body, white-hot
+ * core, blue base) that breathes and flickers, leans into drafts from the cursor with a
+ * springy wobble, and lights the molten pool, the translucent wax and the table around it.
+ * Click to snuff it: the wick smoulders and a thread of smoke curls up, then it relights.
+ */
+export declare function useCandle(options: UseCandleOptions): import('../../hooks/useCanvasSetup').CanvasSetupResult;

package/lib/components/Cat/Cat.d.ts

@@ -0,0 +1,42 @@
+import { BaseCanvasProps } from '../../types';
+
+type CatPreset = "default" | "tuxedo" | "siamese" | "grey" | "midnight" | "monochrome";
+interface CatPresetValues {
+    furColor?: string;
+    stripeColor?: string;
+    bellyColor?: string;
+    eyeColor?: string;
+    cushionColor?: string;
+    backgroundColor?: string;
+}
+export declare const PRESETS: Record<CatPreset, CatPresetValues>;
+export interface CatProps extends BaseCanvasProps {
+    /** Main coat color (default: "#d9822b") */
+    furColor?: string;
+    /** Tabby stripes, tail bands and tail tip (default: "#8f4a16") */
+    stripeColor?: string;
+    /** Chest, muzzle and paws (default: "#f4dcc0") */
+    bellyColor?: string;
+    /** Iris color, seen when it opens an eye (default: "#9cc23a") */
+    eyeColor?: string;
+    /** Cushion color (default: "#7a2f3d") */
+    cushionColor?: string;
+    /** Room color; "transparent" drops the scene (default: "#140f16") */
+    backgroundColor?: string;
+    /** Cat scale (default: 1) */
+    size?: number;
+    /** Ears flick at nearby movement and an eye cracks open to watch the cursor (default: true) */
+    followCursor?: boolean;
+    /** Hover slowly to pet (it purrs and kneads); tap to startle it awake (default: true) */
+    interactive?: boolean;
+    /** Fixed full-viewport, click-through layer over the page (default: false) */
+    overlay?: boolean;
+    /** Nap on top of an element marked `data-otc-solid` instead of a cushion (default: false) */
+    collide?: boolean;
+    /** Overlay z-index (default: 10) */
+    zIndex?: number;
+    /** Named preset: "default" | "tuxedo" | "siamese" | "grey" | "midnight" | "monochrome" */
+    preset?: CatPreset | string;
+}
+export declare const Cat: import('react').ForwardRefExoticComponent<CatProps & import('react').RefAttributes<HTMLCanvasElement>>;
+export {};

package/lib/components/Cat/index.d.ts

@@ -0,0 +1,2 @@
+export { Cat } from './Cat';
+export type { CatProps } from './Cat';

package/lib/components/Cat/useCat.d.ts

@@ -0,0 +1,22 @@
+export interface UseCatOptions {
+    furColor: string;
+    stripeColor: string;
+    bellyColor: string;
+    eyeColor: string;
+    cushionColor: string;
+    backgroundColor: string;
+    size: number;
+    followCursor: boolean;
+    interactive: boolean;
+    overlay: boolean;
+    collide: boolean;
+}
+/** Is (x, y) on the curled body? Body-local units of S, origin at the cat's feet. */
+export declare function onCat(x: number, y: number): boolean;
+/**
+ * A cat asleep, curled nose-to-tail on a cushion. It breathes, dreams (tail tip and whiskers
+ * twitch), flicks an ear at nearby movement and cracks one eye open to watch the cursor. Hover
+ * slowly over it to pet it: it purrs and kneads. Tap it and it startles awake, then settles
+ * back to sleep. With `collide` it naps on top of a `data-otc-solid` element instead.
+ */
+export declare function useCat(options: UseCatOptions): import('../../hooks/useCanvasSetup').CanvasSetupResult;

package/lib/components/Eye/Eye.d.ts

@@ -0,0 +1,46 @@
+import { BaseCanvasProps } from '../../types';
+import { EyePupilShape } from './useEye';
+
+type EyePreset = "default" | "ocean" | "amber" | "violet" | "serpent" | "monochrome";
+interface EyePresetValues {
+    irisColor?: string;
+    irisInnerColor?: string;
+    scleraColor?: string;
+    skinColor?: string;
+    lashColor?: string;
+    backgroundColor?: string;
+    pupilShape?: EyePupilShape;
+    pupilSize?: number;
+    showLashes?: boolean;
+}
+export declare const PRESETS: Record<EyePreset, EyePresetValues>;
+export interface EyeProps extends BaseCanvasProps {
+    /** Outer iris color (default: "#4a7c59") */
+    irisColor?: string;
+    /** Color of the ring around the pupil (default: "#c8963e") */
+    irisInnerColor?: string;
+    /** Color of the white of the eye (default: "#f1ebe4") */
+    scleraColor?: string;
+    /** Eyelid and face skin color (default: "#c99a7e") */
+    skinColor?: string;
+    /** Lash and lash-line color (default: "#1a1210") */
+    lashColor?: string;
+    /** Canvas background; "transparent" lets the face fade into the page (default: "#0c0807") */
+    backgroundColor?: string;
+    /** "round" or a reptile-like "slit" pupil (default: "round") */
+    pupilShape?: EyePupilShape;
+    /** Resting pupil size as a fraction of the iris, 0.08–0.85 (default: 0.38) */
+    pupilSize?: number;
+    /** Eye scale relative to the canvas, 0.2–1.5 (default: 1) */
+    eyeSize?: number;
+    /** Gaze follows the cursor anywhere on the page and the pupil narrows as it nears; off = the eye looks around on its own (default: true) */
+    followCursor?: boolean;
+    /** Average ms between blinks; 0 = only blink when clicked (default: 4000) */
+    blinkInterval?: number;
+    /** Draw eyelashes (default: true) */
+    showLashes?: boolean;
+    /** Named preset: "default" | "ocean" | "amber" | "violet" | "serpent" | "monochrome" */
+    preset?: EyePreset | string;
+}
+export declare const Eye: import('react').ForwardRefExoticComponent<EyeProps & import('react').RefAttributes<HTMLCanvasElement>>;
+export {};

package/lib/components/Eye/index.d.ts

@@ -0,0 +1,3 @@
+export { Eye } from './Eye';
+export type { EyeProps } from './Eye';
+export type { EyePupilShape } from './useEye';

package/lib/components/Eye/useEye.d.ts

@@ -0,0 +1,29 @@
+import { RefObject } from 'react';
+
+export type EyePupilShape = "round" | "slit";
+export interface UseEyeOptions {
+    irisColor: string;
+    irisInnerColor: string;
+    scleraColor: string;
+    skinColor: string;
+    lashColor: string;
+    backgroundColor: string;
+    pupilShape: EyePupilShape;
+    pupilSize: number;
+    eyeSize: number;
+    followCursor: boolean;
+    blinkInterval: number;
+    showLashes: boolean;
+}
+/** Blink closure 0..1 at `s` seconds into a blink: fast close, brief hold, slower open. */
+export declare function blinkClosure(s: number): number;
+/**
+ * A single living eye, painted like a chiaroscuro portrait: skin falls away into darkness
+ * around an almond-shaped opening. The iris is a baked texture of radial stroma fibres,
+ * a pale collarette, crypts and a dark limbal ring; the pupil breathes (hippus), narrows
+ * as the cursor (the light) approaches and widens when startled. The gaze moves in
+ * saccades with tiny microsaccades, the upper lid rides with it, the lashes follow the
+ * lid through each blink, and the wet cornea holds a fixed window reflection.
+ * Click to make it blink.
+ */
+export declare function useEye(canvasRef: RefObject<HTMLCanvasElement | null>, options: UseEyeOptions): void;

package/lib/components/Fireworks/Fireworks.d.ts

@@ -43,6 +43,8 @@ export interface FireworksProps extends BaseCanvasProps {
     glowBlur?: number;
     /** Canvas background (default: "#04060f") */
     backgroundColor?: string;
+    /** Draw the night scene (sky, stars, burst glow, skyline). false = fireworks only, over a plain backgroundColor fill ("transparent" to overlay). (default: true) */
+    showBackground?: boolean;
     /** Shell upward speed (default: 12) */
     shellSpeed?: number;
     /** Number of background stars (default: 0) */

package/lib/components/Fireworks/useFireworks.d.ts

@@ -14,6 +14,7 @@ export interface UseFireworksOptions {
     glowEffect: boolean;
     glowBlur: number;
     backgroundColor: string;
+    showBackground: boolean;
     shellSpeed: number;
     starCount: number;
     starColor: string;

package/lib/components/FluidSimulation/useFluidSimulation.d.ts

@@ -1,5 +1,3 @@
-import { RefObject } from 'react';
-
 export interface UseFluidSimulationOptions {
     resolution: number;
     viscosity: number;
@@ -14,4 +12,12 @@ export interface UseFluidSimulationOptions {
     mouseForce: number;
     inkRadius: number;
 }
-export declare function useFluidSimulation(canvasRef: RefObject<HTMLCanvasElement | null>, options: UseFluidSimulationOptions): void;
+/** Semi-Lagrangian advection; velocities are in cells per second. */
+export declare function advect(W: number, H: number, b: number, d: Float32Array, d0: Float32Array, u: Float32Array, v: Float32Array, dt: number): void;
+/**
+ * Ink in water. Three slow ink jets orbit the canvas and bursts bloom on a timer, all cycling
+ * through the palette, so the field is always flowing and marbling even untouched. Moving the
+ * cursor drags ink and current behind it; a tap blows a ring outward. Ink is tone-mapped so
+ * overlapping colors mix rather than blow out, with a faint relief sheen on its folds.
+ */
+export declare function useFluidSimulation(options: UseFluidSimulationOptions): import('../../hooks/useCanvasSetup').CanvasSetupResult;

package/lib/components/GameOfLife/GameOfLife.d.ts

@@ -27,13 +27,13 @@ export interface GameOfLifeProps extends BaseCanvasProps {
     aliveColor?: string;
     /** Color of old cells. (default: "#004d14") */
     oldColor?: string;
-    /** Color of dead cells / background. (default: "#000000") */
+    /** Faint lattice dots marking dead cells. (default: "#000000") */
     deadColor?: string;
     /** Color cells by generation age. (default: true) */
     showAge?: boolean;
     /** Wrap cells at canvas edges. (default: true) */
     wrapEdges?: boolean;
-    /** Click to toggle cells. (default: true) */
+    /** Click toggles a cell, drag paints life. (default: true) */
     interactive?: boolean;
     /** Canvas background color. (default: "#000000") */
     backgroundColor?: string;

package/lib/components/GameOfLife/useGameOfLife.d.ts

@@ -20,4 +20,13 @@ export interface UseGameOfLifeOptions {
     interactive: boolean;
     backgroundColor: string;
 }
-export declare function useGameOfLife(canvasRef: RefObject<HTMLCanvasElement | null>, options: UseGameOfLifeOptions, handleRef: RefObject<GameOfLifeHandle | null>): void;
+/** One Conway generation. Cells hold their age (0 = dead, 1 = newborn, capped at 255). */
+export declare function stepLife(grid: Uint8Array, next: Uint8Array, cols: number, rows: number, wrap: boolean): number;
+/**
+ * Conway's Game of Life as living light. Cells are soft glowing dots that swell in when born,
+ * cool from the newborn color to the old color as they age, and leave embers that fade when
+ * they die; generations cross-fade instead of snapping, under a bloom made from the board
+ * itself. Click toggles a cell, dragging paints life. When the board settles into still lifes
+ * and blinkers, a few gliders drift in to stir it up again.
+ */
+export declare function useGameOfLife(options: UseGameOfLifeOptions, handleRef: RefObject<GameOfLifeHandle | null>): import('../../hooks/useCanvasSetup').CanvasSetupResult;

package/lib/components/Hummingbird/Hummingbird.d.ts

@@ -0,0 +1,43 @@
+import { BaseCanvasProps } from '../../types';
+
+type HummingbirdPreset = "default" | "ruby" | "violet" | "sunset" | "frost" | "monochrome";
+interface HummingbirdPresetValues {
+    bodyColor?: string;
+    throatColor?: string;
+    bellyColor?: string;
+    flowerColor?: string;
+    backgroundColor?: string;
+}
+export declare const PRESETS: Record<HummingbirdPreset, HummingbirdPresetValues>;
+export interface HummingbirdProps extends BaseCanvasProps {
+    /** Iridescent back and head (default: "#2f9e6a") */
+    bodyColor?: string;
+    /** Gorget (throat patch) color; it flashes as the bird turns (default: "#ff2d6f") */
+    throatColor?: string;
+    /** Belly color (default: "#e9e4d4") */
+    bellyColor?: string;
+    /** Trumpet flower color (default: "#e8433a") */
+    flowerColor?: string;
+    /** Garden color; "transparent" drops the scene (default: "#0c1712") */
+    backgroundColor?: string;
+    /** Number of birds, 0–8 (default: 1) */
+    birdCount?: number;
+    /** Bird scale (default: 1) */
+    size?: number;
+    /** Dart speed multiplier (default: 1) */
+    speed?: number;
+    /** A slow cursor draws a bird over to look; a fast one scares it off (default: true) */
+    interactive?: boolean;
+    /** Draw the flowers (default: true) */
+    showFlowers?: boolean;
+    /** Fixed full-viewport, click-through layer over the page (default: false) */
+    overlay?: boolean;
+    /** Elements marked `data-otc-solid` become flowers; the hovered one is visited first (default: false) */
+    collide?: boolean;
+    /** Overlay z-index (default: 10) */
+    zIndex?: number;
+    /** Named preset: "default" | "ruby" | "violet" | "sunset" | "frost" | "monochrome" */
+    preset?: HummingbirdPreset | string;
+}
+export declare const Hummingbird: import('react').ForwardRefExoticComponent<HummingbirdProps & import('react').RefAttributes<HTMLCanvasElement>>;
+export {};

package/lib/components/Hummingbird/index.d.ts

@@ -0,0 +1,2 @@
+export { Hummingbird } from './Hummingbird';
+export type { HummingbirdProps } from './Hummingbird';

package/lib/components/Hummingbird/useHummingbird.d.ts

@@ -0,0 +1,35 @@
+import { Solid } from '../../runtime/physics';
+
+export interface UseHummingbirdOptions {
+    bodyColor: string;
+    throatColor: string;
+    bellyColor: string;
+    flowerColor: string;
+    backgroundColor: string;
+    birdCount: number;
+    size: number;
+    speed: number;
+    interactive: boolean;
+    showFlowers: boolean;
+    overlay: boolean;
+    collide: boolean;
+}
+/** Somewhere a bird can feed: the beak tip goes to (x, y) while the bird faces `face`. */
+export interface Nectar {
+    x: number;
+    y: number;
+    face: 1 | -1;
+    key: string;
+}
+/** Feeding spots beside each solid's left and right edge, beak touching the edge. */
+export declare function solidNectar(solids: readonly Solid[]): Nectar[];
+/**
+ * Hummingbirds in a dusk garden. Wings beat too fast to see, so each stroke is drawn as a
+ * motion blur, densest at the ends where the wing turns, with a faint strobe of the wing
+ * itself. A bird darts between trumpet flowers, stops dead, fans its tail to brake, sips
+ * with a pumping motion and backs straight out before darting away; pollen puffs where it
+ * feeds and its gorget flashes as it turns. A slow cursor draws one over to inspect it, a
+ * fast one scares it off, and rival birds chase each other away from the flowers. With
+ * `collide`, `data-otc-solid` elements become flowers, and the hovered one is visited now.
+ */
+export declare function useHummingbird(options: UseHummingbirdOptions): import('../../hooks/useCanvasSetup').CanvasSetupResult;