SKILL.md- the skill, written out in plain English

   render_video({composition: "QuoteCard", props: {quote: "<extracted text>", author: "<derived or null>"}})

   url = "/artifacts/<artifactId>/file"
   root = Card([
     CardHeader("QuoteCard video", "Rendered successfully"),
     VideoPlayer(url, "<the quote text>")
   ])

import { score } from "../../lib/eval.ts";
score("remotion", run_id, {
  score: intent.includes("render") ? 0.5 : 1.0,  // render=0.5 at dispatch; edit/list=1.0
  intent_type: "render" | "edit" | "list",
  clip_count: clips?.length ?? 0,
  primary_issue: <null | gate-fail reason>,
});

criteria:
  - name: gate_checks_ffmpeg
    kind: deterministic
    check: "Render request gate runs `which ffmpeg` and returns non-empty path. If empty, gate fails with install message."
  - name: list_returns_30day_window
    kind: deterministic
    check: "List request reads `state/log/media/clips.ndjson` and filters to clips created in past 30 days. Returns array shape: {clips: [{id, name, duration_s, dimensions, created_at, thumbnail_url, format}], total: N}."
  - name: edit_stages_without_writing
    kind: deterministic
    check: "Edit request returns staged mutation object without writing to disk. Response shape: {edit_staged: true, clip_id, mutation, preview}. File system unchanged."
  - name: render_dispatch_async
    kind: deterministic
    check: "Render request invokes ffmpeg/Remotion asynchronously, captures PID immediately, logs to `state/log/remotion-renders.ndjson`, returns {rendering: true, render_pid, output_path, eta_seconds} immediately without waiting."
  - name: render_score_timing
    kind: deterministic
    check: "Render requests score 0.5 at dispatch; list/edit requests score 1.0 immediately. Render upgrades to 1.0 only when artifact auditor verifies completed."
  - name: intent_parsing_graceful
    kind: deterministic
    check: "Unrecognizable intent gates gracefully (no throw). Returns clear help text with example intents."

AGENTS.md- what the AI loads when this skill comes up

cd ~/projects/snappy-remotion && npx remotion render src/index.ts CapabilityDemo \
  ~/projects/snappy-os/state/log/media/renders/capability-demo-$(date +%s).mp4

   cd ~/projects/snappy-remotion && npx remotion render src/index.ts ImageDrivenDemo \
     ~/projects/snappy-os/state/log/media/renders/demo-$(date +%s).mp4 \
     --props '{"scenes":[{"title":"snappy","subtitle":"AI that composes","imagePath":"/tmp/demo-scenes/scene1.png","durationFrames":90},...],"title":"snappy"}'

# 1. Generate images through the harness first:
#    generate_image({prompt: "SCENE DESCRIPTION, 16:9"})
#    Each result returns an artifact or https URL such as /artifacts/<id>/file.
#
# 2. Only if the Remotion composition requires local imagePath values, download:
mkdir -p /tmp/demo-scenes
curl -fsSL "http://127.0.0.1:3147/artifacts/<scene-1-artifact-id>/file" -o /tmp/demo-scenes/scene1.png
curl -fsSL "http://127.0.0.1:3147/artifacts/<scene-2-artifact-id>/file" -o /tmp/demo-scenes/scene2.png
curl -fsSL "http://127.0.0.1:3147/artifacts/<scene-3-artifact-id>/file" -o /tmp/demo-scenes/scene3.png

# 3. Build props JSON and render
cd ~/projects/snappy-remotion
PROPS=$(python3 -c "
import json
scenes = [
  {'title': 'snappy', 'subtitle': 'AI that composes, not just responds', 'imagePath': '/tmp/demo-scenes/scene1.png', 'durationFrames': 90},
  {'title': 'Meeting to LinkedIn to Video', 'subtitle': 'One prompt. Compound response.', 'imagePath': '/tmp/demo-scenes/scene2.png', 'durationFrames': 90},
  {'title': '252 skills.', 'subtitle': 'Always discovering.', 'imagePath': '/tmp/demo-scenes/scene3.png', 'durationFrames': 90},
  {'title': '', 'subtitle': 'snappy-os - built for one', 'imagePath': '/tmp/demo-scenes/scene1.png', 'durationFrames': 60},
]
print(json.dumps({'scenes': scenes}))
")
OUTPUT=~/projects/snappy-os/state/log/media/renders/image-driven-demo-$(date +%s).mp4
npx remotion render src/index.ts ImageDrivenDemo "$OUTPUT" --props "$PROPS"

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * snappy-remotion/api.ts -- Programmatic video generation via Remotion.
 *
 * Generates video from React components: quote cards, social clips, course intros,
 * data visualizations, branded overlays. The Remotion project lives at
 * ~/projects/snappy-remotion and must be scaffolded before first use.
 *
 * Env vars:
 *   SNAPPY_REMOTION_DIR  Path to the Remotion project directory.
 *                        Defaults to $HOME/projects/snappy-remotion.
 *
 * Usage:
 *   npx tsx api.ts scaffold
 *   npx tsx api.ts list
 *   npx tsx api.ts render QuoteCard --props '{"text":"Ship it"}'
 *   npx tsx api.ts preview
 *   npx tsx api.ts add ToolDemo "Animated tool walkthrough"
 *
 * Or import as module:
 *   import { scaffoldProject, listCompositions, render, preview, addComposition } from "./remotion.ts";
 */

import { execSync, spawn } from "child_process";
import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync } from "fs";
import { join, basename, dirname } from "path";
import { fileURLToPath } from "url";
import os from "os";
import { env } from "./env.ts";

// ---------------------------------------------------------------------------
// Constants
// ---------------------------------------------------------------------------

const PROJECT_DIR = process.env.SNAPPY_REMOTION_DIR ?? join(os.homedir(), "projects", "snappy-remotion");
const SRC_DIR = join(PROJECT_DIR, "src");
const COMP_DIR = join(SRC_DIR, "compositions");
const LIB_DIR = join(SRC_DIR, "lib");

// Clip ledger that "show my videos" reads. Lives in the snappy-os repo, NOT the
// external remotion project dir. state/lib -> repo root.
const CLIPS_LEDGER = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "state/log/media/clips.ndjson");

/** Snappy brand constants used by all compositions. */
export const BRAND = {
  primary: "#2563EB",
  dark: "#0F172A",
  light: "#F8FAFC",
  accent: "#F59E0B",
  cream: "#F5F0E6",
  ink: "#3d3929",
  cta: "#c96442",
  font: "Inter",
  serifFont: "EB Garamond",
} as const;

export const brand = BRAND;

/** Default render dimensions per format. */
export const FORMATS: Record<string, { width: number; height: number; fps: number; durationInFrames: number }> = {
  "vertical":   { width: 1080, height: 1920, fps: 30, durationInFrames: 150 },
  "square":     { width: 1080, height: 1080, fps: 30, durationInFrames: 150 },
  "landscape":  { width: 1920, height: 1080, fps: 30, durationInFrames: 150 },
  "youtube":    { width: 1280, height: 720,  fps: 30, durationInFrames: 300 },
  "story":      { width: 1080, height: 1920, fps: 30, durationInFrames: 450 },
};

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

function ensureProject(): void {
  if (!existsSync(join(PROJECT_DIR, "package.json"))) {
    throw new Error(
      `Remotion project not found at ${PROJECT_DIR}. Run \`npx tsx state/lib/remotion.ts scaffold\` first.`,
    );
  }
}

function exec(cmd: string, cwd?: string, timeoutMs?: number): string {
  return execSync(cmd, {
    encoding: "utf-8",
    ...(timeoutMs != null ? { timeout: timeoutMs } : {}),
    cwd: cwd || PROJECT_DIR,
    stdio: ["pipe", "pipe", "pipe"],
  }).trim();
}

// ---------------------------------------------------------------------------
// Template content (used by scaffold)
// ---------------------------------------------------------------------------

const PACKAGE_JSON = JSON.stringify(
  {
    name: "snappy-remotion",
    version: "1.0.0",
    private: true,
    scripts: {
      start: "remotion studio",
      build: "remotion render src/index.ts",
      upgrade: "remotion upgrade",
    },
    dependencies: {
      "@remotion/cli": "^4",
      "@remotion/player": "^4",
      react: "^18",
      "react-dom": "^18",
      remotion: "^4",
    },
    devDependencies: {
      "@types/react": "^18",
      typescript: "^5",
    },
  },
  null,
  2,
);

const TSCONFIG = JSON.stringify(
  {
    compilerOptions: {
      target: "ES2022",
      module: "ES2022",
      moduleResolution: "bundler",
      jsx: "react-jsx",
      strict: true,
      esModuleInterop: true,
      skipLibCheck: true,
      outDir: "dist",
    },
    include: ["src"],
  },
  null,
  2,
);

const REMOTION_CONFIG = `import { Config } from "@remotion/cli/config";
Config.setVideoImageFormat("png");
Config.setOverwriteOutput(true);
`;

const BRAND_TS = `// Brand constants for all Remotion compositions.
// Source of truth: snappy-positioning AGENTS.md §8 + snappy-remotion/api.ts BRAND export.

export const brand = {
  primary: "${BRAND.primary}",
  dark: "${BRAND.dark}",
  light: "${BRAND.light}",
  accent: "${BRAND.accent}",
  cream: "${BRAND.cream}",
  ink: "${BRAND.ink}",
  cta: "${BRAND.cta}",
  font: "${BRAND.font}",
  serifFont: "${BRAND.serifFont}",
} as const;
`;

const TRANSITIONS_TS = `import { interpolate, useCurrentFrame, Easing } from "remotion";

/** Fade in over \`frames\` frames, starting at \`delay\`. */
export function useFadeIn(delay = 0, frames = 20): number {
  const frame = useCurrentFrame();
  return interpolate(frame, [delay, delay + frames], [0, 1], {
    extrapolateLeft: "clamp",
    extrapolateRight: "clamp",
    easing: Easing.out(Easing.ease),
  });
}

/** Slide in from direction over \`frames\` frames. Returns translateX or translateY px. */
export function useSlideIn(
  direction: "left" | "right" | "up" | "down" = "up",
  delay = 0,
  frames = 25,
  distance = 60,
): number {
  const frame = useCurrentFrame();
  const sign = direction === "right" || direction === "down" ? 1 : -1;
  return interpolate(frame, [delay, delay + frames], [sign * distance, 0], {
    extrapolateLeft: "clamp",
    extrapolateRight: "clamp",
    easing: Easing.out(Easing.cubic),
  });
}

/** Scale from 0 to 1 over \`frames\` frames. */
export function useScaleIn(delay = 0, frames = 20): number {
  const frame = useCurrentFrame();
  return interpolate(frame, [delay, delay + frames], [0, 1], {
    extrapolateLeft: "clamp",
    extrapolateRight: "clamp",
    easing: Easing.out(Easing.back(1.5)),
  });
}
`;

const QUOTE_CARD_TSX = `import { AbsoluteFill, useCurrentFrame, interpolate, Easing } from "remotion";
import { brand } from "../lib/brand.ts";

export type QuoteCardProps = {
  text: string;
  speaker?: string;
  title?: string;
};

export const QuoteCard: React.FC<QuoteCardProps> = ({ text, speaker, title }) => {
  const frame = useCurrentFrame();
  const textOpacity = interpolate(frame, [10, 35], [0, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
  const speakerOpacity = interpolate(frame, [30, 50], [0, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
  const quoteY = interpolate(frame, [10, 35], [30, 0], { extrapolateLeft: "clamp", extrapolateRight: "clamp", easing: Easing.out(Easing.ease) });
  const lineWidth = interpolate(frame, [0, 25], [0, 80], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });

  return (
    <AbsoluteFill style={{ backgroundColor: brand.cream, justifyContent: "center", alignItems: "center", padding: 80, fontFamily: brand.serifFont }}>
      <div style={{ width: lineWidth, height: 3, backgroundColor: brand.cta, marginBottom: 40 }} />
      <div style={{ opacity: textOpacity, transform: \`translateY(\${quoteY}px)\`, fontSize: 52, lineHeight: 1.4, color: brand.ink, textAlign: "center", maxWidth: 800 }}>
        \\u201c{text}\\u201d
      </div>
      {speaker && (
        <div style={{ opacity: speakerOpacity, marginTop: 40, fontSize: 28, color: brand.ink, letterSpacing: 2, textTransform: "uppercase" }}>
          {speaker}{title ? \` \\u2014 \${title}\` : ""}
        </div>
      )}
    </AbsoluteFill>
  );
};
`;

const SOCIAL_CLIP_TSX = `import { AbsoluteFill, useCurrentFrame, interpolate, Easing } from "remotion";
import { brand } from "../lib/brand.ts";

export type SocialClipProps = {
  text: string;
  subtitle?: string;
  background?: string;
};

export const SocialClip: React.FC<SocialClipProps> = ({ text, subtitle, background }) => {
  const frame = useCurrentFrame();
  const titleOpacity = interpolate(frame, [5, 25], [0, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
  const titleY = interpolate(frame, [5, 25], [40, 0], { extrapolateLeft: "clamp", extrapolateRight: "clamp", easing: Easing.out(Easing.ease) });
  const subOpacity = interpolate(frame, [20, 40], [0, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });

  return (
    <AbsoluteFill style={{ backgroundColor: background || brand.dark, justifyContent: "center", alignItems: "center", padding: 60, fontFamily: brand.font }}>
      <div style={{ opacity: titleOpacity, transform: \`translateY(\${titleY}px)\`, fontSize: 64, fontWeight: 700, color: brand.light, textAlign: "center", maxWidth: 900, lineHeight: 1.3 }}>
        {text}
      </div>
      {subtitle && (
        <div style={{ opacity: subOpacity, marginTop: 30, fontSize: 28, color: brand.accent, textAlign: "center" }}>
          {subtitle}
        </div>
      )}
    </AbsoluteFill>
  );
};
`;

const COURSE_INTRO_TSX = `import { AbsoluteFill, useCurrentFrame, interpolate, Sequence, Easing } from "remotion";
import { brand } from "../lib/brand.ts";

export type CourseIntroProps = {
  text: string;
  category?: string;
  lessonNumber?: number;
};

export const CourseIntro: React.FC<CourseIntroProps> = ({ text, category, lessonNumber }) => {
  const frame = useCurrentFrame();
  const bgScale = interpolate(frame, [0, 60], [1.05, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
  const categoryOpacity = interpolate(frame, [10, 25], [0, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
  const titleOpacity = interpolate(frame, [20, 45], [0, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
  const titleY = interpolate(frame, [20, 45], [50, 0], { extrapolateLeft: "clamp", extrapolateRight: "clamp", easing: Easing.out(Easing.ease) });
  const lineWidth = interpolate(frame, [15, 40], [0, 120], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });

  return (
    <AbsoluteFill style={{ backgroundColor: brand.cream, justifyContent: "center", alignItems: "center", fontFamily: brand.font, transform: \`scale(\${bgScale})\` }}>
      {category && (
        <div style={{ opacity: categoryOpacity, fontSize: 22, letterSpacing: 4, textTransform: "uppercase", color: brand.cta, marginBottom: 20, fontWeight: 600 }}>
          {lessonNumber != null ? \`Lesson \${lessonNumber} · \` : ""}{category}
        </div>
      )}
      <div style={{ width: lineWidth, height: 2, backgroundColor: brand.ink, marginBottom: 30 }} />
      <div style={{ opacity: titleOpacity, transform: \`translateY(\${titleY}px)\`, fontSize: 56, fontWeight: 700, color: brand.ink, textAlign: "center", maxWidth: 800, lineHeight: 1.3, fontFamily: brand.serifFont }}>
        {text}
      </div>
    </AbsoluteFill>
  );
};
`;

const DATA_VIZ_TSX = `import { AbsoluteFill, useCurrentFrame, interpolate, Easing } from "remotion";
import { brand } from "../lib/brand.ts";

export type DataVizProps = {
  text: string;
  value?: string;
  subtitle?: string;
  unit?: string;
};

export const DataViz: React.FC<DataVizProps> = ({ text, value, subtitle, unit }) => {
  const frame = useCurrentFrame();
  const valueOpacity = interpolate(frame, [10, 30], [0, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
  const valueScale = interpolate(frame, [10, 35], [0.5, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp", easing: Easing.out(Easing.back(1.3)) });
  const labelOpacity = interpolate(frame, [25, 45], [0, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
  const subOpacity = interpolate(frame, [35, 55], [0, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });

  return (
    <AbsoluteFill style={{ backgroundColor: brand.dark, justifyContent: "center", alignItems: "center", fontFamily: brand.font, padding: 60 }}>
      {value && (
        <div style={{ opacity: valueOpacity, transform: \`scale(\${valueScale})\`, fontSize: 140, fontWeight: 800, color: brand.accent, textAlign: "center" }}>
          {value}{unit && <span style={{ fontSize: 60, color: brand.light }}>{unit}</span>}
        </div>
      )}
      <div style={{ opacity: labelOpacity, marginTop: 20, fontSize: 40, fontWeight: 600, color: brand.light, textAlign: "center", maxWidth: 700 }}>
        {text}
      </div>
      {subtitle && (
        <div style={{ opacity: subOpacity, marginTop: 16, fontSize: 24, color: "#94a3b8", textAlign: "center" }}>
          {subtitle}
        </div>
      )}
    </AbsoluteFill>
  );
};
`;

const BRANDED_OVERLAY_TSX = `import { AbsoluteFill, useCurrentFrame, interpolate, Easing } from "remotion";
import { brand } from "../lib/brand.ts";

export type BrandedOverlayProps = {
  text: string;
  position?: "bottom-left" | "bottom-right" | "top-left" | "top-right";
};

export const BrandedOverlay: React.FC<BrandedOverlayProps> = ({ text, position = "bottom-left" }) => {
  const frame = useCurrentFrame();
  const slideIn = interpolate(frame, [5, 25], [-100, 0], { extrapolateLeft: "clamp", extrapolateRight: "clamp", easing: Easing.out(Easing.ease) });
  const opacity = interpolate(frame, [5, 25], [0, 0.95], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });

  const isBottom = position.startsWith("bottom");
  const isRight = position.endsWith("right");

  return (
    <AbsoluteFill>
      <div
        style={{
          position: "absolute",
          [isBottom ? "bottom" : "top"]: 40,
          [isRight ? "right" : "left"]: 40,
          opacity,
          transform: \`translateY(\${isBottom ? -slideIn : slideIn}px)\`,
          backgroundColor: "rgba(15, 23, 42, 0.85)",
          padding: "12px 24px",
          borderRadius: 8,
          borderLeft: \`3px solid \${brand.cta}\`,
          fontFamily: brand.font,
          fontSize: 22,
          color: brand.light,
          fontWeight: 500,
          maxWidth: 500,
        }}
      >
        {text}
      </div>
    </AbsoluteFill>
  );
};
`;

const ROOT_TSX = `import { Composition } from "remotion";
import { QuoteCard, QuoteCardProps } from "./compositions/QuoteCard.ts";
import { SocialClip, SocialClipProps } from "./compositions/SocialClip.ts";
import { CourseIntro, CourseIntroProps } from "./compositions/CourseIntro.ts";
import { DataViz, DataVizProps } from "./compositions/DataViz.ts";
import { BrandedOverlay, BrandedOverlayProps } from "./compositions/BrandedOverlay.ts";

export const RemotionRoot: React.FC = () => {
  return (
    <>
      <Composition
        id="QuoteCard"
        component={QuoteCard}
        durationInFrames={150}
        fps={30}
        width={1080}
        height={1080}
        defaultProps={{ text: "Build and control agents to get huge results." } satisfies QuoteCardProps}
      />
      <Composition
        id="SocialClip"
        component={SocialClip}
        durationInFrames={150}
        fps={30}
        width={1080}
        height={1920}
        defaultProps={{ text: "Ship it." } satisfies SocialClipProps}
      />
      <Composition
        id="CourseIntro"
        component={CourseIntro}
        durationInFrames={150}
        fps={30}
        width={1920}
        height={1080}
        defaultProps={{ text: "Getting Started", category: "Agentic Development" } satisfies CourseIntroProps}
      />
      <Composition
        id="DataViz"
        component={DataViz}
        durationInFrames={150}
        fps={30}
        width={1080}
        height={1080}
        defaultProps={{ text: "Hours saved per week", value: "37", unit: "hrs" } satisfies DataVizProps}
      />
      <Composition
        id="BrandedOverlay"
        component={BrandedOverlay}
        durationInFrames={150}
        fps={30}
        width={1920}
        height={1080}
        defaultProps={{ text: "snappy.ai", position: "bottom-left" } satisfies BrandedOverlayProps}
      />
    </>
  );
};
`;

const INDEX_TS = `import { registerRoot } from "remotion";
import { RemotionRoot } from "./Root.ts";
registerRoot(RemotionRoot);
`;

const COMP_TEMPLATE = (name: string, description: string) => `import { AbsoluteFill, useCurrentFrame, interpolate, Easing } from "remotion";
import { brand } from "../lib/brand.ts";

export type ${name}Props = {
  text: string;
};

/** ${description} */
export const ${name}: React.FC<${name}Props> = ({ text }) => {
  const frame = useCurrentFrame();
  const opacity = interpolate(frame, [5, 25], [0, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });

  return (
    <AbsoluteFill style={{ backgroundColor: brand.cream, justifyContent: "center", alignItems: "center", fontFamily: brand.font, padding: 60 }}>
      <div style={{ opacity, fontSize: 48, fontWeight: 700, color: brand.ink, textAlign: "center" }}>
        {text}
      </div>
    </AbsoluteFill>
  );
};
`;

// ---------------------------------------------------------------------------
// Public API
// ---------------------------------------------------------------------------

/**
 * Create the Remotion project at ~/projects/snappy-remotion if it doesn't exist.
 * Writes all template files and installs dependencies.
 */
export function scaffoldProject(): string {
  if (existsSync(join(PROJECT_DIR, "package.json"))) {
    return `Project already exists at ${PROJECT_DIR}. Delete it to re-scaffold.`;
  }

  // Create directory structure
  for (const dir of [PROJECT_DIR, SRC_DIR, COMP_DIR, LIB_DIR]) {
    mkdirSync(dir, { recursive: true });
  }

  // Write all template files
  const files: [string, string][] = [
    [join(PROJECT_DIR, "package.json"), PACKAGE_JSON],
    [join(PROJECT_DIR, "tsconfig.json"), TSCONFIG],
    [join(PROJECT_DIR, "remotion.config.ts"), REMOTION_CONFIG],
    [join(SRC_DIR, "index.ts"), INDEX_TS],
    [join(SRC_DIR, "Root.tsx"), ROOT_TSX],
    [join(LIB_DIR, "brand.ts"), BRAND_TS],
    [join(LIB_DIR, "transitions.ts"), TRANSITIONS_TS],
    [join(COMP_DIR, "QuoteCard.tsx"), QUOTE_CARD_TSX],
    [join(COMP_DIR, "SocialClip.tsx"), SOCIAL_CLIP_TSX],
    [join(COMP_DIR, "CourseIntro.tsx"), COURSE_INTRO_TSX],
    [join(COMP_DIR, "DataViz.tsx"), DATA_VIZ_TSX],
    [join(COMP_DIR, "BrandedOverlay.tsx"), BRANDED_OVERLAY_TSX],
  ];

  for (const [path, content] of files) {
    writeFileSync(path, content, "utf-8");
  }

  // Install dependencies
  exec("npm install", PROJECT_DIR, 120000);

  return `Scaffolded Remotion project at ${PROJECT_DIR}. ${files.length} files written. Dependencies installed.`;
}

/**
 * List available compositions from the project's Root.tsx.
 * Parses composition IDs from <Composition id="..."> in Root.tsx.
 */
export function listCompositions(): string[] {
  ensureProject();
  const rootPath = join(SRC_DIR, "Root.tsx");
  if (!existsSync(rootPath)) {
    throw new Error(`Root.tsx not found at ${rootPath}`);
  }
  const content = readFileSync(rootPath, "utf-8");
  const ids: string[] = [];
  const re = /id="([^"]+)"/g;
  let m: RegExpExecArray | null;
  while ((m = re.exec(content)) !== null) {
    ids.push(m[1]);
  }
  return ids;
}

export type RenderOpts = {
  output?: string;
  width?: number;
  height?: number;
  fps?: number;
  durationInFrames?: number;
  format?: keyof typeof FORMATS;
};

/**
 * Append a clip row to the ledger that "show my videos" reads, atomically with
 * the render. The engine produced real mp4s but nothing recorded the ledger, so
 * every video was an invisible orphan (the produce-vs-record seam). Best-effort
 * ffprobe for duration+dimensions; on any probe failure we still write the row
 * so a clip is NEVER invisible. A ledger failure can't break the render — the
 * mp4 is the deliverable, the row is bookkeeping.
 */
function recordClipLedgerRow(outputPath: string, compositionId: string): void {
  try {
    if (!existsSync(outputPath)) return;
    let duration_s = 0;
    let dimensions = "unknown";
    try {
      const out = execSync(
        `ffprobe -v error -select_streams v:0 -show_entries stream=width,height -show_entries format=duration -of json ${JSON.stringify(outputPath)}`,
        { encoding: "utf8" },
      );
      const j = JSON.parse(out) as { streams?: Array<{ width?: number; height?: number }>; format?: { duration?: string } };
      const s = j.streams?.[0] ?? {};
      duration_s = j.format?.duration ? Math.round(Number(j.format.duration) * 10) / 10 : 0;
      dimensions = s.width && s.height ? `${s.width}x${s.height}` : "unknown";
    } catch { /* keep fallbacks; a clip with unknown metadata still beats an invisible one */ }
    mkdirSync(dirname(CLIPS_LEDGER), { recursive: true });
    appendFileSync(
      CLIPS_LEDGER,
      JSON.stringify({
        id: basename(outputPath, ".mp4"),
        name: compositionId || basename(outputPath, ".mp4"),
        duration_s,
        dimensions,
        created_at: new Date().toISOString(),
        thumbnail_url: null,
        format: "mp4",
        path: outputPath,
        composition: compositionId,
      }) + "\n",
    );
  } catch { /* ledger is bookkeeping; never break the render */ }
}

/**
 * Render a composition to MP4.
 * Uses `npx remotion render` in the project directory.
 * Returns the absolute path to the output file.
 */
export function render(
  compositionId: string,
  props: Record<string, unknown> = {},
  opts: RenderOpts = {},
): string {
  ensureProject();

  const ts = Date.now();
  const outputPath = opts.output || `/tmp/snappy-remotion-${compositionId.toLowerCase()}-${ts}.mp4`;

  // Resolve format defaults
  const fmt = opts.format ? FORMATS[opts.format] : undefined;
  const width = opts.width || fmt?.width;
  const height = opts.height || fmt?.height;
  const fps = opts.fps || fmt?.fps;
  const duration = opts.durationInFrames || fmt?.durationInFrames;

  const parts = [
    "npx", "remotion", "render",
    "src/index.ts",
    compositionId,
    `"${outputPath}"`,
  ];

  if (Object.keys(props).length > 0) {
    // Write props to a temp file to avoid shell escaping issues
    const propsPath = `/tmp/snappy-remotion-props-${ts}.json`;
    writeFileSync(propsPath, JSON.stringify(props), "utf-8");
    parts.push("--props", propsPath);
  }

  if (width) parts.push("--width", String(width));
  if (height) parts.push("--height", String(height));
  if (fps) parts.push("--fps", String(fps));
  // 2026-05-07: Remotion's `--frames` takes a RANGE, not a count. The old
  // `--frames 150` made the CLI think we wanted a single still ("Selected
  // a single frame. Assuming you want to output an image"), then it
  // rejected the .mp4 extension. For a full video we pass a range
  // "0-149" so callers who want to override duration still work; if no
  // duration is passed, we omit the flag and let the composition's
  // declared durationInFrames win.
  if (duration && duration > 0) parts.push(`--frames=0-${Math.max(0, duration - 1)}`);

  exec(parts.join(" "), PROJECT_DIR, 600000);

  // Record the clip atomically with the render — the produce-vs-record seam
  // that left every render an invisible orphan. Best-effort, never throws.
  recordClipLedgerRow(outputPath, compositionId);

  return outputPath;
}

/**
 * Streaming render — wraps `render()` with an async generator that yields
 * video.start + video.complete events for SSE relay. Mirrors the image-gen
 * NDJSON pattern (item 3) so the snappy-os dispatch handler can emit a
 * loading-state surface immediately and editMode-patch the preview when
 * the render lands.
 *
 * Auto-picks composition based on duration heuristic ("SocialClip" for
 * short clips, "QuoteCard" for the shortest, "BrandedOverlay" for longer)
 * unless an explicit composition is provided via opts.composition.
 */
export interface RemotionRenderArgs {
  prompt: string;
  duration: number;
  voice?: string;
  composition?: string;
  output?: string;
}

export type RemotionRenderEvent =
  | { event: "video.start"; id: string; prompt: string; composition: string }
  | { event: "video.complete"; id: string; url: string; prompt: string; composition: string }
  | { event: "video.error"; id: string; reason: string; prompt?: string };

export async function* remotionRender(args: RemotionRenderArgs): AsyncGenerator<RemotionRenderEvent> {
  const { prompt, duration, voice = "rachel", composition, output } = args;
  const id = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;

  // Project must exist; if Remotion CLI not installed, yield error early.
  if (!existsSync(PROJECT_DIR)) {
    yield {
      event: "video.error",
      id,
      reason: "Remotion project not scaffolded; run: npx tsx state/lib/remotion.ts scaffold",
    };
    return;
  }

  // Heuristic composition pick: short = QuoteCard / SocialClip, long = BrandedOverlay.
  const pickedComposition = composition || (duration <= 5 ? "SocialClip" : duration <= 10 ? "QuoteCard" : "BrandedOverlay");

  yield { event: "video.start", id, prompt, composition: pickedComposition };

  try {
    const outputPath = render(pickedComposition, { text: prompt, voice }, output ? { output } : {});
    // Existing render() returns a local mp4 path. Convert to a file:// URL
    // the snappy-chat CardImage can mount. CDN upload is a future step
    // (mirror image-gen's CDN behavior when ready).
    const url = outputPath.startsWith("/") ? `file://${outputPath}` : outputPath;
    yield { event: "video.complete", id, url, prompt, composition: pickedComposition };
  } catch (err) {
    const reason = err instanceof Error ? err.message : String(err);
    yield { event: "video.error", id, reason, prompt };
  }
}

/**
 * Start the Remotion Studio dev server for visual editing.
 * Returns the Studio URL (default http://localhost:3000).
 * Runs as a background process -- caller is responsible for stopping it.
 */
export function preview(compositionId?: string, props?: Record<string, unknown>): string {
  ensureProject();

  const parts = ["npx", "remotion", "studio", "src/index.ts"];
  const child = spawn(parts[0], parts.slice(1), {
    cwd: PROJECT_DIR,
    detached: true,
    stdio: "ignore",
  });
  child.unref();

  const url = "http://localhost:3000";
  return compositionId ? `${url}/?composition=${compositionId}` : url;
}

/**
 * Scaffold a new composition from the template.
 * Creates the .tsx file and registers it in Root.tsx.
 * Returns the path to the new composition file.
 */
export function addComposition(name: string, description: string): string {
  ensureProject();

  if (!/^[A-Z][a-zA-Z0-9]+$/.test(name)) {
    throw new Error(`Composition name must be PascalCase: ${name}`);
  }

  const filePath = join(COMP_DIR, `${name}.tsx`);
  if (existsSync(filePath)) {
    throw new Error(`Composition already exists: ${filePath}`);
  }

  // Write the composition file
  writeFileSync(filePath, COMP_TEMPLATE(name, description), "utf-8");

  // Register in Root.tsx
  const rootPath = join(SRC_DIR, "Root.tsx");
  let root = readFileSync(rootPath, "utf-8");

  // Add import
  const importLine = `import { ${name}, ${name}Props } from "./compositions/${name}.ts";`;
  const lastImportIdx = root.lastIndexOf("import ");
  const lastImportEnd = root.indexOf("\n", lastImportIdx);
  root = root.slice(0, lastImportEnd + 1) + importLine + "\n" + root.slice(lastImportEnd + 1);

  // Add Composition before the closing </>
  const compBlock = `      <Composition
        id="${name}"
        component={${name}}
        durationInFrames={150}
        fps={30}
        width={1080}
        height={1080}
        defaultProps={{ text: "${description}" } satisfies ${name}Props}
      />\n`;
  const closingIdx = root.lastIndexOf("</>");
  root = root.slice(0, closingIdx) + compBlock + "    " + root.slice(closingIdx);

  writeFileSync(rootPath, root, "utf-8");

  return filePath;
}

// ---------------------------------------------------------------------------
// CLI
// ---------------------------------------------------------------------------

if ((() => { try { return import.meta.url === `file://${realpathSync(process.argv[1])}`; } catch { return false; } })()) {
  (async () => {
    const [, , cmd, ...args] = process.argv;

    switch (cmd) {
      case "scaffold": {
        console.log(scaffoldProject());
        break;
      }
      case "list": {
        const comps = listCompositions();
        for (const c of comps) console.log(c);
        break;
      }
      case "render": {
        const [comp, ...rest] = args;
        if (!comp) {
          console.error("Usage: api.ts render <compositionId> [--props '{...}'] [--format vertical|square|landscape|youtube|story] [--output path]");
          process.exit(1);
        }
        let props: Record<string, unknown> = {};
        let output = "";
        let format = "";
        let width: number | undefined;
        let height: number | undefined;
        let fps: number | undefined;
        let durationInFrames: number | undefined;
        for (let i = 0; i < rest.length; i++) {
          if (rest[i] === "--props" && rest[i + 1]) { try { props = JSON.parse(rest[++i]); } catch (e) { console.error("Invalid JSON in --props:", e instanceof Error ? e.message : String(e)); process.exit(1); } continue; }
          if (rest[i] === "--output" && rest[i + 1]) { output = rest[++i]; continue; }
          if (rest[i] === "--format" && rest[i + 1]) { format = rest[++i]; continue; }
          if (rest[i] === "--width" && rest[i + 1]) { width = Number(rest[++i]); continue; }
          if (rest[i] === "--height" && rest[i + 1]) { height = Number(rest[++i]); continue; }
          if (rest[i] === "--fps" && rest[i + 1]) { fps = Number(rest[++i]); continue; }
          if (rest[i] === "--duration" && rest[i + 1]) { durationInFrames = Number(rest[++i]); continue; }
        }
        const outPath = render(comp, props, {
          output: output || undefined,
          format: (format as keyof typeof FORMATS) || undefined,
          width,
          height,
          fps,
          durationInFrames,
        });
        console.log(outPath);
        break;
      }
      case "preview": {
        const [comp] = args;
        const url = preview(comp || undefined);
        console.log(`Remotion Studio started: ${url}`);
        break;
      }
      case "add": {
        const [name, ...descParts] = args;
        const desc = descParts.join(" ");
        if (!name || !desc) {
          console.error("Usage: api.ts add <PascalCaseName> <description>");
          process.exit(1);
        }
        const path = addComposition(name, desc);
        console.log(`Created: ${path}`);
        break;
      }
      default:
        console.log("Usage: npx tsx api.ts [scaffold|list|render|preview|add] ...");
        console.log("");
        console.log("  scaffold                          Create the Remotion project");
        console.log("  list                              List available compositions");
        console.log("  render <comp> --props '{...}'     Render composition to MP4");
        console.log("  preview [comp]                    Start Remotion Studio");
        console.log("  add <Name> <description>          Add a new composition");
    }
  })();
}

scripts- helper scripts it can run

prose-only skill - 2 inline code blocks live in SKILL.md above (no state/bin/ sidecar yet).

how we check it- the checks, plus the last 10 runs

no recent runs logged - the eval contract is declared but nothing has been graded yet