gitreel 0.1.0

package/dist/engine/scenes/TerminalScene.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { interpolate, useCurrentFrame } from "remotion";
+import { FPS, theme } from "../theme";
+import { Panel, SceneShell } from "./SceneShell";
+export const TerminalScene = ({ kicker, title, command, output, fontSize = 30, outputAtSecond = 0.8, highlightPattern }) => {
+    const frame = useCurrentFrame();
+    const typedChars = Math.floor(interpolate(frame, [4, outputAtSecond * FPS - 4], [0, command.length], {
+        extrapolateLeft: "clamp",
+        extrapolateRight: "clamp",
+    }));
+    const outputLines = output.replace(/\n$/, "").split("\n");
+    return (_jsx(SceneShell, { kicker: kicker, title: title, center: true, children: _jsxs(Panel, { padding: 0, children: [_jsxs("div", { style: {
+                        display: "flex",
+                        gap: 10,
+                        padding: "18px 24px",
+                        borderBottom: `1px solid ${theme.stroke}`,
+                        alignItems: "center",
+                    }, children: [[theme.red, theme.amber, theme.green].map((color, i) => (_jsx("span", { style: { width: 18, height: 18, borderRadius: "50%", backgroundColor: color } }, i))), _jsx("span", { style: { fontFamily: theme.fontMono, fontSize: 22, color: theme.textDim, marginLeft: 14 }, children: "terminal" })] }), _jsxs("div", { style: { padding: 36, fontFamily: theme.fontMono, fontSize, lineHeight: 1.6 }, children: [_jsxs("div", { style: { color: theme.text }, children: [_jsx("span", { style: { color: theme.green }, children: "\u276F " }), command.slice(0, typedChars), typedChars < command.length && _jsx("span", { style: { color: theme.accent2 }, children: "\u258C" })] }), _jsx("div", { style: { marginTop: 16 }, children: outputLines.map((line, i) => {
+                                const at = outputAtSecond * FPS + i * 2;
+                                const appear = interpolate(frame, [at, at + 5], [0, 1], {
+                                    extrapolateLeft: "clamp",
+                                    extrapolateRight: "clamp",
+                                });
+                                const highlighted = highlightPattern?.test(line) ?? false;
+                                return (_jsx("div", { style: {
+                                        opacity: appear,
+                                        whiteSpace: "pre",
+                                        color: highlighted ? theme.accent2 : theme.text,
+                                        fontWeight: highlighted ? 700 : 400,
+                                    }, children: line.length === 0 ? " " : line }, i));
+                            }) })] })] }) }));
+};

package/dist/engine/scenes/TitleCard.d.ts

@@ -0,0 +1,10 @@
+import React from "react";
+export declare const TitleCard: React.FC<{
+    chip?: string;
+    words: readonly string[];
+    subtitle?: string;
+}>;
+export declare const Pop: React.FC<{
+    at: number;
+    children: React.ReactNode;
+}>;

package/dist/engine/scenes/TitleCard.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { AbsoluteFill, spring, useCurrentFrame, useVideoConfig } from "remotion";
+import { theme } from "../theme";
+import { SceneShell } from "./SceneShell";
+export const TitleCard = ({ chip, words, subtitle }) => {
+    const frame = useCurrentFrame();
+    const { fps } = useVideoConfig();
+    return (_jsx(SceneShell, { center: true, children: _jsxs(AbsoluteFill, { style: { display: "flex", justifyContent: "center", alignItems: "center", flexDirection: "column" }, children: [chip && (_jsx(Pop, { at: 0, children: _jsx("span", { style: {
+                            fontFamily: theme.fontMono,
+                            fontSize: 30,
+                            color: theme.accent2,
+                            border: `2px solid ${theme.accent2}55`,
+                            borderRadius: 999,
+                            padding: "8px 28px",
+                            marginBottom: 40,
+                            display: "inline-block",
+                        }, children: chip }) })), _jsx("div", { style: { display: "flex", gap: 28, flexWrap: "wrap", justifyContent: "center", maxWidth: 1500 }, children: words.map((word, i) => {
+                        const pop = spring({ frame: frame - 6 - i * 5, fps, config: { damping: 13, stiffness: 160, mass: 0.6 } });
+                        return (_jsx("span", { style: {
+                                fontFamily: theme.fontDisplay,
+                                fontWeight: 800,
+                                fontSize: 120,
+                                color: i === words.length - 1 ? theme.accent : theme.text,
+                                transform: `scale(${pop}) rotate(${(1 - pop) * (i % 2 === 0 ? -4 : 4)}deg)`,
+                                display: "inline-block",
+                            }, children: word }, i));
+                    }) }), subtitle && (_jsx(Pop, { at: 14 + words.length * 5, children: _jsx("div", { style: { fontFamily: theme.fontDisplay, fontSize: 38, color: theme.textDim, marginTop: 36 }, children: subtitle }) }))] }) }));
+};
+export const Pop = ({ at, children }) => {
+    const frame = useCurrentFrame();
+    const { fps } = useVideoConfig();
+    const pop = spring({ frame: frame - at, fps, config: { damping: 14, stiffness: 150, mass: 0.6 } });
+    return _jsx("div", { style: { transform: `scale(${pop})`, opacity: Math.min(1, pop * 1.4) }, children: children });
+};

package/dist/engine/scenes/VerdictCard.d.ts

@@ -0,0 +1,13 @@
+import React from "react";
+import { type Severity } from "../theme";
+export type VerdictCount = {
+    readonly severity: Severity;
+    readonly count: number;
+    readonly label: string;
+};
+export declare const VerdictCard: React.FC<{
+    counts: readonly VerdictCount[];
+    stamp: string;
+    stampColor?: string;
+    stampAtSecond?: number;
+}>;

package/dist/engine/scenes/VerdictCard.js

@@ -0,0 +1,44 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Audio, Sequence, spring, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+import { FPS, severityColor, theme } from "../theme";
+import { SceneShell } from "./SceneShell";
+export const VerdictCard = ({ counts, stamp, stampColor = theme.green, stampAtSecond = 1.6 }) => {
+    const frame = useCurrentFrame();
+    const { fps } = useVideoConfig();
+    const stampFrame = stampAtSecond * FPS;
+    const stampPop = spring({ frame: frame - stampFrame, fps, config: { damping: 11, stiffness: 230, mass: 0.8 } });
+    return (_jsxs(SceneShell, { kicker: "the verdict", center: true, children: [_jsx("div", { style: { display: "flex", gap: 40, marginBottom: 80 }, children: counts.map((entry, i) => {
+                    const pop = spring({ frame: frame - 6 - i * 7, fps, config: { damping: 14, stiffness: 170, mass: 0.6 } });
+                    const color = severityColor[entry.severity];
+                    return (_jsxs("div", { style: {
+                            width: 330,
+                            backgroundColor: theme.bgPanel,
+                            border: `2px solid ${color}55`,
+                            borderTop: `8px solid ${color}`,
+                            borderRadius: 18,
+                            padding: "34px 30px",
+                            textAlign: "center",
+                            transform: `scale(${pop})`,
+                            opacity: pop,
+                        }, children: [_jsx("div", { style: { fontFamily: theme.fontDisplay, fontWeight: 800, fontSize: 96, color }, children: entry.count }), _jsx("div", { style: {
+                                    fontFamily: theme.fontDisplay,
+                                    fontWeight: 600,
+                                    fontSize: 28,
+                                    letterSpacing: 2,
+                                    color: theme.textDim,
+                                    textTransform: "uppercase",
+                                }, children: entry.label })] }, i));
+                }) }), frame >= stampFrame && (_jsx(Sequence, { from: Math.round(stampFrame), name: "stamp-thud", children: _jsx(Audio, { src: staticFile("sfx/thud.wav"), volume: 0.6 }) })), _jsx("div", { style: {
+                    fontFamily: theme.fontDisplay,
+                    fontWeight: 900,
+                    fontSize: 110,
+                    letterSpacing: 6,
+                    color: stampColor,
+                    border: `10px solid ${stampColor}`,
+                    borderRadius: 24,
+                    padding: "10px 60px",
+                    transform: `rotate(-7deg) scale(${0.6 + stampPop * 0.4})`,
+                    opacity: stampPop,
+                    textShadow: `0 0 60px ${stampColor}66`,
+                }, children: stamp })] }));
+};

package/dist/engine/theme.d.ts

@@ -0,0 +1,20 @@
+export declare const FPS = 30;
+export declare const theme: {
+    readonly bg: "#0b0d12";
+    readonly bgPanel: "#11141d";
+    readonly bgCode: "#0d1017";
+    readonly stroke: "#252b3d";
+    readonly text: "#e9edf5";
+    readonly textDim: "#8b94aa";
+    readonly accent: "#8b5cf6";
+    readonly accent2: "#22d3ee";
+    readonly green: "#34d399";
+    readonly red: "#fb7185";
+    readonly amber: "#fbbf24";
+    readonly grey: "#7a8194";
+    readonly fontDisplay: "'Avenir Next', 'Helvetica Neue', Helvetica, Arial, sans-serif";
+    readonly fontMono: "'SF Mono', Menlo, 'Cascadia Code', Consolas, monospace";
+};
+export type Severity = "blocking" | "warn" | "nit";
+export declare const severityColor: Record<Severity, string>;
+export declare const severityLabel: Record<Severity, string>;

package/dist/engine/theme.js

@@ -0,0 +1,27 @@
+export const FPS = 30;
+export const theme = {
+    bg: "#0b0d12",
+    bgPanel: "#11141d",
+    bgCode: "#0d1017",
+    stroke: "#252b3d",
+    text: "#e9edf5",
+    textDim: "#8b94aa",
+    accent: "#8b5cf6",
+    accent2: "#22d3ee",
+    green: "#34d399",
+    red: "#fb7185",
+    amber: "#fbbf24",
+    grey: "#7a8194",
+    fontDisplay: "'Avenir Next', 'Helvetica Neue', Helvetica, Arial, sans-serif",
+    fontMono: "'SF Mono', Menlo, 'Cascadia Code', Consolas, monospace",
+};
+export const severityColor = {
+    blocking: theme.red,
+    warn: theme.amber,
+    nit: theme.grey,
+};
+export const severityLabel = {
+    blocking: "BLOCKING",
+    warn: "WORTH A LOOK",
+    nit: "NIT",
+};

package/dist/engine/timeline.d.ts

@@ -0,0 +1,25 @@
+import React from "react";
+export type SceneSpec = {
+    id: string;
+    element: React.ReactNode;
+    extraSeconds?: number;
+    fixedSeconds?: number;
+    sfx?: string;
+    sfxVolume?: number;
+};
+export type NarrationManifest = {
+    voice: string;
+    scenes: Record<string, {
+        seconds: number;
+        text: string;
+    }>;
+};
+export declare function sceneDurationInFrames(spec: SceneSpec, manifest: NarrationManifest): number;
+export declare function totalDurationInFrames(specs: readonly SceneSpec[], manifest: NarrationManifest): number;
+export declare const Timeline: React.FC<{
+    episodeId: string;
+    scenes: readonly SceneSpec[];
+    manifest: NarrationManifest;
+    music?: string;
+    musicVolume?: number;
+}>;

package/dist/engine/timeline.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { AbsoluteFill, Audio, Sequence, staticFile } from "remotion";
+import { FPS, theme } from "./theme";
+const NARRATION_START_PAD_SECONDS = 0.25;
+const DEFAULT_TAIL_SECONDS = 0.5;
+export function sceneDurationInFrames(spec, manifest) {
+    if (spec.fixedSeconds !== undefined) {
+        return Math.round(spec.fixedSeconds * FPS);
+    }
+    const narration = manifest.scenes[spec.id]?.seconds ?? 1.5;
+    const total = NARRATION_START_PAD_SECONDS + narration + (spec.extraSeconds ?? DEFAULT_TAIL_SECONDS);
+    return Math.round(total * FPS);
+}
+export function totalDurationInFrames(specs, manifest) {
+    return specs.reduce((sum, spec) => sum + sceneDurationInFrames(spec, manifest), 0);
+}
+export const Timeline = ({ episodeId, scenes, manifest, music, musicVolume }) => {
+    let cursor = 0;
+    const sequences = scenes.map((spec) => {
+        const duration = sceneDurationInFrames(spec, manifest);
+        const from = cursor;
+        cursor += duration;
+        const hasNarration = manifest.scenes[spec.id] !== undefined && spec.fixedSeconds === undefined;
+        return (_jsxs(Sequence, { from: from, durationInFrames: duration, name: spec.id, children: [hasNarration && (_jsx(Sequence, { from: Math.round(NARRATION_START_PAD_SECONDS * FPS), name: `${spec.id}-narration`, children: _jsx(Audio, { src: staticFile(`audio/${episodeId}/${spec.id}.wav`) }) })), spec.sfx && _jsx(Audio, { src: staticFile(`sfx/${spec.sfx}`), volume: spec.sfxVolume ?? 0.4 }), spec.element] }, spec.id));
+    });
+    return (_jsxs(AbsoluteFill, { style: { backgroundColor: theme.bg }, children: [music && _jsx(Audio, { loop: true, src: staticFile(`music/${music}`), volume: musicVolume ?? 0.13 }), sequences] }));
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "gitreel",
+  "version": "0.1.0",
+  "description": "Turn your pull requests into movie trailers — narrated, fast-paced, agent-authored PR review videos.",
+  "keywords": ["pull-request", "code-review", "video", "remotion", "tts", "agent", "skill"],
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "gitreel": "dist/cli/index.js"
+  },
+  "exports": {
+    "./engine": {
+      "types": "./dist/engine/index.d.ts",
+      "default": "./dist/engine/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["dist", "assets/music", "assets/sfx", "templates", "skills", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@remotion/bundler": "^4.0.0",
+    "@remotion/cli": "^4.0.0",
+    "@remotion/renderer": "^4.0.0",
+    "commander": "^12.1.0",
+    "diff": "^7.0.0",
+    "kokoro-js": "^1.2.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "remotion": "^4.0.0",
+    "shiki": "^1.29.0"
+  },
+  "devDependencies": {
+    "@types/diff": "^6.0.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^18.3.0",
+    "typescript": "^5.7.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": ["esbuild", "onnxruntime-node", "protobufjs", "sharp"]
+  }
+}

package/skills/gitreel/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: gitreel
+description: Turn a GitHub pull request into a narrated, fast-paced movie-trailer-style review video. Use when the user asks for a PR video, a video walkthrough/review of a PR, or invokes /gitreel. Args: PR number or URL (required), mode `short` (default, ~3-5 min) or `long` (~6-10 min), optional path to a review .md whose findings get woven into the video, optional --draft for a fast low-res preview.
+---
+
+# gitreel
+
+You produce a narrated video that reviews a GitHub PR — fast-paced, funny, visually clean
+(Fireship-style). The `gitreel` CLI is your instrument: it owns the render engine, TTS, and
+workspace. You are the writer-director: you read the PR, write the screenplay (narration +
+scene composition), and drive the CLI.
+
+## Step 0 — ensure the engine
+
+Run `gitreel --version`. If missing, install it: `npm i -g gitreel`, then run `gitreel doctor`
+and resolve anything it flags (it checks node ≥ 20, the `gh` CLI auth, the render browser).
+`gitreel where` prints the workspace (default `~/gitreel`, override via `GITREEL_HOME`).
+
+## Pipeline
+
+1. **Gather**: `gh pr view <n> --json title,body,commits,files` and `gh pr diff <n>` (add
+   `--repo owner/name` for PRs outside the cwd). Read the PR body and the commit sequence —
+   the video narrates the change in logical order (commit order is usually right).
+2. **Scaffold**: `gitreel new <episode-id>` (use `<repo>-<number>`, e.g. `fastify-5821`). This
+   creates `episodes/<id>/episode.tsx` + `narration.json` in the workspace.
+3. **Write the screenplay** (narration.json + episode.tsx). Structure is non-negotiable,
+   high level FIRST:
+   - (a) **title card**; (b) **goal scene** — what the PR is for, in plain words, before any code;
+     (c) **architecture diagram** (`DiagramScene`) — pre-existing parts dimmed, narration says
+     "none of this is new"; (d) **files overview** (`FileTreeScene`) — every changed file grouped
+     by area, narration walks the groups via spotlights; (e) **problem statement** — why this
+     change is needed/hard; (f) **roadmap** (`MontageBeat` with per-item `atSecond`) — the numbered
+     steps the detail half will follow; (g) **detail scenes**, kickers numbered
+     "step N of M · <area>"; (h) **review beats**; (i) **verdict card**.
+   - Short mode = 3–5 load-bearing changes close-up; long mode = every commit gets a beat.
+4. **Narrate**: `gitreel narrate <id>`. Caches per-scene by text; `--force` regenerates all.
+5. **Time the beats**: read `<workspace>/public/audio/<id>/manifest.json` for each scene's
+   measured seconds, then set every `atSecond` (spotlights, diagram reveals, morphs) at
+   word-fraction × measured duration. Never guess timings from word counts alone.
+6. **Verify with stills BEFORE the full render**: `gitreel still <id> --frame <n>` at each scene's
+   midpoint (compute frame offsets: scenes run sequentially, each 0.25s lead + narration seconds
+   + 0.5s tail, at 30fps). Look for: clipped titles (drop the scene title or shrink fontSize),
+   overflowing panels, spotlights on wrong lines, arrows not landing on their boxes.
+7. **Render**: `gitreel render <id>` (`--draft` for fast low-res iteration), then open the
+   printed MP4 path for the user.
+
+## Episode contract
+
+`episode.tsx` default-exports an `EpisodeDefinition` from `gitreel/engine`:
+`{ id, music: "drive.wav", musicVolume: 0.11, scenes: SceneSpec[] }`. Each `SceneSpec` is
+`{ id, element, sfx?, sfxVolume?, extraSeconds?, fixedSeconds? }` — scene ids must match
+narration.json scene ids; narration audio duration drives scene duration.
+
+Scene primitives (all from `gitreel/engine`): `TitleCard`, `BigText`, `CodeScene` (timed
+`spotlights`, optional `tree` breadcrumb + `finding` callout), `DiffMorph` (before→after morph at
+`morphAtSecond`), `DiagramScene` (nodes/arrows with timed reveals — ALWAYS set explicit
+`fromSide`/`toSide` on arrows), `FileTreeScene` (grouped files, per-group spotlights),
+`TerminalScene` (typed command + revealed output), `MontageBeat`, `VerdictCard`, `CalloutOverlay`,
+plus `SceneShell`/`Panel`/`FileChip` for bespoke scenes. SFX in the workspace: `whoosh.wav`,
+`pop.wav`, `sting.wav`, `thud.wav`, `tick.wav`, `success.wav`.
+
+## Craft rules (each one earned from viewer feedback — do not skip)
+
+- **Length is not a constraint.** Viewers can 2x. Cutting context to save seconds is the cardinal
+  sin; never let a video feel like it assumes knowledge it didn't establish.
+- **Every detail scene grounds itself in its first sentence** — whose code this is, who calls it,
+  or what came before ("this is the class the CLI calls", "remember the Router from earlier?").
+  A scene that opens cold on new code is a bug.
+- **Introduce every example before its payoff.** Any class/fixture appearing in a terminal-output
+  scene needs its own intro scene (code + tree breadcrumb) first.
+- **Never show a file the viewer can't place** — unfamiliar paths get the `tree` breadcrumb.
+- **Introduce fixture/demo code as fake**: narration says it's a fake project that exists for
+  tests; badge it "fake demo code" (amber). Never present it as the PR's production code.
+- **Existing vs new, everywhere**: pre-existing code/architecture renders dimmed + tagged; new
+  code full-brightness. Never present old code as new.
+- **Narration style**: punchy, dry-to-roasty humor, short sentences, no filler. Spell for speech
+  ("T-S morph", "PR fifty eight twenty one"). ~150 spoken words ≈ 1 minute. Voice `am_michael`,
+  speed 1.1.
+- **Review findings**: if the user supplied a review .md, extract findings and weave each into the
+  scene showing that code via the `finding` prop (severity: blocking=red / warn=amber / nit=grey).
+  No review file → do your own light pass over the diff. Always end with `VerdictCard`
+  (counts + stamp).
+- Code snippets: abridge to what the narration discusses (≤ ~20 lines per scene), real code from
+  the diff, never pseudo-code presented as real.
+- New scene-type ideas are welcome — build bespoke scenes from `SceneShell`/`Panel` primitives in
+  the episode file; they don't need to live in the engine.
+
+## Gotchas (each one cost a render — respect them)
+
+- The bundler does NOT type-check episode.tsx; type errors surface only as runtime crashes during
+  still/render. Render one cheap still immediately after writing the episode to catch them early.
+- `spotlights[].lines` ranges are TUPLES: `[[4, 9]]`, never `{ from: 4, to: 9 }`.
+- Diagram arrow labels draw UNDER node boxes — keep them short and away from nodes.
+- All `atSecond` timings are scene-local; narration starts after a 0.25s lead pad, so add 0.25 to
+  every word-fraction timing.
+- `DiagramScene` nodes: `kind: "new"` shows a NEW badge automatically; `kind: "focus"` is for
+  spotlighting pre-existing code and shows a badge only if you set `badge: "..."` — never present
+  existing code as new.
+- `React` must be imported in episode.tsx.

package/templates/episode/episode.tsx

@@ -0,0 +1,32 @@
+import React from "react";
+import { BigText, TitleCard, type EpisodeDefinition, type SceneSpec } from "gitreel/engine";
+
+const scenes: SceneSpec[] = [
+  {
+    id: "cold-open",
+    sfx: "whoosh.wav",
+    element: (
+      <TitleCard chip="your repo · PR #0" words={["hello", "gitreel"]} subtitle="a freshly scaffolded episode" />
+    ),
+  },
+  {
+    id: "goal",
+    sfx: "pop.wav",
+    element: (
+      <BigText
+        emoji="🎬"
+        text="replace these scenes with your story"
+        sub="import scene primitives from gitreel/engine"
+      />
+    ),
+  },
+];
+
+const episode: EpisodeDefinition = {
+  id: "EPISODE_ID",
+  music: "drive.wav",
+  musicVolume: 0.11,
+  scenes,
+};
+
+export default episode;

package/templates/episode/narration.json

@@ -0,0 +1,8 @@
+{
+  "voice": "am_michael",
+  "speed": 1.1,
+  "scenes": [
+    { "id": "cold-open", "text": "This is a freshly scaffolded gitreel episode." },
+    { "id": "goal", "text": "Replace these scenes with your story. Then narrate, verify stills, and render." }
+  ]
+}