Creative Web Algorithm

Creative Web Algorithm v3.0

Transform STATE A → STATE B while preserving valid behavior, proving each significant change, and delivering a production-grade experience. Never begin by editing.

Operating Contract (Inviolable)

1. Observe before modifying. Map the entire runtime before touching a single line.
2. Never patch unknown runtimes, exported snapshots, iframes, or minified bundles until execution model is fully mapped.
3. Component decisions only: Keep, Refactor, Replace, Remove, or mark Unknown. Never remove without evidence.
4. Strict separation: RENDERING ≠ UI ≠ ANIMATION ≠ STATE ≠ ASSETS ≠ PERFORMANCE_POLICY. Each layer has its own module, its own tests, its own lifecycle.
5. Never claim a feature exists until it has been run and tested in a real browser. Console + Network + Performance tabs required.
6. Prefer reversible incremental migrations over rewrites. Every change must be rollbackable in ≤1 commit.
7. If the format prevents reliable development, extract/reconstruct the runtime first. Stop, diagnose, rebuild the foundation before continuing.
8. One owned render loop. One state machine. One source of truth for scene state. No orphaned RAF handles, no duplicate loops.
9. Memory is a first-class concern. Every GPU resource, every listener, every timer must have an explicit disposal path.
10. Accessibility is non-negotiable. Every visual effect must have a reduced-motion fallback and keyboard/screen-reader equivalent.

Phase 0 — OBSERVE (Zero Modifications)

Goal: Produce a complete Architecture Map before writing any code.

Scan Checklist

Output: Architecture Map

# Architecture Map — [Project Name]

## Entry Points
- [ ] Primary: [file] → [initialization sequence]
- [ ] Secondary: [file] → [purpose]

## Module Graph
- [module A] imports [B, C]
- [module B] exports [X, Y]
- [module C] depends on [D, E]

## State Management
- [ ] Single source of truth: [store/context/prop]
- [ ] Derived state: [computed values]
- [ ] Side effects: [saga/epic/effect]

## Render Architecture
- [ ] Primary renderer: [Three.js/Canvas2D/WebGL]
- [ ] Secondary renderers: [overlays, post-processing]
- [ ] Render loop ownership: [which module]

## Asset Pipeline
- [ ] Loading strategy: [lazy/eager/prefetch]
- [ ] Cache policy: [memory/disk/None]
- [ ] Fallback assets: [low-res/progressive]

## Performance Profile
- [ ] Current FPS: [target/described]
- [ ] Memory budget: [bytes]
- [ ] Frame budget: [ms]
- [ ] Bundle size: [KB]

## Known Issues
- [ ] [Issue description, evidence, impact]

Dependency Graph (ASCII)

[Entry] → [Renderer] → [Scene] → [Camera]
              ↓              ↓
        [PostFX]        [Lights]
              ↓              ↓
        [UI Layer] ← [State Store]
              ↓
        [Animation] → [Assets]

Phase 1 — CLASSIFY

Goal: Create a Component Decision Map with evidence for every component.

Decision Categories

Decision Record Format

## Component Decision Map

### [Component Name]
- **Location:** [file:line]
- **Current state:** [working/broken/debt]
- **Evidence:** [test results, performance metrics, bug reports]
- **Decision:** KEEP / REFACTOR / REPLACE / REMOVE / UNKNOWN
- **Rationale:** [why this decision]
- **Risk if wrong:** [what breaks]
- **Reversibility:** [how to undo]

### [Next Component]
...

Evidence Requirements

• Performance data: FPS benchmarks, memory snapshots, frame timing
• Functional tests: Unit tests passing/failing, integration test results
• User feedback: Bug reports, support tickets, analytics data
• Code quality: Cyclomatic complexity, bundle impact, coupling metrics

Phase 2 — DETECT FAILURE MODES

Goal: For every issue, record CAUSE → EFFECT → FIX. Fix causes, not symptoms.

Failure Mode Catalog

Failure Mode Report

## Failure Mode Analysis

### F-001: [Title]
- **Severity:** Critical / High / Medium / Low
- **CAUSE:** [root cause]
- **EFFECT:** [observable impact]
- **FIX:** [specific solution]
- **Evidence:** [data proving this]
- **Prevention:** [how to avoid in future]

Phase 3 — DEFINE TARGET ARCHITECTURE

Goal: Create a maintainable, scalable structure with strict layer separation.

Canonical Directory Structure

project/
├── src/
│   ├── scene/              # Scene graph, objects, entities
│   │   ├── index.ts
│   │   ├── Camera.ts       # Camera management, transitions
│   │   ├── Lights.ts       # Lighting system
│   │   ├── Objects/        # Reusable 3D objects
│   │   │   ├── Indexed.ts  # Pre-registered geometries
│   │   │   └── Materials/  # Material definitions
│   │   └── Environment/    # Sky, fog, post-processing
│   ├── renderer/           # Renderer configuration, context
│   │   ├── index.ts
│   │   ├── WebGLContext.ts # Context creation, loss handling
│   │   └── PostFX/         # Bloom, SSAO, chromatic, etc.
│   ├── shaders/            # GLSL source code
│   │   ├── common.glsl
│   │   ├── vertex/
│   │   └── fragment/
│   ├── effects/            # Visual effects pipeline
│   │   ├── LiquidGlass.ts
│   │   ├── Chromatic.ts
│   │   ├── Haze.ts
│   │   └── Particles.ts
│   ├── animation/          # Animation system
│   │   ├── Animator.ts     # Main animation controller
│   │   ├── Tweens.ts       # Easing functions
│   │   └── Timeline.ts     # Sequenced animations
│   ├── ui/                 # HTML/CSS overlay layer
│   │   ├── components/
│   │   ├── styles/
│   │   └── state/          # UI state (separate from scene state)
│   ├── assets/             # Static assets, textures, models
│   │   ├── textures/
│   │   ├── models/
│   │   └── audio/
│   ├── state/              # Single source of truth for scene state
│   │   ├── Store.ts        # Centralized state management
│   │   └── selectors.ts    # Derived state
│   ├── utils/              # Shared utilities
│   │   ├── math.ts
│   │   ├── geometry.ts
│   │   └── helpers.ts
│   └── main.ts             # Entry point, boot sequence
├── tests/
│   ├── unit/
│   ├── integration/
│   └── visual/
├── public/
│   └── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
└── README.md

Architecture Rules

1. RENDERING ≠ UI ≠ ANIMATION ≠ STATE ≠ ASSETS ≠ PERFORMANCE — Each module owns its domain, never crosses boundaries without explicit interfaces.
2. Single source of truth — Scene state lives in state/Store.ts. UI state lives in ui/state/. Never duplicate.
3. Renderer is agnostic — renderer/ knows nothing about scene content. Scene provides geometries; renderer draws them.
4. Animation is parameterized — All motion derives from time, delta, velocity, damping, easing. Never hardcode frame counts.
5. Assets are lazy — Load on demand. Preload only critical path (<100KB).
6. Effects are composable — PostFX pipeline is a chain. Add/remove without affecting core render.
7. Cleanup is mandatory — Every module exports dispose(). Call it on unmount/context loss.

Phase 4 — BUILD THE VISUAL SYSTEM

Goal: Create a layered scene graph with explicit depth, parallax, and motion policy.

Scene Graph Layers (Front to Back)

┌─────────────────────────────────┐
│  UI LAYER                       │  ← HTML/CSS overlay, interactive controls
│  ─────────────────────────────  │
│  INTERACTION LAYER              │  ← Raycasting, pointer events, hover
│  ─────────────────────────────  │
│  PARTICLES LAYER                │  ← Atmospheric particles, ambient
│  ─────────────────────────────  │
│  SUBJECT LAYER                  │  ← Main 3D object, hero geometry
│  ─────────────────────────────  │
│  LIGHTING LAYER                 │  → Reflections, shadows, glow
│  ─────────────────────────────  │
│  ENVIRONMENT LAYER              │  → Sky, fog, ground, skybox
│  ─────────────────────────────  │
│  DEPTH LAYERS                   │  → Parallax planes, background depth
│  ─────────────────────────────  │
│  ATMOSPHERE LAYER               │  → Haze, fog, volumetric light
│  ─────────────────────────────  │
│  BACKGROUND LAYER               │  → Solid color, gradient, gradient
└─────────────────────────────────┘

Layer Configuration

Each layer has explicit properties:

interface LayerConfig {
  name: string;
  depth: number;           // 0.0 (back) to 1.0 (front)
  parallaxCoefficient: number; // 0.0 (static) to 1.0 (follows pointer)
  motionPolicy: 'static' | 'parallax' | 'animated' | 'interactive';
  opacity: number;         // 0.0 to 1.0
  visible: boolean;
  quality: 'high' | 'medium' | 'low';
}

Parameterized Inputs

Route these same inputs to ALL visual layers:

• time — clock.getElapsedTime() — drives all animations
• pointer — mouse.x, mouse.y — drives parallax, hover, interaction
• viewport — window.innerWidth/innerHeight — drives resolution, scale
• scroll — window.scrollY — drives depth, reveals, transitions
• delta — clock.getDelta() — drives frame-rate-independent motion

Anti-pattern: Applying arbitrary transforms to every element and calling it "3D". Every transform must serve a visual purpose documented in the layer config.

Phase 5 — BUILD THE MATERIAL SYSTEM SELECTIVELY

Goal: Choose materials hierarchically. Every effect must earn its place.

Material Hierarchy

Primary (One Dominant Effect): Choose ONE primary visual identity:

• Liquid Glass: MeshPhysicalMaterial with transmission: 0.85, thickness: 0.5, ior: 1.5, clearcoat: 1.0, roughness: 0.05. Creates refractive, reflective surfaces.
• Liquid Metal: MeshPhysicalMaterial with metalness: 1.0, roughness: 0.0, color: [theme], envMapIntensity: 2.0. Creates mirror-like metallic surfaces.
• Ethereal: MeshStandardMaterial with emissive, transparent, opacity: 0.3, wireframe: true. Creates ghostly, sci-fi surfaces.
• Neon Glow: MeshBasicMaterial with emissive, emissiveIntensity: 2.0, transparent: true, opacity: 0.8. Creates glowing, holographic surfaces.

Secondary (Supporting Effects):

• Reflection/Refraction: Environment maps, cubeCamera, refractionRatio
• Fresnel: FresnelMaterial or custom shader with dot(normal, viewDir)
• Displacement: displacementMap, displacementScale, vertex displacement
• Chromatic: Custom shader with RGB channel offset based on view angle

Atmospheric (Global Effects):

• Bloom: UnrealBloomPass — strength 0.5-1.5, radius 0.4, threshold 0.85
• Light Scatter: LensFlare, sprite glow, AdditiveBlending
• Haze: FogExp2 or custom depth-based fog
• RGB Shift: Custom post-process shader with chromatic aberration offset

Material Decision Rules

1. Never use a generated still image to cover or replace an existing animated canvas unless explicitly requested by the user.
2. Remove effects that do not improve composition. If a bloom pass doesn't add visual value, remove it. If a chromatic effect distracts from the subject, kill it.
3. One primary effect. Supporting effects only earn their place if they enhance the primary without competing.
4. Performance budget: Primary material <2 shader compiles. Total post-processing <3 passes.

Liquid Glass Implementation Template

// Fragment shader for liquid glass
uniform float uTime;
uniform float uTransmission;
uniform vec3 uColor;
uniform float uIOR;

void main() {
  vec3 viewDir = normalize(vViewPosition);
  vec3 normal = normalize(vNormal);
  
  // Fresnel for edge glow
  float fresnel = pow(1.0 - dot(viewDir, normal), 3.0);
  
  // Transmission for refraction
  vec3 refracted = texture2D(uTransmissionMap, vUv).rgb;
  vec3 transmitted = mix(uColor, refracted, uTransmission);
  
  // Edge glow
  vec3 edgeGlow = vec3(0.0, 0.9, 0.97) * fresnel * 0.5;
  
  gl_FragColor = vec4(transmitted + edgeGlow, 0.85 + fresnel * 0.15);
}

Phase 6 — BUILD DETERMINISTIC MOTION

Goal: All motion derives from parameterized inputs. Never hardcoded values.

Motion Parameter System

interface MotionParams {
  velocity: number;        // Base speed (units/sec)
  acceleration: number;    // Rate of change of velocity
  damping: number;         // Friction/decay (0-1)
  easing: 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' | 'elastic' | 'bounce';
  depth: number;           // Z-depth parallax coefficient
  amplitude: number;       // Max displacement
  frequency: number;       // Oscillations per second
  phase: number;           // Time offset
}

Routing Protocol

All inputs MUST route to ALL relevant transforms:

[time] → camera.transform, layer.transform, shader.uniforms, lighting.position, particle.velocity, UI.transition
[pointer] → camera.position (parallax), layer.parallax, object.rotation (follow)
[scroll] → camera.position (depth), layer.opacity (reveal), object.scale (approach)
[viewport] → renderer.dpr, camera.aspect, object.scale (responsive)

Animation Loop Contract

// ONE owned loop per renderer
class AnimationLoop {
  private rafId: number | null = null;
  private lastTime = 0;
  
  start() {
    const tick = (timestamp: number) => {
      const delta = timestamp - this.lastTime;
      this.lastTime = timestamp;
      this.update(delta, timestamp);
      this.rafId = requestAnimationFrame(tick);
    };
    this.rafId = requestAnimationFrame(tick);
  }
  
  stop() {
    if (this.rafId !== null) {
      cancelAnimationFrame(this.rafId);
      this.rafId = null;
    }
  }
  
  private update(delta: number, timestamp: number) {
    // Route delta to ALL systems:
    this.scene.update(delta);
    this.ui.update(delta);
    this.particles.update(delta);
    this.camera.update(delta);
  }
  
  dispose() {
    this.stop();
    // Clean up all listeners, observers, GPU resources
  }
}

Rules:

• Use requestAnimationFrame only through this ONE owned loop.
• Never create additional setTimeout, setInterval, or secondary RAF loops.
• Always provide dispose() that cleans up listeners, RAF handles, observers, and GPU resources.
• Use clock.getDelta() for frame-rate-independent motion. Never assume 60fps.

Phase 7 — ENFORCE PERFORMANCE

Goal: Adaptive quality with explicit budgets and mobile-specific states.

Quality Tiers

enum Quality { HIGH = 'high', MEDIUM = 'medium', LOW = 'low' }

interface QualityConfig {
  dpr: number;                    // 2, 1.5, 1
  resolution: number;             // 1, 0.75, 0.5
  particleCount: number;          // 10000, 5000, 1000
  shadowMap: { size: number, enabled: boolean }; // 2048/1024/512
  postProcessing: { bloom: boolean, ssao: boolean, chromatic: boolean };
  animationFrequency: number;     // 60, 30, 15 fps cap
  textureSize: number;            // 1024, 512, 256
  geometryDetail: number;         // high/medium/low segment counts
}

Quality Selection Logic

function selectQuality(): Quality {
  const cores = navigator.hardwareConcurrency || 2;
  const memory = (navigator as any).deviceMemory || 4;
  const dpr = Math.min(window.devicePixelRatio, 2);
  const isMobile = /Mobi|Android/i.test(navigator.userAgent);
  const fps = getBaselineFPS(); // Measure initial FPS
  
  if (isMobile || cores < 4 || memory < 4 || fps < 30) return Quality.LOW;
  if (cores < 8 || memory < 8 || dpr > 1.5 || fps < 45) return Quality.MEDIUM;
  return Quality.HIGH;
}

Degradation Cascade (Priority Order)

When performance degrades, reduce in this order:

1. Atmospheric effects first — bloom, haze, fog
2. Particles second — reduce count, simplify shader
3. Shader resolution third — lower texture sizes, fewer segments
4. Preserve the primary composition — the hero object must remain visible and coherent

Performance Budgets

Mobile State

Mobile is a distinct lower-cost rendering state, not merely a scaled desktop:

• Different geometry LODs (not just scaled down)
• Different particle systems (points vs. sprites)
• Different post-processing pipeline (no bloom on mobile)
• Touch-optimized interaction (no hover-dependent UI)
• Reduced shadow quality (no real-time shadows on LOW)

Phase 8 — REAL LOADING STATE MACHINE

Goal: Explicit, deterministic loading with no arbitrary timeouts.

State Machine

┌─────────────┐
│   BOOT      │  ← Entry point, initialize globals
└──────┬──────┘
       ↓
┌──────────────┐
│INITIALIZING  │  ← Setup modules, validate dependencies
└──────┬───────┘
       ↓
┌─────────────────┐
│LOADING_ASSETS   │  ← Load textures, models, audio, fonts
│(with progress)  │  ← Report progress to UI
└──────┬──────────┘
       ↓
┌───────────────────────┐
│INITIALIZING_RENDERER  │  ← Create WebGL context, compile shaders
└──────┬────────────────┘
       ↓
┌────────────┐
│   READY    │  ← All assets loaded, renderer initialized
└──────┬─────┘
       ↓
┌────────────┐
│  ENTERING  │  ← First render, transition in
└──────┬─────┘
       ↓
┌────────────┐
│   ACTIVE   │  ← Full interactive experience
└────┬───────┘
     ↓ (from any state)
┌─────────────────┐
│RECOVERABLE_ERROR│  ← Asset failed, context lost, etc.
└──────┬──────────┘
       ↓
┌────────────┐
│  FALLBACK  │  ← Graceful degradation, cached content, error UI
└──────┬─────┘
       ↓ (user action / retry)
┌────────────┐
│   ACTIVE   │  ← Retry successful
└────────────┘

SPECIAL: ENTERING → ACTIVE (skip, if no transition needed)

State Implementation

class LoadingStateMachine {
  state: State = 'BOOT';
  progress: number = 0;
  errors: Error[] = [];
  
  async transition(to: State) {
    const valid = this.allowedTransitions[this.state];
    if (!valid.includes(to)) throw new Error(`Invalid transition: ${this.state} → ${to}`);
    this.state = to;
    this.onStateChange(to);
  }
  
  async loadAssets(urls: string[], onProgress: (p: number) => void) {
    await this.transition('LOADING_ASSETS');
    const results = await Promise.allSettled(
      urls.map(url => fetch(url).then(r => r.blob()))
    );
    // Handle partial failures gracefully
    const successes = results.filter(r => r.status === 'fulfilled');
    const failures = results.filter(r => r.status === 'rejected');
    if (failures.length > 0 && successes.length === 0) {
      await this.transition('RECOVERABLE_ERROR');
    }
    this.progress = successes.length / urls.length;
  }
  
  // skip is ALWAYS safe and idempotent
  skip() {
    this.transition('ACTIVE'); // or FALLBACK if assets not loaded
  }
}

Rules

• Advance on actual asset/renderer readiness, never an arbitrary timeout
• Display actionable errors — "Failed to load texture X. Retry?" not "Error 404"
• Skip is always safe and idempotent — calling skip twice does nothing bad
• Enter → Active can skip if assets are cached (service worker)
• Any state → Recoverable Error → Fallback → Active for error recovery

Phase 9 — VERIFY AFTER EVERY SIGNIFICANT CHANGE

Goal: Run the full verification matrix. Never stack unverified patches.

Verification Matrix

BUILD ──────────────────────────────
  → tsc --noEmit (or equivalent)
  → Rollup/Vite build succeeds
  → No TypeScript errors
  → No bundler warnings

RUN ────────────────────────────────
  → Opens in browser without errors
  → No console errors (0 critical)
  → No console warnings (0 new)
  → Network tab: all assets load (200 OK)
  → FPS ≥ target (≥30 minimum)

INSPECT CONSOLE ────────────────────
  → Zero errors
  → Zero warnings from our code
  → No deprecated API usage
  → No CORS violations
  → No CSP violations

TEST INTERACTION ───────────────────
  → Click/hover/touch all interactive elements
  → All event handlers fire correctly
  → No duplicate listener warnings
  → Scroll works without jank

TEST BOOT ──────────────────────────
  → Fresh load: BOOT → INITIALIZING → LOADING → RENDERER → READY → ENTERING → ACTIVE
  → Progress bar updates correctly
  → Skip button works from any state
  → Error state triggers correctly on failed asset

TEST SKIP ──────────────────────────
  → Skip from BOOT: works, shows fallback
  → Skip from LOADING_ASSETS: works, shows cached content
  → Skip from INITIALIZING_RENDERER: works, shows static content
  → Skip is idempotent: calling twice = calling once

TEST RESIZE ────────────────────────
  → Window resize: camera aspect updates
  → DPR change: renderer resize triggered
  → Mobile rotate: layout adapts
  → No layout shift (CLS < 0.1)

TEST MOBILE ────────────────────────
  → Touch events work
  → Quality = LOW selected automatically
  → Reduced motion respects prefers-reduced-motion
  → No hover-dependent UI visible
  → Touch target sizes ≥ 44px

TEST PERFORMANCE ───────────────────
  → Performance tab: no long tasks (>50ms)
  → Memory: no leak over 5 min session
  → GPU: no context lost events
  → Frame time: consistent (no spikes)

VISUAL QA ──────────────────────────
  → All layers render in correct order
  → Colors match design specification
  → Typography is legible at all sizes
  → Animations are smooth (60fps target)
  → No visual artifacts, flickering, or tearing

On Failure Protocol

1. Roll back the last change (git checkout or revert)
2. Identify the exact cause (not the symptom — trace back)
3. Modify ONE thing (never multiple changes at once)
4. Test again (full verification matrix)
5. Only then proceed to next change

Anti-pattern: Stacking unverified patches. If something breaks, revert and debug one change at a time.

Phase 10 — FINAL ACCEPTANCE

Goal: All success criteria met. "The page loads" is not success.

Acceptance Checklist

• Functional: All features work as specified. No bugs. All states handled.
• Visually coherent: Design is consistent, colors match, typography is unified.
• Performant: All performance budgets met. FPS ≥ target. No jank.
• Responsive: Works on desktop, tablet, mobile. Layout adapts correctly.
• Accessible: Keyboard navigable, screen-reader friendly, prefers-reduced-motion respected, ARIA labels present.
• Maintainable: Clean architecture, documented code, modular structure, tests pass.
• Demonstrated through verification loop: All phases 9 tests pass.

Final Deliverable Package

1. Source code (all files, clean, commented)
2. Architecture notes (Architecture Map, Decision Map)
3. Performance report (FPS, memory, frame time metrics)
4. Test results (verification matrix status)
5. Documentation (README, setup instructions, API docs)
6. Assets manifest (all files, sizes, formats)
7. Deployment guide (build commands, hosting config)

Required First Response for Existing Projects

Before writing ANY code, return ONLY:

1. Architecture Map (Phase 0 output)
2. Component Decision Map (Phase 1 output)
3. Failure Modes (CAUSE → EFFECT → FIX from Phase 2)
4. Target Architecture (Phase 3 output — directory structure)
5. Implementation Sequence (ordered list of tasks, phase by phase)
6. Risks (what could go wrong, mitigation strategies)

Then wait for explicit authorization unless the user has already authorized implementation.

Anti-Patterns Catalog (Never Do These)

Debugging Strategies

Common Issues and Solutions

Canvas is black / white:

1. Check WebGL context: canvas.getContext('webgl2') — if null, browser doesn't support WebGL2
2. Check shader compilation: renderer.debug.checkShaderErrors = true
3. Check scene graph: scene.children.length > 0 — empty scene renders black
4. Check camera position: camera must be outside the near plane and facing objects

FPS drops suddenly:

1. Check particle count: scene.children.filter(c => c.isPoints).length
2. Check shadow map: renderer.shadowMap.enabled — disable if not needed
3. Check draw calls: renderer.info.render.calls — >100 is suspicious
4. Check geometry: geometry.attributes.position.count — high vertex counts kill FPS

Memory growing:

1. Take heap snapshot before and after interaction
2. Check renderer.info.memory.geometries, textures, programs
3. Look for detached DOM elements (DevTools Memory panel)
4. Check for orphaned event listeners (no cleanup on unmount)

Context lost:

1. Listen: canvas.addEventListener('webglcontextlost', handler)
2. Save state, stop all loops
3. Attempt restore: canvas.addEventListener('webglcontextrestored', handler)
4. Rebuild scene from state snapshot, not from scratch

Shader not compiling:

1. renderer.debug.checkShaderErrors = true
2. Check uniform locations: gl.getUniformLocation(program, name) — null means not found
3. Check attribute locations: same pattern
4. Verify GLSL version matches renderer (GLSL 300 es for WebGL2)

Tooling Recommendations

Code Templates

Minimal Three.js Scene (Foundation)

import * as THREE from "three";

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: false });
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
document.body.appendChild(renderer.domElement);

const clock = new THREE.Clock();
const controls = new OrbitControls(camera, renderer.domElement);
controls.enableDamping = true;

const animate = () => {
  const delta = clock.getDelta();
  const time = clock.getElapsedTime();
  controls.update();
  renderer.render(scene, camera);
  requestAnimationFrame(animate);
};
animate();

// Cleanup
window.addEventListener('beforeunload', () => {
  renderer.dispose();
  controls.dispose();
});

Loading State Machine (Implementation)

const STATES = ['BOOT', 'INITIALIZING', 'LOADING_ASSETS', 'INITIALIZING_RENDERER', 'READY', 'ENTERING', 'ACTIVE', 'RECOVERABLE_ERROR', 'FALLBACK'];
const ALLOWED = {
  BOOT: ['INITIALIZING'],
  INITIALIZING: ['LOADING_ASSETS', 'RECOVERABLE_ERROR'],
  LOADING_ASSETS: ['INITIALIZING_RENDERER', 'RECOVERABLE_ERROR'],
  INITIALIZING_RENDERER: ['READY', 'RECOVERABLE_ERROR'],
  READY: ['ENTERING'],
  ENTERING: ['ACTIVE', 'FALLBACK'],
  ACTIVE: ['RECOVERABLE_ERROR'],
  RECOVERABLE_ERROR: ['FALLBACK'],
  FALLBACK: ['ACTIVE'],
};

class StateMachine {
  constructor() { this.state = 'BOOT'; }
  async transition(to) {
    if (!ALLOWED[this.state]?.includes(to)) throw new Error(`Invalid: ${this.state} → ${to}`);
    this.state = to;
    this.onEnter(to);
  }
}

Quality Adaptation Pattern

function getConfig() {
  const isMobile = /Mobi|Android/i.test(navigator.userAgent);
  const cores = navigator.hardwareConcurrency || 2;
  const quality = isMobile || cores < 4 ? 'LOW' : cores < 8 ? 'MEDIUM' : 'HIGH';
  return QUALITY_PRESETS[quality];
}

Compact Checklist

• Observe before modify — Architecture Map complete
• Extract runtime if snapshot/iframe/CSP prevents reliable work
• One renderer loop, one state machine, explicit cleanup — No orphaned resources
• No static hero replacing working motion — Everything animated or has purpose
• One primary visual effect; supporting effects earn their place — Material hierarchy respected
• Adaptive quality and mobile state — Not just scaled desktop
• Boot/skip/error/resize/mobile tested — Full verification matrix
• Console and performance checked — Zero errors, FPS on target
• Accessible — reduced-motion, keyboard, ARIA
• Deliver source plus architecture notes when useful — Documentation complete

Version History

• v3.0 — Added: Quality tiers with budgets, mobile distinct state, accessibility requirements, anti-patterns catalog, debugging strategies, tooling recommendations, code templates, performance budgets table, material hierarchy, error recovery paths, version history
• v2.0 — Added: Liquid glass/metal material system, deterministic motion parameters, loading state machine implementation
• v1.0 — Original: Observe → Classify → Detect → Architecture → Visual → Material → Motion → Performance → Loading → Verify → Accept