chati-dev 4.2.2 → 4.3.1

package/framework/scaffold/motion-premium/lib/animations/useSmoothScroll.ts.template

@@ -0,0 +1,67 @@
+/**
+ * lib/animations/useSmoothScroll.ts — scaffold motion-premium v1.0.0
+ *
+ * Initializes Lenis + GSAP integration exactly once per app lifecycle.
+ * Must be mounted in a top-level client component (phase 3: LenisProvider).
+ *
+ * Non-obvious choices:
+ *
+ * - `destroyed` flag closure + check inside `.then` — React 19 + strict mode
+ *   double-mount problem. `initLenis()` is async (dynamic import of 'lenis').
+ *   If the component mounts, unmounts, and remounts quickly (strict mode does
+ *   this on first render in dev), the first .then callback may resolve AFTER
+ *   the first unmount ran. Without the flag, the stale instance gets written
+ *   to lenisRef.current and the cleanup function for the first mount destroys
+ *   the NEW (second mount's) instance. Flag + immediate `lenis.destroy()` in
+ *   the `if (destroyed)` branch guarantees at most one live Lenis, always.
+ *
+ * - `useRef<Awaited<ReturnType<typeof initLenis>> | null>` — typing the ref
+ *   as the awaited return of the async function avoids duplicating the Lenis
+ *   type import here. If `initLenis` is refactored later, the ref type
+ *   follows automatically.
+ *
+ * - Returns the ref, not the instance — consumers (LenisProvider) can pass
+ *   the ref through React context without re-rendering when the internal
+ *   Lenis instance changes (refs don't trigger renders).
+ */
+
+'use client';
+
+import { useEffect, useRef } from 'react';
+import { initLenis } from './gsap';
+
+/**
+ * Hook that initializes Lenis smooth scroll once per app lifecycle.
+ * Must be called in a top-level client component (e.g. LenisProvider in phase 3).
+ * Handles cleanup on unmount; race-safe under React strict mode.
+ *
+ * Returns a ref that holds the live Lenis instance, or null before init
+ * completes / after unmount.
+ */
+export function useSmoothScroll() {
+  const lenisRef = useRef<Awaited<ReturnType<typeof initLenis>> | null>(null);
+
+  useEffect(() => {
+    let destroyed = false;
+
+    initLenis().then((lenis) => {
+      // Race guard: if the component already unmounted before Lenis finished
+      // loading (dynamic import), destroy the fresh instance immediately.
+      if (destroyed) {
+        lenis.destroy();
+        return;
+      }
+      lenisRef.current = lenis;
+    });
+
+    return () => {
+      destroyed = true;
+      if (lenisRef.current) {
+        lenisRef.current.destroy();
+        lenisRef.current = null;
+      }
+    };
+  }, []);
+
+  return lenisRef;
+}

package/framework/scaffold/motion-premium/lib/brand.ts.template

@@ -0,0 +1,43 @@
+/**
+ * Brand tokens — single source of truth for project colors.
+ *
+ * Scaffold-applied file; user-owned (protected from upgrades via hash diff
+ * in .chati/manifest.json). Edit freely.
+ *
+ * To re-sync these values into app/globals.css (the CSS custom properties
+ * consumed by Tailwind v4), run:
+ *
+ *   npx chati-dev scaffold motion-premium --sync-brand
+ *
+ * The scaffold-applier reads this file, resolves each placeholder in
+ * globals.css.template (e.g. {{PRIMARY_HEX}}), and rewrites only the brand
+ * --color-* var block. Your spacing/radius/shadow customizations are preserved.
+ *
+ * See scaffold/motion-premium/scaffold.yaml for the full placeholder map.
+ */
+
+export const brand = {
+  colors: {
+    /** Primary brand color (hex). Used for CTAs, focus rings, primary actions. */
+    primary:       '{{PRIMARY_HEX}}',
+    /** Primary as "R, G, B" triple — required for rgba(var(--color-primary-rgb), alpha) constructs in shadows. */
+    primaryRgb:    '{{PRIMARY_RGB}}',
+    /** Primary hover state (usually lighter/more saturated). */
+    primaryHover:  '{{PRIMARY_HOVER_HEX}}',
+    /** Deepest background layer — page body default. */
+    bgDeep:        '{{BG_DEEP_HEX}}',
+    /** Primary background level — main content surface. */
+    bgPrimary:     '{{BG_PRIMARY_HEX}}',
+    /** Elevated background — cards, modals, panels. */
+    bgElevated:    '{{BG_ELEVATED_HEX}}',
+    /** Primary text color — high-contrast copy. */
+    textPrimary:   '{{TEXT_PRIMARY_HEX}}',
+    /** Secondary text — supporting copy, metadata. */
+    textSecondary: '{{TEXT_SECONDARY_HEX}}',
+    /** Inverse text — sits on primary-colored backgrounds (buttons etc). */
+    textInverse:   '{{TEXT_INVERSE_HEX}}',
+  },
+} as const;
+
+export type Brand = typeof brand;
+export type BrandColor = keyof typeof brand.colors;

package/framework/scaffold/motion-premium/scaffold.yaml

@@ -0,0 +1,178 @@
+# Scaffold Premium — motion-premium v1.0.0
+#
+# Declarative manifest for the motion-premium scaffold preset. Consumed by
+# the scaffold-applier at apply time (Phase 4) to resolve placeholders and
+# emit files into the target project.
+#
+# Contract: this schema is STABLE within v1.x. Additions only (new optional
+# fields). Breaking changes bump the major version and provide migrations.
+
+id: motion-premium
+version: 1.0.0
+description: "Premium animation infrastructure: GSAP + Lenis + cinematic providers. Opinionated for Next.js / React 18+ / Tailwind v4."
+
+framework:
+  chati_dev: ">=4.3.0"
+
+stack:
+  build_tools: ["nextjs", "react-vite"]
+  tailwind: ">=4.0.0"
+  typescript: ">=5.0.0"
+  node: ">=18.0.0"
+  react: ">=18.0.0"
+  # Runtime peer deps imported directly by templates. Bumping policy: every two
+  # minor bumps, re-validate templates. GSAP 3.12 is the stable line post-3.11;
+  # framer-motion 11 is the React 19 support line; lenis 1.1 introduced the
+  # `wrapper`/`content` refactor templates rely on.
+  gsap: "^3.12.5"
+  "framer-motion": "^11.0.0"
+  lenis: "^1.1.0"
+  # v4.3.1+: Playwright required for QA-Visual screenshot-based gate.
+  # Without it, visual-qa.js falls back to source-code analysis (gateway: WEAK).
+  # Run `npx playwright install chromium` once after npm install for the binary.
+  playwright: "^1.44.0"
+
+# Placeholder resolution — keys reference brand source fields.
+# Resolved once at scaffold apply time (Decision 3: install-time, one-shot).
+# To re-sync CSS vars after editing brand.ts, run: scaffold motion-premium --sync-brand
+placeholders:
+  PRIMARY_HEX:
+    source: brand.colors.primary
+    default: "#7C3AED"
+    type: hex
+  PRIMARY_RGB:
+    source: brand.colors.primaryRgb
+    default: "124, 58, 237"
+    type: rgb_triple
+  PRIMARY_HOVER_HEX:
+    source: brand.colors.primaryHover
+    default: "#6D28D9"
+    type: hex
+  BG_DEEP_HEX:
+    source: brand.colors.bgDeep
+    default: "#0A0A0F"
+    type: hex
+  BG_PRIMARY_HEX:
+    source: brand.colors.bgPrimary
+    default: "#111118"
+    type: hex
+  BG_ELEVATED_HEX:
+    source: brand.colors.bgElevated
+    default: "#1A1A24"
+    type: hex
+  TEXT_PRIMARY_HEX:
+    source: brand.colors.textPrimary
+    default: "#FAFAFA"
+    type: hex
+  TEXT_SECONDARY_HEX:
+    source: brand.colors.textSecondary
+    default: "#A1A1AA"
+    type: hex
+  TEXT_INVERSE_HEX:
+    source: brand.colors.textInverse
+    default: "#0A0A0F"
+    type: hex
+
+# Brand source resolution priority (Decision 3). First match wins.
+brand_sources:
+  - path: lib/brand.ts
+    type: typescript
+    description: "Existing brand tokens (brownfield or post-F3 scaffold install)"
+  - path: artifacts/4-UX/brandbook.md
+    type: markdown
+    description: "UX-authored brandbook (greenfield, post-UX phase)"
+  - path: artifacts/4-UX/brandbook.yaml
+    type: yaml
+    description: "Alternate brandbook format"
+  - type: interactive
+    prompt: true
+    description: "Fallback: ask user for each placeholder with default hints"
+
+# Files shipped by this scaffold. Phase 1: foundation (2). Phase 2: animations (6). Phase 3: providers (5). Phase 4: ui contract (2). Total: 15.
+files:
+  - source: app/globals.css.template
+    target: app/globals.css
+    phase: foundation
+    override: partial
+    notes: "Brand --color-* vars auto-synced from brand.ts; spacing/radius/shadow user-editable."
+  - source: lib/brand.ts.template
+    target: lib/brand.ts
+    phase: foundation
+    override: full
+    notes: "User-owned. Protected from upgrades via hash diff in manifest.json."
+  - source: lib/animations/gsap.ts.template
+    target: lib/animations/gsap.ts
+    phase: animations
+    override: none
+    notes: "Module-level plugin registration + Lenis/GSAP integration. Scaffold-owned — the 13 sauce patterns live here."
+  - source: lib/animations/tokens.ts.template
+    target: lib/animations/tokens.ts
+    phase: animations
+    override: partial
+    notes: "Adjust values, keep the exported shape (EASINGS/EASING_CURVES/DURATIONS/STAGGERS/SCROLL_TRIGGER_DEFAULTS)."
+  - source: lib/animations/useGsapContext.ts.template
+    target: lib/animations/useGsapContext.ts
+    phase: animations
+    override: none
+    notes: "Scoped context + reduced-motion safeguard + ctx.revert cleanup. Core pattern — do not modify."
+  - source: lib/animations/useSmoothScroll.ts.template
+    target: lib/animations/useSmoothScroll.ts
+    phase: animations
+    override: none
+    notes: "Race-guarded async Lenis init. Used by LenisProvider in phase 3."
+  - source: lib/animations/useScrollSnapStepper.ts.template
+    target: lib/animations/useScrollSnapStepper.ts
+    phase: animations
+    override: none
+    notes: "Wheel accumulator + touch + entry cooldown for panel-snap pins. Imported into components that use pinned sequences."
+  - source: lib/animations/refreshCoordinator.ts.template
+    target: lib/animations/refreshCoordinator.ts
+    phase: animations
+    override: none
+    notes: "Debounced ScrollTrigger.refresh() singleton. Coalesces mount-burst refreshes."
+  - source: components/animation/LenisProvider.tsx.template
+    target: components/animation/LenisProvider.tsx
+    phase: providers
+    override: none
+    notes: "Root client component for Lenis init + scrollRestoration manual enforcement."
+  - source: components/animation/BackgroundCrossfadeProvider.tsx.template
+    target: components/animation/BackgroundCrossfadeProvider.tsx
+    phase: providers
+    override: partial
+    notes: "User customizes color stops via props; ScrollTrigger logic is scaffold-owned."
+  - source: components/animation/PageTransitionWrapper.tsx.template
+    target: components/animation/PageTransitionWrapper.tsx
+    phase: providers
+    override: none
+    notes: "Framer Motion opacity fade on pathname change + post-exit scroll reset."
+  - source: components/animation/Preloader.tsx.template
+    target: components/animation/Preloader.tsx
+    phase: providers
+    override: partial
+    notes: "User supplies children (logo slot), videoSelector, durations; readiness gate + RAF are scaffold-owned."
+  - source: app/layout.tsx.template
+    target: app/layout.tsx
+    phase: providers
+    override: partial
+    notes: "Scaffold ships provider nesting + pre-hydration scroll/motion scripts. User fills metadata, fonts, chrome, analytics."
+  - source: components/ui/Container.tsx.template
+    target: components/ui/Container.tsx
+    phase: ui-contract
+    override: none
+    notes: "@contract: sole authority for max-width + horizontal padding. Never edit."
+  - source: components/ui/PageSection.tsx.template
+    target: components/ui/PageSection.tsx
+    phase: ui-contract
+    override: none
+    notes: "Vertical rhythm wrapper. noPadding / noContainer escape hatches for heroes and full-bleed layouts."
+
+# Contract — principles this scaffold encodes.
+# Violating any of these during dev breaks the premium guarantees.
+principles:
+  - "One Container authority — components/ui/Container.tsx is the sole max-width + horizontal padding owner (Phase 4)"
+  - "Fluid type from day one — Utopia clamp scale across all text-* tokens, no retrofit"
+  - "xl breakpoint overridden to 75rem — eliminates the 1200–1279px dead zone (MacBook Air M4)"
+  - "Mobile-first stack; promote to desktop via matchMedia gates, not CSS-only"
+  - "Reduced motion first-class — @media (prefers-reduced-motion) + data-gsap-target safety net"
+  - "Single RAF loop — gsap.ticker drives Lenis (Phase 2)"
+  - "Scope isolation via gsap.context(fn, containerRef) (Phase 2)"

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

@@ -0,0 +1,90 @@
+# motion-premium-3d
+
+React Three Fiber + Three.js scroll-driven 3D layer for premium sites. Extends `motion-premium` — apply that one FIRST (the 2D base), then this one on top.
+
+## Setup
+
+After `npm install`, run once to download the chromium browser binary used by QA-Visual screenshots:
+
+```bash
+npx playwright install chromium
+```
+
+QA-Visual Phase 3c uses real browser screenshots to count `canvas_hosts` and `scene_fallbacks` in the rendered DOM. Without chromium, R3F visual QA is blind.
+
+## When to apply
+
+Apply when the project brief or Animation Inventory cites **explicit 3D intent**:
+
+- Named 3D reference sites (Oryzo camera rig, Igloo Inc scenes, many Awwwards winners).
+- Phrase-level signals: "scroll-synced 3D hero", "camera pull", "product rotation", "scroll-driven WebGL", "interactive scene".
+- Animation Inventory rows whose "Reproducible via" column points at `scaffold/motion-premium-3d/*`.
+
+The Fase 10 auto-gate fires for this preset when `scaffold_signals.motion_premium_3d.confidence >= 0.8` (higher threshold than 2D motion-premium's 0.7 per ADR-3D-07 — false positives here cost ~600KB of bundle pressed onto a project that did not need it).
+
+## When NOT to apply
+
+- 2D-only projects. Apply motion-premium alone.
+- Mobile-first experiences where GPU budget is the primary constraint. The WebGL fallback (ADR-3D-05) handles low-end cases, but you pay the detection cost everywhere.
+- Static marketing pages without scroll choreography.
+- Projects on providers other than Claude Code where R3F's peer-dep matrix is hard to verify at install.
+
+## What it ships
+
+12 templates across 4 phases (webgl / canvas / scroll-scene / demo). Final inventory:
+
+```
+lib/webgl/detect.ts.template
+components/webgl/WebGLContext.tsx.template
+components/webgl/SceneFallback.tsx.template
+components/3d/CanvasProvider.tsx.template
+components/3d/InvalidateOnScroll.tsx.template
+components/3d/ScrollScene.tsx.template
+components/3d/CameraRig.tsx.template
+components/3d/ScrollCrossfade.tsx.template
+components/3d/MeshCrossfade.tsx.template
+app/(3d)/scroll-demo/page.tsx.template
+app/(3d)/scroll-demo/ScrollDemoClient.tsx.template
+app/(3d)/scroll-demo/ScrollDemoCanvas.tsx.template
+```
+
+All 12 entries match `scaffold.yaml` `files[]` exactly. All target paths are DISJOINT from motion-premium. The two presets compose.
+
+## Override classification
+
+| File pattern | Override | Notes |
+|---|---|---|
+| `lib/webgl/*`                       | none    | Scaffold-owned — detection logic is invariant |
+| `components/webgl/WebGLContext`     | none    | Context shape consumed by every 3D template |
+| `components/webgl/SceneFallback`    | partial | Extend with children (headline/CTA); keep role/aria contract |
+| `components/3d/CanvasProvider`      | none    | Single-RAF contract + WebGL gate — do not modify |
+| `components/3d/InvalidateOnScroll`  | none    | RAF bridge from gsap.ticker to R3F invalidate() |
+| `components/3d/ScrollScene`         | none    | Pinned section + progress ref — scaffold-owned |
+| `components/3d/CameraRig`           | partial | User supplies keyframes[] via props; lerp internals fixed |
+| `components/3d/ScrollCrossfade`     | partial | Customise stops[] / at[] for uneven spacing |
+| `components/3d/MeshCrossfade`       | partial | Mesh geometry / materials are project-specific |
+| `app/(3d)/scroll-demo/page`         | partial | Route-group entry — customise or remove for production |
+| `app/(3d)/scroll-demo/ScrollDemoClient`  | partial | Client wrapper + overlay HTML — user extends |
+| `app/(3d)/scroll-demo/ScrollDemoCanvas`  | partial | Canvas subtree (CanvasProvider + InvalidateOnScroll + CameraRig + MeshCrossfade + Preload) |
+
+## ADRs governing this preset
+
+- **ADR-3D-01** — Separate preset, not extension
+- **ADR-3D-02** — R3F + drei, not vanilla Three.js
+- **ADR-3D-03** — Single RAF via `frameloop="demand"`
+- **ADR-3D-04** — `next/dynamic({ ssr: false })` for all Canvas templates
+- **ADR-3D-05** — WebGL detection + graceful degradation
+- **ADR-3D-06** — Peer-deps pinned by minor (three `^0.160`, R3F `^8.15`)
+- **ADR-3D-07** — New auto-gate signal with confidence threshold 0.8
+- **ADR-3D-08** — `prefers-reduced-motion: reduce` MUST render the fallback
+
+Full context in `.planning/motion-premium-3d-v1.md`.
+
+## How to apply
+
+```
+npx chati-dev scaffold motion-premium         # 2D base first
+npx chati-dev scaffold motion-premium-3d      # 3D layer on top
+```
+
+Or via the Fase 10 auto-gate after qa-planning, when signals align.

package/framework/scaffold/motion-premium-3d/app/(3d)/scroll-demo/ScrollDemoCanvas.tsx.template

@@ -0,0 +1,81 @@
+'use client';
+
+/**
+ * ScrollDemoCanvas — dynamically imported via next/dynamic({ ssr: false })
+ * from ScrollDemoClient. Owns the Canvas subtree.
+ *
+ * Bundles:
+ *   @react-three/fiber  — Canvas, useThree, useFrame
+ *   @react-three/drei   — Preload (utility)
+ *   three                — Vector3, geometries, materials
+ * Rest of the app does not import these; the dynamic boundary isolates
+ * the ~600KB 3D bundle from pages that do not need it.
+ */
+
+import { Preload } from '@react-three/drei';
+import { CanvasProvider } from '@/components/3d/CanvasProvider';
+import { InvalidateOnScroll } from '@/components/3d/InvalidateOnScroll';
+import { CameraRig } from '@/components/3d/CameraRig';
+import { MeshCrossfade } from '@/components/3d/MeshCrossfade';
+import { SceneFallback } from '@/components/webgl/SceneFallback';
+
+/**
+ * Keyframes for the demo camera path. Replace with your own keyframes
+ * when customising — CameraRig lerps position + lookAt + optional FOV.
+ */
+const DEMO_KEYFRAMES = [
+  { at: 0,    position: [0, 0, 8]  as [number, number, number], lookAt: [0, 0, 0] as [number, number, number], fov: 50 },
+  { at: 0.5,  position: [4, 2, 6]  as [number, number, number], lookAt: [0, 0, 0] as [number, number, number], fov: 55 },
+  { at: 1,    position: [0, 4, 4]  as [number, number, number], lookAt: [0, 0, 0] as [number, number, number], fov: 60 },
+];
+
+export default function ScrollDemoCanvas() {
+  return (
+    <CanvasProvider fallback={<SceneFallback fullBleed accessibleLabel="3D scene unavailable" />}>
+      <InvalidateOnScroll />
+
+      <ambientLight intensity={0.4} />
+      <directionalLight position={[5, 5, 5]} intensity={0.8} />
+
+      <CameraRig keyframes={DEMO_KEYFRAMES} />
+
+      {/*
+        MeshCrossfade: single slot; only the active variant mounts.
+        Replace primitives with your own glTF meshes (useGLTF from drei).
+      */}
+      <MeshCrossfade
+        variants={[
+          {
+            at: 0,
+            render: () => (
+              <mesh>
+                <boxGeometry args={[1.5, 1.5, 1.5]} />
+                <meshStandardMaterial color="#7C3AED" />
+              </mesh>
+            ),
+          },
+          {
+            at: 0.5,
+            render: () => (
+              <mesh>
+                <sphereGeometry args={[1, 32, 32]} />
+                <meshStandardMaterial color="#A78BFA" />
+              </mesh>
+            ),
+          },
+          {
+            at: 1,
+            render: () => (
+              <mesh>
+                <torusGeometry args={[1, 0.4, 16, 64]} />
+                <meshStandardMaterial color="#EDE9FE" />
+              </mesh>
+            ),
+          },
+        ]}
+      />
+
+      <Preload all />
+    </CanvasProvider>
+  );
+}

package/framework/scaffold/motion-premium-3d/app/(3d)/scroll-demo/ScrollDemoClient.tsx.template

@@ -0,0 +1,75 @@
+'use client';
+
+/**
+ * ScrollDemoClient — working example wiring together every P2-P4
+ * template. A single pinned scroll scene with:
+ *   - WebGL gate (P2: WebGLContext + SceneFallback)
+ *   - Canvas mount with single-RAF (P3: CanvasProvider +
+ *     InvalidateOnScroll)
+ *   - Scroll-driven camera (P4: CameraRig)
+ *   - Mesh crossfade (P4: MeshCrossfade)
+ *
+ * Real-world scenes replace the box/sphere/torus primitives with
+ * glTF meshes loaded via drei's `useGLTF` (not imported here to keep
+ * the demo light; see motion-premium-3d README for asset pipeline
+ * guidance).
+ *
+ * Preload hint: drei's <Preload all /> tells R3F to compile all
+ * materials in the scene at mount time, eliminating the flash that
+ * otherwise happens when a new material appears mid-scroll.
+ */
+
+import { useRef } from 'react';
+import dynamic from 'next/dynamic';
+import { Preload } from '@react-three/drei';
+import { Container } from '@/components/ui/Container';
+import { WebGLProvider } from '@/components/webgl/WebGLContext';
+import { SceneFallback } from '@/components/webgl/SceneFallback';
+import {
+  ScrollScene,
+  ScrollSceneContext,
+  type ScrollSceneRef,
+} from '@/components/3d/ScrollScene';
+
+// ADR-3D-04: R3F / Three.js dependencies must load client-only. Wrapping
+// the scene in next/dynamic with ssr: false ensures Next never attempts
+// to run Canvas code on the server, and the loading state paints the
+// considered fallback instead of a blank canvas during hydration.
+const ScrollDemoCanvas = dynamic(() => import('./ScrollDemoCanvas'), {
+  ssr:     false,
+  loading: () => <SceneFallback fullBleed accessibleLabel="Loading scroll demo" />,
+});
+
+export default function ScrollDemoClient() {
+  const sceneRef = useRef<ScrollSceneRef>(null);
+
+  return (
+    <WebGLProvider>
+      <ScrollScene ref={sceneRef} length={3} scrub={true}>
+        <Container className="relative z-10 flex h-full flex-col justify-end pb-24">
+          <p className="text-sm uppercase tracking-wider opacity-60">motion-premium-3d demo</p>
+          <h1 className="text-display-lg max-w-2xl">
+            Scroll to animate the scene.
+          </h1>
+        </Container>
+
+        <div className="absolute inset-0">
+          <ScrollSceneContext.Provider value={sceneRef.current?.progress ?? null}>
+            <ScrollDemoCanvas />
+          </ScrollSceneContext.Provider>
+        </div>
+      </ScrollScene>
+    </WebGLProvider>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Sub-components defined below are referenced only via next/dynamic above.
+// They are exported from the Client module so the dynamic import is cheap
+// (single chunk). In production demos, prefer a separate file for clearer
+// code-split boundaries.
+// ---------------------------------------------------------------------------
+
+export function ScrollDemoCanvasInline() {
+  return <Preload all />;
+}

package/framework/scaffold/motion-premium-3d/app/(3d)/scroll-demo/page.tsx.template

@@ -0,0 +1,26 @@
+/**
+ * /scroll-demo — demo route for motion-premium-3d.
+ *
+ * Server Component by design: metadata exports live here; the actual
+ * scroll-scene + Canvas tree live in the sibling Client Component
+ * (ScrollDemoClient). This separation keeps the route group
+ * "(3d)" URL-transparent while respecting the Next.js 16 rule that
+ * `next/dynamic({ ssr: false })` must be invoked from a Client boundary.
+ *
+ * Users typically remove this route after validating the scaffold on
+ * their own content. The `(3d)` route group ( -parens- ) means URLs
+ * stay at `/scroll-demo`; dropping the whole `app/(3d)/` folder is a
+ * one-step undo.
+ */
+
+import type { Metadata } from 'next';
+import ScrollDemoClient from './ScrollDemoClient';
+
+export const metadata: Metadata = {
+  title:       'Scroll Demo — motion-premium-3d',
+  description: 'Scaffold demo: pinned scroll scene, camera rig tied to scroll progress, scene crossfade. Remove when validated.',
+};
+
+export default function ScrollDemoPage() {
+  return <ScrollDemoClient />;
+}

package/framework/scaffold/motion-premium-3d/components/3d/CameraRig.tsx.template

@@ -0,0 +1,100 @@
+'use client';
+
+/**
+ * CameraRig — interpolates camera position, target, and optional FOV
+ * across keyframes driven by the ScrollSceneContext progress ref.
+ *
+ * Must mount inside <CanvasProvider> AND inside <ScrollScene>'s
+ * context. Reads progress on every frame via useFrame — zero React
+ * re-renders, no state library.
+ *
+ * Keyframe format: an array of { at: 0..1, position, lookAt, fov? }
+ * sorted by `at`. Between keyframes, linear interpolation (or custom
+ * easing via `ease` on the keyframe). Before the first/after the last,
+ * the camera clamps to that keyframe's pose.
+ *
+ * Usage:
+ *   <CameraRig
+ *     keyframes={[
+ *       { at: 0,   position: [0, 0, 8], lookAt: [0, 0, 0],  fov: 50 },
+ *       { at: 0.5, position: [4, 2, 6], lookAt: [0, 0, 0] },
+ *       { at: 1,   position: [0, 4, 3], lookAt: [0, 0, 0],  fov: 60 },
+ *     ]}
+ *   />
+ */
+
+import { useContext, useMemo } from 'react';
+import { useThree, useFrame } from '@react-three/fiber';
+import { Vector3, PerspectiveCamera as ThreePerspectiveCamera } from 'three';
+import { ScrollSceneContext } from './ScrollScene';
+
+export interface CameraKeyframe {
+  at:         number;                  // 0..1
+  position:   [number, number, number];
+  lookAt:     [number, number, number];
+  fov?:       number;
+  /** Custom easing on the segment ending at this keyframe (optional). */
+  ease?:      (t: number) => number;
+}
+
+export interface CameraRigProps {
+  keyframes: CameraKeyframe[];
+}
+
+const DEFAULT_EASE = (t: number) => t; // linear; override per keyframe
+
+export function CameraRig({ keyframes }: CameraRigProps) {
+  const progressRef = useContext(ScrollSceneContext);
+  const camera      = useThree((s) => s.camera);
+
+  // Sorted copy + Vector3 presets — done once.
+  const kf = useMemo(() => {
+    const sorted = [...keyframes].sort((a, b) => a.at - b.at);
+    return sorted.map((k) => ({
+      at:       k.at,
+      position: new Vector3(...k.position),
+      lookAt:   new Vector3(...k.lookAt),
+      fov:      k.fov,
+      ease:     k.ease || DEFAULT_EASE,
+    }));
+  }, [keyframes]);
+
+  // Scratch vectors reused every frame (no per-frame allocation).
+  const posScratch    = useMemo(() => new Vector3(), []);
+  const lookAtScratch = useMemo(() => new Vector3(), []);
+
+  useFrame(() => {
+    if (!progressRef || kf.length === 0) return;
+    const t = Math.max(0, Math.min(1, progressRef.current.progress));
+
+    // Find the bracketing keyframe pair.
+    let a = kf[0];
+    let b = kf[kf.length - 1];
+    for (let i = 0; i < kf.length - 1; i++) {
+      if (t >= kf[i].at && t <= kf[i + 1].at) {
+        a = kf[i];
+        b = kf[i + 1];
+        break;
+      }
+    }
+
+    const range = b.at - a.at;
+    const local = range === 0 ? 0 : (t - a.at) / range;
+    const eased = b.ease(local);
+
+    posScratch.lerpVectors(a.position, b.position, eased);
+    lookAtScratch.lerpVectors(a.lookAt, b.lookAt, eased);
+
+    camera.position.copy(posScratch);
+    camera.lookAt(lookAtScratch);
+
+    // FOV interpolation (only meaningful on perspective cameras).
+    if (a.fov != null && b.fov != null && (camera as ThreePerspectiveCamera).isPerspectiveCamera) {
+      const fov = a.fov + (b.fov - a.fov) * eased;
+      (camera as ThreePerspectiveCamera).fov = fov;
+      (camera as ThreePerspectiveCamera).updateProjectionMatrix();
+    }
+  });
+
+  return null;
+}