framecode 1.0.0

package/README.md

@@ -0,0 +1,97 @@
+# FrameCode
+
+[![npm version](https://img.shields.io/npm/v/framecode)](https://www.npmjs.com/package/framecode)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![stars](https://img.shields.io/github/stars/esau-morais/framecode?style=social)](https://github.com/esau-morais/framecode)
+
+CLI-first video generator that turns code snippets into social-ready videos with Remotion + Shiki.
+
+## Features
+
+- 5 built-in themes: `vercel-dark`, `story-gradients`, `retro-terminal`, `github-dark`, `synthwave-84`
+- Animations: `morph`, `typewriter`, `cascade` (with per-file overrides)
+- Presets: `post` (9:16), `tutorial` (16:9), `square` (1:1)
+- Optional brand kit overlay: logo, Twitter/X handle, website, accent color
+- Interactive render wizard or fully scripted CLI flow
+
+## Quick Start
+
+```bash
+bunx framecode init --local
+framecode render "~/projects/demo/src/**/*.ts" -t vercel-dark -a cascade -p tutorial
+```
+
+## Installation
+
+```bash
+bun add -g framecode
+framecode --help
+```
+
+## Usage
+
+```bash
+# Example 1: Single file
+framecode render "~/projects/demo/src/intro.ts" -t story-gradients -a typewriter
+
+# Example 2: Multi-file with per-step overrides in config
+framecode render "~/projects/demo/src/**/*.ts" "!**/*.test.ts" -c framecode.json
+
+# Example 3: Add brand kit on render
+framecode render "~/projects/demo/src/main.ts" \
+  --logo "~/projects/demo/public/logo.png" \
+  --twitter framecodehq \
+  --website framecode.dev \
+  --accent "#ff8800"
+```
+
+## Config
+
+Create config with:
+
+```bash
+framecode init --local
+```
+
+Minimal `framecode.json`:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/esau-morais/framecode/main/framecode.schema.json",
+  "theme": "vercel-dark",
+  "preset": "tutorial",
+  "animation": "cascade",
+  "stepConfigs": [{ "file": "intro.ts", "animation": "typewriter", "charsPerSecond": 42 }],
+  "brand": { "twitter": "@framecodehq", "accent": "#ff8800" }
+}
+```
+
+## Themes
+
+```bash
+framecode themes
+```
+
+Shows built-in themes first, then the full Shiki theme catalog.
+
+## Animations
+
+- `morph`: smooth transition between snapshots
+- `typewriter`: character reveal with cursor
+- `cascade`: line-by-line reveal with stagger
+
+## Roadmap
+
+Current focus: Phase 1 MVP CLI completion (themes, brand kit, docs polish), then monorepo + web in Phase 2.
+
+## Contributing
+
+```bash
+bun install
+bun run lint
+bun run typecheck
+```
+
+## License
+
+MIT

package/framecode.schema.json

@@ -0,0 +1,154 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "type": "object",
+  "definitions": {
+    "animation": {
+      "type": "string",
+      "enum": [
+        "morph",
+        "typewriter",
+        "cascade"
+      ],
+      "default": "morph"
+    },
+    "stepConfig": {
+      "type": "object",
+      "properties": {
+        "file": {
+          "type": "string",
+          "description": "Filename to match (exact match)"
+        },
+        "animation": {
+          "$ref": "#/definitions/animation",
+          "description": "Animation style override for this step"
+        },
+        "charsPerSecond": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Characters per second for typewriter animation"
+        }
+      },
+      "required": [
+        "file"
+      ],
+      "additionalProperties": false
+    },
+    "brand": {
+      "type": "object",
+      "properties": {
+        "logo": {
+          "type": "string",
+          "description": "Logo source URL, data URL, or local file path"
+        },
+        "twitter": {
+          "type": "string",
+          "description": "Twitter/X handle watermark"
+        },
+        "website": {
+          "type": "string",
+          "description": "Website watermark"
+        },
+        "accent": {
+          "type": "string",
+          "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$",
+          "description": "Brand accent color (#RGB or #RRGGBB)"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "properties": {
+    "theme": {
+      "type": "string",
+      "enum": [
+        "vercel-dark",
+        "story-gradients",
+        "retro-terminal",
+        "github-dark",
+        "github-light",
+        "nord",
+        "dracula",
+        "monokai",
+        "tokyo-night",
+        "catppuccin-mocha",
+        "rose-pine",
+        "synthwave-84",
+        "material-theme-darker",
+        "one-dark-pro",
+        "vitesse-dark",
+        "vitesse-light",
+        "min-dark",
+        "min-light",
+        "night-owl",
+        "ayu-dark",
+        "gruvbox-dark-medium",
+        "gruvbox-light-medium",
+        "everforest-dark",
+        "everforest-light",
+        "kanagawa-wave",
+        "rose-pine-moon",
+        "rose-pine-dawn",
+        "catppuccin-latte",
+        "catppuccin-frappe",
+        "catppuccin-macchiato",
+        "github-dark-dimmed",
+        "github-dark-high-contrast",
+        "github-light-high-contrast",
+        "dark-plus",
+        "light-plus",
+        "poimandres",
+        "slack-dark",
+        "one-light",
+        "material-theme-lighter",
+        "material-theme-ocean",
+        "material-theme-palenight",
+        "dracula-soft",
+        "houston"
+      ],
+      "default": "vercel-dark"
+    },
+    "preset": {
+      "type": "string",
+      "enum": [
+        "post",
+        "tutorial",
+        "square"
+      ],
+      "default": "tutorial"
+    },
+    "animation": {
+      "$ref": "#/definitions/animation"
+    },
+    "charsPerSecond": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 30,
+      "description": "Global characters per second for typewriter animation"
+    },
+    "fps": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 120,
+      "default": 30
+    },
+    "width": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "height": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "brand": {
+      "$ref": "#/definitions/brand"
+    },
+    "stepConfigs": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/stepConfig"
+      },
+      "description": "Per-step animation configuration overrides"
+    }
+  },
+  "additionalProperties": false
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "framecode",
+  "version": "1.0.0",
+  "private": false,
+  "description": "CLI-first video generator that turns code snippets into videos",
+  "license": "MIT",
+  "author": "Esau Morais <esaumorais7@gmail.com> (https://emots.dev)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/esau-morais/framecode.git"
+  },
+  "bin": {
+    "framecode": "src/cli/index.ts"
+  },
+  "files": [
+    "framecode.schema.json",
+    "src"
+  ],
+  "type": "module",
+  "module": "src/index.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "remotion studio",
+    "build": "remotion bundle",
+    "upgrade": "remotion upgrade",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint",
+    "lint:fix": "oxfmt",
+    "prepublishOnly": "bun run typecheck && bun run lint && bun run build"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.0.0-alpha.9",
+    "@remotion/bundler": "4.0.399",
+    "@remotion/cli": "4.0.399",
+    "@remotion/google-fonts": "4.0.399",
+    "@remotion/layout-utils": "4.0.399",
+    "@remotion/renderer": "4.0.399",
+    "@remotion/studio": "4.0.399",
+    "@remotion/tailwind-v4": "^4.0.399",
+    "chalk": "^5.6.2",
+    "codehike": "1.0.7",
+    "commander": "^14.0.2",
+    "polished": "4.3.1",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "remotion": "4.0.399",
+    "shiki": "^3.20.0",
+    "tailwindcss": "^4.1.18",
+    "twoslash": "^0.3.6",
+    "zod": "3.22.3"
+  },
+  "devDependencies": {
+    "@remotion/eslint-plugin": "^4.0.399",
+    "@types/bun": "^1.3.5",
+    "@types/react": "19.2.7",
+    "@types/web": "0.0.312",
+    "oxfmt": "^0.22.0",
+    "oxlint": "^1.36.0",
+    "typescript": "5.9.3"
+  }
+}

package/src/BrandOverlay.tsx

@@ -0,0 +1,129 @@
+import React, { useMemo } from "react";
+import { Img, staticFile } from "remotion";
+import { horizontalPadding } from "./font";
+import { useThemeColors } from "./calculate-metadata/theme";
+import type { BrandConfig } from "./calculate-metadata/schema";
+
+function normalizeHandle(handle?: string): string | null {
+  if (!handle) {
+    return null;
+  }
+
+  const trimmed = handle.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  return trimmed.startsWith("@") ? trimmed : `@${trimmed}`;
+}
+
+function normalizeWebsite(website?: string): string | null {
+  if (!website) {
+    return null;
+  }
+
+  const trimmed = website.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  return trimmed.replace(/^https?:\/\//i, "");
+}
+
+function resolveLogoSource(logo: string): string {
+  if (/^(https?:)?\/\//i.test(logo) || logo.startsWith("data:")) {
+    return logo;
+  }
+
+  const normalizedPath = logo.replaceAll("\\", "/").replace(/^\//, "");
+  return staticFile(normalizedPath);
+}
+
+export function BrandOverlay({ brand }: { readonly brand?: BrandConfig }) {
+  const themeColors = useThemeColors();
+
+  const handle = normalizeHandle(brand?.twitter);
+  const website = normalizeWebsite(brand?.website);
+  const logo = brand?.logo?.trim() ? resolveLogoSource(brand.logo) : null;
+
+  const hasTopLeft = Boolean(logo || website);
+  const hasBottomRight = Boolean(handle);
+
+  if (!hasTopLeft && !hasBottomRight) {
+    return null;
+  }
+
+  const accent = brand?.accent ?? themeColors.icon.foreground;
+
+  const chipStyle = useMemo<React.CSSProperties>(
+    () => ({
+      border: `1px solid ${accent}`,
+      backgroundColor: "rgba(0, 0, 0, 0.58)",
+      color: themeColors.foreground,
+      borderRadius: 999,
+      padding: "8px 14px",
+      fontSize: 26,
+      lineHeight: 1,
+      letterSpacing: 0.2,
+      fontWeight: 600,
+      textShadow: "0 2px 8px rgba(0, 0, 0, 0.5)",
+    }),
+    [accent, themeColors.foreground],
+  );
+
+  return (
+    <>
+      {hasTopLeft ? (
+        <div
+          style={{
+            position: "absolute",
+            top: 32,
+            left: horizontalPadding,
+            display: "flex",
+            alignItems: "center",
+            gap: 12,
+            pointerEvents: "none",
+          }}
+        >
+          {logo ? (
+            <div
+              style={{
+                width: 52,
+                height: 52,
+                borderRadius: 12,
+                border: `1px solid ${accent}`,
+                backgroundColor: "rgba(0, 0, 0, 0.58)",
+                display: "flex",
+                alignItems: "center",
+                justifyContent: "center",
+                overflow: "hidden",
+              }}
+            >
+              <Img
+                src={logo}
+                style={{
+                  width: "80%",
+                  height: "80%",
+                  objectFit: "contain",
+                }}
+              />
+            </div>
+          ) : null}
+          {website ? <span style={chipStyle}>{website}</span> : null}
+        </div>
+      ) : null}
+      {hasBottomRight ? (
+        <div
+          style={{
+            position: "absolute",
+            right: horizontalPadding,
+            bottom: 32,
+            pointerEvents: "none",
+          }}
+        >
+          <span style={chipStyle}>{handle}</span>
+        </div>
+      ) : null}
+    </>
+  );
+}

package/src/CascadeTransition.tsx

@@ -0,0 +1,88 @@
+import { useMemo, useCallback } from "react";
+import { interpolate, spring, useCurrentFrame, useVideoConfig } from "remotion";
+import {
+  Pre,
+  HighlightedCode,
+  AnnotationHandler,
+  InnerLine,
+} from "codehike/code";
+import { fontFamily, fontSize as baseFontSize, tabSize } from "./font";
+import { useMarkHandler } from "./annotations/Mark";
+import { useFocusHandler } from "./annotations/Focus";
+
+type TimingMode = "spring" | "linear";
+
+export function CascadeTransition({
+  code,
+  staggerDelay = 3,
+  timing = "spring",
+  fontSize,
+}: {
+  readonly code: HighlightedCode;
+  readonly staggerDelay?: number;
+  readonly timing?: TimingMode;
+  readonly fontSize?: number;
+}) {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+
+  const getLineProgress = useCallback(
+    (lineNum: number) => {
+      const delay = (lineNum - 1) * staggerDelay;
+      return timing === "spring"
+        ? spring({ frame, fps, delay, config: { damping: 20, stiffness: 100 } })
+        : interpolate(frame, [delay, delay + 15], [0, 1], {
+            extrapolateLeft: "clamp",
+            extrapolateRight: "clamp",
+          });
+    },
+    [frame, fps, staggerDelay, timing],
+  );
+
+  const cascadeHandler: AnnotationHandler = useMemo(
+    () => ({
+      name: "cascade",
+      Line: (props) => {
+        const progress = getLineProgress(props.lineNumber);
+        const translateY = interpolate(progress, [0, 1], [10, 0]);
+
+        return (
+          <InnerLine
+            merge={props}
+            style={{
+              opacity: progress,
+              transform: `translate3d(0, ${translateY}px, 0)`,
+              display: "block",
+              willChange: "transform, opacity",
+              backfaceVisibility: "hidden",
+            }}
+          />
+        );
+      },
+    }),
+    [getLineProgress],
+  );
+
+  const markHandler = useMarkHandler(getLineProgress);
+
+  const focusHandler = useFocusHandler(code);
+
+  const handlers = useMemo(
+    () => [cascadeHandler, markHandler, focusHandler],
+    [cascadeHandler, markHandler, focusHandler],
+  );
+
+  const style: React.CSSProperties = useMemo(
+    () => ({
+      fontSize: fontSize ?? baseFontSize,
+      lineHeight: 1.5,
+      fontFamily,
+      tabSize,
+      margin: 0,
+      whiteSpace: "pre",
+    }),
+    [fontSize],
+  );
+
+  return <Pre code={code} handlers={handlers} style={style} />;
+}

package/src/CodeTransition.tsx

@@ -0,0 +1,103 @@
+import { Easing, interpolate, useDelayRender, useCurrentFrame } from "remotion";
+import { Pre, HighlightedCode, AnnotationHandler } from "codehike/code";
+import React, { useEffect, useLayoutEffect, useMemo, useState } from "react";
+import {
+  calculateTransitions,
+  getStartingSnapshot,
+  TokenTransitionsSnapshot,
+} from "codehike/utils/token-transitions";
+import { applyStyle } from "./utils";
+import { callout } from "./annotations/Callout";
+import { useMorphMarkHandler } from "./annotations/Mark";
+import { useFocusHandler } from "./annotations/Focus";
+import { tokenTransitions } from "./annotations/InlineToken";
+import { errorInline, errorMessage } from "./annotations/Error";
+import { fontFamily, fontSize as baseFontSize, tabSize } from "./font";
+
+export function CodeTransition({
+  oldCode,
+  newCode,
+  durationInFrames = 30,
+  fontSize,
+}: {
+  readonly oldCode: HighlightedCode | null;
+  readonly newCode: HighlightedCode;
+  readonly durationInFrames?: number;
+  readonly fontSize?: number;
+}) {
+  const frame = useCurrentFrame();
+
+  const ref = React.useRef<HTMLPreElement>(null);
+  const [oldSnapshot, setOldSnapshot] =
+    useState<TokenTransitionsSnapshot | null>(null);
+  const { delayRender, continueRender } = useDelayRender();
+  const [handle] = React.useState(() => delayRender());
+
+  const prevCode: HighlightedCode = useMemo(() => {
+    return oldCode || { ...newCode, tokens: [], annotations: [] };
+  }, [newCode, oldCode]);
+
+  const code = useMemo(() => {
+    return oldSnapshot ? newCode : prevCode;
+  }, [newCode, prevCode, oldSnapshot]);
+
+  useEffect(() => {
+    if (!oldSnapshot) {
+      setOldSnapshot(getStartingSnapshot(ref.current!));
+    }
+  }, [oldSnapshot]);
+
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  useLayoutEffect(() => {
+    if (!oldSnapshot) {
+      setOldSnapshot(getStartingSnapshot(ref.current!));
+      return;
+    }
+    const transitions = calculateTransitions(ref.current!, oldSnapshot);
+    transitions.forEach(({ element, keyframes, options }) => {
+      const delay = durationInFrames * options.delay;
+      const duration = durationInFrames * options.duration;
+      const linearProgress = interpolate(
+        frame,
+        [delay, delay + duration],
+        [0, 1],
+        { extrapolateLeft: "clamp", extrapolateRight: "clamp" },
+      );
+      const progress = interpolate(linearProgress, [0, 1], [0, 1], {
+        easing: Easing.bezier(0.17, 0.67, 0.76, 0.91),
+      });
+
+      applyStyle({ element, keyframes, progress, linearProgress });
+    });
+    continueRender(handle);
+  });
+
+  const markHandler = useMorphMarkHandler();
+
+  const focusHandler = useFocusHandler(newCode);
+
+  const handlers: AnnotationHandler[] = useMemo(
+    () => [
+      tokenTransitions,
+      markHandler,
+      focusHandler,
+      callout,
+      errorInline,
+      errorMessage,
+    ],
+    [markHandler, focusHandler],
+  );
+
+  const style: React.CSSProperties = useMemo(
+    () => ({
+      position: "relative",
+      fontSize: fontSize ?? baseFontSize,
+      lineHeight: 1.5,
+      fontFamily,
+      tabSize,
+    }),
+    [fontSize],
+  );
+
+  return <Pre ref={ref} code={code} handlers={handlers} style={style} />;
+}