Skip to content

feat: add Three.js splash screen on app startup#48

Merged
j4rviscmd merged 1 commit intomainfrom
feat/splash-screen
Mar 25, 2026
Merged

feat: add Three.js splash screen on app startup#48
j4rviscmd merged 1 commit intomainfrom
feat/splash-screen

Conversation

@j4rviscmd
Copy link
Copy Markdown
Owner

Summary

Add a full-screen animated splash screen that displays during app initialization. The splash shows a constellation particle field with a slowly rotating wireframe icosahedron behind the "Scripta" wordmark.

Changes

New files (6)

  • src/features/splash/lib/constants.ts — Configuration constants (particle count, colors, timing)
  • src/features/splash/lib/createScene.ts — Pure Three.js scene factory (particles + connection lines + wireframe icosahedron)
  • src/features/splash/hooks/useSplashLifecycle.ts — Lifecycle state machine (active → fading → done)
  • src/features/splash/hooks/useThreeScene.ts — React ↔ Three.js imperative bridge with dynamic import
  • src/features/splash/ui/SplashScreen.tsx — Full-screen overlay component with fade-out transition
  • src/features/splash/index.ts — Public API barrel export

Modified files (2)

  • src/app/providers/store-provider.tsx — Export storeInitPromise for splash timing coordination
  • src/main.tsx — Add <SplashScreen /> as overlay sibling

Dependencies

  • Added three and @types/three

Architecture

Follows the Clean architecture pattern with clear separation of concerns:

features/splash/
├── index.ts              # Public API
├── ui/SplashScreen.tsx   # React overlay + text
├── hooks/
│   ├── useSplashLifecycle.ts  # Timing state machine
│   └── useThreeScene.ts      # Three.js bridge
└── lib/
    ├── constants.ts      # Configuration
    └── createScene.ts    # Pure Three.js scene

Behavior

  1. Splash appears immediately on app launch (dark background + "Scripta" text)
  2. Three.js constellation loads via dynamic import (~50ms)
  3. Waits for both: store initialization AND minimum 2-second display
  4. Smooth 700ms opacity fade-out
  5. Component unmounts, Three.js resources fully disposed

Technical Notes

  • Three.js is code-split via dynamic import() — separate Vite chunk, not in main bundle
  • StrictMode-safe: cleanup guards prevent double-creation
  • Full GPU resource cleanup on dispose (geometries, materials, renderer)
  • Zero changes to Rust backend

Add a full-screen animated splash screen that displays during app
initialization. The splash shows a constellation particle field with
a slowly rotating wireframe icosahedron behind the "Scripta" wordmark.

The splash remains visible until both the store initialization completes
and a minimum 2-second display time has elapsed, then fades out smoothly.

Implementation follows the Clean architecture pattern with clear
separation of concerns:
- lib/constants.ts: configuration constants
- lib/createScene.ts: pure Three.js scene factory
- hooks/useSplashLifecycle.ts: lifecycle state machine
- hooks/useThreeScene.ts: React ↔ Three.js bridge
- ui/SplashScreen.tsx: overlay component

Three.js is loaded via dynamic import() for automatic code-splitting,
keeping it out of the main bundle.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@j4rviscmd j4rviscmd merged commit a52d3b2 into main Mar 25, 2026
@j4rviscmd j4rviscmd deleted the feat/splash-screen branch March 25, 2026 14:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant