reelme 0.3.0 → 0.5.0

package/template/src/cinematic/look.ts

@@ -5,14 +5,31 @@
 //
 // Looks are pure data; colors come from the resolved Theme at render time.
 
+import { MotionProfile } from "../theme";
+
 export type LookId = "keynote" | "noir" | "arcade" | "blueprint" | "editorial";
 
-export type TransitionStyle = "cut" | "fade" | "dip" | "whip" | "rise" | "punch" | "zoom";
+export type TransitionStyle = "cut" | "fade" | "dip" | "whip" | "rise" | "punch" | "zoom" | "wipe" | "flip";
 
 export type CameraMove = "push" | "drift" | "pan" | "float" | "still";
 
 export type AtmosphereOverlay = "none" | "grid" | "scanlines" | "dust";
 
+/**
+ * The backdrop SYSTEM a look is staged on. This is the look's silhouette: two
+ * looks with different backdrops read as different films even before grading.
+ * The old single recipe (dark field + drifting radial orbs) was the template's
+ * fingerprint — every reel shared it, and an orb in empty space reads as a
+ * smudge, not a light. Each system covers the frame with intent instead:
+ *
+ * - mesh:      full-bleed multi-hue gradient field (accent + accent2), slow drift
+ * - spotlight: one elliptical light pool aimed where the content sits
+ * - sweep:     saturated full-frame diagonal gradient between the brand hues
+ * - grid:      structural engineering grid — the graphic IS the backdrop
+ * - field:     rich near-solid editorial color field with a soft top wash
+ */
+export type BackdropSystem = "mesh" | "spotlight" | "sweep" | "grid" | "field";
+
 export interface Grade {
   /** Tint color layered over the whole frame. */
   color: string;
@@ -22,7 +39,9 @@ export interface Grade {
 
 export interface CinematicLook {
   id: LookId;
-  /** Radial accent-light intensity behind the content (0..1). */
+  /** Which backdrop system stages the whole reel. */
+  backdrop: BackdropSystem;
+  /** Backdrop light/color intensity (0..1). */
   glow: number;
   /** Whether a second, cooler light source is added for depth. */
   twoTone: boolean;
@@ -31,47 +50,69 @@ export interface CinematicLook {
   /** Film-grain opacity on the final frame (0..1); skipped for gif output. */
   grain: number;
   overlay: AtmosphereOverlay;
-  /** Base camera move applied to every scene's content. */
+  /** Arrival move for every scene's content: a zoom that eases to a rest. */
   camera: CameraMove;
   /** Camera amplitude multiplier (1 = default). */
   cameraIntensity: number;
   grade: Grade;
-  /** Default cut style; the rhythm picker varies around it. */
-  transition: TransitionStyle;
   /** Editing energy: higher tightens enter timings and favors hard cuts. */
   energy: number;
+  /**
+   * Spring physics for in-scene element animation. Motion is part of the
+   * production design: a look should *move* differently, not just look
+   * different. The Reel feeds this into the theme so every scene's springs
+   * inherit the look's personality (smooth, snappy, weighty, ...).
+   */
+  motion: MotionProfile;
 }
 
 const LOOKS: Record<LookId, Omit<CinematicLook, "id">> = {
   // Clean keynote stage — soft key light, gentle push, long dissolves.
+  // Motion: settled, no bounce — elements arrive and hold.
   keynote: {
+    backdrop: "mesh",
     glow: 0.5, twoTone: false, vignette: 0.35, grain: 0.04, overlay: "none",
     camera: "push", cameraIntensity: 1, grade: { color: "#ffffff", blend: "soft-light", alpha: 0.05 },
-    transition: "fade", energy: 0.4,
+    energy: 0.4,
+    motion: { damping: 22, stiffness: 100, mass: 1.0 },
   },
   // Low-key cinema — deep vignette, cool grade, slow drift, dips to black.
+  // Motion: heavy and deliberate — weighty mass, slow to settle.
   noir: {
+    backdrop: "spotlight",
     glow: 0.42, twoTone: true, vignette: 0.62, grain: 0.09, overlay: "dust",
     camera: "drift", cameraIntensity: 1.1, grade: { color: "#2a3550", blend: "multiply", alpha: 0.22 },
-    transition: "dip", energy: 0.35,
+    energy: 0.35,
+    motion: { damping: 28, stiffness: 78, mass: 1.4 },
   },
   // Saturated arcade — dual lights, scanlines, snappy whips and zooms.
+  // Motion: snappy but settled — light mass, high stiffness, near-critical
+  // damping. Energy comes from speed, not from overshoot: a bouncing element
+  // reads as a toy, not a cut (gallery feedback).
   arcade: {
+    backdrop: "sweep",
     glow: 0.72, twoTone: true, vignette: 0.3, grain: 0.05, overlay: "scanlines",
     camera: "float", cameraIntensity: 1.25, grade: { color: "#ff3da6", blend: "screen", alpha: 0.06 },
-    transition: "whip", energy: 0.85,
+    energy: 0.85,
+    motion: { damping: 20, stiffness: 155, mass: 0.7 },
   },
   // Engineering blueprint — cool tint, faint grid, measured pans, mixed cuts.
+  // Motion: stiff and precise — quick, minimal bounce, machined.
   blueprint: {
+    backdrop: "grid",
     glow: 0.45, twoTone: false, vignette: 0.42, grain: 0.06, overlay: "grid",
     camera: "pan", cameraIntensity: 1, grade: { color: "#1e3a5f", blend: "soft-light", alpha: 0.12 },
-    transition: "cut", energy: 0.6,
+    energy: 0.6,
+    motion: { damping: 30, stiffness: 150, mass: 1.1 },
   },
   // Premium brand film — warm grade, big soft vignette, very slow elegant push.
+  // Motion: the smoothest — elegant glide, no perceptible bounce.
   editorial: {
+    backdrop: "field",
     glow: 0.55, twoTone: false, vignette: 0.5, grain: 0.07, overlay: "none",
     camera: "push", cameraIntensity: 0.7, grade: { color: "#ffb27a", blend: "overlay", alpha: 0.08 },
-    transition: "fade", energy: 0.3,
+    energy: 0.3,
+    motion: { damping: 26, stiffness: 88, mass: 1.15 },
   },
 };
 

package/template/src/cinematic/transitions.tsx

@@ -8,9 +8,11 @@ import { CinematicLook, TransitionStyle } from "./look";
 const RHYTHM: Record<string, TransitionStyle[]> = {
   keynote: ["fade", "rise", "fade", "rise"],
   noir: ["dip", "fade", "dip", "rise"],
-  arcade: ["whip", "punch", "zoom", "whip"],
-  blueprint: ["cut", "rise", "cut", "whip"],
-  editorial: ["fade", "fade", "rise", "fade"],
+  // No flip: a hinged swing reads as a gimmick next to the rest of the edit
+  // (gallery feedback) — arcade's energy now comes from fast zooms and whips.
+  arcade: ["zoom", "whip", "zoom", "fade"],
+  blueprint: ["cut", "wipe", "cut", "whip"],
+  editorial: ["fade", "wipe", "rise", "fade"],
 };
 
 export function transitionFor(look: CinematicLook, index: number, total: number): TransitionStyle {
@@ -43,8 +45,11 @@ export const Enter: React.FC<EnterProps> = ({ style, look, fromBlack, seed, chil
   const p = interpolate(frame, [0, win], [0, 1], { ...ease, easing: Easing.out(Easing.cubic) });
 
   let opacity = 1;
-  let transform = "";
+  let scale: string | undefined;
+  let translate: string | undefined;
   let filter: string | undefined;
+  let transform: string | undefined;
+  let clipPath: string | undefined;
 
   switch (style) {
     case "cut":
@@ -54,25 +59,38 @@ export const Enter: React.FC<EnterProps> = ({ style, look, fromBlack, seed, chil
       break;
     case "rise":
       opacity = p;
-      transform = `translateY(${interpolate(p, [0, 1], [44, 0])}px)`;
+      translate = `0 ${interpolate(p, [0, 1], [44, 0])}px`;
       break;
     case "whip":
       opacity = interpolate(frame, [0, win * 0.7], [0, 1], ease);
-      transform = `translateX(${interpolate(p, [0, 1], [90 * dir, 0])}px)`;
+      translate = `${interpolate(p, [0, 1], [90 * dir, 0])}px 0`;
       filter = `blur(${interpolate(p, [0, 1], [14, 0])}px)`;
       break;
     case "punch":
       opacity = interpolate(frame, [0, win * 0.6], [0, 1], ease);
-      transform = `scale(${interpolate(p, [0, 1], [1.12, 1])})`;
+      scale = String(interpolate(p, [0, 1], [1.07, 1]));
       break;
     case "zoom":
       opacity = p;
-      transform = `scale(${interpolate(p, [0, 1], [0.9, 1])})`;
+      scale = String(interpolate(p, [0, 1], [0.9, 1]));
       break;
     case "dip":
       // Content snaps in; a black veil over the top lifts away → dip-to-black.
       opacity = interpolate(frame, [0, win * 0.5], [0, 1], ease);
       break;
+    case "wipe": {
+      // A hard edge sweeps across, revealing the shot. Direction alternates by
+      // seed so consecutive wipes don't all travel the same way.
+      opacity = interpolate(frame, [0, win * 0.3], [0, 1], ease);
+      const remain = interpolate(p, [0, 1], [100, 0]);
+      clipPath = dir > 0 ? `inset(0 ${remain}% 0 0)` : `inset(0 0 0 ${remain}%)`;
+      break;
+    }
+    case "flip":
+      // Shot swings in on a vertical hinge — a single playful rotation.
+      opacity = interpolate(frame, [0, win * 0.5], [0, 1], ease);
+      transform = `perspective(1400px) rotateY(${interpolate(p, [0, 1], [62 * dir, 0])}deg)`;
+      break;
   }
 
   const dipVeil = style === "dip" && (
@@ -83,7 +101,9 @@ export const Enter: React.FC<EnterProps> = ({ style, look, fromBlack, seed, chil
 
   return (
     <>
-      <AbsoluteFill style={{ opacity, transform, filter, willChange: "transform, opacity" }}>
+      <AbsoluteFill
+        style={{ opacity, scale, translate, filter, transform, clipPath, willChange: "scale, translate, opacity, transform, clip-path" }}
+      >
         {children}
       </AbsoluteFill>
       {dipVeil}

package/template/src/components/primitives/Arrow.tsx

@@ -10,11 +10,14 @@ interface ArrowProps {
   label?: string;
   theme: Theme;
   startFrame?: number;
+  /** Line weight; supporting graphics need real presence at video size. */
+  strokeWidth?: number;
+  labelSize?: number;
 }
 
-const ARROW_HEAD_SIZE = 10;
+const ARROW_HEAD_SIZE = 14;
 
-export const Arrow: React.FC<ArrowProps> = ({ x1, y1, x2, y2, label, theme, startFrame = 0 }) => {
+export const Arrow: React.FC<ArrowProps> = ({ x1, y1, x2, y2, label, theme, startFrame = 0, strokeWidth = 3.5, labelSize = 22 }) => {
   const frame = useCurrentFrame();
   const { fps } = useVideoConfig();
   const elapsed = frame - startFrame;
@@ -50,7 +53,7 @@ export const Arrow: React.FC<ArrowProps> = ({ x1, y1, x2, y2, label, theme, star
         x2={x2short}
         y2={y2short}
         stroke={theme.accent}
-        strokeWidth={2.5}
+        strokeWidth={strokeWidth}
         strokeDasharray={len}
         strokeDashoffset={dashOffset}
         strokeLinecap="round"
@@ -68,9 +71,9 @@ export const Arrow: React.FC<ArrowProps> = ({ x1, y1, x2, y2, label, theme, star
       {label && progress > 0.5 && (
         <text
           x={midX}
-          y={midY - 10}
+          y={midY - 14}
           fill={theme.textMuted}
-          fontSize={15}
+          fontSize={labelSize}
           textAnchor="middle"
           fontFamily={theme.fontSans}
           opacity={interpolate(progress, [0.5, 1], [0, 1])}

package/template/src/components/primitives/Bar.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { useCurrentFrame, useVideoConfig, spring, interpolate } from "remotion";
+import { useCurrentFrame, useVideoConfig, spring, interpolate, Easing } from "remotion";
 import { Theme } from "../../theme";
 
 interface Props {
@@ -21,8 +21,12 @@ export const Bar: React.FC<Props> = ({ label, valueText, fraction, hero, theme,
     fps,
     config: theme.motion,
   });
-  const width = interpolate(Math.max(0, progress), [0, 1], [0, Math.max(0, Math.min(1, fraction))]);
+  const width = interpolate(Math.max(0, progress), [0, 1], [0, Math.max(0, Math.min(1, fraction))], {
+    extrapolateLeft: "clamp",
+    extrapolateRight: "clamp",
+  });
   const valueOpacity = interpolate(frame - startFrame, [10, 22], [0, 1], {
+    easing: Easing.bezier(0.16, 1, 0.3, 1),
     extrapolateLeft: "clamp",
     extrapolateRight: "clamp",
   });

package/template/src/components/primitives/Caption.tsx

@@ -28,7 +28,7 @@ export const Caption: React.FC<CaptionProps> = ({ text, theme, startFrame = 0, b
         display: "flex",
         justifyContent: "center",
         opacity,
-        transform: `translateY(${translateY}px)`,
+        translate: `0 ${translateY}px`,
       }}
     >
       <div
@@ -38,7 +38,7 @@ export const Caption: React.FC<CaptionProps> = ({ text, theme, startFrame = 0, b
           borderRadius: 999,
           padding: "10px 28px",
           fontFamily: theme.fontSans,
-          fontSize: 22,
+          fontSize: 32,
           fontWeight: 500,
           color: theme.text,
           letterSpacing: "-0.01em",

package/template/src/components/primitives/CodeBlock.tsx

@@ -61,19 +61,30 @@ export const CodeBlock: React.FC<CodeBlockProps> = ({
   framesPerLine = 9,
 }) => {
   const frame = useCurrentFrame();
-  const { fps } = useVideoConfig();
+  const { fps, width: frameWidth } = useVideoConfig();
   const elapsed = frame - startFrame;
   const lines = code.split("\n");
+  // Scale type with the frame so the editor window commands wide canvases
+  // (ch-based width sizing inherits this automatically).
+  const fontSize = Math.max(22, Math.round(frameWidth * 0.0135));
   const visibleCount = Math.max(0, Math.min(lines.length, Math.floor(elapsed / framesPerLine) + 1));
 
+  // Size the window to the longest line of the FULL snippet (not the partial
+  // reveal) so it arrives at its final width and never stretches to fill the
+  // frame — an editor window several times wider than its code reads as empty
+  // chrome (gallery feedback). 83px covers gutter, line numbers, and padding.
+  const cols = Math.min(Math.max(lines.reduce((m, l) => Math.max(m, l.length), 0), 24), 88);
+
   return (
-    <div style={{ fontFamily: theme.fontMono, fontSize: 20, lineHeight: 1.7 }}>
+    <div style={{ fontFamily: theme.fontMono, fontSize, lineHeight: 1.7, width: `calc(${cols}ch + 83px)`, maxWidth: "100%" }}>
       <div
         style={{
           background: "#0d1117",
-          borderRadius: 10,
+          borderRadius: 12,
           overflow: "hidden",
-          boxShadow: "0 8px 48px rgba(0,0,0,0.6)",
+          // Contact shadow + brand-light halo so the window sits in the stage.
+          boxShadow: `0 30px 90px -18px ${theme.accent}59, 0 24px 60px rgba(0,0,0,0.55)`,
+          outline: "1px solid rgba(255,255,255,0.09)",
         }}
       >
         {/* Title bar */}
@@ -95,9 +106,11 @@ export const CodeBlock: React.FC<CodeBlockProps> = ({
           </span>
         </div>
 
-        {/* Code lines */}
+        {/* Code lines. All rows are laid out from frame 0 (unrevealed ones
+            invisible) so the window opens at its final height — the reveal
+            happens inside stable chrome instead of inflating it. */}
         <div style={{ padding: "20px 0" }}>
-          {lines.slice(0, visibleCount).map((line, i) => {
+          {lines.map((line, i) => {
             const lineNum = i + 1;
             const isHighlight = highlightLine !== undefined && lineNum === highlightLine;
             const highlightOpacity =
@@ -115,6 +128,7 @@ export const CodeBlock: React.FC<CodeBlockProps> = ({
                 style={{
                   display: "flex",
                   padding: "0 24px",
+                  visibility: i < visibleCount ? "visible" : "hidden",
                   background: isHighlight
                     ? `rgba(${hexToRgb(theme.accent)}, ${0.15 * highlightOpacity})`
                     : "transparent",
@@ -128,7 +142,7 @@ export const CodeBlock: React.FC<CodeBlockProps> = ({
                     color: "#484f58",
                     minWidth: 32,
                     userSelect: "none",
-                    fontSize: 16,
+                    fontSize: Math.round(fontSize * 0.8),
                     paddingTop: 1,
                   }}
                 >

package/template/src/components/primitives/Icon.tsx

@@ -54,6 +54,13 @@ const ICON_MAP: Record<string, LucideIcon> = {
   zap: Zap,
 };
 
+// Whether a name resolves to a real icon. Callers use this to fall back visibly
+// (e.g. to a numbered marker) instead of rendering an empty slot when a brief
+// names an icon outside the registry (F6).
+export function hasIcon(name: string): boolean {
+  return name.toLowerCase() in ICON_MAP;
+}
+
 export interface IconProps {
   name: string;
   size?: number;

package/template/src/components/primitives/KeyPill.tsx

@@ -34,7 +34,7 @@ export const KeyPill: React.FC<KeyPillProps> = ({ label, theme, startFrame = 0 }
         color: theme.text,
         minWidth: 60,
         letterSpacing: "-0.01em",
-        transform: `scale(${scale})`,
+        scale: String(scale),
         opacity,
       }}
     >

package/template/src/components/primitives/Label.tsx

@@ -12,7 +12,10 @@ interface LabelProps {
   emphasis?: string;
 }
 
-const sizeMap = { sm: 22, md: 32, lg: 48, xl: 72 };
+// Floors from the video-layout rules at 1080-wide: labels >=32, supporting >=44,
+// headline >=84. Each step meets or clears its floor so text stays readable at
+// viewing distance.
+const sizeMap = { sm: 32, md: 44, lg: 60, xl: 88 };
 
 export const Label: React.FC<LabelProps> = ({
   text,

package/template/src/components/primitives/Loop.tsx

@@ -0,0 +1,65 @@
+import React from "react";
+import { useCurrentFrame, useVideoConfig } from "remotion";
+
+type LoopProperty = "scale" | "translateX" | "translateY" | "rotate";
+
+interface Props {
+  /** Which transform channel oscillates. */
+  property?: LoopProperty;
+  /**
+   * Peak deviation from rest: px for translate, degrees for rotate, and a
+   * scale delta for scale (0.02 = breathes between 0.98 and 1.02).
+   */
+  amplitude?: number;
+  /** Seconds for one full cycle. */
+  period?: number;
+  /** 0..1 phase offset so several looped elements don't move in lockstep. */
+  phase?: number;
+  /**
+   * Skip the motion (gif output): a perpetually moving element changes every
+   * frame and defeats gif compression, same reasoning as the Camera.
+   */
+  disabled?: boolean;
+  children: React.ReactNode;
+}
+
+/**
+ * Applies a subtle, continuous, seamless oscillation to a held element — the
+ * declarative "loop" channel the entrance springs don't cover. Motion is a sine
+ * driven by useCurrentFrame, so it loops without a seam and renders
+ * deterministically. Keep amplitudes small: this is meant to read as "alive",
+ * not as a bounce.
+ */
+export const Loop: React.FC<Props> = ({
+  property = "translateY",
+  amplitude = 6,
+  period = 3.5,
+  phase = 0,
+  disabled,
+  children,
+}) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  if (disabled) return <>{children}</>;
+
+  const v = Math.sin((frame / (period * fps) + phase) * Math.PI * 2) * amplitude;
+
+  let style: React.CSSProperties;
+  switch (property) {
+    case "scale":
+      style = { scale: String(1 + v) };
+      break;
+    case "translateX":
+      style = { translate: `${v}px 0` };
+      break;
+    case "rotate":
+      style = { rotate: `${v}deg` };
+      break;
+    case "translateY":
+    default:
+      style = { translate: `0 ${v}px` };
+      break;
+  }
+
+  return <div style={{ ...style, willChange: "transform" }}>{children}</div>;
+};

package/template/src/components/primitives/RevealText.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { useCurrentFrame, useVideoConfig, spring, interpolate } from "remotion";
+import { useCurrentFrame, useVideoConfig, spring, interpolate, Easing } from "remotion";
 import { Theme } from "../../theme";
 
 interface RevealTextProps {
@@ -44,7 +44,29 @@ export const RevealText: React.FC<RevealTextProps> = ({
   const frame = useCurrentFrame();
   const { fps } = useVideoConfig();
   const words = text.split(" ");
-  const emphWord = emphasis?.trim().toLowerCase();
+
+  // Resolve which word indices the accent covers. A multi-word accent phrase
+  // ("one command") must emphasize the whole contiguous run, not silently no-op
+  // because no single word equals the phrase (F2). Punctuation is stripped from
+  // both sides so "video." matches "video".
+  const clean = (w: string) => w.replace(/[.,!?:;]/g, "").toLowerCase();
+  const cleanedWords = words.map(clean);
+  const emphIndices = new Set<number>();
+  const accentWords = emphasis?.trim() ? emphasis.trim().split(/\s+/).map(clean).filter(Boolean) : [];
+  if (accentWords.length === 1) {
+    const a = accentWords[0];
+    cleanedWords.forEach((c, i) => {
+      if (c === a || c.includes(a)) emphIndices.add(i);
+    });
+  } else if (accentWords.length > 1) {
+    for (let i = 0; i + accentWords.length <= cleanedWords.length; i++) {
+      const matches = accentWords.every((a, j) => {
+        const c = cleanedWords[i + j];
+        return c === a || c.includes(a);
+      });
+      if (matches) accentWords.forEach((_, j) => emphIndices.add(i + j));
+    }
+  }
 
   return (
     <div
@@ -57,7 +79,6 @@ export const RevealText: React.FC<RevealTextProps> = ({
         lineHeight,
         letterSpacing,
         maxWidth,
-        textShadow: glow ? "0 6px 40px rgba(0,0,0,0.45)" : undefined,
       }}
     >
       {words.map((word, i) => {
@@ -65,17 +86,23 @@ export const RevealText: React.FC<RevealTextProps> = ({
         const p = spring({ frame: elapsed, fps, config: theme.motion });
         const y = interpolate(p, [0, 1], [112, 0], { extrapolateRight: "clamp" });
         const opacity = interpolate(elapsed, [0, 6], [0, 1], {
+          easing: Easing.bezier(0.16, 1, 0.3, 1),
           extrapolateLeft: "clamp",
           extrapolateRight: "clamp",
         });
-        const clean = word.replace(/[.,!?:;]/g, "").toLowerCase();
-        const isEmph = emphWord && (clean === emphWord || word.toLowerCase().includes(emphWord));
+        const isEmph = emphIndices.has(i);
+        // The clip mask exists only for the rise. Once the word is at rest the
+        // mask is released and the glow fades in — a soft 40px shadow inside an
+        // overflow-hidden span gets sheared into visible rectangles, so the two
+        // must never coexist (gallery feedback: "shadow looks cut off").
+        const settled = y < 1;
+        const shadowAlpha = glow && settled ? interpolate(p, [0.991, 1], [0, 0.45], { extrapolateLeft: "clamp", extrapolateRight: "clamp" }) : 0;
         return (
           <React.Fragment key={i}>
             <span
               style={{
                 display: "inline-block",
-                overflow: "hidden",
+                overflow: settled ? "visible" : "hidden",
                 paddingBottom: "0.14em",
                 marginBottom: "-0.14em",
                 verticalAlign: "bottom",
@@ -84,9 +111,10 @@ export const RevealText: React.FC<RevealTextProps> = ({
               <span
                 style={{
                   display: "inline-block",
-                  transform: `translateY(${y}%)`,
+                  translate: `0 ${y}%`,
                   opacity,
                   color: isEmph ? theme.accent : undefined,
+                  textShadow: shadowAlpha > 0 ? `0 6px 40px rgba(0,0,0,${shadowAlpha.toFixed(3)})` : undefined,
                 }}
               >
                 {word}

package/template/src/components/primitives/Stage.tsx

@@ -0,0 +1,62 @@
+import React from "react";
+import { AbsoluteFill } from "remotion";
+import { Theme } from "../../theme";
+import { Caption } from "./Caption";
+
+// Standard horizontal safe inset for scene content — keeps text off the frame
+// edges (the video-layout rules want key content ~120px in on a 1080–1920 frame).
+export const STAGE_INSET = 120;
+
+interface StageProps {
+  theme: Theme;
+  /** Stacking direction of the content. */
+  direction?: "row" | "column";
+  justify?: React.CSSProperties["justifyContent"];
+  align?: React.CSSProperties["alignItems"];
+  gap?: number;
+  /** Horizontal padding; defaults to the standard safe inset on both sides. */
+  padding?: React.CSSProperties["padding"];
+  /** Optional caption rendered as the film's bottom pill. */
+  caption?: string;
+  captionStart?: number;
+  bottomInset?: number;
+  children: React.ReactNode;
+}
+
+/**
+ * The shared scene root. Every scene is shot on the one continuous Atmosphere, so
+ * the root is ALWAYS transparent — never paint an opaque full-frame fill here or
+ * the stage behind it disappears and the reel stops reading as one film. Content
+ * is centered by default so leftover space stays symmetric (composed negative
+ * space) instead of being dumped against one edge as a void. For a hero + aside
+ * composition use `direction="row"` with `justify="space-between"`.
+ */
+export const Stage: React.FC<StageProps> = ({
+  theme,
+  direction = "column",
+  justify = "center",
+  align = "center",
+  gap,
+  padding,
+  caption,
+  captionStart = 50,
+  bottomInset = 0,
+  children,
+}) => {
+  return (
+    <AbsoluteFill
+      style={{
+        background: "transparent",
+        display: "flex",
+        flexDirection: direction,
+        alignItems: align,
+        justifyContent: justify,
+        gap,
+        padding: padding ?? `0 ${STAGE_INSET}px`,
+      }}
+    >
+      {children}
+      {caption && <Caption text={caption} theme={theme} startFrame={captionStart} bottomInset={bottomInset} />}
+    </AbsoluteFill>
+  );
+};