cinematic-scroll-skill 2.1.0

package/templates/nextjs/components/EditionsPage.tsx

@@ -0,0 +1,116 @@
+'use client';
+
+import React from 'react';
+import { ScrollBackgroundMorph } from 'choreo-3d';
+import { editionChapters, editionThemes } from '@/lib/editions-manifest';
+import { ChapterScene } from '@/components/ChapterScene';
+
+/**
+ * Editions release page orchestrator.
+ *
+ * Each chapter is a self-contained <ChapterScene> with 7 parallax layers,
+ * a perspective camera, word-stagger title reveal, and a mobile fallback.
+ * This file stays small on purpose — extend chapters in `editions-manifest.ts`.
+ */
+export function EditionsPage() {
+  const [activeId, setActiveId] = React.useState(editionChapters[0]?.id ?? null);
+
+  React.useEffect(() => {
+    const nodes = editionChapters
+      .map((chapter) => document.getElementById(chapter.id))
+      .filter(Boolean) as HTMLElement[];
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        const visible = entries
+          .filter((entry) => entry.isIntersecting)
+          .sort((a, b) => b.intersectionRatio - a.intersectionRatio)[0];
+        if (visible?.target.id) setActiveId(visible.target.id);
+      },
+      { threshold: [0.25, 0.5, 0.75], rootMargin: '-10% 0px -10% 0px' },
+    );
+
+    nodes.forEach((node) => observer.observe(node));
+    return () => observer.disconnect();
+  }, []);
+
+  return (
+    <main className="relative min-h-screen overflow-x-hidden bg-[#0b0907] text-white selection:bg-white selection:text-black">
+      <ScrollBackgroundMorph activeId={activeId} themes={editionThemes} />
+      <TopNav />
+      <ChapterIndex activeId={activeId} />
+
+      {editionChapters.map((chapter, i) => (
+        <ChapterScene key={chapter.id} chapter={chapter} eager={i === 0} />
+      ))}
+    </main>
+  );
+}
+
+// ─── Persistent top nav with safe-area + 44px tap targets ─────────────────
+
+function TopNav() {
+  return (
+    <nav
+      className="fixed inset-x-0 top-0 z-50 flex items-center justify-between bg-black/30 px-[max(env(safe-area-inset-left),1.25rem)] backdrop-blur-sm md:px-8"
+      style={{ paddingTop: 'max(env(safe-area-inset-top), 0.75rem)', paddingBottom: '0.75rem' }}
+    >
+      <a
+        href="#prologue"
+        className="grid h-11 min-w-[44px] place-items-center font-mono text-xs uppercase tracking-[0.22em] text-white"
+      >
+        Editions Demo
+      </a>
+      <div className="hidden items-center gap-2 md:flex">
+        {editionChapters.slice(1, 5).map((chapter) => (
+          <a
+            key={chapter.id}
+            href={`#${chapter.id}`}
+            className="grid h-11 min-w-[44px] place-items-center px-3 text-xs uppercase tracking-[0.18em] text-white/75 hover:text-white"
+          >
+            {chapter.eyebrow}
+          </a>
+        ))}
+        <a
+          href="#prologue"
+          className="ml-2 grid h-11 min-w-[88px] place-items-center rounded-full bg-white px-5 text-xs font-semibold uppercase tracking-[0.16em] text-black"
+        >
+          Start
+        </a>
+      </div>
+    </nav>
+  );
+}
+
+// ─── Persistent chapter index — hidden on mobile, hidden on iPad portrait ─
+
+function ChapterIndex({ activeId }: { activeId: string | null }) {
+  return (
+    <aside
+      aria-label="Chapter index"
+      className="fixed bottom-6 left-5 z-50 hidden w-44 text-white/70 lg:block"
+      style={{
+        paddingLeft: 'env(safe-area-inset-left)',
+        paddingBottom: 'env(safe-area-inset-bottom)',
+      }}
+    >
+      <p className="mb-3 font-mono text-[10px] uppercase tracking-[0.24em]">Chapters</p>
+      <div className="space-y-1">
+        {editionChapters.map((chapter) => {
+          const isActive = activeId === chapter.id;
+          return (
+            <a
+              key={chapter.id}
+              href={`#${chapter.id}`}
+              className="grid min-h-[36px] grid-cols-[24px_1fr] items-baseline gap-2 font-mono text-[11px] uppercase tracking-[0.16em]"
+              aria-current={isActive ? 'true' : undefined}
+            >
+              <span className={isActive ? 'text-white' : 'text-white/35'}>{chapter.roman}</span>
+              <span className={isActive ? 'text-white' : 'text-white/45'}>{chapter.eyebrow}</span>
+            </a>
+          );
+        })}
+      </div>
+    </aside>
+  );
+}

package/templates/nextjs/components/SmoothScrollProvider.tsx

@@ -0,0 +1,8 @@
+'use client';
+
+import { useLenisSmoothScroll } from '@/lib/use-lenis';
+
+export function SmoothScrollProvider({ children }: { children: React.ReactNode }) {
+  useLenisSmoothScroll();
+  return <>{children}</>;
+}

package/templates/nextjs/lib/api-guard.ts

@@ -0,0 +1,110 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { timingSafeEqual } from 'crypto';
+
+/**
+ * Dependency-free guards for the fal.ai API routes.
+ *
+ * Why this exists: the generate/proxy routes spend your FAL_KEY (each image is
+ * real money). Without a gate, a deployed URL is an anonymous billing drain.
+ *
+ *   - rateLimit:    best-effort per-IP throttle (always on)
+ *   - requireBearer / isBearerValid: optional shared-secret gate
+ *     (enabled by setting GENERATE_API_SECRET)
+ *
+ * Rate limiting is in-memory: it holds within a warm Fluid Compute instance but
+ * is not a cross-instance guarantee. For hard global limits, back `hits` with a
+ * shared store (Upstash / Vercel KV).
+ */
+
+const WINDOW_MS = 60_000;
+const MAX_REQUESTS = 10;
+/** Hard backstop so a flood of unique (spoofed) IPs can't grow the Map unbounded. */
+const MAX_TRACKED_IPS = 10_000;
+const hits = new Map<string, number[]>();
+let lastSweep = 0;
+
+export function clientIp(req: NextRequest): string {
+  const fwd = req.headers.get('x-forwarded-for');
+  if (fwd) return fwd.split(',')[0]!.trim();
+  return req.headers.get('x-real-ip') ?? 'unknown';
+}
+
+/** Drop entries whose hits have all aged out; runs at most once per window. */
+function sweep(now: number, windowMs: number): void {
+  if (now - lastSweep < windowMs) return;
+  lastSweep = now;
+  for (const [ip, times] of hits) {
+    if (times.every((t) => now - t >= windowMs)) hits.delete(ip);
+  }
+}
+
+/** Returns null if allowed, or a 429 response if the caller is over the limit. */
+export function rateLimit(
+  req: NextRequest,
+  max = MAX_REQUESTS,
+  windowMs = WINDOW_MS,
+): NextResponse | null {
+  const ip = clientIp(req);
+  const now = Date.now();
+  sweep(now, windowMs);
+
+  const recent = (hits.get(ip) ?? []).filter((t) => now - t < windowMs);
+  if (recent.length >= max) {
+    return NextResponse.json(
+      { error: 'Rate limit exceeded. Try again shortly.' },
+      { status: 429, headers: { 'Retry-After': String(Math.ceil(windowMs / 1000)) } },
+    );
+  }
+  // Backstop: if the Map is somehow saturated with new IPs, force a sweep; if it
+  // is still full, fail closed (429) rather than grow without bound.
+  if (!hits.has(ip) && hits.size >= MAX_TRACKED_IPS) {
+    lastSweep = 0;
+    sweep(now, windowMs);
+    if (hits.size >= MAX_TRACKED_IPS) {
+      return NextResponse.json(
+        { error: 'Server busy. Try again shortly.' },
+        { status: 429, headers: { 'Retry-After': String(Math.ceil(windowMs / 1000)) } },
+      );
+    }
+  }
+  recent.push(now);
+  hits.set(ip, recent);
+  return null;
+}
+
+function safeEqual(a: string, b: string): boolean {
+  const ab = Buffer.from(a);
+  const bb = Buffer.from(b);
+  if (ab.length !== bb.length) return false;
+  return timingSafeEqual(ab, bb);
+}
+
+/** True if `authorization` carries the configured `Bearer <GENERATE_API_SECRET>`. */
+export function isBearerValid(authorization: string | null | undefined): boolean {
+  const secret = process.env.GENERATE_API_SECRET;
+  if (!secret) return false;
+  const token = authorization?.startsWith('Bearer ') ? authorization.slice(7) : '';
+  return safeEqual(token, secret);
+}
+
+/**
+ * Shared-secret gate for route handlers.
+ *   - GENERATE_API_SECRET set        -> requires `Authorization: Bearer <secret>`.
+ *   - unset in development           -> no-op (returns null) so local demos work.
+ *   - unset in production (incl.     -> fails CLOSED with 503 so a careless deploy
+ *     Vercel preview/prod builds)       can't run an anonymous billing drain.
+ * Returns null if allowed, or an error response otherwise.
+ */
+export function requireBearer(req: NextRequest): NextResponse | null {
+  if (!process.env.GENERATE_API_SECRET) {
+    if (process.env.NODE_ENV === 'production') {
+      return NextResponse.json(
+        { error: 'Server misconfigured: GENERATE_API_SECRET is required in production.' },
+        { status: 503 },
+      );
+    }
+    return null;
+  }
+  if (isBearerValid(req.headers.get('authorization'))) return null;
+  return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+}

package/templates/nextjs/lib/editions-manifest.ts

@@ -0,0 +1,224 @@
+import type { ScrollMorphTheme } from 'choreo-3d';
+
+export type EditionChapter = {
+  id: string;
+  roman: string;
+  eyebrow: string;
+  title: string;
+  summary: string;
+  technicalDetail: string;
+  features: string[];
+  accent: string;
+  /**
+   * Optional. When undefined, ChapterScene renders the CSS-only ChapterDemoVisual
+   * (works beautifully without any fal.ai setup). Set to a path like
+   * `/generated/<id>.jpg` after running `node scripts/generate-chapter-assets.mjs`.
+   */
+  background?: string;
+  /** Optional inline base64/blur data URL — enables Next/Image blur placeholder. */
+  backgroundBlur?: string;
+  foreground?: string;
+  poster?: string;
+  video?: string;
+  /** Background-morph atmosphere for this chapter. */
+  atmosphere: ScrollMorphTheme;
+  visualPrompt: {
+    subject: string;
+    productTruth: string;
+    historicalLayer: 'renaissance' | 'baroque' | 'atelier' | 'architectural' | 'industrial';
+    modernLayer: string;
+    palette: string[];
+    camera: 'wide' | 'medium' | 'macro' | 'isometric' | 'low-angle';
+  };
+};
+
+/**
+ * 8-chapter demo manifest. Replace with project-specific chapters.
+ * 6–12 chapters is the sweet spot — under 6 feels light, over 12 feels endless.
+ */
+export const editionChapters: EditionChapter[] = [
+  {
+    id: 'prologue',
+    roman: 'I',
+    eyebrow: 'The Release',
+    title: 'A new operating layer for visual decisions.',
+    summary:
+      'A cinematic chaptered page that turns product updates into a world people understand in seconds.',
+    technicalDetail:
+      'Scroll progress drives 7 pinned layers per chapter, atmospheric background morphs, and generated visual assets.',
+    features: ['Chapter taxonomy', 'Generated visual system', 'HTML overlay typography'],
+    accent: '#ff4fc3',
+    // background: '/generated/prologue.webp',   ← uncomment after running `node scripts/generate-chapter-assets.mjs`
+    foreground: '/generated/prologue-figure.webp',
+    atmosphere: {
+      background: 'linear-gradient(to bottom, #0b0907 0%, #1a1410 60%, #2a1a14 100%)',
+    },
+    visualPrompt: {
+      subject: 'two figures in a classical studio discovering a glowing product interface on a table',
+      productTruth: 'the product turns fragmented updates into a coherent release system',
+      historicalLayer: 'renaissance',
+      modernLayer: 'transparent software panel, product cards, subtle AI terminal glow',
+      palette: ['aged cream', 'deep umber', 'acid pink', 'soft sky blue'],
+      camera: 'wide',
+    },
+  },
+  {
+    id: 'agentic',
+    roman: 'II',
+    eyebrow: 'Agentic Layer',
+    title: 'The interface stops waiting for instructions.',
+    summary: 'Agents convert product context into suggested actions, experiments, and operational next steps.',
+    technicalDetail: 'Fast foreground UI layer over a slow generated background keeps content editable.',
+    features: ['Action routing', 'Context memory', 'Approval gates'],
+    accent: '#b4ff38',
+    // background: '/generated/agentic.webp',
+    atmosphere: {
+      background: 'linear-gradient(to bottom right, #0d1410 0%, #14201a 60%, #1f2e1c 100%)',
+    },
+    visualPrompt: {
+      subject: 'a classical cartographer mapping commerce routes that become glowing conversational pathways',
+      productTruth: 'agents expose product actions across chat, search, and workflow surfaces',
+      historicalLayer: 'baroque',
+      modernLayer: 'floating graph nodes, chat cards, route lines, product tiles',
+      palette: ['dark olive', 'gold leaf', 'blackened green', 'electric lime'],
+      camera: 'medium',
+    },
+  },
+  {
+    id: 'studio',
+    roman: 'III',
+    eyebrow: 'Visual Studio',
+    title: 'Assets become a pipeline, not a folder.',
+    summary: 'fal.ai generates chapter images, posters, and variants through a structured prompt contract.',
+    technicalDetail: 'Server-side generation protects credentials, normalises prompts, and records output metadata.',
+    features: ['fal.ai proxy', 'Prompt manifest', 'Variant generation'],
+    accent: '#37c7ff',
+    // background: '/generated/studio.webp',
+    atmosphere: {
+      background: 'linear-gradient(to bottom, #0a1418 0%, #102230 60%, #1a3447 100%)',
+    },
+    visualPrompt: {
+      subject: 'a painterly atelier where canvases connect to a modern asset generation console',
+      productTruth: 'creative direction becomes repeatable infrastructure',
+      historicalLayer: 'atelier',
+      modernLayer: 'generation queue, image grid, prompt cards, render status lights',
+      palette: ['warm canvas', 'sepia', 'cyan', 'bone white'],
+      camera: 'wide',
+    },
+  },
+  {
+    id: 'taste',
+    roman: 'IV',
+    eyebrow: 'Taste Layer',
+    title: 'Quality becomes a scoring function.',
+    summary: 'Every generated asset passes a measurable taste filter before reaching the page.',
+    technicalDetail: 'Evaluation runs as a pure function on prompt + output metadata; scores feed back into ranking.',
+    features: ['Composition scoring', 'Palette adherence', 'Brand voice gate'],
+    accent: '#e87e7e',
+    // background: '/generated/taste.webp',
+    atmosphere: {
+      background: 'linear-gradient(to bottom, #1a0f10 0%, #2a181a 60%, #3a2024 100%)',
+    },
+    visualPrompt: {
+      subject: 'a renaissance textile master inspecting silk samples under structured studio light',
+      productTruth: 'taste is enforced as a deterministic, measurable layer',
+      historicalLayer: 'renaissance',
+      modernLayer: 'score readouts, composition overlays, accept/reject toggles',
+      palette: ['deep crimson', 'ivory', 'oxidised brass', 'soft rose'],
+      camera: 'macro',
+    },
+  },
+  {
+    id: 'infrastructure',
+    roman: 'V',
+    eyebrow: 'Infrastructure',
+    title: 'The mesh that holds the worlds together.',
+    summary: 'Edge runtime, queue workers, and private networking that keep generation fast and durable.',
+    technicalDetail: 'Vercel Edge + queue workers + Tailscale mesh. Background jobs use fal.queue webhook callbacks.',
+    features: ['Edge runtime', 'Durable queues', 'Mesh networking'],
+    accent: '#c8a0f0',
+    // background: '/generated/infrastructure.webp',
+    atmosphere: {
+      background: 'linear-gradient(to bottom, #100b1a 0%, #1a142a 60%, #28203f 100%)',
+    },
+    visualPrompt: {
+      subject: 'a victorian engine room reimagined as a soft, glowing distributed computing diagram',
+      productTruth: 'the platform survives spikes and stays cheap at idle',
+      historicalLayer: 'industrial',
+      modernLayer: 'queue depth gauges, edge region map, latency sparklines',
+      palette: ['twilight purple', 'brass', 'steel blue', 'ember orange'],
+      camera: 'wide',
+    },
+  },
+  {
+    id: 'deploy',
+    roman: 'VI',
+    eyebrow: 'Deploy Layer',
+    title: 'Every release is a reversible plan.',
+    summary: 'DAG-based deploys make each step inspectable, pausable, and revertable.',
+    technicalDetail: 'Plans compile to a DAG; agents execute steps with explicit approval gates between layers.',
+    features: ['DAG planner', 'Approval gates', 'One-click rollback'],
+    accent: '#f0c060',
+    // background: '/generated/deploy.webp',
+    atmosphere: {
+      background: 'linear-gradient(to bottom, #1a1308 0%, #2a1f10 60%, #3a2d18 100%)',
+    },
+    visualPrompt: {
+      subject: 'an architectural drafting studio where blueprints flow into a glowing release plan',
+      productTruth: 'deployments stop being terrifying',
+      historicalLayer: 'architectural',
+      modernLayer: 'plan tiles, approval buttons, rollback timeline',
+      palette: ['vellum', 'india ink', 'amber', 'bone'],
+      camera: 'isometric',
+    },
+  },
+  {
+    id: 'integration',
+    roman: 'VII',
+    eyebrow: 'Integration Surface',
+    title: 'Plug into anything you already use.',
+    summary: 'FastMCP tools, REST connectors, and webhooks make the platform a citizen of your stack.',
+    technicalDetail: 'Adapters expose the same primitives to MCP, REST, and event sources without per-target rewrites.',
+    features: ['MCP server', 'REST connectors', 'Webhook gateway'],
+    accent: '#60d0e0',
+    // background: '/generated/integration.webp',
+    atmosphere: {
+      background: 'linear-gradient(to bottom, #08161a 0%, #102830 60%, #1a3a47 100%)',
+    },
+    visualPrompt: {
+      subject: 'a telegraph exchange where copper wires resolve into a clean modern integration diagram',
+      productTruth: 'integration becomes a configuration, not a project',
+      historicalLayer: 'industrial',
+      modernLayer: 'tool registry, connector cards, webhook log',
+      palette: ['midnight teal', 'copper', 'sky', 'graphite'],
+      camera: 'medium',
+    },
+  },
+  {
+    id: 'horizon',
+    roman: 'VIII',
+    eyebrow: 'The Horizon',
+    title: 'Compounding advantage, one chapter at a time.',
+    summary: 'Each release adds a permanent capability — the platform learns the way an atelier learns.',
+    technicalDetail: 'A capability graph captures what the platform can do; agents query it to plan future work.',
+    features: ['Capability graph', 'Learned templates', 'Open roadmap'],
+    accent: '#e8e0c8',
+    // background: '/generated/horizon.webp',
+    atmosphere: {
+      background: 'linear-gradient(to bottom, #14110a 0%, #1f1b12 60%, #2e2820 100%)',
+    },
+    visualPrompt: {
+      subject: 'a cliff surveyor at dawn measuring a wide unfolding landscape',
+      productTruth: 'the system gets better every release without changing what it is',
+      historicalLayer: 'atelier',
+      modernLayer: 'roadmap card, capability map, version timeline',
+      palette: ['parchment', 'rust', 'sky', 'ink'],
+      camera: 'wide',
+    },
+  },
+];
+
+/** Theme map keyed by chapter id, ready to pass to <ScrollBackgroundMorph themes={...}>. */
+export const editionThemes: Record<string, ScrollMorphTheme> = Object.fromEntries(
+  editionChapters.map((chapter) => [chapter.id, chapter.atmosphere]),
+);

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

@@ -0,0 +1,12 @@
+import { fal } from '@fal-ai/client';
+
+let configured = false;
+
+export function configureFalClient() {
+  if (configured) return fal;
+  fal.config({
+    proxyUrl: '/api/fal/proxy',
+  });
+  configured = true;
+  return fal;
+}

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

@@ -0,0 +1,86 @@
+import { fal } from '@fal-ai/client';
+import { buildEditionPrompt, EDITION_AVOID, type EditionAssetPrompt } from './prompt-contract';
+import { getModel, resolveModelId, type FalImageModelId, type Orientation } from './fal-models';
+
+export type GeneratedEditionAsset = {
+  chapterId: string;
+  url: string;
+  modelId: FalImageModelId;
+  requestId?: string;
+  raw: unknown;
+};
+
+const ORIENTATION_FOR: Record<EditionAssetPrompt['outputRole'], Orientation> = {
+  hero: 'landscape',
+  'chapter-bg': 'landscape',
+  'foreground-object': 'portrait',
+  poster: 'portrait',
+  'motion-source': 'landscape',
+};
+
+/**
+ * Synchronous generation — best for prototyping and asset-script batches up to ~5 chapters.
+ * For long-running batches or video models, use `submitEditionImage()` (queue + webhook).
+ */
+export async function generateEditionImage(
+  input: EditionAssetPrompt,
+  overrideModelId?: FalImageModelId,
+): Promise<GeneratedEditionAsset> {
+  const modelId = overrideModelId ?? resolveModelId(process.env.FAL_IMAGE_MODEL);
+  const model = getModel(modelId);
+
+  const modelInput = model.buildInput({
+    prompt: buildEditionPrompt(input),
+    avoid: EDITION_AVOID,
+    orientation: ORIENTATION_FOR[input.outputRole],
+    seed: input.seed,
+  });
+
+  const result = await fal.subscribe(modelId, {
+    input: modelInput,
+    logs: true,
+  });
+
+  const url = model.extractUrl(result.data);
+  if (!url) {
+    throw new Error(`fal.ai (${modelId}) returned no image URL. Raw: ${JSON.stringify(result.data).slice(0, 200)}`);
+  }
+
+  return {
+    chapterId: input.chapterId,
+    url,
+    modelId,
+    requestId: result.requestId,
+    raw: result.data,
+  };
+}
+
+/**
+ * Async submission — returns a request_id immediately, fal posts the result to
+ * `webhookUrl` when complete. Use this in production for batch generation, video
+ * models, or any chapter set above 5 images.
+ *
+ * The webhook receiver lives at `app/api/fal/webhook/route.ts`.
+ */
+export async function submitEditionImage(
+  input: EditionAssetPrompt,
+  webhookUrl: string,
+  overrideModelId?: FalImageModelId,
+): Promise<{ requestId: string; modelId: FalImageModelId }> {
+  const modelId = overrideModelId ?? resolveModelId(process.env.FAL_IMAGE_MODEL);
+  const model = getModel(modelId);
+
+  const modelInput = model.buildInput({
+    prompt: buildEditionPrompt(input),
+    avoid: EDITION_AVOID,
+    orientation: ORIENTATION_FOR[input.outputRole],
+    seed: input.seed,
+  });
+
+  const { request_id } = await fal.queue.submit(modelId, {
+    input: modelInput,
+    webhookUrl,
+  });
+
+  return { requestId: request_id, modelId };
+}