cinematic-scroll-skill 2.1.0

package/examples/GETTING_STARTED.md

@@ -0,0 +1,279 @@
+# Getting started — fal.ai image generation (beginner guide)
+
+The full-release-site mode of this skill generates chapter hero images through **fal.ai**. You bring your own API key. The skill does **not** ship with keys, credits, or a shared account — and you can skip fal.ai entirely (the page renders stunning CSS-only chapter visuals at $0).
+
+---
+
+## Quick answers
+
+| Question | Answer |
+|---|---|
+| Do I get a fal.ai key with the skill? | **No.** You create a free fal.ai account and add your own key. |
+| Who pays for image generation? | **You**, directly to fal.ai (pay-as-you-go credits). |
+| Is my key exposed in the browser? | **No.** Keys stay server-side via a Next.js proxy route. |
+| Can I skip fal.ai and use my own images? | **Yes.** Replace manifest asset URLs with your own files in `public/`. |
+
+---
+
+## What you need before you start
+
+1. **Node.js 18+** and **npm**
+2. A **Next.js App Router** project (or let the skill scaffold one for you)
+3. A **fal.ai account** — sign up at [https://fal.ai](https://fal.ai)
+4. About **5 minutes** for first-time key setup
+
+Estimated cost for a typical 8-chapter release page: **~$0.50–$2.00** in fal.ai credits (model-dependent). Check current pricing on fal.ai before generating large batches.
+
+---
+
+## Step 1 — Create a fal.ai account and API key
+
+1. Go to [https://fal.ai](https://fal.ai) and sign up (email or GitHub).
+2. Open **Dashboard → API Keys** (or **Settings → Keys**).
+3. Click **Create API Key**.
+4. Copy the key immediately — it looks like:
+
+   ```
+   abc123def456:9876543210abcdef9876543210abcdef
+   ```
+
+   Format is always `key_id:key_secret` (two parts separated by a colon).
+
+5. Add billing/credits if fal.ai prompts you. Most accounts need a small credit balance before generation works.
+
+> **Security:** Treat this key like a password. Never commit it to Git, never paste it into client-side React components, and never share it in screenshots.
+
+---
+
+## Step 2 — Add the key to your project
+
+In your Next.js project root (same folder as `package.json`):
+
+1. Copy the example env file:
+
+   ```bash
+   cp .env.example .env.local
+   ```
+
+2. Open `.env.local` and set your key:
+
+   ```bash
+   FAL_KEY="your_key_id:your_key_secret"
+   FAL_IMAGE_MODEL="fal-ai/flux-2-pro"
+   NEXT_PUBLIC_SITE_NAME="My Release Page"
+   ```
+
+3. Confirm `.env.local` is in `.gitignore` (Next.js adds this by default).
+
+### Environment variables explained
+
+| Variable | Required? | What it does |
+|---|---|---|
+| `FAL_KEY` | **Yes** | Your fal.ai API key. Read only on the **server** (API routes). |
+| `FAL_IMAGE_MODEL` | No | Image model id. Default: `fal-ai/flux-2-pro` (see tier table below). |
+| `FAL_VIDEO_MODEL` | No | Optional video model for motion loops. Leave empty until you need video. |
+| `NEXT_PUBLIC_SITE_NAME` | No | Site title shown in the browser tab. Safe to expose (no secret). |
+
+### Image model tiers
+
+Change `FAL_IMAGE_MODEL` to switch — no code change needed.
+
+**FLUX family — best photorealism, material texture, editorial depth**
+
+| Model ID | Cost/img | Speed | When to use |
+|---|---|---|---|
+| `fal-ai/flux-2-pro` | ~$0.06 | ~4s | **Default — SOTA editorial, portraits, materials** |
+| `fal-ai/flux-2-max` | ~$0.08 | ~5s | Final hero renders, absolute max quality |
+| `fal-ai/flux-2/turbo` | ~$0.02 | ~2s | Draft rounds, fast iteration |
+| `fal-ai/flux-pro/v1.1/ultra` | ~$0.06 | ~10s | Prev-gen 4MP alternative |
+| `fal-ai/flux-pro/v1.1` | ~$0.05 | ~4.5s | High-volume cost-sensitive batches |
+| `fal-ai/flux/dev` | Free | Slow | **NON-COMMERCIAL ONLY — local prototyping, never production** |
+
+**Google "Nano Banana" family — best for text-in-image, conversational editing, complex scene direction**
+
+(Yes, "Nano Banana" is the real Google/fal.ai nickname — not a joke.)
+
+| Model ID | Nickname | Cost/img | Speed | When to use |
+|---|---|---|---|---|
+| `fal-ai/gemini-3-pro-image-preview` | Nano Banana Pro | ~$0.15 | ~8s | Complex prompts, typography, web-search grounding |
+| `fal-ai/gemini-3.1-flash-image-preview` | Nano Banana 2 | ~$0.07 | ~2s | Newest Flash — fast + accurate text in image |
+| `fal-ai/gemini-2.5-flash-image` | Nano Banana | ~$0.04 | ~2s | Cheapest Google option |
+| `fal-ai/imagen3` | Imagen 3 | ~$0.04 | ~3s | Strong photorealism at low cost |
+
+**When to use Nano Banana instead of FLUX:**
+- Your chapter heroes need legible text baked into the image (labels, signs, editorial title cards)
+- You're doing iterative editing ("darken the background, add fog")
+- You need web-search-grounded imagery (real-world references)
+
+**FLUX.2 Pro wins for:** editorial depth, skin/fabric/material texture, atmospheric still-life — the core use case of this skill.
+
+**Typical 8-chapter release page cost:**
+- FLUX.2 Pro default: 8 × $0.06 = **~$0.48**
+- Nano Banana 2 alternative: 8 × $0.07 = **~$0.56**
+- Mixed (6 FLUX + 2 Nano Banana for text-heavy chapters): **~$0.50**
+
+---
+
+## Step 3 — Install dependencies
+
+From your project root, run **one command at a time** (do not paste multi-line blocks with `#` comments — zsh will error):
+
+```bash
+npm install
+```
+
+If install fails with `No matching version found for @studio-freight/lenis`:
+
+- The project has the **wrong Lenis package**. Replace dependencies with the bundled `templates/nextjs/package.json`.
+- Use `lenis` (^1.3.23), **not** `@studio-freight/lenis`.
+
+Required packages (from bundled template):
+
+```bash
+npm install choreo-3d framer-motion gsap lenis @fal-ai/client @fal-ai/server-proxy next react react-dom
+```
+
+If the skill copied templates from `templates/nextjs/`, use the bundled `package.json` instead of merging manually.
+
+---
+
+## Step 4 — How the key is used (safe pattern)
+
+The bundled templates use a **server-side proxy**. Your browser never sees `FAL_KEY`.
+
+```
+Browser  →  /api/fal/proxy  →  fal.ai API
+                ↑
+         FAL_KEY injected here (server only)
+```
+
+| File | Role |
+|---|---|
+| `app/api/fal/proxy/route.ts` | Proxies browser fal requests; key stays on server |
+| `app/api/generate-edition-asset/route.ts` | Server route for chapter image generation |
+| `lib/fal-client.ts` | Client config — sets `proxyUrl: '/api/fal/proxy'` only |
+| `lib/fal-generate.ts` | Builds prompts and calls fal on the server |
+| `lib/prompt-contract.ts` | Structured prompt schema per chapter |
+
+**Rule:** If you see `FAL_KEY` or `process.env.FAL_KEY` inside a `'use client'` component, that is a bug — move the call to an API route.
+
+---
+
+## Step 5 — Run locally and test one image
+
+1. Start the dev server:
+
+   ```bash
+   npm run dev
+   ```
+
+2. Test the generation route (replace values with your chapter):
+
+   ```bash
+   curl -X POST http://localhost:3000/api/generate-edition-asset \
+     -H "Content-Type: application/json" \
+     -d '{
+       "chapterId": "prologue",
+       "subject": "classical marble bust beside a glowing laptop",
+       "productTruth": "AI release notes as editorial artifact",
+       "historicalLayer": "renaissance",
+       "modernLayer": "glass UI panel, monospace code overlay",
+       "palette": ["#0a0a0a", "#f5f0e8", "#c9a227"],
+       "camera": "medium",
+       "outputRole": "hero"
+     }'
+   ```
+
+3. A successful response includes an image `url` you can open in the browser.
+
+4. If you get `{ "error": "Missing FAL_KEY" }`, your `.env.local` is missing, misnamed, or the dev server was started before you added the key — **restart `npm run dev`**.
+
+---
+
+## Step 6 — Generate assets for all chapters
+
+Use the bundled batch script — it reads `lib/editions-manifest.ts`, calls fal once per chapter, and writes both the URL and the binary to `public/generated/`.
+
+```bash
+# Dry run: print prompts only, no fal calls, no credit cost
+node scripts/generate-chapter-assets.mjs --dry-run
+
+# Generate all chapters with the default model (FLUX.2 Pro)
+node scripts/generate-chapter-assets.mjs
+
+# Only regenerate two chapters
+node scripts/generate-chapter-assets.mjs --only prologue,studio
+
+# Use a different model just for this run
+node scripts/generate-chapter-assets.mjs --model fal-ai/gemini-3-pro-image-preview
+```
+
+Output:
+
+```
+public/generated/
+  prologue.jpg
+  agentic.jpg
+  studio.jpg
+  …
+  manifest.json    ← {chapterId → {url, local, seed, model}}
+```
+
+Set `manifest.assets[id].local` paths on your chapter `background` fields in `editions-manifest.ts` for production — Next/Image will serve them from the static folder.
+
+### Queue mode (batches > 5 images, video, slow models)
+
+```bash
+curl -X POST http://localhost:3000/api/generate-edition-asset \
+  -H "Content-Type: application/json" \
+  -d '{"mode":"queue","chapterId":"prologue", ... }'
+# → { "status":"queued", "requestId":"...", "modelId":"fal-ai/flux-2-pro" }
+```
+
+The result is POSTed to `/api/fal/webhook?chapter=prologue` when fal finishes. Wire that route to your DB / KV to persist the URL — see `app/api/fal/webhook/route.ts`.
+
+---
+
+## Deploying to Vercel (production)
+
+1. Push code **without** `.env.local` (never commit secrets).
+2. In Vercel: **Project → Settings → Environment Variables**.
+3. Add `FAL_KEY` with your key value (Production + Preview).
+4. Optionally add `FAL_IMAGE_MODEL` and `NEXT_PUBLIC_SITE_NAME`.
+5. Redeploy.
+
+The same server proxy pattern works on Vercel — no code changes needed.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `Missing FAL_KEY` | Env file not loaded | Create `.env.local`, set `FAL_KEY`, restart dev server |
+| `401` / `403` from fal | Invalid or expired key | Regenerate key in fal.ai dashboard |
+| `402` / insufficient credits | No fal.ai balance | Add credits in fal.ai billing |
+| Images generate but page is blank | Unrelated to fal — scroll/sandbox issue | Apply the Mode A sandbox fallback rules in `SKILL.md` (§ MODE A) |
+| Key visible in browser DevTools | Key used in client code | Move generation to `/api/generate-edition-asset` only |
+
+---
+
+## Working without fal.ai (static images)
+
+You do not need fal.ai to use the scroll page:
+
+1. Add your own images to `public/assets/…`
+2. Set chapter `asset.src` in `editions-manifest.ts` to those paths
+3. Skip `/api/generate-edition-asset` entirely
+
+The motion system (`choreo-3d`, parallax, pinning) works the same with static assets.
+
+---
+
+## Need help?
+
+When using this skill in Claude or Cursor, try:
+
+> I'm new to fal.ai. Walk me through creating an API key, setting `.env.local`, and generating one test hero image for my release page. Use the bundled templates — do not expose FAL_KEY in client code.
+
+See also `examples/PROMPTS.md` for full build prompts once setup is complete.

package/examples/KNOWN_ISSUES.md

@@ -0,0 +1,50 @@
+# Known issues (QA log)
+
+## 2026-05-23 — Prompt #1: `npm install` fails with ETARGET on Lenis
+
+**Symptom:** `No matching version found for @studio-freight/lenis@^1.0.45`
+
+**Cause:** Claude regenerated `package.json` from memory instead of copying `templates/nextjs/package.json`. The old `@studio-freight/lenis` scope is deprecated (max 1.0.42). Version `^1.0.45` does not exist.
+
+**Fix in skill v1.1.1:**
+- Bundled `templates/nextjs/package.json` with `"lenis": "^1.3.23"`
+- SKILL.md forbids `@studio-freight/lenis` and invented versions
+- Added `lib/use-lenis.ts` + `SmoothScrollProvider.tsx`
+
+**Patch if Claude still generates wrong deps:** replace with bundled `package.json`, run `npm install` again.
+
+---
+
+## 2026-05-23 — Terminal: pasted README block causes `command not found: #`
+
+**Symptom:** `zsh: command not found: #`, `MODULE_NOT_FOUND` for scripts
+
+**Cause:** User pasted multi-line README instructions including `#` comment lines. zsh runs each line separately; comments become invalid commands.
+
+**Fix:** Run one command at a time:
+
+```bash
+npm install
+cp .env.example .env.local
+npm run dev
+```
+
+---
+
+## 2026-05-23 — Claude removed `choreo-3d` and hand-rolled parallax
+
+**Symptom:** Custom `ParallaxChapter.tsx`, inline types instead of `choreo-3d`
+
+**Cause:** Claude ignored bundled `EditionsPage.tsx` which imports `ScrollLayer`, `ScrollChoreography`, etc.
+
+**Fix:** Copy `templates/nextjs/components/EditionsPage.tsx` and ensure `"choreo-3d": "^1.0.0"` in `package.json`.
+
+---
+
+## 2026-05-23 — `next: command not found`
+
+**Symptom:** `npm run dev` → `sh: next: command not found`
+
+**Cause:** `npm install` failed earlier (Lenis ETARGET), so `node_modules` was never created.
+
+**Fix:** Fix `package.json` first, then `npm install`, then `npm run dev`.

package/examples/PROMPTS.md

@@ -0,0 +1,166 @@
+# Trigger Prompts — Cinematic Scroll
+
+Copy, paste, replace the bracketed bits, hit enter. Prompts are grouped by the two modes.
+
+- **Mode A — scroll artifact:** one self-contained HTML/TSX section. No build, no keys.
+- **Mode B — full release site:** a complete Next.js project + optional fal.ai assets.
+
+---
+---
+
+# Mode A — scroll artifacts (single section, instant preview)
+
+Each must output a complete, runnable HTML or TSX artifact.
+
+## Aesthetic worlds
+
+### A1) Bold editorial — graphic brutalism
+
+> Use cinematic-scroll to build a hero chapter for a fashion brand: brutal editorial style, black on white, raw grid lines, oversized title that cuts into view with a hard vertical clip-path wipe (no cross-fade). Pin for 150vh. Background is a stark white void. Title is 20vw tall. A single accent line (2px, black) sweeps left-to-right across the frame at 60% scroll. Progress HUD in top-right corner.
+
+### A2) Elegant quiet luxury
+
+> Use cinematic-scroll to create a pinned chapter for a luxury brand: muted palette (ecru, bark, cognac), long slow parallax (depth 0.15–0.50 only), 220vh pin. Title reveals via letter-spacing scrub from 0.45em to 0em over the first 30% of scroll. Background image drifts barely 3% over the full pin — perceptual depth without movement. No bright colours, no glow. Reduced motion: immediately show mid-state, no snap.
+
+### A3) Contemporary pop — Gen Z energy
+
+> Use cinematic-scroll to build an energetic hero chapter for a productivity app: candy pink and electric lime gradients, bold mixed-case type, fast parallax (depth 0.15–1.40 with wide multiplier gaps), short 90vh pin. Title stagger is fast (each word enters on a 2% offset). A floating UI screenshot layer at depth 1.20 drifts upward faster than the title. Progress HUD included.
+
+### A4) Minimal tech — Linear / Vercel aesthetic
+
+> Use cinematic-scroll to produce a scroll chapter in the Linear release-notes style: #09090b background, Inter stack, no images, SVG line-art illustration at mid-depth, controlled restraint. Pin 120vh. Parallax depth range narrow (0.05–0.35 only). No 3D camera rotation. Title uses letter-spacing scrub only. One thin border line sweeps in from the left at 15% scroll. Compositor-only paths proven in code comments.
+
+### A5) Cinematic dark sci-fi
+
+> Use cinematic-scroll to generate a 200vh pinned chapter for a sci-fi game: near-black background, deep teal atmospheric gradient (depth 0.15), heavy grain overlay (depth 0.30), dramatic character silhouette (depth 0.75) with 3D camera (rotateX ±4°, rotateY ±2°, translateZ −80px). Title uses vertical clip-path mask wipe. Oversized Roman numeral watermark at depth 1.20. Scroll cue badge at depth 1.40. Touch devices: 3D disabled, grain hidden, chapter stacked.
+
+### A6) Soft organic — wellness / botanical
+
+> Use cinematic-scroll to build a calm scroll chapter for a wellness brand: off-white, blush and sage, watercolour-wash background, very slow depth multipliers (max 0.55 on all layers), 180vh pin. Title horizontal wipe (`clip-path: inset(0 100% 0 0) → inset(0 0 0 0)`). No hard edges — all containers 16px radius. Reduce motion: render mid-keyframe static state immediately.
+
+### A7) Typographic maximalism — text as image
+
+> Use cinematic-scroll to build a chapter where the ONLY visual element is the oversized title. Background is a solid colour from the palette. No images, no decorative layers. Title is `clamp(6rem, 20vw, 18rem)` tall, letter-spacing scrubs from 0.5em to −0.02em across the full pin. One word per line, stacked vertically. At depth 1.20, the same word list repeats in ghost form (opacity 0.05) drifting upward. Pin 140vh. A poster in motion.
+
+### A8) Nostalgic retro — analogue grain revival
+
+> Use cinematic-scroll to create a scroll chapter for a vintage audio brand: warm amber and deep burgundy, subtle VHS scan-line overlay (thin repeating horizontal lines at 0.7px, opacity 0.08), wide-tracking serif italic title (letter-spacing +0.06em). Depth layers max at 0.60 — everything moves slowly, suggesting physical weight. Background image shifts only 4% over the full pin. Foreground product render at depth 0.75. Progress HUD styled as an analogue gauge.
+
+## Technical / QA prompts (Mode A)
+
+### A9) Deep parallax + timing gate
+
+> Use cinematic-scroll to build a hero chapter pinned for two viewport heights. Use 5 depth layers: atmosphere (0.15), distant props (0.35), mid texture (0.55), subject image (0.75), typography (1.0). Title fades in by 20% scroll, holds through 70%, drifts out by 100%. Add a live progress HUD.
+
+### A10) Sandbox / iframe-proof fallback
+
+> Use cinematic-scroll to produce a self-contained HTML artifact that works inside sandboxed iframes: container-based scroll root (not window), sticky pinning, normalized progress `p ∈ [0,1]`, guaranteed visible initial state (background opacity ≥ 0.85 at p=0), and a debug HUD. No npm, no build step.
+
+### A11) Mobile-first responsive
+
+> Use cinematic-scroll to build a fully responsive scroll chapter. Desktop: pinned 7-layer parallax, 3D perspective camera. Mobile (<768px): IntersectionObserver fade-up, no pinning, stacked layout, clamp() typography, safe-area-inset padding, 44px tap targets. Touch: backdrop-blur removed, 3D disabled.
+
+### A12) Performance proof
+
+> Use cinematic-scroll to build a scroll chapter annotated with explicit performance guarantees: only `transform` and `opacity` mutate per frame (no top/left/filter), `getBoundingClientRect()` cached once on init, `will-change: transform` on animated layers only, rAF-throttled scroll handler. Include a Lighthouse score target comment.
+
+---
+---
+
+# Mode B — full release sites (Next.js + fal.ai)
+
+## ← START HERE
+
+### B1) Default — the safe scaffolding prompt
+
+Replace `[YOUR PRODUCT IN ONE LINE]`. Everything else has sensible defaults.
+
+> Use cinematic-scroll to scaffold a complete Shopify-Editions-tier cinematic release page for **[YOUR PRODUCT IN ONE LINE]**.
+>
+> Requirements:
+> - **Demo mode** for the first run — do not require my fal.ai key. The page must look stunning on first paint using the CSS-only `ChapterDemoVisual` component.
+> - Copy ALL bundled templates from `templates/nextjs/` **verbatim** — `package.json`, `ChapterScene.tsx`, `ChapterDemoVisual.tsx`, `lib/fal-models.ts`, `lib/fal-generate.ts`, `scripts/setup.mjs`, `scripts/generate-chapter-assets.mjs`. Do not regenerate them from memory.
+> - 8 chapters in `lib/editions-manifest.ts` — customise titles, eyebrows, summaries, technicalDetail, features, accent, atmosphere, and visualPrompt for my product. Leave `background` commented out so demo mode renders.
+> - Default model `fal-ai/flux-2-pro` when I'm ready to generate real images.
+>
+> Finish your response with **exactly three things**, in this order:
+> 1. The two commands to run now: `npm install && npm run dev`
+> 2. The optional fal.ai setup command: `npm run setup`
+> 3. The optional batch command for real images: `npm run generate`
+>
+> Nothing else after those commands.
+
+### B2) Beginner — full fal.ai walkthrough
+
+> I'm new to fal.ai. Using cinematic-scroll, walk me through the full setup: run `npm run setup`, follow each prompt in the wizard, and generate one test hero image. Use the bundled scripts — do not put my key in any client component. Follow `examples/GETTING_STARTED.md`.
+
+## Aesthetic variants — swap B1 for one of these for a different world
+
+### B3) Bold editorial — Brutalist-meets-Balenciaga
+
+> Use cinematic-scroll to build a release page for a fashion-tech brand. Visual world: bold editorial brutalism — oversized black-on-white typography, raw grid lines, stark silhouette photography, zero decoration. 8 chapters, each a magazine double-spread: massive headline lands first, then the image cuts in hard with no cross-fade. Atmospheres alternate white void / ink black. Word-stagger reveals on every title. No gradients, no glass panels — solid-colour blocks and ruled lines.
+
+### B4) Elegant editorial — quiet luxury / Bottega Veneta
+
+> Use cinematic-scroll to create a release page for a luxury leather goods launch. Visual world: quiet luxury — muted earth palettes (stone, ecru, bark, rust), extreme negative space, micro-typography, long unhurried pins (200vh per chapter). 6 chapters. Each foreground figure is a still-life product shot via ScrollDepthImage. One warm cognac highlight throughout. Roman index barely visible (opacity 0.25), surfacing on hover.
+
+### B5) Contemporary pop — vivid Gen-Z launch
+
+> Use cinematic-scroll to generate an 8-chapter launch page for a productivity app targeting Gen Z. Visual world: contemporary pop — neon gradients (electric violet, candy pink, lime green), playful type mixing, chunky pill buttons, UI screenshots as floating foreground objects. Short pins (100vh), fast parallax, quick word-stagger. Background morphs shift between vivid complementary gradient pairs per chapter.
+
+### B6) Minimal tech — Linear / Vercel release
+
+> Use cinematic-scroll to build a chaptered product release page in Linear's style: controlled restraint, dark background (#09090b), Inter/monospace stack, thin borders, no photos — only generative SVG chapter illustrations and sharp UI screenshots. 7 chapters, each 80% text / 20% visual. Subtle parallax (0.05–0.30 only). No 3D camera. Word reveals use letter-spacing scrub. Communicate speed and precision, not spectacle.
+
+### B7) Cinematic dark sci-fi — Blade Runner / A24
+
+> Use cinematic-scroll to generate a feature-film-quality release page for a sci-fi game expansion. Visual world: neo-noir — near-black backgrounds, deep teals and crimson, heavy grain, fog layers, dramatic edge lighting. 9 chapters, all 7 depth layers fully populated. 3D camera at max spec. Type reveals via vertical mask wipe. Generate fal.ai foreground figures with `historicalLayer: 'baroque'` and `modernLayer` set to armour, chrome, UI glow.
+
+### B8) Soft organic — wellness / bioscience
+
+> Use cinematic-scroll to create a calming release page for a longevity science company. Visual world: organic editorial — warm off-whites, blush, sage, parchment, watercolour washes. 6 chapters. Transitions feel like turning pages — long cross-fades (scrub 1.4), slow depth (max 0.6 on background). Titles use clip-path horizontal wipe. Generous border-radius everywhere. Chapter index uses dots. fal.ai with `historicalLayer: 'atelier'`, painterly botanical subjects.
+
+### B9) Typographic maximalism — Pentagram-tier
+
+> Use cinematic-scroll to build a 7-chapter release page where typography IS the art direction. Title is 30vw tall, letter-spaced −0.1em, scrubs 0.4em → 0em over the full pin. No hero images — each chapter background is a single solid palette colour. Foreground uses SVG illustration or generative texture only. Stark bordered cards, no blur. The motion is about the text, not the image.
+
+### B10) Nostalgic retro — 80s / 90s archive revival
+
+> Use cinematic-scroll to generate a release page for a vintage audio brand. Visual world: retro archive — warm amber and burgundy, VHS scan lines, analogue gauge UI, wide serif italic type, physical texture. 6 chapters, each foreground a product render with tactile depth. fal.ai with `historicalLayer: 'industrial'`. Atmospheres desaturated warm-to-cool gradient pairs. Parallax max 0.6 to suggest weight, not speed.
+
+## Technical / QA prompts (Mode B)
+
+### B11) Template integrity test
+
+> Use cinematic-scroll to scaffold a complete Next.js App Router release site. Copy ALL bundled files from `templates/nextjs/` verbatim — especially `package.json` (lenis, not @studio-freight/lenis), `ChapterScene.tsx` (7 layers, perspective camera, word-stagger), and `use-device.ts`. Customise only `editions-manifest.ts`. Keep `FAL_KEY` server-side only. Show where env vars are read and how `prompt-contract.ts` is structured.
+
+### B12) Mobile-first stress test
+
+> Use cinematic-scroll to build the release page mobile-first (375px). Show how `ChapterScene` switches to the mobile fallback below 768px: IntersectionObserver fade-up, no pinning, stacked layout, safe-area padding, 44px tap targets. Then confirm the desktop 7-layer scene is intact at 1280px.
+
+### B13) Performance + Lighthouse gate
+
+> Use cinematic-scroll to produce a full 8-chapter release page with a QA checklist proving: compositor-only scroll paths, reduced-motion static fallback, backdrop-blur removed on touch, iOS video safety (no preserve-3d ancestor around video), Lighthouse Performance ≥ 90.
+
+### B14) Batch asset generation (one command)
+
+> Use cinematic-scroll to scaffold the project, then walk me through `node scripts/generate-chapter-assets.mjs --dry-run` to preview prompts, followed by a real run that generates all 8 chapter images into `public/generated/` and writes `manifest.json`. Show how to point chapter `background` fields at the local paths.
+
+### B15) Model swap (FLUX → Nano Banana, no code edits)
+
+> Use cinematic-scroll to scaffold the page with `FAL_IMAGE_MODEL=fal-ai/flux-2-pro`, generate one hero, then change `.env.local` to `FAL_IMAGE_MODEL=fal-ai/gemini-3-pro-image-preview` and regenerate the same chapter — no code change. The `lib/fal-models.ts` adapter must handle `image_size → aspect_ratio` automatically. Print the request body in each case.
+
+### B16) Queue + webhook (production async)
+
+> Use cinematic-scroll to scaffold the page and demonstrate queue mode: POST to `/api/generate-edition-asset` with `{"mode":"queue", ...}`, get a `requestId`, and show how `app/api/fal/webhook/route.ts` receives the result. Add a minimal in-memory map to persist `{requestId → url}`.
+
+---
+
+## Anti-patterns — do NOT use this skill for
+
+- "Build a basic hero + features + pricing landing page."
+- "Generate a WordPress theme."
+- "Build me a SaaS dashboard with a sidebar and tables."
+- "Add a fade-in when this button is clicked."
+- "Give me motion ideas only, no code." (The skill must output runnable artifacts.)
+- "Regenerate all templates from scratch without reading bundled files."

package/examples/luxe/README.md

@@ -0,0 +1,88 @@
+# Luxe — quiet-luxury maison (Maison Solenne)
+
+A worked example for **cinematic-scroll** in a deliberately restrained world:
+**quiet luxury** — warm ivory and sand grounds, a single muted cognac accent,
+refined thin-serif display type, vast negative space, and *barely-there*
+parallax. The motion is Villeneuve-by-way-of-Kubrick: long 220vh pins, a
+background that drifts only ~3% across the whole pin, and titles that reveal
+through a **letter-spacing scrub** (0.45em → 0em) rather than anything flashy.
+Fictional maison (**Maison Solenne**) — no real people or brands.
+
+Single self-contained `index.html` — no build step, no npm, no external JS.
+The only external request is Google Fonts. GitHub-Pages-native.
+
+## Run it
+
+```bash
+# from the repo root
+python3 -m http.server 8099
+# then open http://localhost:8099/examples/luxe/
+```
+
+…or just double-click `index.html`. It works **immediately, at $0**, with **zero
+image files**: each chapter probes for a real still and, on 404, renders a
+refined CSS-only placeholder (soft warm gradients + subtle grain) so the page
+looks intentional and complete. Drop real stills in later and the page picks
+them up automatically.
+
+## What it demonstrates
+
+- **Quiet-luxury motion** — depth multipliers ≤ 0.50; the framed still drifts
+  only ~3% of the viewport over the entire 220vh pin (perceptual depth without
+  visible movement). No 3D tilt, no glow, no `filter` animation.
+- **Letter-spacing title reveal** — the refined/luxury treatment from
+  `taste-guardrails.md`: the first title fragment scrubs `0.45em → 0em` over
+  the first ~30% of each pin.
+- **GSAP ScrollTrigger showcase beat** — one dedicated, whisper-quiet section
+  ("The Object, Held", inserted after Chapter III) powered by GSAP
+  ScrollTrigger (deferred from CDN, feature-detected). It demonstrates two
+  restrained techniques from `taste-guardrails.md` §2:
+  - **Push-in** — the framed object scales `1 → 1.08` over the pin (a slow zoom
+    toward the subject), with no other foreground motion.
+  - **Match-cut** — two captions share the exact same position; the words swap
+    by `opacity` crossfade while the composition holds perfectly still.
+
+  No 3D tilt, no snap, no velocity effects (museum restraint). If GSAP fails to
+  load — or under reduced-motion / mobile — the beat degrades to a complete
+  static state (object at rest, both captions shown), and the hand-rolled rAF
+  engine is unaffected.
+- **Compositor-only scroll** — only `transform` and `opacity` mutate per frame,
+  in one rAF batch, behind a passive scroll listener; off-screen sections are
+  skipped.
+- **Background morph + quiet rail** — a fixed warm atmosphere crossfades
+  between four ground tones via an IntersectionObserver scroll-spy; the
+  left-hand progress rail marks the active chapter.
+- **Graceful degradation** — `prefers-reduced-motion` and mobile (≤680px) drop
+  the pin entirely for a clean, stacked, full-opacity static mid-state
+  (letter-spacing settled to 0), with a gentle IntersectionObserver fade-up.
+
+## Image slots
+
+The page is built to look complete with **no files present**. To upgrade a
+chapter, drop a JPEG at the probed path below and reload — no code change. All
+paths are relative, so it works at
+`https://<user>.github.io/cinematic-scroll-skill/examples/luxe/`.
+
+| Slot | Probed file (relative) | Aspect ratio | Target px | Generation prompt |
+|------|------------------------|:------------:|:---------:|-------------------|
+| I — Overture | `assets/overture.jpg` | 4 : 5 | 1024 × 1280 | Quiet-luxury website-interface still life: a single muted object — a folded length of pale ecru linen on warm ivory — centred in vast negative space, photographed in soft north-window light. Warm ivory and sand palette, the faintest restrained cognac warmth, no bright colour, no glow, generous soft shadow, refined and calm. Editorial Swiss-museum restraint. No text, no logos, no people. |
+| II — Provenance | `assets/provenance.jpg` | 4 : 5 | 1024 × 1280 | Quiet-luxury still: a worn leather-bound ledger and a single brass key resting on aged sand-coloured paper, shot from above in soft diffuse light. Muted ecru, bark, and restrained cognac tones, vast negative space around the objects, gentle grain, no hard edges. Calm archival mood, expensive restraint. No text, no logos, no people. |
+| III — The Object | `assets/object.jpg` | 4 : 5 | 1024 × 1280 | Quiet-luxury product moment: one hand-burnished cognac-leather object — a minimal unbranded holdall — standing alone on a warm sand surface, framed in soft directional light against an ivory void. Restrained cognac accent, deep soft shadow, no monogram, no hardware, no shine or glow. Refined thin-serif-era catalogue mood, immense negative space. No text, no logos, no people. |
+| IV — Enquire | `assets/audience.jpg` | 4 : 5 | 1024 × 1280 | Quiet-luxury still: a single sheet of heavy ivory correspondence paper and a fountain pen on a bare warm-ecru desk, one shaft of soft window light, long quiet shadow. Muted ivory, sand, and cognac palette, vast empty space, fine grain, soft radii. Calm, patient, intentional. No writing, no text, no logos, no people. |
+
+> Recommended export: **WebP or optimised JPEG, ≤ 200KB each, ≤ 1280px on the
+> long edge** (per `references/performance-budget.md`). The frame uses
+> `object-fit: cover` (via `background-size: cover`), so off-centre crops are
+> forgiving.
+
+## Editing
+
+Open `index.html` and edit the `CHAPTERS` array near the bottom — titles
+(`[text, italic?]` fragments; the first fragment carries the scrub), copy,
+ground-tone `morph`, captions, and the rail labels. Drop matching stills into
+`./assets/<id>.jpg`. That is the whole content model.
+
+## Deploy / preview
+
+Static files only — push to a branch and enable GitHub Pages, or
+`python3 -m http.server 8099` locally and open `/examples/luxe/`.