Lithos

An immersive geology learning experience for exploring landscapes, rocks, and deep time.

Lithos combines cinematic storytelling with interactive scientific tools. Visitors can move from a global field atlas into geological timelines, high-resolution samples, and a scroll-directed 3D strata core—all in one responsive React application.

Highlights

• Interactive Field Atlas — explore geological sites with MapLibre and URL-addressable site selections.
• Geological Storytelling — layered motion, transitions, and PixiJS ash/sediment particle scenes.
• Deep Time Explorer — D3-powered visual chronology of major geological periods and events.
• 3D Strata Core Lab — inspect a procedural ten-layer core through a six-chapter GSAP scroll narrative.
• Sample Lab — examine high-resolution field specimens with OpenSeadragon.
• Learning Journey — course, field guide, plan, live-tour, and sign-up experiences with real navigation.
• Progressive Enhancement — route-level code splitting, reduced-motion support, mobile fallbacks, and WebGL fallbacks.

Main Routes

Route	Experience
/	Home, interactive atlas, and geological story
/course	Course overview and curriculum
/field-guides	Field guide collection
/field-guides/:guideSlug	Interactive sample laboratory
/geology	Deep Time Explorer and geology content
/geology/core-lab	Scroll-directed 3D strata experience
/plans	Membership and learning plans
/live-tour	Live field-tour experience
/sign-up	Course registration flow

Technology

• React 18, TypeScript, and Vite
• Tailwind CSS
• Motion for React and GSAP ScrollTrigger
• Three.js and React Three Fiber
• PixiJS
• MapLibre GL JS
• D3
• OpenSeadragon
• React Router
• Lucide icons

Getting Started

Requirements

• Node.js 20 or newer
• npm 10 or newer

Installation

git clone https://github.com/jackiechou1/Lithos.git
cd Lithos
npm install

Copy the optional environment template:

cp .env.example .env

On Windows PowerShell:

Copy-Item .env.example .env

Start the development server:

npm run dev

Vite will print the local preview URL in the terminal.

Environment Variables

Variable	Required	Description
VITE_MAP_STYLE_URL	No	Custom MapLibre style URL. When omitted, Lithos uses the configured demo style.

Never commit production credentials. Local .env files are ignored; .env.example remains versioned as the template.

Available Scripts

npm run dev      # Start the Vite development server
npm run build    # Type-check and build for production
npm run lint     # Run Oxlint
npm run preview  # Preview the production build locally

Project Structure

src/
├── components/   # Shared UI, motion primitives, and story sections
├── features/     # Atlas, particles, samples, and immersive core modules
├── motion/       # Shared motion configuration
├── pages/        # Route-level experiences
├── App.tsx       # Lazy-loaded routes and page transitions
└── main.tsx      # Application entry point

The heavier visual systems are isolated behind dynamic imports. MapLibre, OpenSeadragon, PixiJS, and the Three.js Core Lab load only when their experiences are requested. Rendering is paused when supported canvases leave the viewport or the browser tab becomes hidden.

Accessibility and Fallbacks

• Honors prefers-reduced-motion.
• Provides non-WebGL geological core artwork when 3D rendering is unavailable.
• Reduces particle density and interaction complexity on smaller screens.
• Preserves keyboard-accessible controls and semantic navigation.

Design and Development Documents

The repository includes the planning documents used to evolve the experience:

• CONTENT_FUNCTIONALITY_PRIORITY_PLAN.md
• GEOLOGICAL_STORY_VISUAL_PLAN.md
• HIGH_IMMERSION_PRIORITY_PLAN.md
• MOTION_PLAN.md
• blueprint.html

Production Build

npm run build
npm run preview

The production output is generated in dist/ and is intentionally excluded from Git. When deploying, configure the host to rewrite unknown paths to index.html so client-side routes work when opened directly.