History Portal

Narrated history lessons for the classroom. Laravel 12 + Livewire 3. The product of The Learning Portal (thelearningportal.us).

Quick start (fresh clone)

composer install
npm install
cp .env.example .env
php artisan key:generate
touch database/database.sqlite
php artisan migrate --seed
php artisan storage:link
npm run build           # or: npm run dev
./scripts/fetch-public-assets.sh   # pulls flag tiles from the live site
composer dev            # serves app + queue + vite + logs

Assets not in the repo

Large binary assets are gitignored. Status for a fresh clone:

• Flags (time-map tiles) — fetched by ./scripts/fetch-public-assets.sh from the live site.
• Avatar 3D models (public/avatars/*/character.glb, ~447 MB) and the animation library (~391 MB) are not hosted online and are not included. A clone renders avatar thumbnails but not the 3D avatars; these assets must be transferred separately.
• public/build, public/hot, public/storage are regenerated by the npm run build and php artisan storage:link steps above.

Scene backgrounds

Backgrounds are sourced from the paintings corpus and Wikimedia Commons, never generated. Originals arrive at up to 3840px and 1.7–3 MB, so every one is resized to fit a 1920×1080 stage and squeezed under 100 KB as it is downloaded. Across the eight heaviest backgrounds in a real install that took 73 MB down to 759 KB.

Encoding is AVIF. At the same visual quality WebP needed more than twice the bytes. An image with no real transparency has its alpha channel dropped rather than carrying a plane that says "all opaque".

Tunable in .env — BACKGROUND_MAX_BYTES, BACKGROUND_MAX_WIDTH, BACKGROUND_MAX_HEIGHT, BACKGROUND_START_QUALITY, BACKGROUND_GRAIN_PRESET, AVIFENC_PATH.

Lessons built before this existed can be re-encoded in place. Originals are kept as bg.original.* until you ask for them to go:

php artisan lessons:optimise-backgrounds --apply

AVIF film grain

The grain is not painted into the pixels. avifenc writes about a hundred bytes of AV1 film-grain parameters into the bitstream and the decoder draws the grain as it paints the image. Baked-in noise would wreck compression — noise is precisely what a codec cannot predict — while the parameter set is free and leaves a smooth, cheap image underneath. It also covers the banding heavy compression leaves in skies and shadows, which is what lets an aggressively compressed backdrop still look filmic instead of blotchy.

Measured here: preset 1 cost 111 bytes over the same encode with no grain, and in Chrome the decoded gradient went from a neighbour-pixel delta of 0.0009 to 3.28 — the browser really is synthesising it, not ignoring the parameters.

Encode a single file:

./scripts/encode-avif-grain.sh --quality 65 --speed 6 --grain 1 source.png public/images/source.avif

Render every built-in preset from one source, for visual comparison:

./scripts/test-avif-grain-presets.sh source.png tmp/grain-tests

Presets 1–16 are different grain models, not a weak-to-strong dial — pick one by looking at skies, shadows and gradients at 100% zoom, not by reaching for the highest number. Preset 0 writes an honest no-grain baseline to compare against.

Grain is applied to the colour planes only (color: scope); alpha is preserved and never grained, because grain on a transparency mask makes the edges of a cut-out crawl.

Requires avifenc built with AOM — brew install libavif on macOS, or your distribution's libavif/libavif-tools package built against libaom. Without it the app falls back to Imagick AVIF (no grain) and then WebP, so nothing breaks; you just lose the grain. Anything that decodes and re-encodes the file downstream — a CDN, an image optimiser — will discard the grain parameters, so check the asset as actually served.

---

About Laravel

Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experience to be truly fulfilling. Laravel takes the pain out of development by easing common tasks used in many web projects, such as:

• Simple, fast routing engine.
• Powerful dependency injection container.
• Multiple back-ends for session and cache storage.
• Expressive, intuitive database ORM.
• Database agnostic schema migrations.
• Robust background job processing.
• Real-time event broadcasting.

Laravel is accessible, powerful, and provides tools required for large, robust applications.

Learning Laravel

Laravel has the most extensive and thorough documentation and video tutorial library of all modern web application frameworks, making it a breeze to get started with the framework. You can also check out Laravel Learn, where you will be guided through building a modern Laravel application.

If you don't feel like reading, Laracasts can help. Laracasts contains thousands of video tutorials on a range of topics including Laravel, modern PHP, unit testing, and JavaScript. Boost your skills by digging into our comprehensive video library.

Laravel Sponsors

We would like to extend our thanks to the following sponsors for funding Laravel development. If you are interested in becoming a sponsor, please visit the Laravel Partners program.

Premium Partners

• Vehikl
• Tighten Co.
• Kirschbaum Development Group
• 64 Robots
• Curotec
• DevSquad
• Redberry
• Active Logic

Contributing

Thank you for considering contributing to the Laravel framework! The contribution guide can be found in the Laravel documentation.

Code of Conduct

In order to ensure that the Laravel community is welcoming to all, please review and abide by the Code of Conduct.

Security Vulnerabilities

If you discover a security vulnerability within Laravel, please send an e-mail to Taylor Otwell via [email protected]. All security vulnerabilities will be promptly addressed.

License

The Laravel framework is open-sourced software licensed under the MIT license.