cinematic-scroll-skill 2.1.0

package/templates/nextjs/lib/fal-models.ts

@@ -0,0 +1,213 @@
+/**
+ * fal.ai model registry — per-model input adapters.
+ *
+ * Each model on fal.ai has subtly different input parameters:
+ *   - FLUX.2 family uses `image_size` (enum) and ignores `negative_prompt`/`num_images`
+ *   - Gemini "Nano Banana" family uses `aspect_ratio` (different enum) + `resolution` + `num_images`
+ *   - Imagen 3 uses `aspect_ratio`
+ *
+ * This file is the single source of truth that maps a generic `GenericImageRequest`
+ * to the exact shape each model expects. Update here when fal.ai changes a schema —
+ * never inline model params in calling code.
+ *
+ * Source: https://fal.ai/docs/model-api-reference (verified 2026).
+ */
+
+export type FalImageModelId =
+  | 'fal-ai/flux-2-pro'
+  | 'fal-ai/flux-2-max'
+  | 'fal-ai/flux-2/turbo'
+  | 'fal-ai/flux-pro/v1.1/ultra'
+  | 'fal-ai/flux-pro/v1.1'
+  | 'fal-ai/gemini-3-pro-image-preview'
+  | 'fal-ai/gemini-3.1-flash-image-preview'
+  | 'fal-ai/gemini-2.5-flash-image'
+  | 'fal-ai/imagen3';
+
+export type Orientation = 'landscape' | 'portrait' | 'square';
+export type OutputFormat = 'jpeg' | 'png' | 'webp';
+
+export type GenericImageRequest = {
+  prompt: string;
+  /** What the asset is for — drives orientation defaults. */
+  orientation: Orientation;
+  /** Inline negative-prompt language. FLUX ignores `negative_prompt` so we append it to the prompt string instead. */
+  avoid?: string;
+  outputFormat?: OutputFormat;
+  seed?: number;
+  /** Gemini-only: 1K | 2K | 4K. Ignored by FLUX models. */
+  resolution?: '1K' | '2K' | '4K';
+};
+
+export type FalModelDescriptor = {
+  id: FalImageModelId;
+  family: 'flux' | 'gemini' | 'imagen';
+  /** Approx cost in USD per generation. */
+  costPerImage: number;
+  /** Typical wall-clock seconds. */
+  speedSec: number;
+  buildInput: (req: GenericImageRequest) => Record<string, unknown>;
+  /** Extract the first image URL from a fal result. */
+  extractUrl: (data: unknown) => string | undefined;
+};
+
+// ─── FLUX family ──────────────────────────────────────────────────────────
+
+const FLUX_IMAGE_SIZE: Record<Orientation, string> = {
+  landscape: 'landscape_16_9',
+  portrait: 'portrait_4_3',
+  square: 'square_hd',
+};
+
+const buildFluxInput = (req: GenericImageRequest) => {
+  // FLUX.2 ignores negative_prompt — inline it into the prompt instead.
+  const prompt = req.avoid ? `${req.prompt} Avoid: ${req.avoid}.` : req.prompt;
+  return {
+    prompt,
+    image_size: FLUX_IMAGE_SIZE[req.orientation],
+    output_format: req.outputFormat === 'webp' ? 'png' : (req.outputFormat ?? 'jpeg'),
+    enable_safety_checker: true,
+    safety_tolerance: '2',
+    ...(req.seed !== undefined ? { seed: req.seed } : {}),
+  };
+};
+
+// ─── Gemini family (Nano Banana) ──────────────────────────────────────────
+
+const GEMINI_ASPECT: Record<Orientation, string> = {
+  landscape: '16:9',
+  portrait: '3:4',
+  square: '1:1',
+};
+
+const buildGeminiInput = (req: GenericImageRequest) => {
+  // Gemini supports negative-language via prompt rewriting only.
+  const prompt = req.avoid ? `${req.prompt} Avoid: ${req.avoid}.` : req.prompt;
+  return {
+    prompt,
+    aspect_ratio: GEMINI_ASPECT[req.orientation],
+    output_format: req.outputFormat ?? 'png',
+    resolution: req.resolution ?? '1K',
+    num_images: 1,
+    safety_tolerance: '4',
+    ...(req.seed !== undefined ? { seed: req.seed } : {}),
+  };
+};
+
+// ─── Imagen 3 ─────────────────────────────────────────────────────────────
+
+const IMAGEN_ASPECT: Record<Orientation, string> = {
+  landscape: '16:9',
+  portrait: '3:4',
+  square: '1:1',
+};
+
+const buildImagenInput = (req: GenericImageRequest) => ({
+  prompt: req.avoid ? `${req.prompt} Avoid: ${req.avoid}.` : req.prompt,
+  aspect_ratio: IMAGEN_ASPECT[req.orientation],
+  num_images: 1,
+  ...(req.seed !== undefined ? { seed: req.seed } : {}),
+});
+
+// ─── Shared output extractor ──────────────────────────────────────────────
+
+const extractFirstUrl = (data: unknown): string | undefined => {
+  if (!data || typeof data !== 'object') return undefined;
+  const images = (data as { images?: Array<{ url?: string }> }).images;
+  return images?.[0]?.url;
+};
+
+// ─── Registry ─────────────────────────────────────────────────────────────
+
+export const FAL_MODELS: Record<FalImageModelId, FalModelDescriptor> = {
+  'fal-ai/flux-2-pro': {
+    id: 'fal-ai/flux-2-pro',
+    family: 'flux',
+    costPerImage: 0.06,
+    speedSec: 4,
+    buildInput: buildFluxInput,
+    extractUrl: extractFirstUrl,
+  },
+  'fal-ai/flux-2-max': {
+    id: 'fal-ai/flux-2-max',
+    family: 'flux',
+    costPerImage: 0.08,
+    speedSec: 5,
+    buildInput: buildFluxInput,
+    extractUrl: extractFirstUrl,
+  },
+  'fal-ai/flux-2/turbo': {
+    id: 'fal-ai/flux-2/turbo',
+    family: 'flux',
+    costPerImage: 0.02,
+    speedSec: 2,
+    buildInput: buildFluxInput,
+    extractUrl: extractFirstUrl,
+  },
+  'fal-ai/flux-pro/v1.1/ultra': {
+    id: 'fal-ai/flux-pro/v1.1/ultra',
+    family: 'flux',
+    costPerImage: 0.06,
+    speedSec: 10,
+    buildInput: buildFluxInput,
+    extractUrl: extractFirstUrl,
+  },
+  'fal-ai/flux-pro/v1.1': {
+    id: 'fal-ai/flux-pro/v1.1',
+    family: 'flux',
+    costPerImage: 0.05,
+    speedSec: 4.5,
+    buildInput: buildFluxInput,
+    extractUrl: extractFirstUrl,
+  },
+  'fal-ai/gemini-3-pro-image-preview': {
+    id: 'fal-ai/gemini-3-pro-image-preview',
+    family: 'gemini',
+    costPerImage: 0.15,
+    speedSec: 8,
+    buildInput: buildGeminiInput,
+    extractUrl: extractFirstUrl,
+  },
+  'fal-ai/gemini-3.1-flash-image-preview': {
+    id: 'fal-ai/gemini-3.1-flash-image-preview',
+    family: 'gemini',
+    costPerImage: 0.07,
+    speedSec: 2,
+    buildInput: buildGeminiInput,
+    extractUrl: extractFirstUrl,
+  },
+  'fal-ai/gemini-2.5-flash-image': {
+    id: 'fal-ai/gemini-2.5-flash-image',
+    family: 'gemini',
+    costPerImage: 0.04,
+    speedSec: 2,
+    buildInput: buildGeminiInput,
+    extractUrl: extractFirstUrl,
+  },
+  'fal-ai/imagen3': {
+    id: 'fal-ai/imagen3',
+    family: 'imagen',
+    costPerImage: 0.04,
+    speedSec: 3,
+    buildInput: buildImagenInput,
+    extractUrl: extractFirstUrl,
+  },
+};
+
+/** Resolve a model id from env or fallback to FLUX.2 Pro (the recommended default). */
+export function resolveModelId(envValue?: string): FalImageModelId {
+  const id = envValue as FalImageModelId | undefined;
+  return id && id in FAL_MODELS ? id : 'fal-ai/flux-2-pro';
+}
+
+export function getModel(id: FalImageModelId): FalModelDescriptor {
+  return FAL_MODELS[id];
+}
+
+export const ALLOWED_FAL_ENDPOINTS = [
+  ...Object.keys(FAL_MODELS),
+  // Edit variants — many models also expose /edit
+  'fal-ai/flux-2-pro/edit',
+  'fal-ai/gemini-3-pro-image-preview/edit',
+  'fal-ai/gemini-3.1-flash-image-preview/edit',
+];

package/templates/nextjs/lib/prompt-contract.ts

@@ -0,0 +1,97 @@
+/**
+ * Structured editorial prompt contract for fal.ai image generation.
+ *
+ * The same prompt format works across FLUX.2, Gemini "Nano Banana", and Imagen 3.
+ * Negative-prompt language is inlined via `EDITION_AVOID` and applied by
+ * `fal-models.ts` because FLUX.2 ignores the `negative_prompt` API param.
+ */
+
+export type HistoricalLayer = 'renaissance' | 'baroque' | 'atelier' | 'architectural' | 'industrial';
+export type CameraMode = 'wide' | 'medium' | 'macro' | 'isometric' | 'low-angle';
+export type OutputRole = 'hero' | 'chapter-bg' | 'foreground-object' | 'poster' | 'motion-source';
+
+export type EditionAssetPrompt = {
+  chapterId: string;
+  subject: string;
+  productTruth: string;
+  historicalLayer: HistoricalLayer;
+  modernLayer: string;
+  palette: string[];
+  camera: CameraMode;
+  outputRole: OutputRole;
+  /** Optional — deterministic generation when set. */
+  seed?: number;
+  /** Optional — override the default editorial aesthetic for a single chapter. */
+  aestheticDirection?: string;
+};
+
+const HISTORICAL_GUIDANCE: Record<HistoricalLayer, string> = {
+  renaissance:
+    'Renaissance composition: layered chiaroscuro, dramatic fabric, sfumato edges, classical proportions, museum-grade lighting.',
+  baroque:
+    'Baroque composition: theatrical movement, deep shadow contrast, gilded textures, dynamic diagonals, opulent palette.',
+  atelier:
+    'Painterly atelier composition: visible brushwork, warm sepia base, soft natural studio light, painterly imperfection.',
+  architectural:
+    'Architectural drafting composition: orthographic clarity, parchment tones, fine ink lines, structural geometry, blueprint sensibility.',
+  industrial:
+    'Industrial-era composition: forged metal, oxidised brass, steam-warm light, mechanical detail, victorian engine-room atmosphere.',
+};
+
+const CAMERA_GUIDANCE: Record<CameraMode, string> = {
+  wide: 'Wide cinematic shot, deep field, atmospheric perspective.',
+  medium: 'Medium shot, balanced subject framing, contextual environment.',
+  macro: 'Macro detail shot, shallow depth of field, tactile material focus.',
+  isometric: 'Clean isometric projection, technical clarity, even lighting.',
+  'low-angle': 'Low-angle hero shot, monumental perspective, sky negative space.',
+};
+
+const OUTPUT_ROLE_GUIDANCE: Record<OutputRole, string> = {
+  hero: 'Primary chapter hero image. Compose with negative space at top-left for HTML title overlay.',
+  'chapter-bg': 'Background plate. Subject de-emphasised, atmosphere primary, suitable for radial vignette overlay.',
+  'foreground-object': 'Isolated subject on neutral background. Portrait crop. Clean edge separation for cut-out use.',
+  poster: 'Editorial poster composition. Strong central subject, dramatic palette, frame-filling.',
+  'motion-source': 'First-frame of a motion sequence. Stable composition, gentle implied movement.',
+};
+
+export function buildEditionPrompt(input: EditionAssetPrompt): string {
+  const parts: string[] = [
+    'Original editorial product-scene image for a high-craft interactive release website.',
+    `Scene: ${input.subject}.`,
+    `Product truth: ${input.productTruth}.`,
+    HISTORICAL_GUIDANCE[input.historicalLayer],
+    `Modern layer: ${input.modernLayer} — integrated naturally, not stickered on.`,
+    `Palette: ${input.palette.join(', ')}.`,
+    CAMERA_GUIDANCE[input.camera],
+    OUTPUT_ROLE_GUIDANCE[input.outputRole],
+  ];
+
+  if (input.aestheticDirection) {
+    parts.push(`Aesthetic direction: ${input.aestheticDirection}.`);
+  }
+
+  parts.push(
+    'No brand logos, no readable text, no imitation of named living artists, no stock-photo gloss.',
+  );
+
+  return parts.join(' ');
+}
+
+/**
+ * Inline negative-prompt language. Applied by `fal-models.ts` as
+ * "Avoid: …" inside the main prompt string, because FLUX.2 Pro ignores
+ * the `negative_prompt` API parameter.
+ */
+export const EDITION_AVOID = [
+  'brand logos',
+  'unreadable text overlays',
+  'fake UI labels baked into the image',
+  'watermarks',
+  'low resolution',
+  'distorted hands',
+  'extra limbs',
+  'over-saturated colour',
+  'plastic skin',
+  'generic AI gloss',
+  'stock photography composition',
+].join(', ');

package/templates/nextjs/lib/use-device.ts

@@ -0,0 +1,42 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+/** True when viewport is narrower than the given breakpoint (default 768px). SSR-safe. */
+export function useIsMobile(breakpoint = 768) {
+  const [isMobile, setIsMobile] = useState(false);
+  useEffect(() => {
+    const mq = window.matchMedia(`(max-width: ${breakpoint - 1}px)`);
+    const handler = () => setIsMobile(mq.matches);
+    handler();
+    mq.addEventListener('change', handler);
+    return () => mq.removeEventListener('change', handler);
+  }, [breakpoint]);
+  return isMobile;
+}
+
+/** True on coarse-pointer / no-hover devices (touch). */
+export function useIsTouch() {
+  const [isTouch, setIsTouch] = useState(false);
+  useEffect(() => {
+    const mq = window.matchMedia('(hover: none) and (pointer: coarse)');
+    const handler = () => setIsTouch(mq.matches);
+    handler();
+    mq.addEventListener('change', handler);
+    return () => mq.removeEventListener('change', handler);
+  }, []);
+  return isTouch;
+}
+
+/** True when user requests reduced motion. */
+export function useReducedMotion() {
+  const [reduced, setReduced] = useState(false);
+  useEffect(() => {
+    const mq = window.matchMedia('(prefers-reduced-motion: reduce)');
+    const handler = () => setReduced(mq.matches);
+    handler();
+    mq.addEventListener('change', handler);
+    return () => mq.removeEventListener('change', handler);
+  }, []);
+  return reduced;
+}

package/templates/nextjs/lib/use-lenis.ts

@@ -0,0 +1,35 @@
+'use client';
+
+import { useEffect } from 'react';
+import Lenis from 'lenis';
+
+/**
+ * Smooth scroll for release pages. Disabled when prefers-reduced-motion is set.
+ * If GSAP ScrollTrigger is used, forward Lenis rAF to ScrollTrigger.update().
+ */
+export function useLenisSmoothScroll(enabled = true) {
+  useEffect(() => {
+    if (!enabled) return;
+    const mq = window.matchMedia('(prefers-reduced-motion: reduce)');
+    if (mq.matches) return;
+
+    const lenis = new Lenis({
+      duration: 1.2,
+      smoothWheel: true,
+      wheelMultiplier: 1,
+      touchMultiplier: 1.2,
+    });
+
+    let frameId = 0;
+    const raf = (time: number) => {
+      lenis.raf(time);
+      frameId = requestAnimationFrame(raf);
+    };
+    frameId = requestAnimationFrame(raf);
+
+    return () => {
+      cancelAnimationFrame(frameId);
+      lenis.destroy();
+    };
+  }, [enabled]);
+}

package/templates/nextjs/next.config.ts

@@ -0,0 +1,29 @@
+import type { NextConfig } from 'next';
+
+/**
+ * Baseline security response headers for the deployed app (defense-in-depth).
+ *
+ * A strict Content-Security-Policy is intentionally left out: GSAP/Framer Motion
+ * and Next.js inject inline styles/scripts, so a wrong CSP silently breaks the
+ * page. Add one deliberately (with nonces) once your asset origins are settled —
+ * a starting point is commented below.
+ */
+const securityHeaders = [
+  { key: 'X-Content-Type-Options', value: 'nosniff' },
+  { key: 'X-Frame-Options', value: 'DENY' },
+  { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
+  { key: 'Strict-Transport-Security', value: 'max-age=31536000; includeSubDomains' },
+  { key: 'Permissions-Policy', value: 'camera=(), microphone=(), geolocation=()' },
+  // {
+  //   key: 'Content-Security-Policy',
+  //   value: "default-src 'self'; img-src 'self' https: data: blob:; style-src 'self' 'unsafe-inline'; script-src 'self'",
+  // },
+];
+
+const nextConfig: NextConfig = {
+  async headers() {
+    return [{ source: '/:path*', headers: securityHeaders }];
+  },
+};
+
+export default nextConfig;