creative-frontend-core

name	creative-frontend-core
description	Shared reference for the creative-frontend cluster: the in-browser-vs-video decision matrix, in-browser tool selection, prefers-reduced-motion baseline, GPU/performance budget, Astro hydration boundaries for animation, and version matrix. USE WHEN deciding how to implement web motion/animation/video, or for the cross-cutting rules every spoke (GSAP, Anime.js, web-motion-library, Remotion) shares.
cluster	creative-frontend
version	1.0.0

Creative Frontend Core

Shared rules for the creative-frontend cluster. The orchestrator and every spoke reference this — it holds the cross-cutting decisions so nothing is duplicated or contradicted.

1. Decision matrix — in-browser vs render-time (video)

Question	If YES
Does it respond to user input (scroll, hover, click, drag) in real time?	in-browser
Must the artifact be a file (.mp4/.webm/.gif) to upload/embed?	Remotion
Needs deterministic frame timing, audio sync, or pixel-perfect output?	Remotion
One-off hero/section effect on a live page?	in-browser
Needs N data-driven variants (per-user, per-product, per-locale)?	Remotion (programmatic)
Must work with JS disabled / degrade gracefully?	in-browser (CSS-first) or a pre-rendered video

When both apply (interactive page that also ships a video), do both: build the page in-browser, render the video with Remotion, embed it.

2. In-browser tool selection

Need	Use	Spoke
Scroll-linked: pin, scrub, parallax, reveal, horizontal-scroll	GSAP ScrollTrigger	astro-gsap-scrolltrigger
Timeline/sequence, SVG draw & morph, stagger grids, tween JS objects	Anime.js	animejs
Simple enter/exit, state change, page-to-page morph	CSS transitions / Astro View Transitions	astro-framework
Drop-in hero / landing / 3D / WebGL / Framer-Motion component	Pre-built library	web-motion-library

Reach for CSS / View Transitions first; escalate to GSAP/Anime.js only when the effect needs scroll-linking, sequencing, or fine timeline control.

3. Reduced motion (non-negotiable a11y baseline)

Gate every non-essential animation behind reduced-motion and provide a static end-state:

• CSS: wrap motion in @media (prefers-reduced-motion: no-preference) { … }.
• GSAP: use gsap.matchMedia() with a "(prefers-reduced-motion: reduce)" branch that sets the final state instantly.
• Anime.js: check window.matchMedia('(prefers-reduced-motion: reduce)').matches and skip or jump to the end.
• Remotion: accept a reducedMotion prop / offer a still poster frame for embeds.

Essential motion (e.g., a loading spinner conveying state) may remain, but minimize it.

4. Performance budget

• Animate compositor-only properties: transform and opacity. Never animate layout properties (width, height, top, left, margin, padding) — they trigger layout/paint and thrash.
• Use will-change sparingly and remove it after the animation; permanent will-change wastes memory.
• Target 60fps (≈16ms/frame); keep per-frame JS under ~4ms. Profile with DevTools Performance + the FPS meter.
• Defer animation scripts off the critical path (see hydration below). Lazy-load heavy libs (GSAP plugins, three.js) only on routes that use them.

5. Astro hydration boundaries for animation

Where animation code runs matters as much as what it does:

• Plain <script> in .astro — bundled, runs once on initial load. Good for global GSAP init. But under View Transitions it does not re-run on client-side nav.
• Framework island directive — pick by position/urgency:
  • client:load — above-the-fold hero that must animate immediately.
  • client:visible — below-the-fold; animate when scrolled into view (best default for reveals).
  • client:idle — non-urgent ambient motion.
  • client:only — client-only libraries (some WebGL/three.js) that can't SSR.
• View Transitions gotchas (when <ClientRouter /> is enabled):
  • Re-init scroll/timeline logic on astro:page-load (fires on first load and after each nav); call ScrollTrigger.refresh() after layout settles.
  • Clean up on astro:before-swap — kill ScrollTriggers/timelines to prevent duplicates and leaks.
  • Use transition:persist for elements whose animation state must survive navigation.

6. Version / install matrix

Spoke	Install	Notes
GSAP	gsap (+ gsap/ScrollTrigger, registered via gsap.registerPlugin)	Free tier covers ScrollTrigger; SplitText et al. now free in recent versions.
Anime.js	animejs	v3 (anime()) vs v4 (new createTimeline/import API) differ — confirm version; the animejs spoke covers both.
Remotion	remotion + @remotion/cli (+ @remotion/lambda / @remotion/cloudrun for scaled renders)	Renders need a bundler step; Lambda/Cloud Run incur real cost+time — confirm scope first.
Astro	astro + integrations (@astrojs/react etc.); <ClientRouter /> for view transitions	Match integration versions to the Astro major.

7. Shared guardrails

• Compositor-only props (transform/opacity); no layout-animating.
• Always provide a reduced-motion path and a sensible static fallback.
• Re-init and clean up animations across Astro view transitions — no duplicate ScrollTriggers, no leaks.
• Don't ship will-change permanently.
• Confirm scope and expected cost/time before heavy Remotion renders (Lambda/Cloud Run).
• Prefer CSS/View Transitions before adding a JS animation dependency.