A Gift For Anne

A timeline based on https://tlb.betteroff.studio/. The following is a summary of its contents and behaviour.

🎨 Features

• Cinematic Horizontal Timeline - Smooth scrolling archive of visual memories
• Premium Typography - Bold editorial design with mix-blend-mode color inversion
• Physics-Based Scrolling - Lenis smooth scroll with momentum and inertia
• Interactive Sound Effects - High-quality audio feedback with Howler.js
• Video Support - Autoplay/pause video cards with viewport detection
• Music Player - Fully functional audio playback with Howler.js
• Sticky Notes - Draggable notes with paper textures, deletion animations, and optional realtime sync across users
• Timeline Ruler - Synced date ruler with animated tick sounds
• Responsive Design - Optimized for desktop, tablet, and mobile
• Accessibility - WCAG AA compliant with keyboard navigation
• Performance - 60fps animations, lazy loading, optimized images

🚀 Getting Started

Prerequisites

• Node.js 18+ and npm/pnpm/yarn
• Modern browser (Chrome, Firefox, Safari, Edge)

Installation

1. Clone and navigate to the project:

2. Install dependencies:

npm install

3. Add sound effects (optional): See SOUND_SETUP.md for detailed instructions on adding high-quality sound files.

4. Run the development server:

npm run dev

5. Open your browser: Navigate to http://localhost:3000

6. Validate timeline media mappings (recommended):

npm run validate:timeline

Build for Production

npm run build
npm start

📁 Project Structure

hiromix/
├── src/
│   ├── app/
│   │   ├── layout.tsx          # Root layout with fonts and metadata
│   │   ├── page.tsx             # Homepage with all components
│   │   └── globals.css          # Global styles and Tailwind
│   ├── components/
│   │   ├── Navigation.tsx       # Top navigation menu
│   │   ├── HeroHeader.tsx       # Fixed central header with inversion
│   │   ├── TimelineCarousel.tsx # Main horizontal carousel
│   │   ├── TimelineCard.tsx     # Image card component
│   │   ├── VideoCard.tsx        # Video card with autoplay
│   │   ├── TimelineRuler.tsx    # Bottom timeline ruler
│   │   ├── MusicPlayer.tsx      # Music widget with Howler.js
│   │   └── QueueDropdown.tsx    # Expandable music queue
│   ├── data/
│   │   ├── timeline.ts          # Timeline items mock data
│   │   └── music.ts             # Music tracks mock data
│   ├── types/
│   │   └── index.ts             # TypeScript interfaces
│   └── lib/
│       └── utils.ts             # Utility functions
├── public/                      # Static assets
├── next.config.mjs              # Next.js configuration
├── tailwind.config.ts           # Tailwind theme customization
├── tsconfig.json                # TypeScript configuration
└── package.json                 # Dependencies and scripts

Technologies

• Framework: Next.js 14+ (App Router)
• Language: TypeScript 5+
• Styling: Tailwind CSS 3+
• Animation: Framer Motion 12+
• Smooth Scroll: Lenis 1.0+
• Audio: Howler.js 2.2+
• Images: Unsplash API (via Next.js Image)
• Icons: Lucide React

Customization

Adding Your Own Content

📖 See CONTENT_GUIDE.md for complete instructions on adding your images and videos!

The timeline automatically positions content based on dates and adjusts spacing dynamically:

• Expands when photos are sparse (more space between items)
• Contracts to minimum spacing when photos are dense
• Date-based positioning ensures chronological accuracy

Quick Start:

1. Create folders: public/media/images/ and public/media/videos/
2. Add your media files
3. Edit src/data/timeline.ts with your content and dates

Timeline Items:

{
  id: "unique-id",
  title: "Project Title",
  date: "2024-06-15T00:00:00.000Z", // ISO 8601 format required
  type: "image" | "video",
  src: "/media/images/photo.jpg",
  width: "portrait" | "square" | "landscape",
  category: "Category Name",
  videoSrc: "/media/videos/clip.mp4" // for video type
}

Music Tracks:

{
  id: "unique-id",
  title: "Song Title",
  artist: "Artist Name",
  album: "Album Name",
  albumArt: "cover-art-url",
  audioSrc: "audio-file-url",
  duration: 263 // in seconds
}

Customizing Theme

Edit tailwind.config.ts to modify:

• Colors (currently monochrome)
• Typography scale
• Animation timing
• Breakpoints

Header Text

Edit the header text in src/components/HeroHeader.tsx:

<span>YOUR BRAND®</span>
<span>YOUR TAGLINE</span>
<span>(YEAR)</span>

Loading Screen (Pond + GIF + Percentage)

The homepage now includes a loading screen on every full page load/reload with:

• A pond background image
• A centered loading GIF
• A time-based percentage counter (default ~3 seconds)

1. Place your assets in:
   • public/assets/loading/pond-background.jpg
   • public/assets/loading/loading.gif
2. Edit settings in src/lib/loadingScreenConfig.ts:
   • durationMs (loading length)
   • pondBackgroundSrc and loadingGifSrc (asset paths)
   • heading (loading label text)
3. Load behavior:
   • The loader replays each time the website is reloaded.

Sound Effects

The website includes interactive sound effects:

• Timeline Ticks - Mechanical clicks as you scroll through time (velocity-based)
• Paper Sounds - Realistic foley for note interactions (pickup, place, crumple, fall)
• Sound Controls - Toggle and volume control in bottom-right corner

Sound files need to be added separately. See SOUND_SETUP.md for:

• Required sound files and formats
• Free sources (Freesound, Zapsplat, BBC)
• Conversion instructions
• Audio specifications

The sound system works gracefully without audio files - it will display console warnings but won't break functionality.

⌨️ Keyboard Navigation

• Tab - Navigate through interactive elements
• Arrow Keys - Scroll timeline (when focused)
• Space/Enter - Activate buttons
• Esc - Close dropdowns

Performance Features

• Lazy Loading - Images and videos load on demand
• Code Splitting - Dynamic imports for optimal bundles
• GPU Acceleration - Transform-based animations
• Responsive Images - WebP/AVIF with Next.js Image
• Reduced Motion - Respects user preferences

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Deployment

Vercel (Recommended)

1. Push to GitHub
2. Import project in Vercel
3. Deploy automatically
4. Add NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY for shared realtime sticky notes

Other Platforms

Build the static export:

npm run build

Deploy the .next folder to your hosting provider.

Environment Variables

Create a .env.local file for custom configuration:

# Optional: Custom Unsplash API key for higher rate limits
NEXT_PUBLIC_UNSPLASH_ACCESS_KEY=your_key_here

# Optional: Supabase realtime sticky notes
NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

# Optional: feature flag (default true)
NEXT_PUBLIC_STICKY_NOTES_REALTIME=true

Realtime Sticky Notes Setup (Supabase)

To share sticky note changes instantly between multiple visitors, configure Supabase:

1. Create a Supabase project.
2. Run supabase/sticky_notes_schema.sql in the Supabase SQL editor.
3. Copy your project URL and anon key into .env.local (and Vercel env vars).
4. Redeploy your site on Vercel.

When Supabase vars are not configured (or when NEXT_PUBLIC_STICKY_NOTES_REALTIME=false), sticky notes automatically fall back to localStorage-only behavior.

Credits

• Design Inspiration: Museum archives, editorial design, luxury fashion websites
• Images: Unsplash API
• Sample Audio: SoundHelix (royalty-free)

License

This project is for portfolio/educational use. Replace all placeholder content with your own before production deployment.

---

Built with ❤️ using Next.js, TypeScript, and Framer Motion