@backbay/glia-three 0.2.0-alpha.2

package/src/environment/WeatherLayer/colors.ts

@@ -0,0 +1,27 @@
+import { AUTUMN_LEAF_COLOR_PRESETS } from "./leafPresets";
+import type { AutumnLeafColorPreset } from "./leafPresets";
+import type { WeatherType } from "./types";
+
+export function resolveWeatherColors({
+  type,
+  configColors,
+  colors,
+  leafColorPreset,
+}: {
+  type: WeatherType;
+  configColors: readonly string[];
+  colors?: readonly string[];
+  leafColorPreset?: AutumnLeafColorPreset;
+}): readonly string[] {
+  if (colors && colors.length > 0) return colors;
+  if (type === "leaves" && leafColorPreset) {
+    return AUTUMN_LEAF_COLOR_PRESETS[leafColorPreset] ?? configColors;
+  }
+  return configColors;
+}
+
+export function colorsKey(colors: readonly string[] | undefined) {
+  if (!colors || colors.length === 0) return "";
+  return colors.join("|");
+}
+

package/src/environment/WeatherLayer/index.ts

@@ -0,0 +1,4 @@
+export { WeatherLayer } from './WeatherLayer';
+export type { WeatherLayerProps, WeatherType } from './types';
+export { AUTUMN_LEAF_COLOR_PRESETS } from "./leafPresets";
+export type { AutumnLeafColorPreset } from "./leafPresets";

package/src/environment/WeatherLayer/leafPresets.ts

@@ -0,0 +1,12 @@
+export const AUTUMN_LEAF_COLOR_PRESETS = {
+  "early-autumn": ["#6b8f3f", "#a9b84a", "#d8c35a", "#e5b04a", "#c97a2c"],
+  "peak-autumn": ["#b63a2b", "#d86b2c", "#e5a93a", "#c56b2b", "#7a3e1b"],
+  "late-autumn": ["#5a3d2b", "#7a563e", "#9a6f4b", "#b68a5e", "#8a6b4f"],
+  golden: ["#f2d27a", "#e9c15c", "#d8a93b", "#b9872a", "#e8b04a"],
+  rust: ["#a34a1f", "#c2602d", "#d6782f", "#e07b39", "#bc6c25"],
+  "maple-red": ["#7a1f1f", "#a02b2b", "#c0302b", "#d44a2c", "#e36a3a"],
+  muted: ["#d4a373", "#c08a5a", "#a66a3f", "#8c5a36", "#e3b07a"],
+} as const;
+
+export type AutumnLeafColorPreset = keyof typeof AUTUMN_LEAF_COLOR_PRESETS;
+

package/src/environment/WeatherLayer/particles.ts

@@ -0,0 +1,227 @@
+import type { Particle, WeatherConfig, WeatherType } from './types';
+import { WEATHER_CONFIGS } from './types';
+import type { EnvironmentStylePreset } from '../shared/types';
+
+function smoothstep(edge0: number, edge1: number, x: number) {
+  const t = Math.max(0, Math.min(1, (x - edge0) / (edge1 - edge0)));
+  return t * t * (3 - 2 * t);
+}
+
+function getSpawnPosition(
+  bounds: { width: number; height: number },
+  velocity: { x: number; y: number }
+) {
+  const margin = 40;
+  if (Math.abs(velocity.x) > Math.abs(velocity.y)) {
+    return {
+      x: velocity.x > 0 ? -margin : bounds.width + margin,
+      y: Math.random() * bounds.height,
+    };
+  }
+
+  return {
+    x: Math.random() * bounds.width,
+    y: velocity.y > 0 ? -margin : bounds.height + margin,
+  };
+}
+
+function getLifeRangeMs(type: WeatherType): [number, number] {
+  switch (type) {
+    case 'rain':
+      return [900, 2200];
+    case 'snow':
+      return [3200, 7200];
+    case 'dust':
+      return [5000, 11000];
+    case 'leaves':
+      return [6000, 14000];
+    case 'embers':
+      return [2600, 6500];
+    case 'fireflies':
+      return [4500, 9000];
+    case 'ash':
+      return [4500, 10000];
+    case 'sakura':
+      return [6500, 15000];
+    case 'sparks':
+      return [450, 1200];
+    case 'spores':
+      return [5000, 12000];
+    default:
+      return [3000, 8000];
+  }
+}
+
+export function createParticle(
+  id: number,
+  type: WeatherType,
+  config: WeatherConfig,
+  wind: { x: number; y: number },
+  bounds: { width: number; height: number },
+  stylePreset: EnvironmentStylePreset = 'ui',
+  colorsOverride?: readonly string[]
+): Particle {
+  const [minSize, maxSize] = config.sizeRange;
+  const [minOpacity, maxOpacity] = config.opacityRange;
+  const [minSpeed, maxSpeed] = config.speedRange;
+
+  const speed = minSpeed + Math.random() * (maxSpeed - minSpeed);
+  let vx = wind.x * speed;
+  let vy = wind.y * speed;
+
+  const depth = stylePreset === 'cinematic' ? Math.sqrt(Math.random()) : 0;
+  const sizeScale = stylePreset === 'cinematic' ? 0.55 + (1 - depth) * 0.45 : 1;
+  const speedScale = stylePreset === 'cinematic' ? 0.6 + (1 - depth) * 0.4 : 1;
+  const opacityScale = stylePreset === 'cinematic' ? 0.45 + (1 - depth) * 0.55 : 1;
+
+  switch (config.motionStyle) {
+    case 'fall':
+      vy = speed;
+      vx = wind.x * 2 + (Math.random() - 0.5) * 0.5;
+      break;
+    case 'rise':
+      vy = -speed;
+      vx = wind.x + (Math.random() - 0.5) * 2;
+      break;
+    case 'drift': {
+      // Some particles should always "fall" even when drifting (snow, leaves, petals).
+      const allowUpdraft = type === 'dust' || type === 'fireflies';
+      const verticalSign = allowUpdraft ? (Math.random() > 0.5 ? 1 : -1) : 1;
+
+      const driftFallScale =
+        type === 'snow' ? 0.35 :
+          type === 'leaves' ? 0.55 :
+            type === 'sakura' ? 0.45 :
+              0.3;
+
+      vy = speed * driftFallScale * verticalSign;
+      vx = wind.x + (Math.random() - 0.5) * 2;
+      break;
+    }
+    case 'erratic':
+      vy = (Math.random() - 0.3) * speed;
+      vx = (Math.random() - 0.5) * speed * 2;
+      break;
+  }
+
+  vx *= speedScale;
+  vy *= speedScale;
+
+  const [minLife, maxLife] = getLifeRangeMs(type);
+  const maxLifeMs = minLife + Math.random() * (maxLife - minLife);
+  const palette = colorsOverride && colorsOverride.length > 0 ? colorsOverride : config.colors;
+  const color = palette.length > 0 ? palette[Math.floor(Math.random() * palette.length)] : '#ffffff';
+  const baseOpacity = (minOpacity + Math.random() * (maxOpacity - minOpacity)) * opacityScale;
+  const baseSize = (minSize + Math.random() * (maxSize - minSize)) * sizeScale;
+
+  // Only some weather types should visibly twinkle.
+  const twinkleAmountBase =
+    type === 'fireflies' ? 0.55 :
+      type === 'sparks' ? 0.35 :
+        type === 'embers' ? 0.18 :
+          type === 'spores' ? 0.12 :
+            0;
+
+  const twinkleAmount = stylePreset === 'cinematic' ? twinkleAmountBase * 0.65 : twinkleAmountBase;
+  const twinkleSpeed =
+    type === 'sparks' ? 0.03 :
+      type === 'fireflies' ? 0.008 :
+        type === 'embers' ? 0.01 :
+          type === 'spores' ? 0.007 :
+            0;
+
+  const driftPhase = Math.random() * Math.PI * 2;
+  const twinklePhase = Math.random() * Math.PI * 2;
+
+  const velocity = { x: vx, y: vy };
+  const spawn = getSpawnPosition(bounds, velocity);
+
+  const rotation =
+    config.shape === 'streak'
+      ? (Math.atan2(velocity.y, velocity.x) * 180) / Math.PI - 90
+      : Math.random() * 360;
+
+  const rotationSpeed =
+    config.shape === 'leaf' || config.shape === 'petal'
+      ? (stylePreset === 'cinematic' ? 0.03 : 0.06) * (Math.random() > 0.5 ? 1 : -1)
+      : 0;
+
+  return {
+    id,
+    x: spawn.x,
+    y: spawn.y,
+    size: baseSize,
+    opacity: baseOpacity,
+    rotation,
+    rotationSpeed,
+    velocity,
+    life: 0,
+    maxLife: maxLifeMs,
+    color,
+    baseOpacity,
+    depth,
+    driftPhase,
+    twinklePhase,
+    twinkleSpeed,
+    twinkleAmount,
+  };
+}
+
+export function updateParticle(
+  particle: Particle,
+  config: WeatherConfig,
+  deltaTime: number
+): Particle {
+  const newLife = particle.life + deltaTime;
+  const lifeRatio = newLife / particle.maxLife;
+
+  // Fade in/out
+  const fadeIn = smoothstep(0, 0.08, lifeRatio);
+  const fadeOut = 1 - smoothstep(0.82, 1, lifeRatio);
+  let opacity = particle.baseOpacity * fadeIn * fadeOut;
+
+  if (particle.twinkleAmount > 0 && particle.twinkleSpeed > 0) {
+    const tw = Math.sin(newLife * particle.twinkleSpeed + particle.twinklePhase);
+    opacity *= Math.max(0.15, 1 + tw * particle.twinkleAmount * 0.5);
+  }
+
+  // Add some drift variation
+  let vx = particle.velocity.x;
+  let vy = particle.velocity.y;
+
+  if (config.motionStyle === 'drift') {
+    vx += Math.sin(newLife * 0.002 + particle.driftPhase) * 0.18;
+    vy += Math.cos(newLife * 0.0016 + particle.driftPhase) * 0.07;
+  } else if (config.motionStyle === 'erratic') {
+    vx += Math.sin(newLife * 0.01 + particle.driftPhase) * 0.25;
+    vy += Math.cos(newLife * 0.012 + particle.driftPhase) * 0.18;
+  }
+
+  return {
+    ...particle,
+    x: particle.x + vx * deltaTime * 0.1,
+    y: particle.y + vy * deltaTime * 0.1,
+    rotation: particle.rotation + particle.rotationSpeed * deltaTime,
+    life: newLife,
+    opacity,
+  };
+}
+
+export function getParticleCount(
+  type: WeatherType,
+  intensity: number,
+  maxParticles: number,
+  stylePreset: EnvironmentStylePreset = 'ui'
+): number {
+  const config = WEATHER_CONFIGS[type];
+  const styleScale =
+    stylePreset === 'cinematic'
+      ? type === 'snow'
+        ? 1.8
+        : type === 'leaves'
+          ? 1.4
+          : 0.7
+      : 1;
+  const desired = Math.floor(config.baseCount * intensity * styleScale);
+  return Math.min(desired, maxParticles);
+}

package/src/environment/WeatherLayer/types.ts

@@ -0,0 +1,140 @@
+import type { BaseLayerProps } from '../shared/types';
+import type { AutumnLeafColorPreset } from './leafPresets';
+
+export type WeatherType =
+  | 'rain' | 'snow' | 'dust' | 'leaves' | 'embers'
+  | 'fireflies' | 'ash' | 'sakura' | 'sparks' | 'spores';
+
+export interface WeatherLayerProps extends BaseLayerProps {
+  type: WeatherType;
+  wind?: { x: number; y: number };
+  color?: string;
+  colors?: readonly string[];
+  leafColorPreset?: AutumnLeafColorPreset;
+  opacity?: number;
+  blur?: boolean;
+  maxParticles?: number;
+}
+
+export interface Particle {
+  id: number;
+  x: number;
+  y: number;
+  size: number;
+  opacity: number;
+  rotation: number;
+  rotationSpeed: number;
+  velocity: { x: number; y: number };
+  life: number;
+  maxLife: number;
+  color: string;
+  baseOpacity: number;
+  depth: number; // 0 (near) → 1 (far)
+  driftPhase: number;
+  twinklePhase: number;
+  twinkleSpeed: number;
+  twinkleAmount: number;
+}
+
+export interface WeatherConfig {
+  baseCount: number;
+  sizeRange: [number, number];
+  opacityRange: [number, number];
+  speedRange: [number, number];
+  motionStyle: 'fall' | 'rise' | 'drift' | 'erratic';
+  shape: 'circle' | 'streak' | 'leaf' | 'petal' | 'glow';
+  colors: string[];
+}
+
+export const WEATHER_CONFIGS: Record<WeatherType, WeatherConfig> = {
+  rain: {
+    baseCount: 200,
+    sizeRange: [1, 3],
+    opacityRange: [0.4, 0.7],
+    speedRange: [15, 25],
+    motionStyle: 'fall',
+    shape: 'streak',
+    colors: ['#a0c4ff', '#bde0fe'],
+  },
+  snow: {
+    baseCount: 150,
+    sizeRange: [2, 6],
+    opacityRange: [0.6, 0.9],
+    speedRange: [1, 3],
+    motionStyle: 'drift',
+    shape: 'circle',
+    colors: ['#ffffff', '#e8f4ff'],
+  },
+  dust: {
+    baseCount: 80,
+    sizeRange: [1, 3],
+    opacityRange: [0.2, 0.4],
+    speedRange: [0.5, 2],
+    motionStyle: 'drift',
+    shape: 'circle',
+    colors: ['#d4a574', '#c9b896'],
+  },
+  leaves: {
+    baseCount: 30,
+    sizeRange: [6, 12],
+    opacityRange: [0.7, 1.0],
+    speedRange: [2, 5],
+    motionStyle: 'drift',
+    shape: 'leaf',
+    colors: ['#d4a373', '#e07b39', '#bc6c25'],
+  },
+  embers: {
+    baseCount: 60,
+    sizeRange: [2, 5],
+    opacityRange: [0.5, 0.8],
+    speedRange: [2, 5],
+    motionStyle: 'rise',
+    shape: 'glow',
+    colors: ['#ff6b35', '#f7931e', '#ffcc00'],
+  },
+  fireflies: {
+    baseCount: 40,
+    sizeRange: [3, 6],
+    opacityRange: [0.3, 1.0],
+    speedRange: [0.3, 1],
+    motionStyle: 'drift',
+    shape: 'glow',
+    colors: ['#90ee90', '#adff2f', '#7fff00'],
+  },
+  ash: {
+    baseCount: 100,
+    sizeRange: [2, 5],
+    opacityRange: [0.3, 0.6],
+    speedRange: [1, 3],
+    motionStyle: 'fall',
+    shape: 'circle',
+    colors: ['#4a4a4a', '#6b6b6b', '#8b8b8b'],
+  },
+  sakura: {
+    baseCount: 50,
+    sizeRange: [6, 12],
+    opacityRange: [0.6, 0.9],
+    speedRange: [1, 3],
+    motionStyle: 'drift',
+    shape: 'petal',
+    colors: ['#ffb7c5', '#ff69b4', '#ffc0cb'],
+  },
+  sparks: {
+    baseCount: 40,
+    sizeRange: [1, 3],
+    opacityRange: [0.7, 1.0],
+    speedRange: [8, 15],
+    motionStyle: 'erratic',
+    shape: 'glow',
+    colors: ['#ffd700', '#ffffff', '#fffacd'],
+  },
+  spores: {
+    baseCount: 60,
+    sizeRange: [4, 8],
+    opacityRange: [0.4, 0.7],
+    speedRange: [0.5, 1.5],
+    motionStyle: 'rise',
+    shape: 'glow',
+    colors: ['#9370db', '#8a2be2', '#da70d6'],
+  },
+};

package/src/environment/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Environment primitives
+ *
+ * Atmospheric and environmental effect components:
+ * - WeatherLayer: Particle-based weather effects (rain, snow, dust, etc.)
+ * - FogLayer: Fog and mist effects
+ * - VolumetricLight: Light shafts, godrays, and glow effects
+ * - AuroraLayer: Sky and aurora effects
+ * - EnvironmentLayer: Convenience wrapper combining all layers with presets
+ */
+
+export * from "./WeatherLayer";
+export * from "./FogLayer";
+export * from "./VolumetricLight";
+export * from "./AuroraLayer";
+export * from "./EnvironmentLayer";
+export * from "./shared";

package/src/environment/shared/index.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './performance';

package/src/environment/shared/noise.ts

@@ -0,0 +1,10 @@
+const NOISE_SVG = `<svg xmlns="http://www.w3.org/2000/svg" width="200" height="200" viewBox="0 0 200 200">
+  <filter id="n">
+    <feTurbulence type="fractalNoise" baseFrequency="0.9" numOctaves="3" seed="2" stitchTiles="stitch" />
+    <feColorMatrix type="saturate" values="0" />
+  </filter>
+  <rect width="200" height="200" filter="url(#n)" opacity="0.55" />
+</svg>`;
+
+export const NOISE_DATA_URL = `data:image/svg+xml,${encodeURIComponent(NOISE_SVG)}`;
+

package/src/environment/shared/performance.ts

@@ -0,0 +1,33 @@
+import { PERFORMANCE_PRESETS, type PerformanceTier, type PerformanceConfig } from './types';
+
+export function detectPerformanceTier(): PerformanceTier {
+  if (typeof window === 'undefined') return 'medium';
+
+  // Check reduced motion first
+  if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+    return 'minimal';
+  }
+
+  // Check device memory (Chrome only)
+  const nav = navigator as Navigator & { deviceMemory?: number };
+  if (nav.deviceMemory && nav.deviceMemory < 4) {
+    return 'low';
+  }
+
+  // Check hardware concurrency
+  if (navigator.hardwareConcurrency && navigator.hardwareConcurrency < 4) {
+    return 'low';
+  }
+
+  // Check if mobile
+  const isMobile = /Android|iPhone|iPad|iPod/i.test(navigator.userAgent);
+  if (isMobile) return 'low';
+
+  // Default to medium
+  return 'medium';
+}
+
+export function getPerformanceConfig(tier?: PerformanceTier): PerformanceConfig {
+  const detected = tier ?? detectPerformanceTier();
+  return PERFORMANCE_PRESETS[detected];
+}

package/src/environment/shared/types.ts

@@ -0,0 +1,26 @@
+export type PerformanceTier = 'high' | 'medium' | 'low' | 'minimal';
+
+export type EnvironmentStylePreset = 'cinematic' | 'ui';
+
+export interface PerformanceConfig {
+  tier: PerformanceTier;
+  maxParticles: number;
+  useShaders: boolean;
+  targetFPS: number;
+}
+
+export const PERFORMANCE_PRESETS: Record<PerformanceTier, PerformanceConfig> = {
+  high: { tier: 'high', maxParticles: 2000, useShaders: true, targetFPS: 60 },
+  medium: { tier: 'medium', maxParticles: 800, useShaders: true, targetFPS: 60 },
+  low: { tier: 'low', maxParticles: 300, useShaders: false, targetFPS: 30 },
+  minimal: { tier: 'minimal', maxParticles: 0, useShaders: false, targetFPS: 0 },
+};
+
+export interface BaseLayerProps {
+  intensity?: number;
+  speed?: number;
+  stylePreset?: EnvironmentStylePreset;
+  enabled?: boolean;
+  className?: string;
+  style?: React.CSSProperties;
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './three/index.js';
+export * from './environment/index.js';

package/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/src/lib/vision-types.ts

@@ -0,0 +1,84 @@
+/**
+ * Vision types - copied from @backbay/glia/vision to avoid circular dependency.
+ * Canonical source: packages/glia/src/vision/types.ts
+ */
+
+export interface VisionSize {
+  width: number;
+  height: number;
+}
+
+export interface VisionCameraPose {
+  position: [number, number, number];
+  target: [number, number, number];
+  up?: [number, number, number];
+  fov?: number;
+  projectionMatrix?: number[];
+}
+
+export interface VisionChannel<T = unknown> {
+  id: string;
+  kind: string;
+  data: T;
+  width?: number;
+  height?: number;
+  meta?: Record<string, unknown>;
+}
+
+export interface VisionTopologyNode {
+  id: string;
+  type: string;
+  label?: string;
+  position?: [number, number, number];
+  radius?: number;
+  bounds?: {
+    min: [number, number, number];
+    max: [number, number, number];
+  };
+  color?: string;
+  meta?: Record<string, unknown>;
+}
+
+export interface VisionTopologyEdge {
+  id?: string;
+  from: string;
+  to: string;
+  type?: string;
+  color?: string;
+  weight?: number;
+  meta?: Record<string, unknown>;
+}
+
+export interface VisionTopology {
+  id?: string;
+  source?: string;
+  updatedAt: number;
+  nodes: VisionTopologyNode[];
+  edges?: VisionTopologyEdge[];
+  meta?: Record<string, unknown>;
+}
+
+export interface VisionFrame {
+  id?: string;
+  source: string;
+  capturedAt: number;
+  size?: VisionSize;
+  camera?: VisionCameraPose;
+  channels?: VisionChannel[];
+  topology?: VisionTopology;
+  meta?: Record<string, unknown>;
+}
+
+export interface VisionCaptureOptions {
+  size?: VisionSize;
+  includeTopology?: boolean;
+  includeCamera?: boolean;
+  signal?: AbortSignal | null;
+}
+
+export interface VisionAdapter {
+  id: string;
+  label?: string;
+  capture(options?: VisionCaptureOptions): Promise<VisionFrame>;
+  getTopology?: () => VisionTopology | null;
+}