@devinilabs/reelstack 1.2.0

package/docs/superpowers/specs/2026-05-09-reelstack-init-readiness-gate-design.md

@@ -0,0 +1,233 @@
+# ReelStack `init` — readiness gate design
+
+**Date:** 2026-05-09
+**Author:** Abhishek Raj (devinilabs)
+**Status:** Draft, ready for implementation planning
+
+## Problem
+
+The current `reelstack init` ([cli/init.js](../../../cli/init.js)) checks system dependencies (Node 20+, ffmpeg, whisper-cpp) but only `warn()`s on missing ones. It then prints "ReelStack is ready" regardless of whether those deps exist or whether the buyer is in a Remotion project.
+
+The result is a paid-product trap: a buyer can complete `init`, see the success banner, run `/reelstack-render` minutes later, and watch it fail because ffmpeg isn't installed or there's no Remotion project to render against. The first impression of a $X9 product becomes "broken".
+
+There are **four** distinct gaps that cause `/reelstack-*` commands to fail at runtime — not just "Remotion is missing" as initially framed:
+
+| # | Gap | Breaks |
+|---|---|---|
+| 1 | No Remotion project (Root.tsx, configs, deps) in cwd | `npm run dev`, every scaffolded reel |
+| 2 | `@devinilabs/reelstack` not in project deps | Scaffolded reels' `import` lines |
+| 3 | System `ffmpeg` not in PATH | `/reelstack-beats`, `/reelstack-render` (BGM mix + GIF), `/reelstack-capture` |
+| 4 | `whisper-cli` / `whisper-cpp` not in PATH | `/reelstack-beats` (audio-locked BEAT extraction) |
+
+Note on #3: even though Remotion v4 ships its own ffmpeg internally for *its* render pipeline, ReelStack's CLI ([cli/render.js:188-225](../../../cli/render.js), [cli/beats.js:72](../../../cli/beats.js)) shells out to **system** ffmpeg via `spawnSync("ffmpeg", ...)`. Remotion's bundled binary doesn't help us. Note also that `npx remotion install` (which historically pre-downloaded ffmpeg) **was removed in v4.0.0** and must not be called.
+
+## Goal
+
+Make `reelstack init`'s success banner provable: after `init` exits 0, every `/reelstack-*` command works.
+
+## Non-goals
+
+- Auto-installing Node. Version managers vary too widely (nvm / fnm / Volta / asdf / system). Hard-fail with a guide link.
+- Auto-installing system binaries on Linux or Windows. Too many package managers, sudo prompts, and edge cases. Print + exit.
+- Calling `npx remotion install`. Removed in Remotion v4.0.0.
+- Doing anything silently. Every install gets a `[Y/n]` prompt.
+
+## Design
+
+A 4-tier readiness gate replaces the current warn-and-continue flow. Each tier is a hard precondition for the next; the success banner only prints if all four pass.
+
+### Top-level flow
+
+```
+1. license.verifyOrPrompt()                  (unchanged)
+2. Tier 1   — Node version hard gate
+3. Tier 2   — System binaries (ffmpeg, whisper-cli)
+4. Install ~/.reelstack runtime              (unchanged: families, templates, utils, docs, cli, reference, package.json)
+5. Install ~/.claude/skills/reelstack        (unchanged)
+6. Install ~/.claude/commands/*              (unchanged)
+7. Tier 3   — Remotion project bootstrap (or detect existing)
+8. Tier 4   — Smoke test
+9. Success banner
+```
+
+Steps 4-6 (the runtime + skill + commands installs from current [cli/init.js:88-117](../../../cli/init.js)) are **preserved unchanged**. The new tiers wrap around them, not replace them.
+
+### Tier 1 — Hard system gate
+
+| Check | On fail |
+|---|---|
+| Node ≥ 20 | Print install URL (https://nodejs.org/, link to `nvm` / `fnm` install). Exit 1. |
+
+Already detected today; just elevate `warn()` → `fail()` + exit.
+
+### Tier 2 — System binaries (ffmpeg required, whisper-cli soft)
+
+Detection uses the existing `which()` helper.
+
+```
+ffmpeg missing?
+├── platform === "darwin" && which("brew")
+│   → prompt: "Run `brew install ffmpeg`? [Y/n]"
+│     ├── yes → spawnSync("brew", ["install", "ffmpeg"], { stdio: "inherit" })
+│     │        re-check via which("ffmpeg"); exit 1 if still missing
+│     └── no  → exit 1 (REQUIRED — /reelstack-render won't work)
+├── platform === "darwin" && no brew
+│   → print: "Install Homebrew (https://brew.sh), then `brew install ffmpeg`"
+│     exit 1
+├── platform === "linux"
+│   → print: "Install via your package manager:
+│              apt-get install ffmpeg     # Debian/Ubuntu
+│              dnf install ffmpeg         # Fedora
+│              pacman -S ffmpeg           # Arch"
+│     exit 1
+└── platform === "win32"
+    → print: "Install via:
+               choco install ffmpeg       # Chocolatey
+               scoop install ffmpeg       # Scoop"
+      exit 1
+```
+
+`whisper-cli` follows the **same flow** but is **soft**: declining doesn't exit, it just disables `/reelstack-beats` (a flag is set in `~/.reelstack/state.json` so other commands can detect it).
+
+### Tier 3 — Remotion project bootstrap
+
+```
+detect cwd state:
+  • cwd has package.json with `remotion` dep
+    → already-Remotion path (current behavior at init.js:122-157)
+  • cwd has package.json without `remotion`
+    → warn: "This folder has a non-Remotion package.json. Bootstrap into a subdirectory instead."
+      offer: "Scaffold ./reelstack-project/? [Y/n]"
+  • cwd has no package.json
+    → offer: "Scaffold a Remotion project at ./reelstack-project/? [Y/n]"
+
+if user accepts:
+  spawnSync("npx", ["create-video@latest", "--yes", "--blank", projectName],
+            { stdio: "inherit", cwd: process.cwd() })
+  process.chdir(path.join(process.cwd(), projectName))
+  spawnSync("npm", ["install", "@devinilabs/reelstack"],
+            { stdio: "inherit", cwd: process.cwd() })
+
+if user declines:
+  print: "Re-run `reelstack init` from inside a Remotion project to wire up imports."
+  exit 0  (not a failure — buyer chose manual path)
+```
+
+`projectName` defaults to `reelstack-project`; `init --name=<dir>` overrides.
+
+The `--yes --blank` flags make `create-video` non-interactive so we control the flow. We use `--blank` (not a template) to keep the bootstrap minimal — the buyer's reels come from `/reelstack-*` scaffolders, not Remotion's defaults.
+
+### Tier 4 — Smoke test
+
+Runs only after Tiers 1-3 pass. Three fast, non-destructive checks (~5 s total) inside the working Remotion project directory:
+
+1. `reelstack scaffold --family=glass --preset=graphify --name=Demo` — proves the scaffolder produces valid TS that registers a composition.
+2. `npx remotion compositions` — proves Remotion's CLI loads the project and finds `Demo`. Catches "configs are wrong" and "imports don't resolve".
+3. `ffmpeg -version` — final sanity check that the binary is executable, not just on disk.
+
+If any step fails, the banner is `ReelStack is NOT ready — smoke test failed at step N` with the failing command's output preserved. Exit 1.
+
+`init --skip-smoke` bypasses Tier 4 for advanced buyers (e.g. CI, re-runs).
+
+## CLI surface
+
+```
+reelstack init                              # full flow
+reelstack init --name=my-reels              # custom subdirectory name for Tier 3
+reelstack init --skip-smoke                 # skip Tier 4 (still prints "ready")
+reelstack init --no-bootstrap               # skip Tier 3 entirely
+                                            # if no Remotion project: print manual-path
+                                            # guidance and exit 0
+                                            # if Remotion project exists: behave normally
+```
+
+### Flag semantics
+
+- **`--skip-smoke`**: success banner still prints. Buyer is opting out of the integration check (e.g. CI re-runs, advanced users). State.json records `smokeTest: "skipped"`.
+- **`--no-bootstrap`**: when no Remotion project is detected, init does NOT run `create-video`. Prints "Re-run from inside a Remotion project" and exits 0 (success — buyer chose manual path). Tier 4 also skipped because there's nothing to smoke-test.
+
+## State persistence
+
+A new file `~/.reelstack/state.json` records:
+
+```json
+{
+  "lastInitAt": "2026-05-09T14:23:00.000Z",
+  "ffmpeg": "ok",
+  "whisperCli": "missing-declined",
+  "smokeTest": "passed"
+}
+```
+
+Used by:
+- `/reelstack-beats` to fail fast with "whisper-cli was declined during init; run `brew install whisper-cpp` and re-run `reelstack init`".
+- `reelstack init` re-runs to skip already-passed checks if `--fast` is passed.
+
+## Buyer experience (target output)
+
+```
+$ npx @devinilabs/reelstack init
+
+  ReelStack v1.2
+  Welcome. Let's get ReelStack set up.
+
+  ✓ License verified (jane@devini.io)
+
+  Checking dependencies…
+  ✓ Node v22.5.0
+  ✗ ffmpeg not found
+    Run `brew install ffmpeg`? [Y/n] y
+    [brew output…]
+  ✓ ffmpeg installed
+  ✓ whisper-cli found
+
+  No Remotion project in this directory.
+  Scaffold one at ./reelstack-project/? [Y/n] y
+    [create-video output…]
+  ✓ Remotion project ready
+  ✓ @devinilabs/reelstack installed
+
+  Smoke test…
+  ✓ Demo.tsx scaffolded
+  ✓ Remotion CLI loads the Demo composition
+  ✓ ffmpeg executes
+
+  ReelStack is ready.
+
+  Next:
+    cd reelstack-project
+    npm run dev                              # open Remotion Studio
+    /reelstack-glass                         # scaffold a Glass Iridescent reel
+```
+
+Every line is provable, not warned-and-prayed.
+
+## File-level changes
+
+| File | Change |
+|---|---|
+| [cli/init.js](../../../cli/init.js) | Restructure into `runTier1()` … `runTier4()`. Replace warn-only checks with hard fails. Add bootstrap and smoke logic. |
+| [cli/utils.js](../../../cli/utils.js) | Add `platformPackageInstaller()` (returns `{ name, command }` per OS), `loadState()` / `saveState()` for `~/.reelstack/state.json`. |
+| `cli/bootstrap.js` (new) | Encapsulates Tier 3: detect cwd state, prompt, run `create-video`, install `@devinilabs/reelstack`. |
+| `cli/smoke.js` (new) | Encapsulates Tier 4: scaffold Demo, run `remotion compositions`, run `ffmpeg -version`. |
+| [cli/beats.js](../../../cli/beats.js) | Read state.json; fail fast with the "declined during init" message if `whisperCli === "missing-declined"`. |
+
+No changes to scaffolders, families, or templates. This is an init-layer change.
+
+## Testing
+
+- **Unit:** mock `which()`, `spawnSync()`, and `process.platform`; assert each tier's branches.
+- **Integration:** docker images per platform target — `darwin-with-brew`, `darwin-without-brew`, `linux-no-deps`, `windows-no-deps` — run `init` end-to-end and assert exit codes + state.json contents.
+- **Manual:** the dev's own machine, in three states: (a) clean cwd, (b) existing non-Remotion project, (c) existing Remotion project. Smoke test must produce a previewable Demo in case (a).
+
+## Open questions
+
+None. Buyer experience and Tier-2 strategy were settled in the brainstorming session on 2026-05-09.
+
+## Related
+
+- [cli/init.js](../../../cli/init.js) — current init flow
+- [cli/render.js](../../../cli/render.js) — direct ffmpeg consumer
+- [cli/beats.js](../../../cli/beats.js) — direct ffmpeg + whisper-cli consumer
+- Remotion getting-started: `npx create-video@latest --yes --blank <name>`
+- Removed: `npx remotion install` (Remotion v4.0.0)

package/families/dark/components/DriftingSpotlights.tsx

@@ -0,0 +1,59 @@
+import React from "react";
+import { AbsoluteFill, useCurrentFrame } from "remotion";
+import { palette, spotlightDrift } from "../palette";
+
+/**
+ * DriftingSpotlights — two overlapping radial-gradient blobs drifting on
+ * sine/cosine paths.
+ *
+ * The Dark Cinematic family's signature background motion. Mood-lights the
+ * void without ever resolving — the eye chases them and the scene reads as
+ * "premium ad-film, late-night, cinematic."
+ *
+ * Drift rates come from `spotlightDrift` in the palette (xRate = 0.004,
+ * yRate = 0.003). Mix-blend-mode "screen" + 60px blur means the blobs add
+ * light without darkening the underlying scene.
+ *
+ * Frame-budget: cheap. Two absolutely-positioned divs with CSS gradients.
+ */
+export const DriftingSpotlights: React.FC<{
+  reduceMotion?: boolean;
+}> = ({ reduceMotion = false }) => {
+  const frame = useCurrentFrame();
+  const cx1 = reduceMotion ? 50 : 50 + 35 * Math.sin(frame * spotlightDrift.xRate);
+  const cy1 = reduceMotion ? 30 : 30 + 20 * Math.cos(frame * spotlightDrift.yRate);
+  const cx2 = reduceMotion ? 50 : 50 + 30 * Math.cos(frame * spotlightDrift.xRate * 0.7);
+  const cy2 = reduceMotion ? 60 : 60 + 25 * Math.sin(frame * spotlightDrift.yRate * 0.6);
+  return (
+    <AbsoluteFill style={{ pointerEvents: "none" }}>
+      <div
+        style={{
+          position: "absolute",
+          left: `${cx1}%`,
+          top: `${cy1}%`,
+          width: 1200,
+          height: 1200,
+          marginLeft: -600,
+          marginTop: -600,
+          background: `radial-gradient(circle, ${palette.claude}33 0%, transparent 60%)`,
+          filter: "blur(60px)",
+          mixBlendMode: "screen",
+        }}
+      />
+      <div
+        style={{
+          position: "absolute",
+          left: `${cx2}%`,
+          top: `${cy2}%`,
+          width: 1000,
+          height: 1000,
+          marginLeft: -500,
+          marginTop: -500,
+          background: `radial-gradient(circle, ${palette.violet}28 0%, transparent 60%)`,
+          filter: "blur(60px)",
+          mixBlendMode: "screen",
+        }}
+      />
+    </AbsoluteFill>
+  );
+};

package/families/dark/components/FilmGrain.tsx

@@ -0,0 +1,44 @@
+import React from "react";
+import { AbsoluteFill } from "remotion";
+
+/**
+ * FilmGrain — SVG turbulence noise overlay at 6% opacity, multiply blend.
+ *
+ * Adds analog texture to the otherwise-perfect zinc void. Used by the
+ * notebooklm preset and any "textured" Dark Cinematic scene where the bg
+ * feels too clean. SVG `feTurbulence` is GPU-rasterized once and stamped
+ * across the frame, so cost is effectively flat regardless of duration.
+ *
+ * Mix-blend "multiply" so the grain only darkens — it never blows out
+ * highlights on the spotlights.
+ */
+export const FilmGrain: React.FC<{
+  opacity?: number;
+  baseFrequency?: number;
+  reduceMotion?: boolean;
+}> = ({ opacity = 0.06, baseFrequency = 0.9, reduceMotion = false }) => {
+  // The SVG itself is static (no frame-based animation), but reduceMotion
+  // dampens grain visibility for low-motion contexts.
+  const finalOpacity = reduceMotion ? opacity * 0.5 : opacity;
+  const svg = `
+    <svg xmlns="http://www.w3.org/2000/svg" width="300" height="300">
+      <filter id="n">
+        <feTurbulence type="fractalNoise" baseFrequency="${baseFrequency}" numOctaves="2" stitchTiles="stitch"/>
+        <feColorMatrix type="saturate" values="0"/>
+      </filter>
+      <rect width="100%" height="100%" filter="url(#n)"/>
+    </svg>
+  `;
+  const dataUri = `url("data:image/svg+xml;utf8,${encodeURIComponent(svg)}")`;
+  return (
+    <AbsoluteFill
+      style={{
+        backgroundImage: dataUri,
+        backgroundRepeat: "repeat",
+        opacity: finalOpacity,
+        mixBlendMode: "multiply",
+        pointerEvents: "none",
+      }}
+    />
+  );
+};

package/families/dark/components/ForestCard.tsx

@@ -0,0 +1,43 @@
+import React, { CSSProperties, ReactNode } from "react";
+import { palette } from "../palette";
+
+/**
+ * ForestCard — dark forest-green card surface (#1a2e1f).
+ *
+ * The Dark Cinematic family's signature embedded UI frame. Used by
+ * claudedispatch and gpt55 presets to wrap UI screenshots, terminal blocks,
+ * and benchmark cards so they sit in the scene as physical surfaces rather
+ * than floating overlays.
+ *
+ * Variants:
+ *   - "default" — palette.cardForest    (#1a2e1f)
+ *   - "lifted"  — palette.cardForestLift (#243a28)
+ *
+ * Multi-layer shadow stack reads as a real card on a dark stage.
+ */
+export const ForestCard: React.FC<{
+  variant?: "default" | "lifted";
+  style?: CSSProperties;
+  children?: ReactNode;
+}> = ({ variant = "default", style, children }) => {
+  const bg = variant === "lifted" ? palette.cardForestLift : palette.cardForest;
+  return (
+    <div
+      style={{
+        background: bg,
+        color: palette.fg,
+        borderRadius: 24,
+        padding: 36,
+        boxShadow: [
+          "0 1px 0 rgba(255,255,255,0.04) inset",
+          "0 -1px 0 rgba(0,0,0,0.4) inset",
+          "0 12px 28px rgba(0,0,0,0.35)",
+          "0 32px 64px rgba(0,0,0,0.55)",
+        ].join(", "),
+        ...style,
+      }}
+    >
+      {children}
+    </div>
+  );
+};

package/families/dark/components/GridBackground.tsx

@@ -0,0 +1,29 @@
+import React from "react";
+import { AbsoluteFill } from "remotion";
+
+/**
+ * GridBackground — 60×60 px grid lines at 4% white opacity, masked to fade
+ * at the edges.
+ *
+ * Provides "environment" — a faint architectural plane that anchors floating
+ * cards and text. Always sits between DriftingSpotlights and the foreground.
+ *
+ * Pure CSS (background-image with two linear gradients + radial mask). Zero
+ * per-frame cost.
+ */
+export const GridBackground: React.FC = () => (
+  <AbsoluteFill
+    style={{
+      backgroundImage: `
+        linear-gradient(to right,  rgba(255,255,255,0.04) 1px, transparent 1px),
+        linear-gradient(to bottom, rgba(255,255,255,0.04) 1px, transparent 1px)
+      `,
+      backgroundSize: "60px 60px",
+      WebkitMaskImage:
+        "radial-gradient(ellipse at center, rgba(0,0,0,1) 30%, rgba(0,0,0,0) 75%)",
+      maskImage:
+        "radial-gradient(ellipse at center, rgba(0,0,0,1) 30%, rgba(0,0,0,0) 75%)",
+      pointerEvents: "none",
+    }}
+  />
+);

package/families/dark/components/RadialVignette.tsx

@@ -0,0 +1,21 @@
+import React from "react";
+import { AbsoluteFill } from "remotion";
+
+/**
+ * RadialVignette — edge-darkening radial gradient.
+ *
+ * Pure CSS, zero per-frame work. Sits on top of the spotlights and grid to
+ * pull focus toward the center of the 1080×1920 frame. Reads as cinema-grade
+ * lighting falloff; without it the corners feel "open" and amateur.
+ *
+ * `pointer-events: none` so it never intercepts overlay interactions.
+ */
+export const RadialVignette: React.FC = () => (
+  <AbsoluteFill
+    style={{
+      background:
+        "radial-gradient(ellipse at center, rgba(0,0,0,0) 50%, rgba(0,0,0,0.55) 100%)",
+      pointerEvents: "none",
+    }}
+  />
+);

package/families/dark/components/Scanlines.tsx

@@ -0,0 +1,35 @@
+import React from "react";
+import { AbsoluteFill, useCurrentFrame } from "remotion";
+
+/**
+ * Brutalist Tactical CRT scanline overlay — opt-in for Dark Cinematic reels
+ * that want a "declassified telemetry" feel. Uses repeating-linear-gradient
+ * to render scanlines + a slow vertical scroll for tube-warmup motion.
+ *
+ * Inspired by leonxlnx/taste-skill-brutalist's Tactical Telemetry mode.
+ */
+export const Scanlines: React.FC<{
+  spacing?: number;         // px between scanlines
+  opacity?: number;         // overall opacity 0..1
+  scrollSpeed?: number;     // px/frame
+  reduceMotion?: boolean;
+}> = ({ spacing = 4, opacity = 0.06, scrollSpeed = 0.5, reduceMotion = false }) => {
+  const frame = useCurrentFrame();
+  const offset = reduceMotion ? 0 : (frame * scrollSpeed) % spacing;
+  return (
+    <AbsoluteFill
+      style={{
+        backgroundImage: `repeating-linear-gradient(
+          0deg,
+          rgba(255,255,255,${opacity}),
+          rgba(255,255,255,${opacity}) 1px,
+          transparent 1px,
+          transparent ${spacing}px
+        )`,
+        backgroundPosition: `0 ${offset}px`,
+        mixBlendMode: "screen",
+        pointerEvents: "none",
+      }}
+    />
+  );
+};

package/families/dark/components/SegmentOpacity.ts

@@ -0,0 +1,37 @@
+import { interpolate } from "remotion";
+import { crossfadeTimings } from "../palette";
+
+/**
+ * SegmentOpacity (`so`) — fades a scene in/out within a [startSec, endSec]
+ * range.
+ *
+ * The Dark Cinematic family's signature scene-transition mechanic. Every
+ * preset wraps its scenes in
+ *
+ *     <div style={{ opacity: so(frame, fps, ...SEGS.body) }}>…</div>
+ *
+ * to crossfade between hook / body / anchor / cta beats without scene cuts.
+ *
+ * Defaults (`fadeInSec` = 0.45, `fadeOutSec` = 0.55) come from
+ * `palette.crossfadeTimings` so the whole family stays in sync. Override per
+ * call when a scene needs a faster snap or a longer dissolve.
+ *
+ * NOT a component — a pure helper. Lives in /components/ alongside the
+ * primitives because every template imports it from the same barrel.
+ */
+export const so = (
+  frame: number,
+  fps: number,
+  startSec: number,
+  endSec: number,
+  fadeInSec: number = crossfadeTimings.fadeInSec,
+  fadeOutSec: number = crossfadeTimings.fadeOutSec,
+): number => {
+  const sec = frame / fps;
+  return interpolate(
+    sec,
+    [startSec, startSec + fadeInSec, endSec - fadeOutSec, endSec],
+    [0, 1, 1, 0],
+    { extrapolateLeft: "clamp", extrapolateRight: "clamp" },
+  );
+};

package/families/dark/components/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Dark Cinematic — primitive components index.
+ * Scaffold templates import from here:
+ *   import { DriftingSpotlights, RadialVignette, GridBackground, ForestCard, FilmGrain, so }
+ *     from "@devinilabs/reelstack/families/dark/components";
+ */
+export { DriftingSpotlights } from "./DriftingSpotlights";
+export { RadialVignette } from "./RadialVignette";
+export { GridBackground } from "./GridBackground";
+export { ForestCard } from "./ForestCard";
+export { FilmGrain } from "./FilmGrain";
+export { so } from "./SegmentOpacity";
+export { Scanlines } from "./Scanlines";

package/families/dark/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Dark Cinematic — family index.
+ */
+export { palette, safeZones, crossfadeTimings, spotlightDrift } from "./palette";
+export type { DarkPalette } from "./palette";
+
+import { preset as stitch } from "./presets/stitch";
+import { preset as stitch2 } from "./presets/stitch2";
+import { preset as codedrop } from "./presets/codedrop";
+import { preset as claudedispatch } from "./presets/claudedispatch";
+import { preset as notebooklm } from "./presets/notebooklm";
+import { preset as gpt55 } from "./presets/gpt55";
+import { preset as resourcescta } from "./presets/resourcescta";
+import { preset as skills } from "./presets/skills";
+
+export const presets = {
+  stitch,
+  stitch2,
+  codedrop,
+  claudedispatch,
+  notebooklm,
+  gpt55,
+  resourcescta,
+  skills,
+} as const;
+
+export const family = {
+  name: "dark",
+  label: "Dark Cinematic",
+  presets: Object.keys(presets) as Array<keyof typeof presets>,
+} as const;

package/families/dark/palette.ts

@@ -0,0 +1,98 @@
+/**
+ * ReelStack — Dark Cinematic palette
+ *
+ * Verified against /Users/abhishekraj/my-video/src/StitchReel.tsx,
+ * ClaudeDispatchReel.tsx, CodeDropReel.tsx, NotebookLMReel.tsx.
+ *
+ * Mood: premium ad-film, late-night, mood-lit cards.
+ *
+ * Multi-brand accents are ALLOWED in this family — Stitch rose, Gemini blue,
+ * NotebookLM blue can all appear in the same reel as Claude terracotta.
+ * The single-accent rule does NOT apply here.
+ */
+export const palette = {
+  // Backgrounds — zinc void
+  bg: "#0a0a0b",
+  bgLift: "#141416",
+  surface: "#1a1a1d",
+  surfaceLift: "#222226",
+
+  // Dark forest green card surface (for agent / benchmark / terminal cards)
+  cardForest: "#1a2e1f",
+  cardForestLift: "#243a28",
+
+  // Foreground
+  fg: "#f5f5f7",      // contrast 18.7:1 on bg #0a0a0b — WCAG AAA
+  fgSoft: "#d1d1d6",  // contrast 13.4:1 on bg #0a0a0b — WCAG AAA
+  fgMuted: "#8e8e93", // contrast 6.4:1  on bg #0a0a0b — WCAG AA
+  fgDim: "#5a5a60",   // contrast 3.1:1  on bg #0a0a0b — WCAG AA-Large
+
+  // Brand accents
+  claude: "#D4663A",
+  claudeSoft: "#e07a54",
+  stitch: "#ff4d9b",
+  stitchSoft: "#ff7fb8",
+  gemini: "#4285f4",
+  notebookBlue: "#4F7DF3",
+
+  // Semantic
+  safe: "#4fc46a",
+  danger: "#e25822",
+  amber: "#fcbb00",
+  violet: "#8d54ff",
+
+  // Terminal text
+  terminalGreen: "#5be8a0",
+
+  // Macro-window dots
+  macClose: "#ff5f57",
+  macMin: "#ffbd2e",
+  macMax: "#28ca42",
+} as const;
+
+export const safeZones = {
+  top: 290,
+  bottom: 1500,
+  canvas: { width: 1080, height: 1920 },
+} as const;
+
+/**
+ * Crossfade timings used by every Dark Cinematic preset. SegmentOpacity (`so()`
+ * helper) reads these as defaults.
+ */
+export const crossfadeTimings = {
+  fadeInSec: 0.45,
+  fadeOutSec: 0.55,
+} as const;
+
+/**
+ * Drift-velocity defaults for DriftingSpotlights — the family's signature
+ * background motion. Two or three spotlights drift at these rates on
+ * sine/cosine paths.
+ */
+export const spotlightDrift = {
+  xRate: 0.004,
+  yRate: 0.003,
+} as const;
+
+/**
+ * NOTE: Dark Cinematic intentionally does NOT export an ALLOWED_ACCENTS list.
+ * Multi-brand accents are part of this family's identity — Stitch rose, Gemini
+ * blue, NotebookLM blue, and Claude terracotta can all appear in the same reel
+ * without lint flagging them as "off-palette". The lint command treats Dark as
+ * the multi-brand exception; every other family gets a strict accent allowlist.
+ */
+
+export type DarkPalette = typeof palette;
+
+/** Re-export grid units so consumers can pull them from the family entrypoint. */
+export {
+  GRID,
+  GRID_2,
+  GRID_4,
+  GRID_6,
+  GRID_8,
+  GRID_12,
+  GRID_16,
+  GRID_24,
+} from "../../utils/grid";