own-the-canvas 2.0.1 → 2.0.2

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 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.

package/README.md

@@ -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 |
 
@@ -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`
 
@@ -209,7 +208,7 @@ import { FluidSimulation } from "own-the-canvas";
 | `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 |
 
 ---
@@ -343,7 +342,6 @@ Nature effects with real models underneath, built for hero sections. Each one ru
 | `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 |
-| `FrostGlass` ✦ | Frost crystals creep across the glass; the cursor is warm breath that melts them |
 | `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 |
@@ -357,7 +355,7 @@ Nature effects with real models underneath, built for hero sections. Each one ru
 
 ## 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;

package/lib/components/Jellyfish/Jellyfish.d.ts

@@ -0,0 +1,37 @@
+import { BaseCanvasProps } from '../../types';
+
+type JellyfishPreset = "default" | "sea-nettle" | "crystal" | "lions-mane" | "ghost" | "monochrome";
+interface JellyfishPresetValues {
+    bellColor?: string;
+    glowColor?: string;
+    backgroundColor?: string;
+    tentacleLength?: number;
+    count?: number;
+}
+export declare const PRESETS: Record<JellyfishPreset, JellyfishPresetValues>;
+export interface JellyfishProps extends BaseCanvasProps {
+    /** Number of jellyfish (default: 4) */
+    count?: number;
+    /** Bell and oral-arm tint (default: "#c9a7e8") */
+    bellColor?: string;
+    /** Rim light, tentacles and flash color (default: "#8fd8ff") */
+    glowColor?: string;
+    /** Water color; "transparent" drops the scene (default: "#04122a") */
+    backgroundColor?: string;
+    /** Tentacle length multiplier (default: 1) */
+    tentacleLength?: number;
+    /** Bell pulse speed multiplier (default: 1) */
+    pulseRate?: number;
+    /** Jellies turn away from the cursor, which stirs the water; taps make them flash (default: true) */
+    interactive?: boolean;
+    /** Fixed full-viewport, click-through layer over the page (default: false) */
+    overlay?: boolean;
+    /** Nudge off elements marked `data-otc-solid` (default: false) */
+    collide?: boolean;
+    /** Overlay z-index (default: 10) */
+    zIndex?: number;
+    /** Named preset: "default" | "sea-nettle" | "crystal" | "lions-mane" | "ghost" | "monochrome" */
+    preset?: JellyfishPreset | string;
+}
+export declare const Jellyfish: import('react').ForwardRefExoticComponent<JellyfishProps & import('react').RefAttributes<HTMLCanvasElement>>;
+export {};

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

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

package/lib/components/Jellyfish/useJellyfish.d.ts

@@ -0,0 +1,20 @@
+export interface UseJellyfishOptions {
+    count: number;
+    bellColor: string;
+    glowColor: string;
+    backgroundColor: string;
+    tentacleLength: number;
+    pulseRate: number;
+    interactive: boolean;
+    overlay: boolean;
+    collide: boolean;
+}
+/** Bell contraction 0..1 over one pulse cycle: a quick squeeze, then a slow relax. */
+export declare function pulse(phase: number): number;
+/**
+ * Moon jellies in open water. Each bell pulses by jet propulsion (a quick squeeze that drives it
+ * forward, a slow relax), steering gently back upward, with verlet tentacles and frilled oral arms
+ * that trail and swirl in the wake. The cursor stirs the water and they turn away from it; a tap
+ * makes nearby bells flash. With `collide` they nudge off `data-otc-solid` elements.
+ */
+export declare function useJellyfish(options: UseJellyfishOptions): import('../../hooks/useCanvasSetup').CanvasSetupResult;

package/lib/components/KoiPond/KoiPond.d.ts

@@ -6,7 +6,7 @@ export interface KoiPondProps extends BaseCanvasProps {
     fishCount?: number;
     /** Primary fish body color (default: "#ff6030") */
     fishColor?: string;
-    /** Scale accent color (default: "#ffffff") */
+    /** Patch color of the markings; every third koi swaps body and patch (default: "#ffffff") */
     scaleColor?: string;
     /** Water background color (default: "#0a1520") */
     waterColor?: string;
@@ -16,7 +16,7 @@ export interface KoiPondProps extends BaseCanvasProps {
     lilyColor?: string;
     /** Fish movement speed multiplier (default: 1) */
     speed?: number;
-    /** Cursor causes ripples (default: true) */
+    /** Cursor leaves ripples; tap to drop food the koi swim up to eat (default: true) */
     interactive?: boolean;
     /** Show lily pads (default: true) */
     showLilies?: boolean;

package/lib/components/KoiPond/useKoiPond.d.ts

@@ -1,5 +1,3 @@
-import { RefObject } from 'react';
-
 export interface UseKoiPondOptions {
     fishCount: number;
     fishColor: string;
@@ -12,4 +10,13 @@ export interface UseKoiPondOptions {
     showLilies: boolean;
     caustics: boolean;
 }
-export declare function useKoiPond(canvasRef: RefObject<HTMLCanvasElement | null>, options: UseKoiPondOptions): void;
+/** Koi body half-width at u (0 = nose, 1 = tail root), as a fraction of body length. */
+export declare function koiWidth(u: number): number;
+/**
+ * A koi pond from above. Koi swim on a flexible 12-point spine with a full silhouette, painted
+ * patches, flapping pectoral fins and a trailing butterfly tail, each casting a soft shadow on the
+ * pond floor below. Sunlight caustics wash over the bottom, lily pads (some flowering) float
+ * above the fish and drift on the ripples. The cursor leaves ripples; tap to drop a food pellet
+ * and the koi race up to eat it.
+ */
+export declare function useKoiPond(options: UseKoiPondOptions): import('../../hooks/useCanvasSetup').CanvasSetupResult;