cinematic-scroll-skill 2.1.0

package/taste-guardrails.md

@@ -0,0 +1,164 @@
+# Taste Guardrails
+
+> The difference between slop and craft is anti-convergence.
+> This skill refuses to produce generic parallax.
+
+These rules are non-negotiable. They exist because every broken scroll site violates at least three of them. An agent skill that does not enforce taste produces tasteless output — regardless of how good the prompt is.
+
+---
+
+## 1. Banned Patterns
+
+The following patterns are prohibited in all generated output. No exceptions, no "just this once."
+
+### 1.1 Never animate `blur()`, `brightness()`, `contrast()`, or any CSS `filter` during scroll
+**Why:** Filters force a full paint-composite cycle on every frame. On mid-tier mobile GPUs this drops you to 20-30fps instantly. The browser cannot cache filtered layers the same way it caches transform layers.
+**Replacement:** Use crossfades between pre-blurred image assets, or fake depth with opacity + scale layering. If you need a rack-focus effect, crossfade two stacked image layers at different scales — never animate the filter itself.
+
+### 1.2 Never scroll-jack content shorter than 800px
+**Why:** Scroll-jacking (hijacking native scroll behavior for pinned sections) is a contract with the user: you are asking them to surrender control in exchange for a curated experience. If the payoff is less than one viewport tall, the contract is broken. The user feels tricked, not delighted.
+**Replacement:** Let short content flow naturally. Reserve pinning for sections with genuine narrative or visual payoff — title choreography, multi-layer depth reveals, or 3D camera moves.
+
+### 1.3 Never pin more than 3 consecutive sections without a "release viewport"
+**Why:** Three pinned sections in a row creates scroll fatigue. The user loses their sense of progress. Page position stops correlating with scroll position, and the cognitive dissonance builds until they rage-quit.
+**Replacement:** After every 3 pinned sections, insert at least 80vh of free-scrolling "breathing room" — a content section, a footer transition, or a clean chapter break. Let the user feel their scroll wheel working again.
+
+### 1.4 Never apply parallax to text content below 18px
+**Why:** Small text in motion destroys readability. The eye cannot track parallax-shifted microcopy. It becomes visual noise, not information.
+**Replacement:** Keep body copy at `position: relative` with no scroll-driven transforms. Reserve parallax for display type (48px+), background layers, and decorative elements only.
+
+### 1.5 Never call `setState` (React) inside a scroll handler — ever
+**Why:** React state updates trigger re-renders. At 60fps, you are asking React to re-render your component tree 60 times per second. On a complex page, this creates jank that no amount of memoization will fix.
+**Replacement:** Use refs and direct DOM manipulation for scroll-driven values. GSAP's `quickTo`, Framer Motion's `useTransform`, or raw `ref.current.style.transform` assignments. Keep React for structural updates only — never for per-frame values.
+
+### 1.6 Never animate `width`, `height`, `top`, `left`, `margin`, or `padding`
+**Why:** These properties trigger layout recalculation (the "layout thrash"). The browser must recompute the position of every affected element, then paint, then composite. This is a 3-4ms penalty per frame on desktop, 10-15ms on mobile. At 60fps you have 16.67ms total.
+**Replacement:** Use `transform: scale()` for size changes, `transform: translate()` for position changes. If you need content to reflow, toggle a CSS class and let a `transition` handle it — never drive it from a scroll scrubber.
+
+### 1.7 Never use more than 7 depth layers per chapter
+**Why:** Each parallax layer is a composited layer in the GPU. Seven layers at high resolution consume significant VRAM. Beyond seven, you risk memory pressure that causes the browser to drop layers back to CPU rasterization — catastrophically slow.
+**Replacement:** Be selective. 3-4 layers is often enough if the content is strong. Use opacity and scale to fake additional depth without extra layers. The best parallax feels deep with 4 layers; the worst parallax feels flat with 12.
+
+### 1.8 Never attach a scroll listener without rAF throttling or a scrub proxy
+**Why:** Raw `scroll` events fire at irregular intervals and can fire multiple times per frame. Reading `scrollY` and updating the DOM synchronously creates inconsistent motion and missed frames.
+**Replacement:** Use Lenis (`requestAnimationFrame`-based smooth scroll), GSAP ScrollTrigger (which internally uses rAF), or a hand-rolled rAF loop that reads scroll position once per frame. Never update layout from inside a raw `addEventListener('scroll')` callback.
+
+### 1.9 Never apply 3D rotation (`rotateX`, `rotateY`, `perspective` tilt) on touch devices or when `prefers-reduced-motion` is active
+**Why:** 3D tilt on touch devices causes motion sickness for a non-trivial percentage of users (vestibular disorders). It also conflicts with native touch gestures — the browser may interpret rotateY as a swipe intent.
+**Replacement:** On touch devices, replace 3D tilt with subtle scale + opacity fades. Respect `prefers-reduced-motion: reduce` by disabling all scroll-driven motion and showing static compositions instead. See the reduced-motion fallback spec in `SKILL.md`.
+
+### 1.10 Never auto-play scroll-driven motion without user interaction
+**Why:** Auto-scrolling or auto-playing pinned sections (via `setInterval`, `ScrollTrigger.to`, or similar) violates user agency. It also breaks screen readers and keyboard navigation.
+**Replacement:** All motion must be scroll-driven or user-triggered. If you want a "playthrough" experience, provide a prominent "Play intro" button that calls `gsap.to(window, { scrollTo: ... })` — once, on user request.
+
+### 1.11 Never use the same easing curve for every animation in a chapter
+**Why:** Uniform easing makes motion feel mechanical — like a PowerPoint transition, not cinema. Real movement has variation: anticipation, overshoot, decay, snap.
+**Replacement:** Vary easings by role. Hero entrances get `power3.out` (dramatic deceleration). Exits get `power2.in` (clean acceleration away). Micro-interactions get `back.out(1.4)` (playful overshoot). Chapter transitions get `power4.inOut` (weighty, deliberate).
+
+---
+
+## 2. Cinematic Vocabulary
+
+Web scroll is not "web design." It is **digital cinematography**. Every scroll behavior maps to a film grammar. Use the right term, implement the right motion, and the site will feel cinematic instead of gimmicky.
+
+| Film Term | Scroll Equivalent | CSS/GSAP Implementation | Use When |
+|-----------|------------------|------------------------|----------|
+| **Dolly zoom** (Vertigo effect) | Background scales while foreground stays fixed | `scale(1 → 1.3)` on background layer + `translateZ(0 → -200px)`; foreground `scale` counter-animates to maintain size | Hero reveal, dramatic entrance, conveying disorientation or revelation |
+| **Whip pan** | Fast horizontal snap between chapters | `translateX(-100vw → 0)` with `power4.inOut` easing, 0.4s duration; content blurs via motion, not filter | Chapter transition, genre shifts, tonal whiplash |
+| **Rack focus** | Shifting attention between depth planes | Crossfade between two stacked layers at different scales — NOT CSS `filter: blur()`. Top layer fades out as bottom layer fades in, with 10-15% overlap | Shifting subject focus, narrative handoffs, revealing hidden detail |
+| **Tracking shot** | Parallax at medium depth, steady camera | `translateY` at 0.5x scroll rate on mid-layer; foreground and background at 0.2x and 0.8x respectively | Narrative scroll, storytelling sequences, guided attention |
+| **Crane shot** | Vertical dolly + subtle rotation | `translateY` + `rotateX(±4deg)` driven by scroll progress; perspective origin at `50% 100%` | Opening sequence, establishing shot, conveying scale and grandeur |
+| **Static two-shot** | Split viewport, both subjects visible, no motion | Two 50vw columns, both `position: sticky`, zero parallax; tension comes from contrast, not movement | Comparisons, debates, dual narratives, before/after |
+| **Match cut** | Identical composition, content swap | Same layout, same element positions; content crossfades with `opacity` while layout holds perfectly still | Category switches, product variants, timeline jumps |
+| **Push-in** | Slow zoom toward a subject | `scale(1 → 1.08)` over 200vh of scroll, combined with `translateY` to keep subject centered; minimal other motion | Intensifying focus, emotional escalation, "the moment before" |
+| **Montage** | Rapid cuts, stacked cards, snap scroll | Multiple pinned sections at 80vh each, snap scroll between them (`snap: 1 / (sections - 1)`), 0.15s transitions | Showcasing variety, process steps, portfolio grids |
+| **Long take** | Single continuous pinned section with layered reveals | One 300vh pin; elements reveal sequentially via staggered `opacity` + `translateY` tied to scroll progress; no snapping, no hard cuts | Immersive narrative, world-building, letting the user explore at their own pace |
+| **Overhead / God shot** | Scale-down from full frame to reveal surrounding context | `scale(1.5 → 1)` + `translateY(20% → 0)` over pin duration; starts tight on detail, pulls back to show full layout | Revealing structure, "where are we" moments, architectural showcases |
+| **Jump scare** (comedic) | Sudden scale snap + rotation | `scale(0.8 → 1.05)` with `back.out(2)` + `rotateZ(-2deg → 0deg)` triggered at scroll threshold; 0.3s duration | Playful reveals, Easter eggs, Gen-Z energy moments |
+
+---
+
+## 3. Pacing Rules
+
+Timing is not a matter of taste. These are working defaults informed by how scroll motion reads perceptually — strong starting points to adjust with intent, not arbitrary numbers.
+
+### 3.1 Default rhythm
+**1.2s of scroll distance per 100vh of content.** If a section is 200vh tall, the user should spend approximately 2.4 seconds scrolling through it at normal speed. This is the baseline — adjust ±20% for dramatic effect, but never violate it without explicit intent.
+
+### 3.2 Pin duration minimum
+**150vh.** Anything shorter and the pin feels like a glitch — the user hasn't mentally settled into the fixed frame before it releases. The content hasn't "landed."
+
+### 3.3 Pin duration maximum
+**400vh.** Beyond this, users think the page is broken. They try to scroll harder, check their mouse, assume the tab froze. If your content genuinely needs more than 400vh, split it into two pinned sections with a 50vh breathing room between.
+
+### 3.4 Chapter transition breathing room
+**Minimum 80vh of free-scroll space between pinned chapters.** This is the "cut" between scenes. Without it, chapters bleed into each other and the narrative structure collapses.
+
+### 3.5 Title reveal duration
+**30-40% of the total pin scroll range.** If a section is pinned for 200vh, the title choreography should occupy 60-80vh of that range. The title must finish revealing before the 70% mark of the pin — the final 30% is for the payoff, the "so what" moment.
+
+### 3.6 Stagger offset
+**5-8% per element, maximum 5 elements before overlap.** If you stagger more than 5 elements, the early ones finish before the late ones start — the user perceives it as random, not choreographed. For 6+ elements, group them into visual clusters and stagger the clusters instead.
+
+### 3.7 Scroll snap dead zone
+**Never snap within 10vh of a pin start or end.** The snap point must sit comfortably inside the pinned range, not at the boundary. Boundary snaps feel like the scroll is fighting the user.
+
+### 3.8 Motion density limit
+**No more than 3 simultaneous motion types in any 50vh window.** If you have parallax, title stagger, and a color morph, you cannot also have 3D tilt and a progress HUD animation in the same viewport. The eye cannot process it. Pick the 3 most important motions and let the others rest.
+
+---
+
+## 4. Anti-Convergence Principles
+
+These rules exist to prevent the output from looking like every other scroll-driven website on Awwwards. Convergence is the enemy. Generic parallax, default easings, and center-aligned everything are symptoms of the same disease: lack of intention.
+
+### 4.1 Never use default easing
+`ease`, `ease-in-out`, and `linear` are banned. Every animation must specify a custom `cubic-bezier` or a named GSAP easing with intentional character. Default easing signals default thinking.
+- **Hero entrances:** `cubic-bezier(0.16, 1, 0.3, 1)` (dramatic deceleration — the "reveal" feel)
+- **Chapter exits:** `cubic-bezier(0.7, 0, 0.84, 0)` (clean acceleration — the "handoff" feel)
+- **Micro-interactions:** `cubic-bezier(0.34, 1.56, 0.64, 1)` (overshoot — the "playful" feel)
+- **Transitions:** `cubic-bezier(0.87, 0, 0.13, 1)` (heavy, deliberate — the "chapter cut" feel)
+
+### 4.2 Never center-align all text
+Centered text is the first sign of a template. Use intentional asymmetry: left-align body copy, center only display titles (and not all of them), and occasionally right-align pull quotes or metadata. Asymmetry creates visual tension. Tension creates interest.
+
+### 4.3 Never repeat a depth multiplier
+If Layer 1 moves at 0.2x scroll rate and Layer 2 at 0.5x, Layer 3 cannot be 0.8x followed by Layer 4 at 1.0x in the next chapter. Vary the spacing: 0.15x, 0.4x, 0.7x, 1.0x in one chapter; 0.1x, 0.35x, 0.6x, 0.9x in the next. Repetition of depth ratios creates a rhythmic monotony the user cannot name but will feel.
+
+### 4.4 Never repeat a transition type between adjacent chapters
+If Chapter 1 uses a whip-pan exit, Chapter 2 cannot use a whip-pan entry. Alternate transition families: fade → slide → scale → rotate. Adjacent chapters using the same transition family feel like a single long chapter that forgot to end.
+
+### 4.5 Always vary title treatment between chapters
+Each chapter must have a distinct title reveal style. Rotate through this vocabulary:
+- **Mask reveal:** `clip-path: inset()` animates to reveal text (dramatic, editorial)
+- **Word stagger:** Each word fades + translates in with 0.08s offset (narrative, literary)
+- **Letter-spacing scrub:** `letter-spacing` expands from `-0.05em` to `0.02em` tied to scroll (refined, luxury)
+- **Scale-down entrance:** Title starts at 1.3x scale, settles to 1.0x with `power2.out` (impactful, bold)
+- **Blur crossfade:** Two title copies crossfade — one sharp, one pre-blurred, swap opacity (soft, atmospheric)
+- **Typewriter reveal:** Characters appear left-to-right with scroll progress (technical, precise)
+- **Split line rise:** Each line of a multi-line title rises from `translateY(40px)` with stagger (editorial, magazine)
+
+Never use the same treatment twice in a row. Never.
+
+### 4.6 Never use the same palette temperature across all chapters
+A site that is warm in Chapter 1, warm in Chapter 2, warm in Chapter 3 feels like a single photograph stretched too thin. Alternate temperature: warm → cool → neutral → warm. The contrast between chapters creates progression. Progression creates narrative.
+
+### 4.7 Depth layers must earn their place
+Every parallax layer must carry distinct visual information. If two layers are visually similar enough that removing one does not change the experience, merge them. Empty parallax is decoration masquerading as design.
+
+### 4.8 Typography must breathe
+Minimum `line-height: 1.1` for display type, `1.5` for body. Maximum 2 typefaces per chapter (one display, one body). If you need a third, use a weight or style variation of an existing family. More than 2 fonts in one viewport is visual cacophony.
+
+---
+
+## 5. Enforcement
+
+These guardrails are referenced in `SKILL.md` and are part of the agent's system prompt. When generating scroll-driven sections, the skill must:
+
+1. Check every output against the Banned Patterns list before delivering.
+2. Name the cinematic technique being used (from the Cinematic Vocabulary table) in the code comments.
+3. Declare the pin duration, stagger offset, and easing curves in the section manifest.
+4. Verify that no two adjacent chapters share a transition type or title treatment.
+5. Include a reduced-motion fallback for every scroll-driven effect.
+
+**Violating these rules is a bug, not a style choice.**

package/templates/nextjs/.env.example

@@ -0,0 +1,41 @@
+# ──────────────────────────────────────────────────────────────────────────
+# Editions Scroll Generator — environment
+# ──────────────────────────────────────────────────────────────────────────
+#
+# You DON'T need to fill this in to see the page. Run `npm run dev` and the
+# 8 chapters render with CSS-only visuals (demo mode).
+#
+# Fill this in when you're ready for real AI-generated chapter heroes.
+# Easiest path: run  `npm run setup`  — interactive wizard does it for you.
+# ──────────────────────────────────────────────────────────────────────────
+
+# Required for AI image generation. Get one at https://fal.ai/dashboard/keys
+# Format: key_id:key_secret (two parts separated by ":")
+# Stays server-side only via /api/fal/proxy — never sent to the browser.
+FAL_KEY=""
+
+# Default image model. See MODELS.md to swap to Nano Banana, Imagen 3, etc.
+FAL_IMAGE_MODEL="fal-ai/flux-2-pro"
+
+# Optional — only fill in if you want video chapter loops.
+FAL_VIDEO_MODEL=""
+
+# Safe to expose (used in the <title> tag only).
+NEXT_PUBLIC_SITE_NAME="Editions Demo"
+
+# ──────────────────────────────────────────────────────────────────────────
+# Abuse protection for the fal.ai API routes (REQUIRED in production)
+# ──────────────────────────────────────────────────────────────────────────
+# The /api/generate-edition-asset and /api/fal/proxy routes spend your FAL_KEY
+# (each image is real money). This shared secret requires
+# `Authorization: Bearer <GENERATE_API_SECRET>` on those routes.
+#   - Local dev (NODE_ENV !== production): may be empty; routes stay open for demos.
+#   - Production / Vercel preview & prod builds: if this is empty the routes FAIL
+#     CLOSED (generate -> 503, proxy -> rejects all) so nothing runs anonymously.
+# Set it before deploying. To intentionally run the proxy open in pure local dev,
+# use FAL_PROXY_ALLOW_UNAUTH below instead.
+GENERATE_API_SECRET=""
+
+# Set to "true" to run the fal proxy WITHOUT auth (pure local dev only).
+# Never set this in a publicly reachable deployment — it opens a billable proxy.
+FAL_PROXY_ALLOW_UNAUTH=""

package/templates/nextjs/app/api/fal/proxy/route.ts

@@ -0,0 +1,33 @@
+import { createRouteHandler } from '@fal-ai/server-proxy/nextjs';
+import { ALLOWED_FAL_ENDPOINTS } from '@/lib/fal-models';
+import { isBearerValid } from '@/lib/api-guard';
+
+export const runtime = 'nodejs';
+
+/**
+ * fal.ai server proxy — keeps FAL_KEY off the client.
+ *
+ * Auth model:
+ *   - `allowedEndpoints` restricts WHICH fal models the proxy will forward to,
+ *     so a compromised client can't burn your account on arbitrary models.
+ *   - `isAuthenticated` restricts WHO may reach it: by default the proxy requires
+ *     `Authorization: Bearer <GENERATE_API_SECRET>` in EVERY environment.
+ *
+ * Previously this was keyed on `NODE_ENV !== 'production'`, which left Vercel
+ * preview/staging URLs (publicly reachable, built with NODE_ENV=production but
+ * often missing the secret) as open, billable fal proxies. Now it is secure by
+ * default; to intentionally run an open proxy (pure local dev), set
+ * FAL_PROXY_ALLOW_UNAUTH=true.
+ *
+ * Reference: https://fal.ai/docs/model-endpoints/server-side
+ */
+const allowUnauthenticated = process.env.FAL_PROXY_ALLOW_UNAUTH === 'true';
+
+export const { GET, POST, PUT } = createRouteHandler({
+  allowedEndpoints: ALLOWED_FAL_ENDPOINTS.map((id) => `${id}/**`),
+  allowUnauthorizedRequests: allowUnauthenticated,
+  async isAuthenticated(behavior: { getHeader: (name: string) => string | null }) {
+    if (allowUnauthenticated) return true;
+    return isBearerValid(behavior.getHeader('authorization'));
+  },
+});

package/templates/nextjs/app/api/fal/webhook/route.ts

@@ -0,0 +1,132 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { createHash, createPublicKey, verify as ed25519Verify } from 'crypto';
+
+export const runtime = 'nodejs';
+
+/**
+ * fal.ai webhook receiver — called when a queued generation completes.
+ *
+ * Payload shape (from https://fal.ai/docs/model-endpoints/webhooks):
+ *   {
+ *     request_id: string,
+ *     gateway_request_id: string,
+ *     status: 'OK' | 'ERROR',
+ *     payload: { images: [{ url, content_type, file_name, file_size, width, height }], seed },
+ *     error?: string
+ *   }
+ *
+ * Production checklist:
+ *   1. [DONE] Verify the request signature against fal's ED25519 public keys
+ *      (see verifyFalWebhook below). Unsigned / invalid requests get a 401.
+ *   2. Persist {request_id → asset_url} in your DB / KV so the client can poll
+ *      or subscribe via SSE / Pusher / Ably.
+ *   3. Always return 200 quickly — fal retries non-2xx responses.
+ */
+
+const JWKS_URL = 'https://rest.fal.ai/.well-known/jwks.json';
+const JWKS_TTL_MS = 24 * 60 * 60 * 1000; // fal recommends caching keys up to 24h
+const MAX_CLOCK_SKEW_SECONDS = 300; // reject requests older/newer than ±5 min (replay protection)
+
+let jwksCache: { keys: string[]; fetchedAt: number } | null = null;
+
+/** Fetch fal's ED25519 public keys (base64url `x` values), cached for 24h. */
+async function getFalPublicKeys(): Promise<string[]> {
+  if (jwksCache && Date.now() - jwksCache.fetchedAt < JWKS_TTL_MS) {
+    return jwksCache.keys;
+  }
+  const res = await fetch(JWKS_URL, { cache: 'no-store' });
+  if (!res.ok) throw new Error(`Failed to fetch fal JWKS: ${res.status}`);
+  const jwks = (await res.json()) as { keys?: Array<{ x?: string }> };
+  const keys = (jwks.keys ?? []).map((k) => k.x).filter((x): x is string => Boolean(x));
+  jwksCache = { keys, fetchedAt: Date.now() };
+  return keys;
+}
+
+/**
+ * Verify a fal.ai webhook per https://fal.ai/docs/model-endpoints/webhooks.
+ *
+ * Signed message = `${requestId}\n${userId}\n${timestamp}\n${sha256hex(body)}`
+ * signed with ED25519; signature delivered as hex in X-Fal-Webhook-Signature.
+ */
+async function verifyFalWebhook(req: NextRequest, rawBody: string): Promise<boolean> {
+  const requestId = req.headers.get('x-fal-webhook-request-id');
+  const userId = req.headers.get('x-fal-webhook-user-id');
+  const timestamp = req.headers.get('x-fal-webhook-timestamp');
+  const signatureHex = req.headers.get('x-fal-webhook-signature');
+
+  if (!requestId || !userId || !timestamp || !signatureHex) return false;
+
+  // 1. Reject stale/future timestamps to blunt replay attacks.
+  const ts = Number(timestamp);
+  if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > MAX_CLOCK_SKEW_SECONDS) {
+    return false;
+  }
+
+  // 2. Rebuild the exact signed message.
+  const bodyHashHex = createHash('sha256').update(rawBody, 'utf8').digest('hex');
+  const message = Buffer.from(`${requestId}\n${userId}\n${timestamp}\n${bodyHashHex}`, 'utf8');
+
+  const signature = Buffer.from(signatureHex, 'hex');
+  if (signature.length !== 64) return false; // ED25519 signatures are 64 bytes
+
+  // 3. Accept if any current fal public key verifies the signature.
+  let keys: string[];
+  try {
+    keys = await getFalPublicKeys();
+  } catch {
+    return false; // fail closed if keys can't be fetched
+  }
+
+  for (const x of keys) {
+    try {
+      const publicKey = createPublicKey({
+        key: { kty: 'OKP', crv: 'Ed25519', x },
+        format: 'jwk',
+      });
+      if (ed25519Verify(null, message, publicKey, signature)) return true;
+    } catch {
+      // malformed key — try the next one
+    }
+  }
+  return false;
+}
+
+export async function POST(req: NextRequest) {
+  // Read the raw body once — needed verbatim for signature hashing.
+  const rawBody = await req.text();
+
+  const verified = await verifyFalWebhook(req, rawBody);
+  if (!verified) {
+    return NextResponse.json({ error: 'Invalid webhook signature' }, { status: 401 });
+  }
+
+  let body: {
+    request_id?: string;
+    gateway_request_id?: string;
+    status?: 'OK' | 'ERROR';
+    payload?: { images?: Array<{ url?: string }>; seed?: number };
+    error?: string;
+  };
+
+  try {
+    body = JSON.parse(rawBody);
+  } catch {
+    return NextResponse.json({ error: 'Invalid JSON' }, { status: 400 });
+  }
+
+  const chapterId = req.nextUrl.searchParams.get('chapter') ?? 'unknown';
+  const imageUrl = body.payload?.images?.[0]?.url;
+
+  // TODO(you): persist this to your storage layer.
+  // Example with @vercel/kv:
+  //   await kv.set(`asset:${chapterId}`, { url: imageUrl, requestId: body.request_id });
+  console.log('[fal-webhook]', {
+    chapterId,
+    requestId: body.request_id,
+    status: body.status,
+    url: imageUrl,
+    error: body.error,
+  });
+
+  return NextResponse.json({ received: true });
+}

package/templates/nextjs/app/api/generate-edition-asset/route.ts

@@ -0,0 +1,66 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { generateEditionImage, submitEditionImage } from '@/lib/fal-generate';
+import { resolveModelId, type FalImageModelId } from '@/lib/fal-models';
+import type { EditionAssetPrompt } from '@/lib/prompt-contract';
+import { rateLimit, requireBearer } from '@/lib/api-guard';
+
+export const runtime = 'nodejs';
+// fal-ai/flux-2-pro typically completes in 3-8s. Allow 60s headroom.
+export const maxDuration = 60;
+
+type RequestBody = EditionAssetPrompt & {
+  /** "sync" (default, blocking) or "queue" (returns request_id, posts result to webhook). */
+  mode?: 'sync' | 'queue';
+  /** Override default FAL_IMAGE_MODEL per-request. */
+  modelId?: FalImageModelId;
+};
+
+export async function POST(req: NextRequest) {
+  // Guard the FAL_KEY: throttle every caller, and (if GENERATE_API_SECRET is set)
+  // require a bearer token. Without this, a deployed URL is an anonymous billing drain.
+  const limited = rateLimit(req);
+  if (limited) return limited;
+
+  const unauthorized = requireBearer(req);
+  if (unauthorized) return unauthorized;
+
+  if (!process.env.FAL_KEY) {
+    return NextResponse.json(
+      { error: 'FAL_KEY missing. Add it to .env.local (see .env.example).' },
+      { status: 500 },
+    );
+  }
+
+  let body: RequestBody;
+  try {
+    body = (await req.json()) as RequestBody;
+  } catch {
+    return NextResponse.json({ error: 'Invalid JSON body' }, { status: 400 });
+  }
+
+  if (!body.chapterId || !body.subject || !body.productTruth) {
+    return NextResponse.json(
+      { error: 'Missing required fields: chapterId, subject, productTruth' },
+      { status: 400 },
+    );
+  }
+
+  const modelId = body.modelId ?? resolveModelId(process.env.FAL_IMAGE_MODEL);
+  const mode = body.mode ?? 'sync';
+
+  try {
+    if (mode === 'queue') {
+      const origin = req.nextUrl.origin;
+      const webhookUrl = `${origin}/api/fal/webhook?chapter=${encodeURIComponent(body.chapterId)}`;
+      const submission = await submitEditionImage(body, webhookUrl, modelId);
+      return NextResponse.json({ status: 'queued', ...submission });
+    }
+
+    const asset = await generateEditionImage(body, modelId);
+    return NextResponse.json({ status: 'ok', ...asset });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown fal.ai error';
+    console.error('[generate-edition-asset]', message, error);
+    return NextResponse.json({ error: message, modelId }, { status: 500 });
+  }
+}

package/templates/nextjs/app/globals.css

@@ -0,0 +1,80 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+:root {
+  color-scheme: dark;
+  /* Fluid type scale — clamp(min, fluid, max) */
+  --fluid-eyebrow: clamp(0.65rem, 0.55rem + 0.3vw, 0.78rem);
+  --fluid-body: clamp(1rem, 0.92rem + 0.45vw, 1.25rem);
+  --fluid-headline: clamp(2.25rem, 1.2rem + 5vw, 5rem);
+  --fluid-display: clamp(3rem, 1.4rem + 9vw, 9.5rem);
+}
+
+html,
+body {
+  background: #0b0907;
+  color: #fff;
+  -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
+}
+
+/* Prevent horizontal bounce / overscroll color flash on iOS */
+html {
+  background-color: #0b0907;
+  overscroll-behavior-y: none;
+}
+
+/* Reserve scrollbar gutter so pin/release doesn't shift layout */
+@media (min-width: 1024px) {
+  html { scrollbar-gutter: stable; }
+}
+
+/* ─── Fluid typography utilities ─────────────────────────────────────── */
+
+.text-fluid-eyebrow { font-size: var(--fluid-eyebrow); }
+.text-fluid-body { font-size: var(--fluid-body); }
+.text-fluid-headline { font-size: var(--fluid-headline); }
+.text-fluid-display { font-size: var(--fluid-display); }
+
+/* ─── Reduced motion: kill animations + neutralise pinned sections ───── */
+
+@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;
+  }
+
+  /* Snap any pinned section into a stable readable state */
+  [data-pin],
+  .scrollchoreography-pin {
+    position: static !important;
+    height: auto !important;
+    min-height: 100vh;
+  }
+}
+
+/* ─── Touch / coarse-pointer adjustments ─────────────────────────────── */
+
+@media (hover: none) and (pointer: coarse) {
+  /* Touch devices: ensure tap targets meet WCAG / HIG 44px minimum */
+  a, button, [role='button'] {
+    min-height: 44px;
+  }
+  /* Disable hover-only transforms */
+  *:hover {
+    transform: none !important;
+  }
+}
+
+/* ─── iOS Safari momentum scroll preservation ─────────────────────────── */
+
+@supports (-webkit-touch-callout: none) {
+  body {
+    -webkit-overflow-scrolling: touch;
+  }
+}

package/templates/nextjs/app/layout.tsx

@@ -0,0 +1,21 @@
+import type { Metadata, Viewport } from 'next';
+import './globals.css';
+
+export const metadata: Metadata = {
+  title: process.env.NEXT_PUBLIC_SITE_NAME ?? 'Editions Demo',
+  description: 'Cinematic chaptered release page built with choreo-3d.',
+};
+
+export const viewport: Viewport = {
+  width: 'device-width',
+  initialScale: 1,
+  viewportFit: 'cover',
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body className="antialiased">{children}</body>
+    </html>
+  );
+}

package/templates/nextjs/app/page.tsx

@@ -0,0 +1,10 @@
+import { EditionsPage } from '@/components/EditionsPage';
+import { SmoothScrollProvider } from '@/components/SmoothScrollProvider';
+
+export default function Page() {
+  return (
+    <SmoothScrollProvider>
+      <EditionsPage />
+    </SmoothScrollProvider>
+  );
+}