cinematic-scroll-skill 2.1.0

package/templates/nextjs/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "editions-release-page",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "setup": "node scripts/setup.mjs",
+    "generate": "node scripts/generate-chapter-assets.mjs",
+    "generate:dry": "node scripts/generate-chapter-assets.mjs --dry-run",
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@fal-ai/client": "^1.10.0",
+    "@fal-ai/server-proxy": "^1.2.0",
+    "@gsap/react": "^2.1.2",
+    "choreo-3d": "1.0.0",
+    "framer-motion": "^12.0.0",
+    "gsap": "^3.13.0",
+    "lenis": "^1.3.23",
+    "next": "^15.5.18",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "overrides": {
+    "postcss": "^8.5.15"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "autoprefixer": "^10.4.0",
+    "eslint": "^9.0.0",
+    "eslint-config-next": "^15.1.0",
+    "postcss": "^8.5.15",
+    "tailwindcss": "^3.4.0",
+    "typescript": "^5.6.0"
+  }
+}

package/templates/nextjs/package.patch.json

@@ -0,0 +1,28 @@
+{
+  "dependencies_to_add": {
+    "choreo-3d": "^1.0.0",
+    "@fal-ai/client": "^1.10.0",
+    "@fal-ai/server-proxy": "^1.2.0",
+    "framer-motion": "^12.0.0",
+    "gsap": "^3.12.0",
+    "lenis": "^1.3.23"
+  },
+  "dependencies_forbidden": {
+    "@studio-freight/lenis": "Package renamed to lenis. Latest old scope version is 1.0.42 only — do NOT use ^1.0.45 or any invented version."
+  },
+  "env_required": [
+    "FAL_KEY"
+  ],
+  "env_optional": [
+    "FAL_IMAGE_MODEL",
+    "FAL_VIDEO_MODEL",
+    "NEXT_PUBLIC_SITE_NAME"
+  ],
+  "fal_model_defaults": {
+    "image": "fal-ai/flux-2-pro",
+    "image_draft": "fal-ai/flux-2/turbo",
+    "image_max": "fal-ai/flux-2-max",
+    "image_budget": "fal-ai/flux-pro/v1.1",
+    "image_dev_only": "fal-ai/flux/dev (NON-COMMERCIAL - never use in production)"
+  }
+}

package/templates/nextjs/postcss.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

package/templates/nextjs/scripts/generate-chapter-assets.mjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+/**
+ * Batch chapter-asset generator.
+ *
+ * Reads `lib/editions-manifest.ts`, calls fal.ai for each chapter's hero image,
+ * and writes the output URLs into `public/generated/manifest.json` plus
+ * downloads the binary to `public/generated/<id>.webp` (or whatever format
+ * the chosen model returns).
+ *
+ * Usage:
+ *   node scripts/generate-chapter-assets.mjs              # generate all chapters
+ *   node scripts/generate-chapter-assets.mjs --dry-run    # print prompts only
+ *   node scripts/generate-chapter-assets.mjs --only prologue,studio
+ *   node scripts/generate-chapter-assets.mjs --model fal-ai/gemini-3-pro-image-preview
+ *
+ * Requires:
+ *   FAL_KEY=key_id:key_secret   (in .env.local)
+ *   FAL_IMAGE_MODEL=fal-ai/flux-2-pro   (optional override)
+ *
+ * NOTE: this is a Node script (not Next runtime) so we use the raw HTTP
+ * endpoint at https://fal.run/<model-id> with the key directly. We do NOT
+ * use the proxy — the proxy is only for browser → server calls.
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { argv, env, exit } from 'node:process';
+
+// ─── arg parsing ──────────────────────────────────────────────────────────
+
+const args = argv.slice(2);
+const flags = {
+  dryRun: args.includes('--dry-run'),
+  only: (args.find((a) => a.startsWith('--only='))?.split('=')[1] ?? '')
+    .split(',')
+    .filter(Boolean),
+  model: args.find((a) => a.startsWith('--model='))?.split('=')[1],
+};
+
+// `--only foo,bar` (space form)
+const onlyIdx = args.indexOf('--only');
+if (onlyIdx !== -1 && args[onlyIdx + 1] && !args[onlyIdx + 1].startsWith('--')) {
+  flags.only = args[onlyIdx + 1].split(',').filter(Boolean);
+}
+const modelIdx = args.indexOf('--model');
+if (modelIdx !== -1 && args[modelIdx + 1] && !args[modelIdx + 1].startsWith('--')) {
+  flags.model = args[modelIdx + 1];
+}
+
+// ─── env ──────────────────────────────────────────────────────────────────
+
+const FAL_KEY = env.FAL_KEY;
+const MODEL_ID = flags.model ?? env.FAL_IMAGE_MODEL ?? 'fal-ai/flux-2-pro';
+
+if (!FAL_KEY && !flags.dryRun) {
+  console.error('\n[generate-chapter-assets] FAL_KEY missing. Set it in .env.local or your shell.\n');
+  exit(1);
+}
+
+// ─── load .env.local manually (so the script works without `dotenv`) ──────
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(__dirname, '..');
+
+try {
+  const envText = await (await import('node:fs/promises')).readFile(
+    resolve(projectRoot, '.env.local'),
+    'utf8',
+  );
+  for (const line of envText.split('\n')) {
+    const m = line.match(/^\s*([A-Z_][A-Z0-9_]*)\s*=\s*"?([^"\n]*)"?\s*$/);
+    if (m && !env[m[1]]) env[m[1]] = m[2];
+  }
+} catch {
+  // .env.local optional
+}
+
+// ─── per-model input builder (mirrors lib/fal-models.ts) ──────────────────
+
+const FLUX_IMAGE_SIZE = { landscape: 'landscape_16_9', portrait: 'portrait_4_3', square: 'square_hd' };
+const GEMINI_ASPECT = { landscape: '16:9', portrait: '3:4', square: '1:1' };
+
+function buildInput(modelId, prompt, orientation) {
+  if (modelId.startsWith('fal-ai/flux')) {
+    return {
+      prompt,
+      image_size: FLUX_IMAGE_SIZE[orientation],
+      output_format: 'jpeg',
+      enable_safety_checker: true,
+      safety_tolerance: '2',
+    };
+  }
+  if (modelId.startsWith('fal-ai/gemini')) {
+    return {
+      prompt,
+      aspect_ratio: GEMINI_ASPECT[orientation],
+      output_format: 'png',
+      resolution: '1K',
+      num_images: 1,
+      safety_tolerance: '4',
+    };
+  }
+  // imagen + fallback
+  return {
+    prompt,
+    aspect_ratio: GEMINI_ASPECT[orientation],
+    num_images: 1,
+  };
+}
+
+// ─── prompt builder (mirrors lib/prompt-contract.ts) ──────────────────────
+
+const HISTORICAL = {
+  renaissance: 'Renaissance composition: layered chiaroscuro, dramatic fabric, sfumato edges, museum-grade lighting.',
+  baroque: 'Baroque composition: theatrical movement, deep shadow contrast, gilded textures, dynamic diagonals.',
+  atelier: 'Painterly atelier composition: visible brushwork, warm sepia base, soft natural studio light.',
+  architectural: 'Architectural drafting composition: orthographic clarity, parchment tones, fine ink lines.',
+  industrial: 'Industrial-era composition: forged metal, oxidised brass, steam-warm light, mechanical detail.',
+};
+
+const CAMERA = {
+  wide: 'Wide cinematic shot, deep field, atmospheric perspective.',
+  medium: 'Medium shot, balanced subject framing.',
+  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.',
+};
+
+const AVOID =
+  'brand logos, unreadable text overlays, fake UI labels, watermarks, low resolution, distorted hands, generic AI gloss';
+
+function buildPrompt(vp) {
+  return [
+    'Original editorial product-scene image for a high-craft interactive release website.',
+    `Scene: ${vp.subject}.`,
+    `Product truth: ${vp.productTruth}.`,
+    HISTORICAL[vp.historicalLayer],
+    `Modern layer: ${vp.modernLayer} — integrated naturally, not stickered on.`,
+    `Palette: ${vp.palette.join(', ')}.`,
+    CAMERA[vp.camera],
+    'Background plate. Subject de-emphasised, atmosphere primary, suitable for radial vignette overlay.',
+    'No brand logos, no readable text, no imitation of named living artists.',
+    `Avoid: ${AVOID}.`,
+  ].join(' ');
+}
+
+// ─── load chapters from the TS manifest at runtime via tiny regex ─────────
+// We avoid `ts-node` so the script stays dependency-free. Chapters are
+// exported as a `const editionChapters` array literal — readable by JSON.parse
+// after light cleanup.
+
+async function loadChapters() {
+  const { readFile } = await import('node:fs/promises');
+  const src = await readFile(resolve(projectRoot, 'lib/editions-manifest.ts'), 'utf8');
+  const m = src.match(/export const editionChapters[^=]*=\s*(\[[\s\S]*?\n\]);/);
+  if (!m) throw new Error('Could not locate editionChapters in lib/editions-manifest.ts');
+  // Strip TS-only bits: trailing commas, single quotes, keys without quotes.
+  const jsonish = m[1]
+    .replace(/'/g, '"')
+    .replace(/,(\s*[}\]])/g, '$1')
+    .replace(/([{,]\s*)([a-zA-Z_][a-zA-Z0-9_]*)\s*:/g, '$1"$2":');
+  return JSON.parse(jsonish);
+}
+
+// ─── main ─────────────────────────────────────────────────────────────────
+
+async function main() {
+  const chapters = await loadChapters();
+  const targets = flags.only.length ? chapters.filter((c) => flags.only.includes(c.id)) : chapters;
+
+  console.log(`\n[generate-chapter-assets] model=${MODEL_ID}  chapters=${targets.length}  dryRun=${flags.dryRun}\n`);
+
+  const outDir = resolve(projectRoot, 'public/generated');
+  await mkdir(outDir, { recursive: true });
+
+  const manifest = { model: MODEL_ID, generatedAt: new Date().toISOString(), assets: {} };
+
+  for (const ch of targets) {
+    const prompt = buildPrompt(ch.visualPrompt);
+    const input = buildInput(MODEL_ID, prompt, 'landscape');
+
+    console.log(`─── ${ch.id} (${ch.roman}) ──────────────────────────────`);
+    if (flags.dryRun) {
+      console.log(prompt);
+      console.log('input:', JSON.stringify(input, null, 2));
+      continue;
+    }
+
+    try {
+      const startedAt = Date.now();
+      const resp = await fetch(`https://fal.run/${MODEL_ID}`, {
+        method: 'POST',
+        headers: {
+          Authorization: `Key ${FAL_KEY}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(input),
+      });
+
+      if (!resp.ok) {
+        const text = await resp.text();
+        throw new Error(`HTTP ${resp.status}: ${text.slice(0, 300)}`);
+      }
+
+      const data = await resp.json();
+      const url = data?.images?.[0]?.url;
+      if (!url) throw new Error(`No image URL in response. Raw: ${JSON.stringify(data).slice(0, 200)}`);
+
+      // Download the binary so the site works offline / without fal CDN dependency.
+      const ext = url.split('.').pop()?.split('?')[0]?.toLowerCase() ?? 'jpg';
+      const safeExt = ['jpg', 'jpeg', 'png', 'webp'].includes(ext) ? ext : 'jpg';
+      const localPath = `public/generated/${ch.id}.${safeExt}`;
+      const bin = await fetch(url).then((r) => r.arrayBuffer());
+      await writeFile(resolve(projectRoot, localPath), Buffer.from(bin));
+
+      const seconds = ((Date.now() - startedAt) / 1000).toFixed(1);
+      console.log(`  ok ${seconds}s  →  /${localPath}`);
+      manifest.assets[ch.id] = {
+        url,
+        local: `/generated/${ch.id}.${safeExt}`,
+        seed: data?.seed,
+        model: MODEL_ID,
+      };
+    } catch (err) {
+      console.error(`  ERROR  ${err.message}`);
+      manifest.assets[ch.id] = { error: String(err.message) };
+    }
+  }
+
+  if (!flags.dryRun) {
+    await writeFile(
+      resolve(outDir, 'manifest.json'),
+      JSON.stringify(manifest, null, 2),
+    );
+    console.log(`\n[generate-chapter-assets] manifest → public/generated/manifest.json\n`);
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  exit(1);
+});

package/templates/nextjs/scripts/setup.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+/**
+ * Interactive setup wizard — run with `npm run setup`.
+ *
+ * Walks a brand-new buyer through the entire fal.ai bootstrap in ~2 minutes:
+ *   1. Detects whether .env.local already exists
+ *   2. Asks if they want to wire up fal.ai now or stay in demo mode
+ *   3. If yes: opens the fal.ai key dashboard in their default browser
+ *   4. Captures the pasted key, validates the shape, writes .env.local
+ *   5. Offers to generate one test image to prove the round-trip works
+ *
+ * Zero dependencies — pure Node + readline.
+ */
+
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout, env, platform, exit } from 'node:process';
+import { readFile, writeFile, access } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(__dirname, '..');
+const envPath = resolve(projectRoot, '.env.local');
+const envExamplePath = resolve(projectRoot, '.env.example');
+
+const rl = createInterface({ input: stdin, output: stdout });
+const ask = (q) => rl.question(q);
+const log = (s) => stdout.write(s + '\n');
+const hr = () => log('\n────────────────────────────────────────────────────────\n');
+
+const FAL_DASHBOARD = 'https://fal.ai/dashboard/keys';
+
+async function fileExists(p) {
+  try { await access(p); return true; } catch { return false; }
+}
+
+function openInBrowser(url) {
+  const cmd = platform === 'darwin' ? 'open' : platform === 'win32' ? 'start' : 'xdg-open';
+  try {
+    spawn(cmd, [url], { stdio: 'ignore', detached: true }).unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function main() {
+  log('\nEditions Scroll Generator — setup wizard\n');
+  log('This wizard wires up fal.ai for AI-generated chapter images.');
+  log('You can skip it and the page still renders beautifully with CSS-only visuals.\n');
+
+  // ── Step 1: existing .env.local? ────────────────────────────────────────
+  if (await fileExists(envPath)) {
+    const overwrite = (await ask('  .env.local already exists. Overwrite? [y/N] ')).trim().toLowerCase();
+    if (overwrite !== 'y' && overwrite !== 'yes') {
+      log('\n  Keeping existing .env.local. Run `npm run dev` to start.\n');
+      rl.close();
+      return;
+    }
+  }
+
+  hr();
+  log('  Choose your mode:\n');
+  log('    [1] Demo mode      — no fal.ai needed, CSS-only chapter visuals (default)');
+  log('    [2] Real images    — set up fal.ai now and generate AI chapter heroes');
+  log('');
+  const mode = (await ask('  Pick 1 or 2 [1]: ')).trim() || '1';
+
+  if (mode === '1') {
+    // Write a minimal demo-mode .env.local so Next.js boots clean
+    const example = (await fileExists(envExamplePath)) ? await readFile(envExamplePath, 'utf8') : '';
+    const minimal = [
+      '# Demo mode — no fal.ai key required.',
+      '# To enable real AI image generation, re-run `npm run setup` and choose option 2.',
+      'NEXT_PUBLIC_SITE_NAME="Editions Demo"',
+      '',
+    ].join('\n');
+    await writeFile(envPath, example.includes('NEXT_PUBLIC_SITE_NAME') ? minimal : minimal);
+    hr();
+    log('  Demo mode is ready. Now run:\n');
+    log('    npm run dev\n');
+    log('  Open http://localhost:3000 to see your 8-chapter page.\n');
+    rl.close();
+    return;
+  }
+
+  // ── Step 2: fal.ai key flow ─────────────────────────────────────────────
+  hr();
+  log('  Step 1 of 3: Get a fal.ai API key\n');
+  log(`  Opening ${FAL_DASHBOARD} in your browser...`);
+  log('  (If it doesn\'t open, copy the URL above manually.)\n');
+  openInBrowser(FAL_DASHBOARD);
+  log('  On the fal.ai dashboard:');
+  log('    1. Sign in (GitHub or email)');
+  log('    2. Click "Create API Key"');
+  log('    3. Copy the key — format is  key_id:key_secret  (two parts, separated by ":")\n');
+
+  let key = '';
+  while (!key) {
+    key = (await ask('  Paste your fal.ai key here: ')).trim();
+    if (!key.includes(':') || key.length < 20) {
+      log('  ! That doesn\'t look right. The key has the format  key_id:key_secret\n');
+      key = '';
+    }
+  }
+
+  hr();
+  log('  Step 2 of 3: Pick a default model\n');
+  log('    [1] fal-ai/flux-2-pro              (recommended — best balance, ~$0.06/img, ~4s)');
+  log('    [2] fal-ai/flux-2/turbo            (fast drafts, ~$0.02/img, ~2s)');
+  log('    [3] fal-ai/gemini-3-pro-image-preview  (Nano Banana Pro, best at text-in-image, ~$0.15/img)');
+  log('    [4] Other (I\'ll pick from MODELS.md later — defaults to flux-2-pro)\n');
+  const m = (await ask('  Pick 1–4 [1]: ')).trim() || '1';
+  const modelMap = {
+    1: 'fal-ai/flux-2-pro',
+    2: 'fal-ai/flux-2/turbo',
+    3: 'fal-ai/gemini-3-pro-image-preview',
+    4: 'fal-ai/flux-2-pro',
+  };
+  const model = modelMap[m] ?? 'fal-ai/flux-2-pro';
+
+  // ── Step 3: write .env.local ────────────────────────────────────────────
+  const contents = [
+    '# Generated by `npm run setup`',
+    `FAL_KEY="${key}"`,
+    `FAL_IMAGE_MODEL="${model}"`,
+    'NEXT_PUBLIC_SITE_NAME="Editions Demo"',
+    '',
+  ].join('\n');
+  await writeFile(envPath, contents);
+
+  hr();
+  log('  .env.local written. FAL_KEY stays on the server (never sent to the browser).\n');
+
+  // ── Step 4: test image ──────────────────────────────────────────────────
+  log('  Step 3 of 3: Generate one test image to verify everything works');
+  log('  This costs roughly $0.06 in fal.ai credits.\n');
+  const test = (await ask('  Generate one test image now? [Y/n] ')).trim().toLowerCase();
+
+  if (test === '' || test === 'y' || test === 'yes') {
+    log('\n  Running: node scripts/generate-chapter-assets.mjs --only prologue\n');
+    env.FAL_KEY = key;
+    env.FAL_IMAGE_MODEL = model;
+    await new Promise((res) => {
+      const child = spawn('node', ['scripts/generate-chapter-assets.mjs', '--only', 'prologue'], {
+        cwd: projectRoot,
+        stdio: 'inherit',
+        env,
+      });
+      child.on('close', res);
+    });
+  }
+
+  hr();
+  log('  Setup complete. Run:\n');
+  log('    npm run dev\n');
+  log('  Open http://localhost:3000\n');
+  log('  To generate the remaining 7 chapter images:');
+  log('    node scripts/generate-chapter-assets.mjs\n');
+  log('  To swap models later, just edit FAL_IMAGE_MODEL in .env.local — no code changes needed.\n');
+
+  rl.close();
+}
+
+main().catch((err) => {
+  console.error('\n  setup failed:', err.message);
+  rl.close();
+  exit(1);
+});

package/templates/nextjs/tailwind.config.ts

@@ -0,0 +1,37 @@
+import type { Config } from 'tailwindcss';
+
+const config: Config = {
+  content: [
+    './app/**/*.{ts,tsx}',
+    './components/**/*.{ts,tsx}',
+    './lib/**/*.{ts,tsx}',
+  ],
+  theme: {
+    extend: {
+      fontFamily: {
+        mono: ['ui-monospace', 'SFMono-Regular', 'Menlo', 'monospace'],
+      },
+      // Fluid type scale — pairs with --fluid-* CSS vars in globals.css
+      fontSize: {
+        'fluid-eyebrow': ['var(--fluid-eyebrow)', { lineHeight: '1.4', letterSpacing: '0.18em' }],
+        'fluid-body': ['var(--fluid-body)', { lineHeight: '1.55' }],
+        'fluid-headline': ['var(--fluid-headline)', { lineHeight: '1.02', letterSpacing: '-0.025em' }],
+        'fluid-display': ['var(--fluid-display)', { lineHeight: '0.92', letterSpacing: '-0.045em' }],
+      },
+      screens: {
+        // Standard sm/md/lg/xl/2xl plus tall-phone + tablet-portrait helpers
+        xs: '420px',
+        'ipad-portrait': { raw: '(min-width: 768px) and (max-width: 1024px) and (orientation: portrait)' },
+      },
+      colors: {
+        ink: '#0b0907',
+      },
+      boxShadow: {
+        'glow-sm': '0 0 24px rgba(255,255,255,0.08)',
+      },
+    },
+  },
+  plugins: [],
+};
+
+export default config;

package/templates/nextjs/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}