@autumnsgrove/groveengine 0.7.0 → 0.8.5

package/dist/ui/components/nature/Logo.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { Season } from './palette';
+interface Props {
+    class?: string;
+    color?: string;
+    trunkColor?: string;
+    season?: Season;
+    animate?: boolean;
+    animateEntrance?: boolean;
+    /** Add breathing animation (subtle pulse for loading states) */
+    breathing?: boolean;
+}
+declare const Logo: import("svelte").Component<Props, {}, "">;
+type Logo = ReturnType<typeof Logo>;
+export default Logo;

package/dist/ui/components/nature/botanical/Acorn.svelte

@@ -0,0 +1,48 @@
+<!--
+  Grove — A place to Be
+  Copyright (c) 2025 Autumn Brown
+  Licensed under AGPL-3.0
+-->
+<script lang="ts">
+	import { bark, earth } from '../palette';
+
+	interface Props {
+		class?: string;
+		capColor?: string;
+		nutColor?: string;
+	}
+
+	let {
+		class: className = 'w-4 h-5',
+		capColor,
+		nutColor
+	}: Props = $props();
+
+	const cap = $derived(capColor ?? bark.bark);
+	const nut = $derived(nutColor ?? earth.clay);
+	const capDetail = bark.darkBark;
+</script>
+
+<!-- Acorn -->
+<svg class={className} xmlns="http://www.w3.org/2000/svg" viewBox="0 0 30 40">
+	<!-- Stem -->
+	<path fill={capDetail} d="M15 0 Q18 0 18 4 L15 6 L12 4 Q12 0 15 0" />
+
+	<!-- Cap -->
+	<ellipse fill={cap} cx="15" cy="12" rx="13" ry="8" />
+	<!-- Cap texture (crosshatch pattern suggestion) -->
+	<path fill="none" stroke={capDetail} stroke-width="0.5" d="M5 10 Q15 14 25 10" opacity="0.4" />
+	<path fill="none" stroke={capDetail} stroke-width="0.5" d="M4 13 Q15 17 26 13" opacity="0.3" />
+	<path fill="none" stroke={capDetail} stroke-width="0.5" d="M8 8 L8 16" opacity="0.2" />
+	<path fill="none" stroke={capDetail} stroke-width="0.5" d="M15 6 L15 16" opacity="0.2" />
+	<path fill="none" stroke={capDetail} stroke-width="0.5" d="M22 8 L22 16" opacity="0.2" />
+
+	<!-- Nut body -->
+	<ellipse fill={nut} cx="15" cy="26" rx="11" ry="14" />
+
+	<!-- Nut highlight -->
+	<ellipse fill="white" cx="12" cy="22" rx="4" ry="5" opacity="0.15" />
+
+	<!-- Bottom point -->
+	<path fill={nut} d="M10 38 Q15 42 20 38 L15 40 Z" />
+</svg>

package/dist/ui/components/nature/botanical/Acorn.svelte.d.ts

@@ -0,0 +1,8 @@
+interface Props {
+    class?: string;
+    capColor?: string;
+    nutColor?: string;
+}
+declare const Acorn: import("svelte").Component<Props, {}, "">;
+type Acorn = ReturnType<typeof Acorn>;
+export default Acorn;

package/dist/ui/components/nature/botanical/Berry.svelte

@@ -0,0 +1,67 @@
+<!--
+  Grove — A place to Be
+  Copyright (c) 2025 Autumn Brown
+  Licensed under AGPL-3.0
+-->
+<script lang="ts">
+	import { accents, greens } from '../palette';
+
+	interface Props {
+		class?: string;
+		berryColor?: string;
+		variant?: 'cluster' | 'single' | 'branch';
+	}
+
+	let {
+		class: className = 'w-6 h-6',
+		berryColor,
+		variant = 'cluster'
+	}: Props = $props();
+
+	const berry = $derived(berryColor ?? accents.berry.ripe);
+	const stem = greens.deepGreen;
+	const highlight = 'white';
+</script>
+
+<!-- Berries -->
+<svg class={className} xmlns="http://www.w3.org/2000/svg" viewBox="0 0 50 50">
+	{#if variant === 'single'}
+		<!-- Single berry -->
+		<circle fill={berry} cx="25" cy="28" r="15" />
+		<circle fill={highlight} cx="20" cy="23" r="4" opacity="0.3" />
+		<path fill="none" stroke={stem} stroke-width="2" d="M25 13 Q25 5 20 2" />
+		<!-- Calyx -->
+		<path fill={stem} d="M20 14 L25 18 L30 14 L28 16 L25 14 L22 16 Z" />
+	{:else if variant === 'cluster'}
+		<!-- Berry cluster -->
+		<path fill="none" stroke={stem} stroke-width="1.5" d="M25 5 L25 15 M25 15 L18 22 M25 15 L32 22 M25 15 L25 25" />
+
+		<circle fill={berry} cx="18" cy="28" r="10" />
+		<circle fill={highlight} cx="14" cy="24" r="2.5" opacity="0.3" />
+
+		<circle fill={berry} cx="32" cy="28" r="10" />
+		<circle fill={highlight} cx="28" cy="24" r="2.5" opacity="0.3" />
+
+		<circle fill={berry} cx="25" cy="38" r="10" />
+		<circle fill={highlight} cx="21" cy="34" r="2.5" opacity="0.3" />
+	{:else}
+		<!-- Berry branch -->
+		<path fill="none" stroke={stem} stroke-width="2" d="M5 25 Q15 20 25 22 Q35 24 45 20" />
+		<!-- Leaves -->
+		<ellipse fill={stem} cx="12" cy="22" rx="5" ry="3" transform="rotate(-20 12 22)" />
+		<ellipse fill={stem} cx="38" cy="20" rx="5" ry="3" transform="rotate(15 38 20)" />
+
+		<!-- Berries along branch -->
+		<circle fill={berry} cx="18" cy="28" r="6" />
+		<circle fill={highlight} cx="16" cy="26" r="1.5" opacity="0.3" />
+
+		<circle fill={berry} cx="28" cy="30" r="6" />
+		<circle fill={highlight} cx="26" cy="28" r="1.5" opacity="0.3" />
+
+		<circle fill={berry} cx="22" cy="36" r="5" />
+		<circle fill={highlight} cx="20" cy="34" r="1.2" opacity="0.3" />
+
+		<circle fill={berry} cx="32" cy="38" r="5" />
+		<circle fill={highlight} cx="30" cy="36" r="1.2" opacity="0.3" />
+	{/if}
+</svg>

package/dist/ui/components/nature/botanical/Berry.svelte.d.ts

@@ -0,0 +1,8 @@
+interface Props {
+    class?: string;
+    berryColor?: string;
+    variant?: 'cluster' | 'single' | 'branch';
+}
+declare const Berry: import("svelte").Component<Props, {}, "">;
+type Berry = ReturnType<typeof Berry>;
+export default Berry;

package/dist/ui/components/nature/botanical/DandelionPuff.svelte

@@ -0,0 +1,98 @@
+<!--
+  Grove — A place to Be
+  Copyright (c) 2025 Autumn Brown
+  Licensed under AGPL-3.0
+-->
+<script lang="ts">
+	import { greens, natural } from '../palette';
+
+	interface Props {
+		class?: string;
+		seedColor?: string;
+		animate?: boolean;
+	}
+
+	let {
+		class: className = 'w-8 h-10',
+		seedColor,
+		animate = true
+	}: Props = $props();
+
+	const seed = $derived(seedColor ?? natural.cream);
+	const stem = $derived(greens.deepGreen);
+</script>
+
+<!-- Dandelion seed head (puff) -->
+<svg class={className} xmlns="http://www.w3.org/2000/svg" viewBox="0 0 60 80">
+	<!-- Stem -->
+	<path fill="none" stroke={stem} stroke-width="2" d="M30 80 Q28 60 30 45" />
+
+	<!-- Central seed head -->
+	<circle fill={seed} cx="30" cy="30" r="8" opacity="0.5" />
+
+	<!-- Seeds with parachutes radiating outward -->
+	<!-- Top seeds -->
+	<g class={animate ? 'drift drift-1' : ''}>
+		<path fill={seed} d="M30 5 L28 12 L30 10 L32 12 Z" opacity="0.7" />
+		<line x1="30" y1="10" x2="30" y2="22" stroke={seed} stroke-width="0.5" opacity="0.5" />
+	</g>
+
+	<g class={animate ? 'drift drift-2' : ''}>
+		<path fill={seed} d="M45 10 L40 15 L42 14 L42 17 Z" opacity="0.7" transform="rotate(30 45 10)" />
+		<line x1="42" y1="14" x2="35" y2="24" stroke={seed} stroke-width="0.5" opacity="0.5" />
+	</g>
+
+	<g class={animate ? 'drift drift-3' : ''}>
+		<path fill={seed} d="M15 10 L20 15 L18 14 L18 17 Z" opacity="0.7" transform="rotate(-30 15 10)" />
+		<line x1="18" y1="14" x2="25" y2="24" stroke={seed} stroke-width="0.5" opacity="0.5" />
+	</g>
+
+	<!-- Side seeds -->
+	<g class={animate ? 'drift drift-4' : ''}>
+		<path fill={seed} d="M55 25 L48 28 L50 27 L49 30 Z" opacity="0.6" />
+		<line x1="49" y1="28" x2="38" y2="28" stroke={seed} stroke-width="0.5" opacity="0.5" />
+	</g>
+
+	<g class={animate ? 'drift drift-5' : ''}>
+		<path fill={seed} d="M5 25 L12 28 L10 27 L11 30 Z" opacity="0.6" />
+		<line x1="11" y1="28" x2="22" y2="28" stroke={seed} stroke-width="0.5" opacity="0.5" />
+	</g>
+
+	<!-- Lower seeds -->
+	<g class={animate ? 'drift drift-6' : ''}>
+		<path fill={seed} d="M50 40 L44 40 L46 38 L45 42 Z" opacity="0.6" />
+		<line x1="45" y1="40" x2="38" y2="35" stroke={seed} stroke-width="0.5" opacity="0.5" />
+	</g>
+
+	<g class={animate ? 'drift drift-7' : ''}>
+		<path fill={seed} d="M10 40 L16 40 L14 38 L15 42 Z" opacity="0.6" />
+		<line x1="15" y1="40" x2="22" y2="35" stroke={seed} stroke-width="0.5" opacity="0.5" />
+	</g>
+
+	<!-- Central dense seeds -->
+	<circle fill={seed} cx="30" cy="22" r="2" opacity="0.8" />
+	<circle fill={seed} cx="25" cy="26" r="2" opacity="0.7" />
+	<circle fill={seed} cx="35" cy="26" r="2" opacity="0.7" />
+	<circle fill={seed} cx="30" cy="32" r="2" opacity="0.6" />
+	<circle fill={seed} cx="24" cy="34" r="1.5" opacity="0.5" />
+	<circle fill={seed} cx="36" cy="34" r="1.5" opacity="0.5" />
+</svg>
+
+<style>
+	@keyframes drift {
+		0%, 100% { transform: translate(0, 0); }
+		50% { transform: translate(var(--drift-x, 2px), var(--drift-y, -2px)); }
+	}
+
+	.drift {
+		animation: drift 3s ease-in-out infinite;
+	}
+
+	.drift-1 { --drift-x: 0px; --drift-y: -3px; animation-delay: 0s; }
+	.drift-2 { --drift-x: 3px; --drift-y: -2px; animation-delay: 0.3s; }
+	.drift-3 { --drift-x: -3px; --drift-y: -2px; animation-delay: 0.6s; }
+	.drift-4 { --drift-x: 4px; --drift-y: 0px; animation-delay: 0.2s; }
+	.drift-5 { --drift-x: -4px; --drift-y: 0px; animation-delay: 0.5s; }
+	.drift-6 { --drift-x: 3px; --drift-y: 2px; animation-delay: 0.4s; }
+	.drift-7 { --drift-x: -3px; --drift-y: 2px; animation-delay: 0.7s; }
+</style>

package/dist/ui/components/nature/botanical/DandelionPuff.svelte.d.ts

@@ -0,0 +1,8 @@
+interface Props {
+    class?: string;
+    seedColor?: string;
+    animate?: boolean;
+}
+declare const DandelionPuff: import("svelte").Component<Props, {}, "">;
+type DandelionPuff = ReturnType<typeof DandelionPuff>;
+export default DandelionPuff;

package/dist/ui/components/nature/botanical/FallingLeavesLayer.svelte

@@ -0,0 +1,170 @@
+<!--
+  Grove — A place to Be
+  Copyright (c) 2025 Autumn Brown
+  Licensed under AGPL-3.0
+-->
+<script lang="ts">
+	import type { Season } from '../palette';
+	import LeafFalling from './LeafFalling.svelte';
+
+	type TreeType = 'logo' | 'pine' | 'aspen' | 'birch' | 'cherry';
+	type LeafVariant = 'simple' | 'maple' | 'cherry' | 'aspen' | 'pine';
+
+	// Animation constants (defaults)
+	const DEFAULT_LEAF_OPACITY = { min: 0.4, max: 0.75 } as const;
+	const DEFAULT_FALL_DURATION = { min: 8, max: 14 } as const;
+	const DEFAULT_FALL_DISTANCE = { min: 12, max: 20 } as const;
+	const DEFAULT_DRIFT_RANGE = 60; // -30 to +30
+	const DEFAULT_SPAWN_DELAY_MAX = 15;
+
+	interface Tree {
+		id: number;
+		x: number;
+		y: number;
+		size: number;
+		treeType: TreeType;
+		zIndex?: number;
+	}
+
+	interface FallingLeaf {
+		id: number;
+		x: number;
+		y: number;
+		size: number;
+		variant: LeafVariant;
+		duration: number;
+		delay: number;
+		drift: number;
+		opacity: number;
+		fallDistance: number;
+	}
+
+	interface Props {
+		trees: Tree[];
+		season?: Season;
+		/** Minimum leaves per tree */
+		minLeavesPerTree?: number;
+		/** Maximum leaves per tree */
+		maxLeavesPerTree?: number;
+		/** Base z-index for the leaf layer (should be below trees) */
+		zIndex?: number;
+		/** Override fall distance range (in vh units) - useful for tall sections */
+		fallDistance?: { min: number; max: number };
+		/** Override fall duration range (in seconds) */
+		fallDuration?: { min: number; max: number };
+		/** Maximum spawn delay (in seconds) */
+		spawnDelayMax?: number;
+	}
+
+	let {
+		trees,
+		season = 'summer',
+		minLeavesPerTree = 2,
+		maxLeavesPerTree = 5,
+		zIndex = -1,
+		fallDistance = DEFAULT_FALL_DISTANCE,
+		fallDuration = DEFAULT_FALL_DURATION,
+		spawnDelayMax = DEFAULT_SPAWN_DELAY_MAX
+	}: Props = $props();
+
+	// Deterministic hash for pseudo-random distribution (avoids visible patterns)
+	function hashSeed(seed: number): number {
+		return Math.abs(Math.sin(seed * 12.9898) * 43758.5453);
+	}
+
+	// Map tree types to appropriate leaf variants (deterministic based on leaf id)
+	function getLeafVariant(treeType: TreeType, leafId: number): LeafVariant {
+		switch (treeType) {
+			case 'cherry':
+				return 'cherry';
+			case 'aspen':
+			case 'birch':
+				return 'aspen';
+			case 'pine':
+				return 'pine';
+			case 'logo':
+			default:
+				// Logo and default get a mix of simple and maple (deterministic with natural distribution)
+				return Math.floor(hashSeed(leafId)) % 2 === 0 ? 'simple' : 'maple';
+		}
+	}
+
+	// Generate falling leaves based on tree positions
+	function generateLeaves(treesData: Tree[]): FallingLeaf[] {
+		const leaves: FallingLeaf[] = [];
+		let leafId = 0;
+
+		for (const tree of treesData) {
+			// Random number of leaves per tree within the configured range
+			const baseLeafCount = minLeavesPerTree + Math.floor(Math.random() * (maxLeavesPerTree - minLeavesPerTree + 1));
+
+			// More leaves for bigger/closer trees, fewer for distant ones
+			const treeDepth = tree.zIndex ?? 1;
+			const depthMultiplier = 0.5 + (treeDepth / 5) * 0.8; // 0.5x for far trees, up to 1.3x for close ones
+			const leafCount = Math.ceil(baseLeafCount * depthMultiplier);
+
+			// Scale leaf size based on tree size (bigger trees = bigger leaves for perspective)
+			const treeSizeFactor = tree.size / 100; // Normalize around 100px tree size
+			const baseLeafSize = 6 + treeSizeFactor * 8; // 6-14px base depending on tree size
+			const leafSizeVariation = 6 + treeSizeFactor * 4; // Additional random variation
+
+			for (let i = 0; i < leafCount; i++) {
+				// Spawn leaves at or above tree canopy for better falling motion
+				// Leaves will animate downward from their spawn point
+				const xOffset = (Math.random() - 0.5) * (tree.size / 8); // Horizontal spread based on tree size
+				// Vertical variation: spawn leaves slightly above to at tree position
+				const yOffset = -2 - Math.random() * 3; // -2% to -5% above tree
+
+				const currentLeafId = leafId++;
+				leaves.push({
+					id: currentLeafId,
+					x: tree.x + xOffset,
+					y: Math.max(0, tree.y + yOffset), // Clamp to not go above viewport
+					size: baseLeafSize + Math.random() * leafSizeVariation,
+					variant: getLeafVariant(tree.treeType, currentLeafId),
+					duration: fallDuration.min + Math.random() * (fallDuration.max - fallDuration.min),
+					delay: Math.random() * spawnDelayMax,
+					drift: (Math.random() - 0.5) * DEFAULT_DRIFT_RANGE,
+					opacity: DEFAULT_LEAF_OPACITY.min + Math.random() * (DEFAULT_LEAF_OPACITY.max - DEFAULT_LEAF_OPACITY.min),
+					fallDistance: fallDistance.min + Math.random() * (fallDistance.max - fallDistance.min)
+				});
+			}
+		}
+
+		return leaves;
+	}
+
+	// Reactive leaves - regenerates when trees or season changes
+	let fallingLeaves = $derived(generateLeaves(trees));
+</script>
+
+<!-- Falling leaves layer - positioned behind trees -->
+<div
+	class="absolute inset-0 pointer-events-none overflow-hidden"
+	style="z-index: {zIndex};"
+>
+	{#each fallingLeaves as leaf (leaf.id)}
+		<div
+			class="absolute"
+			style="
+				left: {leaf.x}%;
+				top: {leaf.y}%;
+				opacity: {leaf.opacity};
+				width: {leaf.size}px;
+				height: {leaf.size}px;
+			"
+		>
+			<LeafFalling
+				class="w-full h-full"
+				variant={leaf.variant}
+				{season}
+				duration={leaf.duration}
+				delay={leaf.delay}
+				drift={leaf.drift}
+				fallDistance={leaf.fallDistance}
+				seed={leaf.id}
+				animate={true}
+			/>
+		</div>
+	{/each}
+</div>

package/dist/ui/components/nature/botanical/FallingLeavesLayer.svelte.d.ts

@@ -0,0 +1,35 @@
+import type { Season } from '../palette';
+type TreeType = 'logo' | 'pine' | 'aspen' | 'birch' | 'cherry';
+interface Tree {
+    id: number;
+    x: number;
+    y: number;
+    size: number;
+    treeType: TreeType;
+    zIndex?: number;
+}
+interface Props {
+    trees: Tree[];
+    season?: Season;
+    /** Minimum leaves per tree */
+    minLeavesPerTree?: number;
+    /** Maximum leaves per tree */
+    maxLeavesPerTree?: number;
+    /** Base z-index for the leaf layer (should be below trees) */
+    zIndex?: number;
+    /** Override fall distance range (in vh units) - useful for tall sections */
+    fallDistance?: {
+        min: number;
+        max: number;
+    };
+    /** Override fall duration range (in seconds) */
+    fallDuration?: {
+        min: number;
+        max: number;
+    };
+    /** Maximum spawn delay (in seconds) */
+    spawnDelayMax?: number;
+}
+declare const FallingLeavesLayer: import("svelte").Component<Props, {}, "">;
+type FallingLeavesLayer = ReturnType<typeof FallingLeavesLayer>;
+export default FallingLeavesLayer;

package/dist/ui/components/nature/botanical/FallingPetalsLayer.svelte

@@ -0,0 +1,174 @@
+<!--
+  Grove — A place to Be
+  Copyright (c) 2025 Autumn Brown
+  Licensed under AGPL-3.0
+-->
+<script lang="ts">
+	import { browser } from '$app/environment';
+	import PetalFalling from './PetalFalling.svelte';
+
+	type PetalVariant = 'round' | 'pointed' | 'heart' | 'curled' | 'tiny';
+
+	// Check for reduced motion preference
+	const prefersReducedMotion = browser
+		? window.matchMedia('(prefers-reduced-motion: reduce)').matches
+		: false;
+
+	interface Props {
+		/** Total number of petals */
+		count?: number;
+		/** Base z-index for the petal layer */
+		zIndex?: number;
+		/** Enable petal animation */
+		enabled?: boolean;
+		/** Opacity range for petals (depth affects final value) */
+		opacity?: { min: number; max: number };
+		/** Fall duration range in seconds (slower = more dreamy) */
+		fallDuration?: { min: number; max: number };
+		/** Horizontal drift range in pixels (petals flutter more than snow) */
+		driftRange?: number;
+		/** Maximum spawn delay in seconds */
+		spawnDelay?: number;
+	}
+
+	let {
+		count = 80,
+		zIndex = 50,
+		enabled = true,
+		opacity = { min: 0.5, max: 0.9 },
+		fallDuration = { min: 12, max: 20 },
+		driftRange = 80,
+		spawnDelay = 15
+	}: Props = $props();
+
+	// Petals fall gently and drift more than snow
+	// Increased distance to ensure they traverse the full viewport
+	const FALL_DISTANCE = { min: 120, max: 150 } as const;
+
+	// Reduce petal count for reduced motion
+	const actualCount = $derived(prefersReducedMotion ? Math.floor(count / 4) : count);
+
+	// Variant distribution - more round and heart shapes for cherry blossoms
+	const petalVariants: PetalVariant[] = ['round', 'round', 'pointed', 'heart', 'curled', 'tiny'];
+
+	interface Petal {
+		id: number;
+		x: number;
+		y: number;
+		size: number;
+		variant: PetalVariant;
+		duration: number;
+		delay: number;
+		drift: number;
+		opacity: number;
+		fallDistance: number;
+	}
+
+	// Deterministic hash for natural distribution
+	function hashRandom(seed: number): number {
+		const hash = Math.abs(Math.sin(seed * 12.9898) * 43758.5453);
+		return hash - Math.floor(hash);
+	}
+
+	// Generate petals across the viewport
+	function generatePetals(): Petal[] {
+		const petals: Petal[] = [];
+
+		for (let i = 0; i < actualCount; i++) {
+			// Prime number multipliers ensure uncorrelated random distributions
+			// across different properties (avoids visible patterns in petal placement)
+			const xRand = hashRandom(i * 7);
+			const yRand = hashRandom(i * 11);
+			const depthRand = hashRandom(i * 13);
+			const durationRand = hashRandom(i * 17);
+			const delayRand = hashRandom(i * 19);
+			const driftRand = hashRandom(i * 23);
+			const distanceRand = hashRandom(i * 29);
+			const variantRand = hashRandom(i * 31);
+
+			// Distribute across full width
+			const x = (i / actualCount) * 100 + (xRand - 0.5) * 15;
+
+			// Start positions: Mix above viewport and within for continuous rain effect
+			// 50% start above for "raining from sky", 50% within for immediate visibility
+			const y = yRand < 0.5
+				? -5 - yRand * 15  // Above viewport: -5% to -20%
+				: yRand * 40;       // Within viewport: 0% to 40%
+
+			// Depth-based sizing:
+			// Far petals are smaller and simpler
+			// Close petals are larger and more detailed
+			const depthFactor = depthRand;
+			const size = 10 + depthFactor * 18; // 10-28px - petals are delicate
+
+			// Variant based on depth
+			let variant: PetalVariant;
+			if (depthFactor < 0.25) {
+				variant = 'tiny';
+			} else {
+				const variantIndex = Math.floor(variantRand * (petalVariants.length - 1));
+				variant = petalVariants[variantIndex];
+			}
+
+			// Since all petals now start above viewport, stagger delays for continuous rain
+			// Shorter delays create more immediate visual interest
+			const actualDelay = delayRand * spawnDelay * 0.6; // Reduce overall delay spread
+
+			// Petals drift more erratically than snow - flutter in the breeze
+			// Use sine wave for more organic drift pattern
+			const baseDrift = (driftRand - 0.5) * driftRange;
+			const driftVariation = Math.sin(i * 0.7) * 20;
+
+			petals.push({
+				id: i,
+				x,
+				y,
+				size,
+				variant,
+				duration: fallDuration.min + durationRand * (fallDuration.max - fallDuration.min),
+				delay: actualDelay,
+				drift: baseDrift + driftVariation,
+				opacity: opacity.min + depthFactor * (opacity.max - opacity.min),
+				fallDistance: FALL_DISTANCE.min + distanceRand * (FALL_DISTANCE.max - FALL_DISTANCE.min)
+			});
+		}
+
+		return petals;
+	}
+
+	// Generate petals once
+	const petals = $derived(generatePetals());
+</script>
+
+{#if enabled}
+	<!-- Falling petals layer - cherry blossoms drifting on spring breeze -->
+	<div
+		class="absolute inset-0 pointer-events-none"
+		style="z-index: {zIndex};"
+		aria-hidden="true"
+	>
+		{#each petals as petal (petal.id)}
+			<div
+				class="absolute"
+				style="
+					left: {petal.x}%;
+					top: {petal.y}%;
+					width: {petal.size}px;
+					height: {petal.size}px;
+				"
+			>
+				<PetalFalling
+					class="w-full h-full"
+					variant={petal.variant}
+					duration={petal.duration}
+					delay={petal.delay}
+					drift={petal.drift}
+					fallDistance={petal.fallDistance}
+					opacity={petal.opacity}
+					seed={petal.id}
+					animate={true}
+				/>
+			</div>
+		{/each}
+	</div>
+{/if}

package/dist/ui/components/nature/botanical/FallingPetalsLayer.svelte.d.ts

@@ -0,0 +1,25 @@
+interface Props {
+    /** Total number of petals */
+    count?: number;
+    /** Base z-index for the petal layer */
+    zIndex?: number;
+    /** Enable petal animation */
+    enabled?: boolean;
+    /** Opacity range for petals (depth affects final value) */
+    opacity?: {
+        min: number;
+        max: number;
+    };
+    /** Fall duration range in seconds (slower = more dreamy) */
+    fallDuration?: {
+        min: number;
+        max: number;
+    };
+    /** Horizontal drift range in pixels (petals flutter more than snow) */
+    driftRange?: number;
+    /** Maximum spawn delay in seconds */
+    spawnDelay?: number;
+}
+declare const FallingPetalsLayer: import("svelte").Component<Props, {}, "">;
+type FallingPetalsLayer = ReturnType<typeof FallingPetalsLayer>;
+export default FallingPetalsLayer;