@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/remotion-motion-graphics/references/scaffold.md

@@ -0,0 +1,144 @@
+# Scaffolding a Remotion project
+
+Use this when the target folder has no Remotion project yet. The result should be a
+clean, neutral, working starting point — **not** a finished style. The user will take
+the visual direction themselves; your job is to remove every obstacle between them and
+that work, and to leave nothing broken or half-wired.
+
+## 1. Initialize
+
+Create a Remotion + TypeScript project in the target folder using the latest Remotion,
+then install and verify it actually runs before moving on. A scaffold that was never
+executed usually has one wrong path in it.
+
+If the folder is empty, the fastest route is the official template:
+
+```bash
+npx create-video@latest . --template blank
+npm install
+```
+
+Then add what the project needs beyond the bare template: `zod` and `@remotion/zod-types`
+(schemas + color pickers in the Studio), `@remotion/google-fonts` or `@remotion/fonts`,
+and `@remotion/transitions` if scenes will cut between each other. Keep every
+`@remotion/*` package on the same version as `remotion` itself — mismatched versions
+produce confusing runtime errors.
+
+## 2. Structure
+
+```
+src/
+  Root.tsx           registers every composition
+  config.ts          shared canvas settings (size, fps) + helpers
+  tokens.ts          brand: colors, radii, spacing (if the user has a brand)
+  fonts.ts           font loading, exports FONT_FAMILY
+  compositions/      one file per graphic
+public/              fonts, images, audio (reached via staticFile())
+out/                 renders (gitignore this)
+```
+
+`out/` and `node_modules/` belong in `.gitignore`. Renders are large and regenerable.
+
+## 3. Canvas config in one place
+
+Resolution and fps live in a single module so the user can switch to 4K or 60fps without
+touching any composition. Default to 1920×1080 at 30fps unless the user's format says
+otherwise (vertical/Reels/TikTok → 1080×1920).
+
+```ts
+// src/config.ts
+export const CANVAS = {
+  width: 1920,
+  height: 1080,
+  fps: 30,
+} as const;
+
+/** Convert seconds to frames at the project frame rate. */
+export const sec = (seconds: number): number => Math.round(seconds * CANVAS.fps);
+
+/** Title-safe margin (5% each side). Keep text inside this so crops don't eat it. */
+export const SAFE_MARGIN = 0.05;
+```
+
+This only pays off if compositions actually use it: size content relative to the canvas
+via `useVideoConfig()`, and express timings in seconds via `sec()`. A composition with
+`fontSize: 72` and `durationInFrames: 150` hardcoded breaks the moment the canvas
+changes, which defeats the point of having the config.
+
+## 4. Four starter compositions
+
+Keep them minimal — the user is going to design their own look, and elaborate starter
+styling is something they have to delete first. Each one demonstrates a technique and
+each one has a clean enter **and** exit so nothing pops or gets cut mid-animation:
+
+| Composition | Demonstrates |
+|---|---|
+| `TitleCard` | Full-frame text, staggered entrance, eased exit |
+| `LowerThird` | Name + role, slide from edge, title-safe placement |
+| `KineticText` | Per-word/per-character animation with springs and stagger |
+| `BadgeOverlay` | **Transparent background** — real alpha channel for editors |
+
+Every one gets a zod schema + `defaultProps` so the user can edit values live in the
+Studio without touching code. Use `zColor()` from `@remotion/zod-types` for colors —
+it renders a real color picker in the Studio instead of a text field.
+
+`BadgeOverlay` is the one that's easy to get wrong: it must paint **no** background at
+all. Its `<AbsoluteFill>` carries no `backgroundColor`. In the Studio you should see a
+checkerboard behind it — that's the proof the alpha channel is intact. See
+`patterns.md` for the full working component.
+
+## 5. Register everything in Root.tsx
+
+```tsx
+import {Composition} from 'remotion';
+import {CANVAS, sec} from './config';
+
+export const Root: React.FC = () => (
+  <>
+    <Composition
+      id="TitleCard"
+      component={TitleCard}
+      durationInFrames={sec(5)}
+      fps={CANVAS.fps}
+      width={CANVAS.width}
+      height={CANVAS.height}
+      schema={titleCardSchema}
+      defaultProps={titleCardDefaultProps}
+    />
+    {/* ...one per graphic */}
+  </>
+);
+```
+
+## 6. Scripts
+
+```json
+{
+  "scripts": {
+    "studio": "remotion studio",
+    "render": "remotion render",
+    "typecheck": "tsc --noEmit",
+    "upgrade": "remotion upgrade"
+  }
+}
+```
+
+## 7. README
+
+The README is what the user reads at 11pm three weeks from now, so write it for that
+moment. It covers:
+
+- **Preview**: `npm run studio`
+- **Adding a graphic**: create the component in `src/compositions/`, register it in
+  `Root.tsx` with a unique id, fps/size, zod schema and defaultProps
+- **Render commands**: the four from SKILL.md (MP4, transparent ProRes, PNG sequence,
+  still) — spelled out and copy-pasteable
+- **Tips**: keep text in the title-safe area; give every animation a full enter and exit;
+  trim leading silence from sound effects so hits land on frame; check a still before
+  committing to a full render
+
+## 8. Finish the job
+
+Launch the Studio, then summarize what you built and the two or three commands the user
+will actually use most. Don't recite the file tree back at them — they can see it. Tell
+them what to do next.

package/skills/remotion-motion-graphics/references/traps.md

@@ -0,0 +1,152 @@
+# Remotion traps
+
+Every bug here was found the expensive way — by someone reading code carefully, or by
+staring at a wrong render. They share a nasty property: **the code looks right and
+nothing throws.** You only find out when the number is wrong, the alpha is gone, or a
+glow is sitting on screen from frame 0.
+
+Check this list against any composition you write or touch. It's faster than rediscovering
+them.
+
+## interpolate defaults to 'extend', not 'clamp'
+
+The single most damaging one, because it silently corrupts *data*.
+
+```tsx
+// A counter that should land on 12400 over 60 frames:
+const value = interpolate(frame, [0, 60], [0, 12400]);
+```
+
+In a 150-frame composition this does not stop at 12400. The default
+`extrapolateRight: 'extend'` keeps the line going: at frame 149 it reads **30793**. The
+headline stat on your graphic is simply wrong, and it looks completely intentional.
+
+Always clamp frame-driven interpolate:
+
+```tsx
+const value = interpolate(frame, [0, 60], [0, 12400], {
+  extrapolateLeft: 'clamp',
+  extrapolateRight: 'clamp',
+});
+```
+
+**But do not clamp a spring remap.** `interpolate(springProgress, [0, 1], [-100, 0])`
+should stay unclamped — the spring's overshoot past 1 is exactly the elasticity you asked
+for, and clamping flattens it back into robotic motion. Rule of thumb: interpolating
+`frame` → clamp. Interpolating a spring's output → don't.
+
+## extrapolateLeft: 'clamp' makes effects visible from frame 0
+
+Subtle and very easy to ship.
+
+```tsx
+// Intent: a ring that expands at the payoff, around frame 72.
+const ring = interpolate(frame, [72, 90], [0, 1], {extrapolateLeft: 'clamp'});
+```
+
+Clamping left pins frames 0–71 to the *start value of the range* — which is `0` here, fine
+— but the moment your range starts at a visible value:
+
+```tsx
+const flash = interpolate(frame, [72, 80], [1, 0], {extrapolateLeft: 'clamp'});
+```
+
+…frames 0–71 all read `1`. The flash sits on screen, at full strength, from the first
+frame of the clip. Gate payoff effects explicitly on their window instead of relying on
+clamping:
+
+```tsx
+const inWindow = frame >= 72;
+const flash = inWindow ? interpolate(frame, [72, 80], [1, 0], {extrapolateRight: 'clamp'}) : 0;
+```
+
+## A backgroundColor anywhere on the root kills the alpha channel
+
+For overlays, the root `<AbsoluteFill>` must paint nothing. Inner shapes can be opaque —
+that's the badge itself. But one `backgroundColor` on the outer fill and your ProRes 4444
+export arrives in Premiere with a black box behind it, and the render gave no warning.
+
+The Studio's checkerboard is the proof. Check it before you render, not after.
+
+## remotion.config.ts defaults to JPEG, which has no alpha
+
+Even with a correctly transparent composition, this silently flattens it:
+
+```ts
+// remotion.config.ts
+Config.setVideoImageFormat('jpeg');  // ← destroys transparency project-wide
+```
+
+Set `'png'` for any project that produces overlays. This one is especially cruel because
+the composition is right, the render command is right, and the output is still wrong.
+
+## Hooks inside .map() break the moment props change
+
+```tsx
+{words.map((word, i) => {
+  const enter = spring({frame: frame - i * 3, fps});  // ← hook inside a loop
+  return <span key={word} style={{opacity: enter}}>{word}</span>;
+})}
+```
+
+`spring()` is a hook. Calling it inside `.map()` means the hook count changes when the
+array length changes — so the first time the user edits the text in the Studio, React
+throws. Extract a child component:
+
+```tsx
+const Word: React.FC<{word: string; index: number}> = ({word, index}) => {
+  const frame = useCurrentFrame();
+  const {fps} = useVideoConfig();
+  const enter = spring({frame: frame - index * 3, fps});
+  return <span style={{opacity: enter, display: 'inline-block'}}>{word}</span>;
+};
+```
+
+## scaleX on a panel stretches the text inside it
+
+Opening a lower-third plate with `transform: scaleX()` also scales its children —
+the name comes out horizontally squashed during the reveal. Use `clip-path` instead,
+which reveals without distorting:
+
+```tsx
+clipPath: `inset(0 ${(1 - reveal) * 100}% 0 0)`
+```
+
+Same trap with `scaleY` on anything containing text.
+
+## Positioned elements paint over non-positioned ones, regardless of DOM order
+
+```tsx
+<AbsoluteFill>              {/* background layer — position: absolute */}
+  <div>…background…</div>
+</AbsoluteFill>
+<div>…your title…</div>     {/* static — paints UNDER the absolute layer */}
+```
+
+The title is invisible and the DOM order says it shouldn't be. Give the content block
+`position: 'relative'` (or its own `<AbsoluteFill>`) so it participates in the same
+stacking context.
+
+## transform does nothing on inline elements
+
+`<span>` is inline by default, so `transform: translateY(...)` is silently ignored — your
+staggered word entrance just fades with no movement, and nothing errors. Add
+`display: 'inline-block'`.
+
+## Mismatched @remotion/* versions
+
+Every `@remotion/*` package must sit on the same version as `remotion` itself. Mismatches
+surface as confusing runtime errors that look like your code's fault.
+
+## fonts.ts pointing at a font that isn't there
+
+`loadFont()` against `staticFile('fonts/Whatever.otf')` with no `public/fonts/` directory
+fails at render time — or, if the module is never imported, does nothing at all while you
+believe the brand font is applied. Renders come out in the fallback face and it's easy to
+miss on a small preview. Confirm the file exists before trusting the type.
+
+## Proportional digits jitter while counting
+
+A counter animating through values visibly wobbles as digit widths change. Add
+`fontVariantNumeric: 'tabular-nums'`. Costs nothing, and its absence is the kind of thing
+that reads as "cheap" without the viewer being able to say why.