# 🌐 Animated Website World
> **A scroll-scrubbed "fly through the world" interactive landing page engine.**
> Built and open-sourced by [Abdullah Formuli](https://github.com/authrain-cloud-abdullahformuli) ([@abdullahformuli](https://x.com/abdullahformuli)).
As you scroll, a pre-rendered camera glides forward through a continuous miniature 3D world with **zero visible cuts**. Scrolling doesn't just push DOM elements around — it acts as a tactile camera controller driving continuous, cinematic motion.
### ▶️ **[Live Demo → authrain-cloud-abdullahformuli.github.io/animated-website-world](https://authrain-cloud-abdullahformuli.github.io/animated-website-world/)**
<sub>▶ **[Watch the full 20-second video](img/showcase.mp4)** · or scroll the **[interactive demo](index.html)** locally.</sub>
---
## What It Is
Traditional websites scroll down a 2D document. **Animated Website World** turns the scroll wheel or thumb-drag into a **camera throttle**:
* Each scene is a pre-rendered video clip (e.g. Market → Grill → Counter → Final Product).
* The zero-dependency scrub engine maps your scroll delta directly to the video's `currentTime`.
* Between scenes, dedicated **connector transitions** glide the camera forward with frame-exact alignment.
* The entire experience streams as one seamless flight with pinned typography, dynamic accents, and route markers.
| The World | Scene 1 (Market) | Scene 2 (Counter) | Scene 3 (Finale) |
|---|---|---|---|
|  |  |  |  |
---
## How It Works (The Core Architecture)
### 1. The Seam Secret: Frame-Exact Boundary Keyframing ✨
The biggest challenge with scroll-scrubbed multi-clip video is preventing "popping" or sudden jumps when switching scenes.
We solve this with boundary keyframing:
```
transition.firstFrame = the EXACT last frame of scene N (extracted from mp4)
transition.lastFrame = the EXACT first frame of scene N+1 (extracted from mp4)
```
By generating transition clips that start on Scene N's true final frame and end on Scene N+1's true initial frame with a continuous low forward glide, **the seams are frame-exact**. The engine transitions `Scene 1 → Transition 1 → Scene 2` with no visual cuts.
### 2. High-Performance Video Scrubbing (Small GOP)
Standard web video has keyframes (I-frames) every 250+ frames. If you try to scrub `currentTime` backwards or forwards on standard video, decoders freeze or stutter.
For silky 60fps scrubbing:
* Encode with a **small GOP** (`-g 8` or `-g 4` on mobile).
* Native 720p or 1080p with `crf 20`, light sharpening, and no audio tracks.
* The engine fetches clips as **Blobs**, allowing instant scrubbing even on static web hosts (GitHub Pages, Netlify, Vercel, S3) that don't support custom HTTP byte-range seeks.
```bash
# Example FFmpeg command for scrub-optimized video:
ffmpeg -i input.mov -c:v libx264 -pix_fmt yuv420p -profile:v high -crf 20 -g 8 -an -movflags +faststart output.mp4
```
### 3. Portable, Dependency-Free Engine
The entire client engine (`assets/scrub-engine.js`) is vanilla JavaScript with **zero external dependencies**. It encapsulates its own DOM, injects its own scoped CSS, and drops into plain HTML, Next.js, React, Vue, or Svelte:
```html
<script src="assets/scrub-engine.js"></script>
<script>
mountScrollWorld(document.getElementById('world'), {
brand: { name: 'Smash & Co.', href: '#top' },
hint: 'scroll to fly in',
diveScroll: 1.3,
connScroll: 0.9,
sections: [
{
id: 'market',
label: 'The Market',
still: 'assets/market.png',
clip: 'assets/vid/market.mp4',
accent: '#6FA84B',
eyebrow: 'Fresh, daily',
title: 'It starts with the good stuff.',
body: 'Local ingredients, baked fresh every morning.',
tags: ['Fresh', 'Locally Sourced']
},
// ... more scenes
],
connectors: [
'assets/vid/conn1.mp4',
'assets/vid/conn2.mp4',
'assets/vid/conn3.mp4'
]
});
</script>
```
---
## Running Locally
Because the scrub engine loads video assets via `fetch()` as blobs, serve the folder over HTTP (rather than opening directly as a `file://` URL):
### Using Node / npx:
```bash
npm start
# or: npx serve -l 8080 .
```
### Using Python:
```bash
python3 -m http.server 8080
```
Open **`http://localhost:8080`** in your browser.
---
## Agent Integration
This repo also includes a plug-and-play skill for AI coding assistants (Claude Code, Cursor, Codex, OpenCode):
* Claude Code: Check `.claude-plugin/`
* Codex / Cursor: Review `AGENTS.md` and `skills/scroll-world-video/SKILL.md`
---
## Author & Maintainer
Created & open-sourced by **[Abdullah Formuli](https://github.com/authrain-cloud-abdullahformuli)**
* 🌐 Website: [calplus.app](https://calplus.app)
* 🛠️ GitHub: [@authrain-cloud-abdullahformuli](https://github.com/authrain-cloud-abdullahformuli)
* 🐦 X/Twitter: [@abdullahformuli](https://x.com/abdullahformuli)
* 📬 Contact: `authrainmedia@gmail.com`
---
## License
This project is licensed under the [MIT License](LICENSE) — free to use and customize for commercial and personal projects.
قراءة الملف الأصلي