@xonovex/skills 0.1.0

package/skills/remotion-guidelines/reference/animations.md

@@ -0,0 +1,121 @@
+# animations: Frame-Driven Animation
+
+**Guideline:** Drive all animations with `useCurrentFrame()` and `interpolate()` or `spring()` functions, never CSS transitions.
+
+**Rationale:** Remotion captures each frame as an image; CSS transitions and Tailwind animations won't render in the video output.
+
+**Example:**
+
+```tsx
+// Simple fade-in over 1 second (30fps = 30 frames)
+const frame = useCurrentFrame();
+const opacity = interpolate(frame, [0, 30], [0, 1], {
+  extrapolateRight: "clamp",
+});
+return <div style={{opacity}}>Fades in</div>;
+
+// Spring bounce entrance
+const scale = spring({frame, fps: 30, config: {damping: 8}});
+return <div style={{transform: `scale(${scale})`}}>Bounces in</div>;
+
+// Bad: Won't animate in Remotion
+<div className="animate-bounce">Won't work</div>
+```
+
+**Linear Interpolation:**
+
+```tsx
+import {interpolate, useCurrentFrame, useVideoConfig} from "remotion";
+
+function FadeIn() {
+  const frame = useCurrentFrame();
+  const {fps} = useVideoConfig();
+
+  // Fade in over 0.5 seconds
+  const opacity = interpolate(frame, [0, 0.5 * fps], [0, 1], {
+    extrapolateRight: "clamp",
+  });
+
+  return <div style={{opacity}}>Content</div>;
+}
+```
+
+**Spring Animation:**
+
+```tsx
+import {spring, useCurrentFrame, useVideoConfig} from "remotion";
+
+function BounceIn() {
+  const frame = useCurrentFrame();
+  const {fps} = useVideoConfig();
+
+  const scale = spring({
+    frame,
+    fps,
+    config: {damping: 10, stiffness: 100},
+  });
+
+  return <div style={{transform: `scale(${scale})`}}>Content</div>;
+}
+```
+
+**Spring Presets:**
+
+```tsx
+// Smooth, no bounce (subtle reveals)
+const smooth = {damping: 200};
+
+// Snappy, minimal bounce (UI elements)
+const snappy = {damping: 20, stiffness: 200};
+
+// Bouncy entrance (playful animations)
+const bouncy = {damping: 8};
+
+// Heavy, slow motion
+const heavy = {damping: 15, stiffness: 80, mass: 2};
+```
+
+**Easing Functions:**
+
+```tsx
+import {Easing, interpolate, useCurrentFrame} from "remotion";
+
+function EasedMove() {
+  const frame = useCurrentFrame();
+
+  const x = interpolate(frame, [0, 30], [0, 200], {
+    easing: Easing.inOut(Easing.ease),
+    extrapolateRight: "clamp",
+  });
+
+  // Available easings: Easing.in, Easing.out, Easing.inOut
+  // Curves: Easing.ease, Easing.quad, Easing.sin, Easing.exp, Easing.circle
+  // Custom: Easing.bezier(0.25, 0.1, 0.25, 1)
+
+  return <div style={{transform: `translateX(${x}px)`}}>Moving</div>;
+}
+```
+
+**Bad vs. Good:**
+
+```tsx
+// Bad: CSS transitions won't render
+<div className="transition-opacity duration-500 opacity-0 hover:opacity-100">Won't animate</div>
+
+// Bad: Tailwind animation
+<div className="animate-bounce">Won't work</div>
+
+// Good: Frame-driven
+const frame = useCurrentFrame();
+const opacity = interpolate(frame, [0, 30], [0, 1]);
+<div style={{opacity}}>Renders correctly</div>
+```
+
+**Techniques:**
+- useCurrentFrame(): Get current frame number from video composition
+- interpolate(): Map frame ranges to value ranges with extrapolation control
+- spring(): Apply physics-based motion with damping, stiffness, mass
+- Spring presets: smooth, snappy, bouncy, heavy for different effects
+- Easing functions: Apply easing curves (ease, quad, sin, exp, circle, bezier)
+- No CSS transitions: Avoid transition classes, they won't render
+- No Tailwind animations: animate-bounce, etc. won't work in Remotion

package/skills/remotion-guidelines/reference/assets.md

@@ -0,0 +1,21 @@
+# assets: Static Files and Asset Loading
+
+**Guideline:** Use `staticFile()` for local assets in `public/` folder; use Remotion media components `<Img>`, `<Video>`, `<Audio>` that await loading.
+
+**Rationale:** staticFile() ensures correct paths; Remotion components wait for full asset load before rendering (native HTML doesn't).
+
+**Example:**
+```tsx
+<Img src={staticFile("logo.png")} />
+<Video src={staticFile("video.mp4")} style={{width: "100%"}} />
+<Audio src={staticFile("music.mp3")} volume={0.5} />
+const {fontFamily} = loadFont({family: "Custom", url: staticFile("fonts/font.woff2")});
+```
+
+**Techniques:**
+- staticFile("path"): Reference public/ assets; auto-encodes special characters
+- Local assets: Place in public/; organize as images/, videos/, audio/, fonts/
+- Remote URLs: Use directly without staticFile (CORS enabled)
+- Google Fonts: `loadFont()` from @remotion/google-fonts/FontName
+- Custom fonts: Load with @remotion/fonts; measure with measureText()
+- Avoid: Native `<img>`, `<video>`, `<audio>` (don't wait for load)

package/skills/remotion-guidelines/reference/captions.md

@@ -0,0 +1,33 @@
+# filename: captions
+
+**Guideline:** Use `@remotion/captions` with `parseSrt()` for accurate timing; use `createTikTokStyleCaptions()` for word-by-word display.
+
+**Rationale:** SRT parsing is error-prone manually; library handles edge cases; `TikTokStyleCaptions` enables smooth word highlighting matching audio timing.
+
+**Example:**
+```tsx
+function Captions({captions}) {
+  const frame = useCurrentFrame();
+  const {fps} = useVideoConfig();
+  const currentTimeMs = (frame / fps) * 1000;
+
+  const activeCaption = captions.find(
+    (c) => currentTimeMs >= c.startMs && currentTimeMs < c.endMs
+  );
+
+  return activeCaption ? (
+    <div style={{position: "absolute", bottom: 100, fontSize: 48, color: "white"}}>
+      {activeCaption.text}
+    </div>
+  ) : null;
+}
+```
+
+**Techniques:**
+- Parse SRT: `const {captions} = parseSrt({input: srtContent})`; captions have `startMs`, `endMs`, `text`
+- Frame to time: `currentTimeMs = (frame / fps) * 1000`; match against caption range
+- TikTok style: `createTikTokStyleCaptions({captions})` returns pages with tokens (individual words)
+- Word highlighting: Check `isActive` per token; apply color/scale transform on active words
+- Remote SRT: Use `delayRender()`/`continueRender()` for async fetch; load before rendering
+- Styling: Add background, padding, text-shadow for readability; center with `transform: translateX(-50%)`
+- Dynamic timing: Use `spring()` for scale animation on word activation for emphasis effect

package/skills/remotion-guidelines/reference/charts.md

@@ -0,0 +1,35 @@
+# filename: charts
+
+**Guideline:** Build charts with React/SVG; animate with `useCurrentFrame()` + `interpolate()` or `spring()`; disable third-party library animations.
+
+**Rationale:** Remotion controls frame-by-frame timing; library animations bypass frame control; manual rendering ensures sync with audio/video.
+
+**Example:**
+```tsx
+function BarChart({data}) {
+  const frame = useCurrentFrame();
+  const {fps} = useVideoConfig();
+
+  return (
+    <AbsoluteFill style={{backgroundColor: "#1a1a2e"}}>
+      <svg width="100%" height="100%">
+        {data.map((item, i) => {
+          const delay = i * 5;
+          const progress = spring({frame: frame - delay - 10, fps, config: {damping: 18}});
+          const barHeight = (item.value / maxValue) * 300 * progress;
+          return <rect key={i} y={350 - barHeight} height={barHeight} fill={item.color} />;
+        })}
+      </svg>
+    </AbsoluteFill>
+  );
+}
+```
+
+**Techniques:**
+- Bar chart: `spring()` for per-bar stagger; `frame - delay` for sequential animation
+- Pie chart: `interpolate()` for smooth arc fill; use SVG path math for arcs
+- Line chart: SVG path with `strokeDasharray`/`strokeDashoffset` for drawing animation
+- Counter numbers: `interpolate(frame, [0, fps], [0, target])` for smooth count
+- Stagger elements: Use `index * delay` to offset animation start per element
+- Disable library animations: Set `animation: false` in Chart.js; don't use D3 `.transition()`
+- Use `interpolate()` for smooth ranges; `spring()` for bouncy/organic feel

package/skills/remotion-guidelines/reference/compositions.md

@@ -0,0 +1,40 @@
+# filename: compositions
+
+**Guideline:** Define compositions in `Root.tsx` with `type` declarations (not `interface`) and Zod `schema` for visual parameter UI; use `calculateMetadata()` for dynamic values.
+
+**Rationale:** `type` works better with `defaultProps` and Zod inference; schema enables GUI parameter editing; `calculateMetadata` enables dynamic duration/dimensions from props.
+
+**Example:**
+```tsx
+const schema = z.object({
+  title: z.string(),
+  backgroundColor: zColor(),
+  fontSize: z.number().min(10).max(200)
+});
+type Props = z.infer<typeof schema>;
+
+export function RemotionRoot() {
+  return (
+    <Composition<Props>
+      id="MyVideo"
+      component={MyVideo}
+      durationInFrames={300}
+      fps={30}
+      width={1920}
+      height={1080}
+      schema={schema}
+      defaultProps={{title: "Hello", backgroundColor: "#fff", fontSize: 48}}
+    />
+  );
+}
+```
+
+**Techniques:**
+- Composition setup: `id`, `component`, `durationInFrames`, `fps`, `width`, `height` required
+- Type vs interface: Always use `type`, not `interface`; works better with Zod inference
+- Schema UI: `z.object({...})` with `zColor()`, `z.number().min().max()`, `z.enum()` for visual editor
+- Dynamic metadata: `calculateMetadata({props}) => ({durationInFrames: ...})` for async resolution
+- Folder organization: Wrap `<Composition>` in `<Folder name="...">` for grouping
+- Still images: `<Still>` for single frames; no `durationInFrames`/`fps` needed
+- Props inference: Use `z.infer<typeof schema>` for type-safe props
+- defaultProps required: Set sensible defaults for all schema fields

package/skills/remotion-guidelines/reference/dom-measurement.md

@@ -0,0 +1,82 @@
+# dom-measurement: Measuring DOM Elements
+
+**Guideline:** Divide `getBoundingClientRect()` values by `useCurrentScale()` to account for Remotion's scale transforms.
+
+**Rationale:** Remotion applies scale transforms to elements; measurements need correction to reflect actual dimensions at scale 1.
+
+**Example:**
+
+```tsx
+// Without scale correction (wrong)
+const rect = ref.current.getBoundingClientRect();
+const width = rect.width;  // Scaled value
+
+// With scale correction (correct)
+const scale = useCurrentScale();
+const width = rect.width / scale;  // Actual unscaled width
+
+// Full example
+const scale = useCurrentScale();
+const {width: scaled_width, height: scaled_height} = ref.current.getBoundingClientRect();
+return <div>Actual size: {scaled_width / scale} x {scaled_height / scale}</div>;
+```
+
+**Correct Measurement:**
+
+```tsx
+import {useCurrentScale} from "remotion";
+import {useEffect, useRef, useState} from "react";
+
+export function MeasuredComponent() {
+  const ref = useRef<HTMLDivElement>(null);
+  const scale = useCurrentScale();
+  const [dimensions, setDimensions] = useState({width: 0, height: 0});
+
+  useEffect(() => {
+    if (!ref.current) return;
+
+    const rect = ref.current.getBoundingClientRect();
+    setDimensions({
+      width: rect.width / scale,
+      height: rect.height / scale,
+    });
+  }, [scale]);
+
+  return (
+    <div ref={ref}>
+      Content to measure ({dimensions.width}x{dimensions.height})
+    </div>
+  );
+}
+```
+
+**Outline vs Border:** Outline doesn't affect layout; border does at different scales.
+
+```tsx
+function PositionedElement() {
+  const ref = useRef<HTMLDivElement>(null);
+  const scale = useCurrentScale();
+  const [position, setPosition] = useState({x: 0, y: 0});
+
+  useEffect(() => {
+    if (!ref.current) return;
+
+    const rect = ref.current.getBoundingClientRect();
+    setPosition({
+      x: rect.left / scale,
+      y: rect.top / scale,
+    });
+  }, [scale]);
+
+  return <div ref={ref}>Element at ({position.x}, {position.y})</div>;
+}
+```
+
+**Techniques:**
+- useCurrentScale(): Get scale factor applied by Remotion
+- Divide measurements: width/scale, height/scale for correct values
+- useEffect hook: Measure elements after mount with scale dependency
+- outline vs border: Use outline to avoid layout shifts at different scales
+- getBoundingClientRect(): Get left, top, width, height of element
+- useRef: Store reference to DOM element for measurement
+- Sync with scale: Update measurements when scale changes

package/skills/remotion-guidelines/reference/gifs.md

@@ -0,0 +1,33 @@
+# gifs: Animated Images (GIF, APNG, WebP, AVIF)
+
+**Guideline:** Use `<AnimatedImage>` for frame-synchronized playback of animated images.
+
+**Rationale:** Native img tags don't sync with Remotion's timeline. `<AnimatedImage>` provides proper frame synchronization and playback control.
+
+**Example:**
+```tsx
+import { AnimatedImage, staticFile, Composition } from 'remotion'
+
+export const MyComposition = () => (
+  <Composition>
+    <AnimatedImage
+      src={staticFile('animation.gif')}
+      width={1920}
+      height={1080}
+      playbackRate={1}
+      loop
+      fit="contain"
+    />
+  </Composition>
+)
+```
+
+**Techniques:**
+- Import `AnimatedImage` and `staticFile` from `remotion` package
+- Set explicit `width` and `height` props for proper sizing and rendering
+- Use `staticFile()` for local assets, remote URLs with CORS headers
+- Control playback speed with `playbackRate` prop (0.5 = half, 2 = double)
+- Set loop behavior: `loop` (default), `pause-after-finish`, or `clear-after-finish`
+- Choose sizing mode: `fit="fill"` (stretch), `fit="contain"` (aspect-ratio), `fit="cover"` (crop)
+- Get GIF duration with `getGifDurationInSeconds()` for dynamic composition length
+- Apply CSS styles: borderRadius, position, opacity, filters

package/skills/remotion-guidelines/reference/lottie.md

@@ -0,0 +1,41 @@
+# lottie: Lottie Animations
+
+**Guideline:** Use `delayRender()` pattern to load Lottie JSON before rendering compositions.
+
+**Rationale:** Animations must load asynchronously. `delayRender()` pauses frame rendering until `continueRender()` is called after JSON loads.
+
+**Example:**
+```tsx
+import { Lottie, useVideoConfig } from '@remotion/lottie'
+import { delayRender, continueRender } from 'remotion'
+
+const handle = delayRender()
+
+export const MyAnimation = () => {
+  const [animData, setAnimData] = useState<LottieAnimationData | null>(null)
+  const { fps } = useVideoConfig()
+
+  useEffect(() => {
+    fetch('https://lottiefiles.com/animations/123.json')
+      .then(r => r.json())
+      .then(data => {
+        setAnimData(data)
+        continueRender(handle)
+      })
+      .catch(err => cancelRender(err))
+  }, [handle])
+
+  return animData ? <Lottie animationData={animData} /> : null
+}
+```
+
+**Techniques:**
+- Install `@remotion/lottie` package before use
+- Call `delayRender()` to pause frame rendering while loading
+- Fetch animation JSON from remote (Lottie Files) or local with `staticFile()`
+- Store fetched JSON in state with `useState<LottieAnimationData | null>()`
+- Call `continueRender(handle)` when JSON loaded successfully
+- Call `cancelRender(err)` if fetch fails to report error
+- Return null while loading to prevent rendering with undefined data
+- Pass animation data to `<Lottie animationData={...} />` component
+- Apply width/height styles via style props

package/skills/remotion-guidelines/reference/maps.md

@@ -0,0 +1,26 @@
+# maps: Map Animations with Mapbox
+
+**Guideline:** Disable Mapbox animations (fadeDuration: 0, interactive: false); control camera/lines via Remotion frames; use turf.js for route.
+
+**Rationale:** Mapbox animations conflict with frame-by-frame rendering; Remotion frame control ensures deterministic animation.
+
+**Example:**
+```tsx
+const _map = new Map({
+  container: ref.current!,
+  interactive: false,  // CRITICAL
+  fadeDuration: 0,     // CRITICAL
+  zoom: 11.53,
+  center: [6.5615, 46.0598],
+});
+// Animate with: turf.along(lineString, distance * progress)
+```
+
+**Techniques:**
+- Map config: interactive: false, fadeDuration: 0 disable Mapbox animations
+- delayRender/continueRender: Wait for map.load and camera.idle events
+- turf.js: Route distance, lineSliceAlong for curved animation
+- Add GeoJSON sources for lines, markers, labels
+- Free camera: Use getFreeCameraOptions(), lookAtPoint() for control
+- Render: --gl=angle --concurrency=1 for Mapbox stability
+- Performance: Hide unwanted features with setConfigProperty("basemap", name, false)

package/skills/remotion-guidelines/reference/media.md

@@ -0,0 +1,39 @@
+# media: Audio and Video Manipulation
+
+**Guideline:** Use `<Audio>` and `<Video>` from Remotion for frame-synchronized playback.
+
+**Rationale:** Native HTML elements don't sync properly with Remotion's timeline. Remotion components provide frame-synchronized playback control.
+
+**Example:**
+```tsx
+import { Video, Audio, useVideoConfig } from 'remotion'
+
+export const MediaComposition = () => {
+  const { fps } = useVideoConfig()
+
+  return (
+    <>
+      <Video
+        src="video.mp4"
+        startFrom={fps * 2}  // Start at 2 seconds
+        endAt={fps * 10}     // End at 10 seconds
+        playbackRate={1}
+        volume={0.8}
+        style={{ width: '100%', height: '100%' }}
+      />
+      <Audio src="audio.mp3" volume={0.5} />
+    </>
+  )
+}
+```
+
+**Techniques:**
+- Import `Audio` and `Video` from `remotion` for frame-synced playback
+- Use `staticFile()` for local media files, remote URLs for external sources
+- Set static volume with number (0-1 range) or dynamic with callback function
+- Trim playback: `startFrom` and `endAt` props in frames (use `fps` for seconds)
+- Control speed with `playbackRate` prop (0.5 = half speed, 2 = double speed)
+- Enable looping with `loop` prop for indefinite repetition
+- Create fade effects with `interpolate()` and frame-based callbacks
+- Get media duration with `getVideoDuration()` or `getAudioDuration()` in calculateMetadata
+- Apply CSS styles: width, height, position, opacity, filters

package/skills/remotion-guidelines/reference/mediabunny.md

@@ -0,0 +1,28 @@
+# mediabunny: Media Metadata and Frame Extraction
+
+**Guideline:** Use Mediabunny for video/audio duration, dimensions, and frame extraction; check decode compatibility before playback.
+
+**Rationale:** Duration enables accurate durationInFrames; decode checks prevent runtime failures with unsupported codecs.
+
+**Example:**
+```tsx
+import {getVideoDuration, getVideoDimensions} from "mediabunny";
+
+calculateMetadata: async ({props}) => {
+  const duration = await getVideoDuration(props.videoUrl);
+  const {width, height} = await getVideoDimensions(props.videoUrl);
+  return {
+    durationInFrames: Math.ceil(duration * 30),
+    width, height
+  };
+}
+```
+
+**Techniques:**
+- getVideoDuration(): Returns seconds; multiply by fps for frames
+- getAudioDuration(): For audio files
+- getVideoDimensions(): Returns {width, height} for dynamic sizing
+- canDecode(): Check Input + getPrimaryVideoTrack/Audio before playback
+- extractFrames(): Sample frames at specific timestamps using VideoSampleSink
+- Filmstrip: Calculate timestamps based on duration and desired grid spacing
+- Cancellation: Pass signal: controller.signal for AbortSignal support

package/skills/remotion-guidelines/reference/sequencing.md

@@ -0,0 +1,44 @@
+# sequencing: Sequencing and Scene Orchestration
+
+**Guideline:** Use `<Sequence>` for timed playback with local frame context and `premountFor` to prevent pop-in.
+
+**Rationale:** Sequences provide local frame context reset and timing control. `premountFor` preloads components early to avoid rendering artifacts.
+
+**Example:**
+```tsx
+import { Sequence, Series, useCurrentFrame, useVideoConfig } from 'remotion'
+
+export const MyComposition = () => {
+  const { fps } = useVideoConfig()
+
+  return (
+    <Series>
+      <Series.Sequence durationInFrames={2 * fps}>
+        <Scene1 />
+      </Series.Sequence>
+      <Series.Sequence durationInFrames={3 * fps} offset={-0.5 * fps}>
+        <Scene2 />  {/* Overlaps with Scene1 by 0.5 sec */}
+      </Series.Sequence>
+      <Series.Sequence durationInFrames={2 * fps}>
+        <Scene3 />
+      </Series.Sequence>
+    </Series>
+  )
+}
+
+const Scene1 = () => {
+  const frame = useCurrentFrame()  // Starts at 0 in this Sequence
+  return <div style={{ opacity: frame / 30 }} />
+}
+```
+
+**Techniques:**
+- Use `<Sequence>` to show/hide components at specific frame ranges
+- Set `from` prop for start frame (calculate with `fps`: `1.5 * fps` for 1.5 seconds)
+- Set `durationInFrames` for length in frames (calculate with `fps`: `2 * fps` for 2 seconds)
+- Enable `premountFor` to preload components early and avoid rendering pop-in
+- Use `layout="none"` to skip AbsoluteFill wrapper for flex/grid/canvas layouts
+- Remember `useCurrentFrame()` returns local frame context within Sequence (starts at 0)
+- Use `<Series>` for automatic sequential timing of multiple scenes
+- Create overlaps with `offset` prop on Series.Sequence (negative value for overlap)
+- Nest Sequences for complex timing and layered compositions

package/skills/remotion-guidelines/reference/text.md

@@ -0,0 +1,24 @@
+# text: Text and Typography
+
+**Guideline:** Load fonts first; use measureText() for dimensions; fitText() to auto-scale; animate with frame-based calculations.
+
+**Rationale:** Font loading is async; measuring text enables precise layout; frame-based animation ensures consistent timing.
+
+**Example:**
+```tsx
+import {loadFont} from "@remotion/google-fonts/Roboto";
+import {measureText, fitText} from "@remotion/layout-utils";
+
+const {fontFamily} = loadFont(); // Google Font
+const {width} = measureText({text: "Hello", fontFamily, fontSize: 48});
+const {fontSize} = fitText({text, withinWidth: 500, fontFamily});
+```
+
+**Techniques:**
+- Google Fonts: `loadFont()` from @remotion/google-fonts/FontName
+- Local fonts: `loadFont({family, url: staticFile(), weight})`
+- measureText(): Returns {width, height}; use validateFontIsLoaded: true
+- fitText(): Auto-scale fontSize to fit container width
+- Typewriter: `Math.floor(frame / fps * charsPerSecond)` to slice text
+- Word highlight: spring() to animate background scaleX across word
+- Stagger reveal: Delay each element by `index * delaySeconds * fps`

package/skills/remotion-guidelines/reference/three-d.md

@@ -0,0 +1,33 @@
+# three-d: 3D Content with Three.js
+
+**Guideline:** Use ThreeCanvas (not react-three-fiber Canvas); animate with useCurrentFrame, not useFrame(); use layout="none" in Sequences.
+
+**Rationale:** useFrame() updates real-time, not frame-perfect; Remotion requires frame-based deterministic animation.
+
+**Example:**
+```tsx
+import {ThreeCanvas} from "@remotion/three";
+import {useCurrentFrame, useVideoConfig} from "remotion";
+
+function RotatingCube() {
+  const frame = useCurrentFrame();
+  const {fps} = useVideoConfig();
+  const rotation = (frame / (2 * fps)) * Math.PI * 2;
+  return (
+    <mesh rotation={[0, rotation, 0]}>
+      <boxGeometry args={[1, 1, 1]} />
+      <meshStandardMaterial color="orange" />
+    </mesh>
+  );
+}
+```
+
+**Techniques:**
+- ThreeCanvas: Remotion-specific wrapper (not R3F Canvas)
+- useCurrentFrame() + fps: Calculate frame-based transforms (rotation, position)
+- interpolate(): Linear motion and camera movement
+- spring(): Bouncing and physics-based animation with config {damping, stiffness}
+- PerspectiveCamera: Animate position/lookAt with useCurrentFrame
+- Sequence layout="none": Required for ThreeCanvas (default layout breaks 3D)
+- Lighting: ambientLight (base), directionalLight (shadows), pointLight (highlights)
+- Stagger: Use `frame - (index * fps * delay)` for sequenced objects

package/skills/remotion-guidelines/reference/timing.md

@@ -0,0 +1,22 @@
+# timing: Timing and Frame Calculations
+
+**Guideline:** Always write durations as seconds multiplied by fps for consistency; use interpolate with frame ranges, not time.
+
+**Rationale:** Seconds * fps pattern is clear and frame-accurate; consistent approach prevents calculation errors.
+
+**Example:**
+```tsx
+const frame = useCurrentFrame();
+const {fps} = useVideoConfig();
+const startFrame = 1 * fps;        // 1 second
+const fadeIn = interpolate(frame, [0, 0.5 * fps], [0, 1], {extrapolateLeft: "clamp"});
+```
+
+**Techniques:**
+- Pattern: `seconds * fps` for all durations (0.1 * fps = 100ms, 1 * fps = 1s)
+- interpolate() ranges in frames: [startFrame, endFrame] not seconds
+- Composition: durationInFrames = totalSeconds * fps
+- Stagger delays: index * delaySeconds * fps
+- Visibility check: frame >= startFrame && frame < endFrame
+- Extrapolation: Use extrapolateLeft/extrapolateRight to clamp values at edges
+- Common: Flash 0.1s, fade 0.5s, transitions 1-2s