chati-dev 4.2.1 → 4.3.0

package/framework/scaffold/motion-premium/README.md

@@ -0,0 +1,89 @@
+# Motion Premium Scaffold — v1.0.0
+
+Opinionated premium animation infrastructure for Next.js / React 18+ / Tailwind v4 projects. Ships the 13 non-negotiable sauce patterns + 12 responsive principles proven on reference implementations (focus-ai-website).
+
+## What this scaffold gives you
+
+**Phase 1 (foundation) — shipped in v1.0.0:**
+- `app/globals.css` — fluid type scale (Utopia-based), 4px-base spacing, radius/shadow tokens, `--breakpoint-xl: 75rem` override, reduced-motion safety net, brand placeholders.
+- `lib/brand.ts` — typed brand token source of truth. Single place to edit project colors.
+
+**Phase 2–4 (coming in v1.0.0 full ship):**
+- `lib/animations/*` — gsap glue, tokens, scoped hooks (Phase 2)
+- `components/animation/*` — Lenis, crossfade, transition, preloader providers (Phase 3)
+- `components/ui/Container.tsx`, `PageSection.tsx` — UI contract (Phase 4)
+
+## When NOT to use this scaffold
+
+- Static landing pages without scroll-driven animation — overkill.
+- Non-Tailwind projects — this scaffold is tightly coupled to Tailwind v4 syntax.
+- Projects already using Framer Motion exclusively (no GSAP/Lenis) — import conflicts.
+
+## How customization works (Decision 3)
+
+Brand tokens flow one-way at install time: `brand.ts` → placeholder resolution → `globals.css` (concrete hex values).
+
+```
+lib/brand.ts       (single source of truth, user-owned)
+       ↓
+scaffold-applier resolves {{PRIMARY_HEX}}, {{PRIMARY_RGB}}, ...
+       ↓
+app/globals.css    (concrete --color-* vars, editable but expected to stay in sync)
+```
+
+**If you edit `brand.ts` after install**, globals.css is NOT auto-updated. Run:
+
+```bash
+npx chati-dev scaffold motion-premium --sync-brand
+```
+
+This re-resolves placeholders and rewrites the brand var block in globals.css without touching your spacing/radius/shadow customizations.
+
+## Override classification
+
+| File | Class | Behavior on upgrade |
+|---|---|---|
+| `lib/brand.ts` | full | Never overwritten. Your edits are protected via hash diff. |
+| `app/globals.css` | partial | Brand vars re-synced on `--sync-brand`; rest of file preserved if user-modified. |
+| `lib/animations/gsap.ts` | none | Scaffold-owned. Upgrades replace, warning if user-modified. |
+| `lib/animations/tokens.ts` | partial | Adjust values (durations, easings, staggers); keep the exported shape. |
+| `lib/animations/useGsapContext.ts` | none | Scaffold-owned. Core pattern (reduced-motion safeguards) — do not modify. |
+| `lib/animations/useSmoothScroll.ts` | none | Scaffold-owned. Race-guarded async Lenis init consumed by `LenisProvider`. |
+| `lib/animations/useScrollSnapStepper.ts` | none | Scaffold-owned. Wheel + touch accumulator for panel-snap pins. |
+| `lib/animations/refreshCoordinator.ts` | none | Scaffold-owned. Debounced `ScrollTrigger.refresh()` singleton. |
+| `components/animation/LenisProvider.tsx` | none | Scaffold-owned. |
+| `components/animation/BackgroundCrossfadeProvider.tsx` | partial | Customize color stops array; keep ScrollTrigger logic. |
+| `components/animation/PageTransitionWrapper.tsx` | none | Scaffold-owned. Framer Motion opacity fade on pathname change. |
+| `components/animation/Preloader.tsx` | partial | Swap video for logo if desired; keep readyState gate. |
+| `app/layout.tsx` | partial | Provider nesting + pre-hydration scroll/motion scripts are scaffold-owned. Fill metadata / fonts / chrome / analytics. |
+| `components/ui/Container.tsx` | none | THE contract. Never edit — subclass via composition if needed. |
+| `components/ui/PageSection.tsx` | none | Scaffold-owned. Use `noPadding` / `noContainer` props for exceptions. |
+
+All 15 files listed above match `scaffold.yaml` `files[]` exactly.
+
+## Anti-patterns (will break the premium guarantees)
+
+1. **Adding max-width or horizontal padding anywhere except Container.tsx** — breaks the "one authority" contract (Principle 1). Visual QA will fail.
+2. **Creating your own Lenis instance** — conflicts with the scaffold's single-RAF loop. Use `useSmoothScroll()` (Phase 2).
+3. **Calling `gsap.registerPlugin` in components** — already registered module-level in `gsap.ts`. Re-registration causes silent failures.
+4. **Inline `text-[var(--text-xl)]` without the `length:` type hint** — Tailwind v4 silently omits untyped arbitrary CSS vars. Use `text-xl` (fluid utility) or `text-[length:var(--text-xl)]`.
+5. **Animating without `data-gsap-target`** — loses the reduced-motion safety net. Every pinned/revealed element must carry this attribute.
+
+## Version info
+
+- **Scaffold**: `motion-premium@1.0.0`
+- **Requires framework**: chati.dev >= 4.3.0
+- **Requires stack**: Next.js OR React Vite, Tailwind v4+, TypeScript 5+, React 18+, Node 18+
+- **Reference implementation**: `focus-ai-website` (all 13 sauce patterns verified in production)
+
+## Upgrading
+
+```bash
+# Check for scaffold updates
+npx chati-dev scaffold motion-premium --check
+
+# Apply latest (preserves your customizations via hash diff)
+npx chati-dev scaffold motion-premium --upgrade
+```
+
+Scaffold versioning is independent of the framework version. Scaffold 1.0.x → 1.1.x is additive-only; 1.x → 2.x may require migrations (provided via `framework/migrations/scaffold-*.yaml`).

package/framework/scaffold/motion-premium/app/globals.css.template

@@ -0,0 +1,400 @@
+@import "tailwindcss";
+
+/* Exclude non-source directories from Tailwind v4 scanning */
+@source not "../artifacts";
+@source not "../.chati";
+@source not "../.chati.dev";
+@source not "../docs";
+
+/* =========================================================
+   DESIGN TOKENS
+   Brand hex values are placeholders, resolved at scaffold
+   apply time from lib/brand.ts (Decision 3).
+   To re-sync after editing brand.ts:
+     npx chati-dev scaffold motion-premium --sync-brand
+   ========================================================= */
+
+:root {
+  color-scheme: dark;
+
+  /* --- Neutral Scale (dark-theme defaults; user-editable) --- */
+  --color-neutral-0: #F5F5FA;
+  --color-neutral-50: #E8E8EE;
+  --color-neutral-100: #D0D0DD;
+  --color-neutral-200: #8A8A9A;
+  --color-neutral-300: #8888A0;
+  --color-neutral-400: #5C5C7A;
+  --color-neutral-500: #3A3A55;
+  --color-neutral-600: #2A2A42;
+  --color-neutral-700: #1F1F35;
+  --color-neutral-800: #1A1A2E;
+  --color-neutral-900: #0F0F1A;
+
+  /* --- Brand Colors (placeholders → resolved from brand.ts) --- */
+  --color-primary: {{PRIMARY_HEX}};
+  --color-primary-rgb: {{PRIMARY_RGB}};
+  --color-primary-hover: {{PRIMARY_HOVER_HEX}};
+  --color-primary-muted: rgba(var(--color-primary-rgb), 0.15);
+
+  /* --- Background Levels --- */
+  --color-secondary: var(--color-neutral-800);
+  --color-bg-deeper: #0A0A12;
+  --color-bg-deep: {{BG_DEEP_HEX}};
+  --color-bg-primary: {{BG_PRIMARY_HEX}};
+  --color-bg-surface: var(--color-bg-deep);
+  --color-bg-elevated: {{BG_ELEVATED_HEX}};
+
+  /* --- Text Levels --- */
+  --color-text-primary: {{TEXT_PRIMARY_HEX}};
+  --color-text-secondary: {{TEXT_SECONDARY_HEX}};
+  --color-text-tertiary: var(--color-neutral-400);
+  --color-text-inverse: {{TEXT_INVERSE_HEX}};
+
+  /* --- Semantic Colors --- */
+  --color-semantic-success: #22C55E;
+  --color-semantic-warning: #F59E0B;
+  --color-semantic-error: #EF4444;
+  --color-semantic-info: #60A5FA;
+
+  /*
+   * Fluid Typography Scale (Utopia-based)
+   * Linear interpolation from 320vw (min) to 2560vw (max, 27" reference).
+   * Formula: slope = (max - min) / 22.4, base = min - slope * 3.2
+   * Expression: clamp(min_rem, base_rem + slope_vw, max_rem)
+   * Every token is mathematically consistent. Same growth curve across the scale.
+   */
+  --text-xs: clamp(0.75rem, 0.732rem + 0.089vw, 0.875rem);      /* 12 -> 14 */
+  --text-sm: clamp(0.875rem, 0.857rem + 0.089vw, 1rem);          /* 14 -> 16 */
+  --text-base: clamp(1rem, 0.982rem + 0.089vw, 1.125rem);        /* 16 -> 18 */
+  --text-lg: clamp(1.125rem, 1.089rem + 0.179vw, 1.375rem);      /* 18 -> 22 */
+  --text-xl: clamp(1.25rem, 1.196rem + 0.268vw, 1.625rem);       /* 20 -> 26 */
+  --text-2xl: clamp(1.5rem, 1.429rem + 0.357vw, 2.125rem);       /* 24 -> 34 */
+  --text-3xl: clamp(1.75rem, 1.625rem + 0.625vw, 2.625rem);      /* 28 -> 42 */
+  --text-4xl: clamp(2.125rem, 1.929rem + 0.982vw, 3.5rem);       /* 34 -> 56 */
+  --text-5xl: clamp(2.5rem, 2.214rem + 1.429vw, 4.5rem);         /* 40 -> 72 */
+  --text-6xl: clamp(3rem, 2.571rem + 2.143vw, 6rem);             /* 48 -> 96 */
+  --text-7xl: clamp(3.5rem, 2.929rem + 2.857vw, 7.5rem);         /* 56 -> 120 */
+  --text-8xl: clamp(4rem, 3.286rem + 3.571vw, 9rem);             /* 64 -> 144 */
+  --text-display: clamp(4.5rem, 3.714rem + 3.929vw, 10rem);      /* 72 -> 160 */
+  --text-hero: clamp(5rem, 4.143rem + 4.286vw, 11rem);           /* 80 -> 176 */
+
+  /* Line-heights paired with fluid sizes */
+  --leading-tight: 1.05;
+  --leading-snug: 1.2;
+  --leading-normal: 1.5;
+  --leading-relaxed: 1.65;
+
+  /* --- Spacing (4px base unit) --- */
+  --space-1: 4px;
+  --space-2: 8px;
+  --space-3: 12px;
+  --space-4: 16px;
+  --space-5: 20px;
+  --space-6: 24px;
+  --space-7: 28px;
+  --space-8: 32px;
+  --space-9: 36px;
+  --space-10: 40px;
+  --space-11: 44px;
+  --space-12: 48px;
+  --space-16: 64px;
+  --space-20: 80px;
+  --space-24: 96px;
+  --space-32: 128px;
+  --space-48: 192px;
+
+  /* --- Layout --- */
+  --container-max-width: 1200px;
+  --nav-height: 72px;
+
+  /* --- Border Radius --- */
+  --radius-none: 0px;
+  --radius-sm: 4px;
+  --radius-md: 8px;
+  --radius-lg: 12px;
+  --radius-xl: 16px;
+  --radius-2xl: 24px;
+  --radius-full: 9999px;
+
+  /* --- Shadows --- */
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.4);
+  --shadow-md: 0 4px 8px rgba(0, 0, 0, 0.5), 0 1px 2px rgba(0, 0, 0, 0.3);
+  --shadow-lg: 0 8px 24px rgba(0, 0, 0, 0.6), 0 2px 4px rgba(0, 0, 0, 0.3);
+  --shadow-xl: 0 20px 48px rgba(0, 0, 0, 0.7), 0 4px 8px rgba(0, 0, 0, 0.4);
+  --shadow-glow-primary: 0 0 24px rgba(var(--color-primary-rgb), 0.2), 0 0 8px rgba(var(--color-primary-rgb), 0.1);
+  --shadow-glow-sm: 0 0 8px rgba(var(--color-primary-rgb), 0.15);
+
+  /* --- Icon Sizes --- */
+  --icon-xs: 12px;
+  --icon-sm: 16px;
+  --icon-md: 20px;
+  --icon-lg: 24px;
+  --icon-xl: 32px;
+  --icon-2xl: 48px;
+
+  /* --- Duration --- */
+  --duration-instant: 0ms;
+  --duration-fast: 150ms;
+  --duration-normal: 300ms;
+  --duration-slow: 500ms;
+  --duration-dramatic: 900ms;
+  --duration-cinematic: 1400ms;
+
+  /* --- Easing --- */
+  --ease-default: cubic-bezier(0.25, 0.1, 0.25, 1);
+  --ease-in: cubic-bezier(0.42, 0, 1, 1);
+  --ease-out: cubic-bezier(0, 0, 0.58, 1);
+  --ease-in-out: cubic-bezier(0.42, 0, 0.58, 1);
+  --ease-spring: cubic-bezier(0.175, 0.885, 0.32, 1.275);
+  --ease-cinematic: cubic-bezier(0.16, 1, 0.3, 1);
+  --ease-gentle: cubic-bezier(0.4, 0, 0.2, 1);
+
+  /* --- Scroll-Driven Scene Background (Phase 3: BackgroundCrossfadeProvider) --- */
+  --scene-bg: var(--color-bg-deep);
+
+  /* --- Button Tokens --- */
+  --btn-padding-x-sm: var(--space-3);
+  --btn-padding-x-md: var(--space-5);
+  --btn-padding-x-lg: var(--space-8);
+  --btn-height-sm: 36px;
+  --btn-height-md: 44px;
+  --btn-height-lg: 52px;
+  --btn-radius: var(--radius-md);
+  --btn-primary-bg: var(--color-primary);
+  --btn-primary-text: var(--color-text-inverse);
+  --btn-primary-hover-bg: var(--color-primary-hover);
+  --btn-secondary-bg: transparent;
+  --btn-secondary-border: 1px solid var(--color-neutral-500);
+  --btn-secondary-text: var(--color-text-primary);
+  --btn-ghost-text: var(--color-text-secondary);
+
+  /* --- Card Tokens --- */
+  --card-bg: var(--color-bg-surface);
+  --card-border: 1px solid var(--color-neutral-600);
+  --card-radius: var(--radius-lg);
+  --card-padding: var(--space-8);
+  --card-hover-shadow: var(--shadow-lg);
+  --card-hover-border: 1px solid var(--color-neutral-500);
+
+  /* --- Input Tokens --- */
+  --input-bg: var(--color-bg-surface);
+  --input-border: 1px solid var(--color-neutral-500);
+  --input-border-focus: 1px solid var(--color-primary);
+  --input-border-error: 1px solid var(--color-semantic-error);
+  --input-radius: var(--radius-md);
+  --input-padding-x: var(--space-4);
+  --input-height: 44px;
+  --input-text: var(--color-text-primary);
+  --input-placeholder: var(--color-text-tertiary);
+
+  /* --- Nav Tokens --- */
+  --nav-bg: rgba(8, 10, 9, 0.85);
+  --nav-backdrop-blur: blur(20px);
+  --nav-border-bottom: 1px solid rgba(255, 255, 255, 0.06);
+  --nav-link-text: var(--color-text-secondary);
+  --nav-link-hover: var(--color-text-primary);
+  --nav-link-active: var(--color-primary);
+
+  /* --- Breakpoints (reference only, use Tailwind breakpoints in classes) --- */
+  --bp-sm: 640px;
+  --bp-md: 768px;
+  --bp-lg: 1024px;
+  --bp-xl: 1280px;
+  --bp-2xl: 1536px;
+}
+
+/* =========================================================
+   TAILWIND v4 @theme BLOCK
+   Registers tokens as Tailwind utilities to avoid
+   arbitrary value syntax where possible.
+   ========================================================= */
+
+@theme {
+  /*
+   * Custom breakpoint override: xl lowered from 80rem (1280px) to 75rem (1200px).
+   * This aligns laptop viewports in the 1200 to 1279 range (MacBook Air M4 13.8"
+   * scaled default) with desktop xl: utilities, eliminating the dead zone where
+   * lg: applied but xl: did not, which produced layout gaps and mismatched padding
+   * between laptop and external desktop monitors.
+   */
+  --breakpoint-xl: 75rem;
+
+  /*
+   * Font sizes: all alias the fluid --text-* tokens defined in :root.
+   * Utopia-based linear fluid scale, 320vw (min) to 2560vw (max).
+   * Registered here so Tailwind utilities text-xs..text-hero render correctly.
+   */
+  --font-size-xs: var(--text-xs);
+  --font-size-sm: var(--text-sm);
+  --font-size-base: var(--text-base);
+  --font-size-lg: var(--text-lg);
+  --font-size-xl: var(--text-xl);
+  --font-size-2xl: var(--text-2xl);
+  --font-size-3xl: var(--text-3xl);
+  --font-size-4xl: var(--text-4xl);
+  --font-size-5xl: var(--text-5xl);
+  --font-size-6xl: var(--text-6xl);
+  --font-size-7xl: var(--text-7xl);
+  --font-size-8xl: var(--text-8xl);
+  --font-size-display: var(--text-display);
+  --font-size-hero: var(--text-hero);
+
+  /* Colors registered in @theme for Tailwind color utilities */
+  --color-primary: {{PRIMARY_HEX}};
+  --color-primary-hover: {{PRIMARY_HOVER_HEX}};
+
+  --color-bg-deeper: #0A0A12;
+  --color-bg-deep: {{BG_DEEP_HEX}};
+  --color-bg-primary: {{BG_PRIMARY_HEX}};
+  --color-bg-surface: var(--color-bg-deep);
+  --color-bg-elevated: {{BG_ELEVATED_HEX}};
+  --color-secondary: var(--color-neutral-800);
+
+  --color-text-primary: {{TEXT_PRIMARY_HEX}};
+  --color-text-secondary: {{TEXT_SECONDARY_HEX}};
+  --color-text-tertiary: var(--color-neutral-400);
+  --color-text-inverse: {{TEXT_INVERSE_HEX}};
+
+  --color-neutral-0: #F5F5FA;
+  --color-neutral-50: #E8E8EE;
+  --color-neutral-100: #D0D0DD;
+  --color-neutral-200: #8A8A9A;
+  --color-neutral-300: #8888A0;
+  --color-neutral-400: #5C5C7A;
+  --color-neutral-500: #3A3A55;
+  --color-neutral-600: #2A2A42;
+  --color-neutral-700: #1F1F35;
+  --color-neutral-800: #1A1A2E;
+  --color-neutral-900: #0F0F1A;
+
+  --color-semantic-success: #22C55E;
+  --color-semantic-warning: #F59E0B;
+  --color-semantic-error: #EF4444;
+  --color-semantic-info: #60A5FA;
+}
+
+/* =========================================================
+   GLOBAL BASE STYLES
+   Must live inside @layer base so Tailwind utilities
+   (mx-auto, px-*, etc.) declared in @layer utilities
+   can override these defaults via normal cascade order.
+   ========================================================= */
+
+@layer base {
+  html {
+    scroll-behavior: auto; /* Lenis handles smooth scroll — see Phase 3 LenisProvider */
+  }
+
+  body {
+    background-color: var(--scene-bg, var(--color-bg-primary));
+    color: var(--color-text-primary);
+    font-family: var(--font-inter, system-ui, sans-serif);
+    font-size: var(--text-base);
+    line-height: 1.65;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+    transition: background-color var(--duration-normal) var(--ease-gentle);
+  }
+
+  h1, h2, h3, h4, h5, h6 {
+    font-family: var(--font-inter, system-ui, sans-serif);
+    color: var(--color-text-primary);
+  }
+  h1 {
+    font-weight: 700;
+    letter-spacing: -0.02em;
+    line-height: 1.1;
+  }
+  h2 {
+    font-weight: 700;
+    letter-spacing: -0.02em;
+    line-height: 1.15;
+  }
+  h3 {
+    font-weight: 600;
+    letter-spacing: -0.01em;
+    line-height: 1.2;
+  }
+  h4 {
+    font-weight: 600;
+    line-height: 1.3;
+  }
+
+  :focus-visible {
+    outline: 2px solid var(--color-primary);
+    outline-offset: 2px;
+  }
+
+  [id] {
+    scroll-margin-top: 80px;
+  }
+}
+
+@layer utilities {
+  .typo-display {
+    font-family: var(--font-inter, system-ui, sans-serif);
+    font-weight: 900;
+    letter-spacing: -0.03em;
+    line-height: 1.05;
+  }
+  .typo-section-label {
+    font-family: var(--font-inter, system-ui, sans-serif);
+    font-weight: 600;
+    letter-spacing: 0.12em;
+    text-transform: uppercase;
+    line-height: 1;
+  }
+  .typo-micro-label {
+    font-family: var(--font-inter, system-ui, sans-serif);
+    font-weight: 600;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    line-height: 1;
+  }
+  .typo-pull-quote {
+    font-family: var(--font-inter, system-ui, sans-serif);
+    font-weight: 400;
+    font-style: italic;
+    line-height: 1.4;
+  }
+  .typo-editorial {
+    font-family: var(--font-inter, system-ui, sans-serif);
+    font-weight: 400;
+    line-height: 1.55;
+  }
+  .typo-caption {
+    font-family: var(--font-inter, system-ui, sans-serif);
+    font-weight: 400;
+    line-height: 1.5;
+  }
+  .typo-body {
+    font-family: var(--font-inter, system-ui, sans-serif);
+    font-weight: 400;
+    line-height: 1.65;
+  }
+}
+
+/* =========================================================
+   REDUCED MOTION — safety net
+   When animations are skipped, all GSAP-controlled elements
+   must be immediately visible in their final state.
+   The [data-gsap-target] selector assumes Phase 2 hooks mark
+   animated elements with this attribute.
+   ========================================================= */
+
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+
+  /* Ensure any GSAP-controlled elements default to visible */
+  [data-gsap-target] {
+    opacity: 1 !important;
+    transform: none !important;
+  }
+}

package/framework/scaffold/motion-premium/app/layout.tsx.template

@@ -0,0 +1,110 @@
+/**
+ * app/layout.tsx — scaffold motion-premium v1.0.0
+ *
+ * Root layout. Defines the provider nesting order, the pre-hydration
+ * scroll-restoration script, and the inline reduced-motion safety-net
+ * style block. User customizes metadata, font loading, analytics,
+ * and site chrome (header/footer) on top of this scaffold.
+ *
+ * Non-obvious choices:
+ *
+ * - Provider nesting order is load-bearing:
+ *     Preloader first (sibling, NOT wrapping) — it needs to cover the
+ *     children while Lenis/GSAP boot. Wrapping inside Lenis would delay
+ *     the preloader behind Lenis's dynamic import.
+ *   Then, deepest-to-shallowest:
+ *     LenisProvider
+ *       ↳ BackgroundCrossfadeProvider  (depends on ScrollTrigger; Lenis
+ *                                        must be live for positions to be
+ *                                        correct)
+ *         ↳ PageTransitionWrapper      (exits must complete before the
+ *                                        next ScrollTrigger registration
+ *                                        from the new route)
+ *           ↳ children                 (user pages)
+ *
+ * - Inline `<script>` (pre-hydration) sets `history.scrollRestoration =
+ *   'manual'` and scrolls to 0 BEFORE React hydrates. This closes the
+ *   brief window where the browser's default scroll-restoration would
+ *   jump to the prior scroll position on back-nav, only to have Lenis
+ *   re-scroll to top a few frames later. The flash is jarring without
+ *   this script. Duplicate of the post-hydration useEffect in
+ *   LenisProvider — both layers are needed.
+ *
+ * - Inline `<style>` (pre-hydration) for reduced-motion mirrors the
+ *   `@media (prefers-reduced-motion)` block in globals.css. Inline
+ *   declaration guarantees the rule applies BEFORE external CSS loads,
+ *   so reduced-motion users on slow networks never see a flash of
+ *   animation on first paint.
+ *
+ * - `suppressHydrationWarning` on <html> — the pre-hydration scroll
+ *   script and style can cause mismatch warnings in React strict mode
+ *   (server-rendered <html> has no effect from the script, client does).
+ *   This suppression is scoped to <html> only; component-level mismatches
+ *   still surface.
+ *
+ * - Metadata block is a placeholder — users should fill in their site
+ *   name, description, OpenGraph, Twitter, JSON-LD, robots, etc.
+ *   Intentionally NOT parameterized via scaffold placeholders because
+ *   metadata is project-specific boilerplate, not brand-tied.
+ */
+
+import type { Metadata } from 'next';
+import './globals.css';
+import { LenisProvider } from '@/components/animation/LenisProvider';
+import { BackgroundCrossfadeProvider } from '@/components/animation/BackgroundCrossfadeProvider';
+import { PageTransitionWrapper } from '@/components/animation/PageTransitionWrapper';
+import { Preloader } from '@/components/animation/Preloader';
+
+// TODO: Fill in per project. See https://nextjs.org/docs/app/building-your-application/optimizing/metadata
+export const metadata: Metadata = {
+  title: {
+    default:  'Your Project Name',
+    template: '%s | Your Project Name',
+  },
+  description: 'Your project description.',
+  // metadataBase: new URL('https://yourdomain.com'),
+  // openGraph: { ... },
+  // twitter: { ... },
+  // robots: { index: true, follow: true },
+};
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        {/* Pre-hydration: manual scroll restoration + scroll to top.
+            Partners with LenisProvider's post-hydration useEffect. */}
+        <script
+          dangerouslySetInnerHTML={{
+            __html: `(function(){try{if('scrollRestoration' in history){history.scrollRestoration='manual';}window.scrollTo(0,0);}catch(e){}})();`,
+          }}
+        />
+        {/* Pre-hydration reduced-motion safety net. Duplicates globals.css
+            so the rule applies before external CSS parses. */}
+        <style
+          dangerouslySetInnerHTML={{
+            __html: `@media (prefers-reduced-motion: reduce){*,*::before,*::after{animation-duration:0.01ms !important;animation-iteration-count:1 !important;transition-duration:0.01ms !important;}[data-gsap-target]{opacity:1 !important;transform:none !important;}}`,
+          }}
+        />
+        {/* TODO: Add font preloads, favicon, JSON-LD, analytics tags here. */}
+      </head>
+      <body className="antialiased">
+        {/* Preloader is a sibling of the provider tree, not a parent:
+            it covers the viewport while Lenis/GSAP boot dynamically. */}
+        <Preloader />
+
+        <LenisProvider>
+          <BackgroundCrossfadeProvider>
+            <PageTransitionWrapper>
+              {children}
+            </PageTransitionWrapper>
+          </BackgroundCrossfadeProvider>
+        </LenisProvider>
+      </body>
+    </html>
+  );
+}