@contractspec/lib.video-gen 1.42.0

package/dist/design/layouts.d.ts

@@ -0,0 +1,69 @@
+import type { VideoFormat } from '@contractspec/lib.contracts-integrations/integrations/providers/video';
+import { VIDEO_FORMATS } from '@contractspec/lib.contracts-integrations/integrations/providers/video';
+export { VIDEO_FORMATS };
+/** Standard FPS for all video output. */
+export declare const DEFAULT_FPS = 30;
+/**
+ * Padding and safe zones for text content within video frames.
+ * Values are in pixels for 1920x1080; scale proportionally for other formats.
+ */
+export declare const videoSafeZone: {
+    /** Horizontal padding from edges */
+    readonly horizontal: 120;
+    /** Vertical padding from edges */
+    readonly vertical: 80;
+    /** Content area width (1920 - 2 * 120) */
+    readonly contentWidth: 1680;
+    /** Content area height (1080 - 2 * 80) */
+    readonly contentHeight: 920;
+};
+/**
+ * Scale safe zone values for a target format.
+ */
+export declare function scaleSafeZone(format: VideoFormat): {
+    horizontal: number;
+    vertical: number;
+    contentWidth: number;
+    contentHeight: number;
+};
+/**
+ * Common layout positions within a 1920x1080 frame.
+ * Use with absolute positioning in compositions.
+ */
+export declare const videoPositions: {
+    /** Centered content */
+    readonly center: {
+        readonly x: 960;
+        readonly y: 540;
+    };
+    /** Top-left content area start */
+    readonly topLeft: {
+        readonly x: 120;
+        readonly y: 80;
+    };
+    /** Top-right content area end */
+    readonly topRight: {
+        readonly x: 1800;
+        readonly y: 80;
+    };
+    /** Bottom-left */
+    readonly bottomLeft: {
+        readonly x: 120;
+        readonly y: 1000;
+    };
+    /** Bottom-right (for logos, watermarks) */
+    readonly bottomRight: {
+        readonly x: 1800;
+        readonly y: 1000;
+    };
+    /** Bottom center (for captions) */
+    readonly bottomCenter: {
+        readonly x: 960;
+        readonly y: 960;
+    };
+};
+/**
+ * Get all format variants for a given primary format.
+ * Returns landscape, square, and portrait variants.
+ */
+export declare function getAllFormatVariants(): VideoFormat[];

package/dist/design/layouts.js

@@ -0,0 +1,45 @@
+// @bun
+var __require = import.meta.require;
+
+// src/design/layouts.ts
+import { VIDEO_FORMATS } from "@contractspec/lib.contracts-integrations/integrations/providers/video";
+var DEFAULT_FPS = 30;
+var videoSafeZone = {
+  horizontal: 120,
+  vertical: 80,
+  contentWidth: 1680,
+  contentHeight: 920
+};
+function scaleSafeZone(format) {
+  const scaleX = format.width / 1920;
+  const scaleY = format.height / 1080;
+  return {
+    horizontal: Math.round(videoSafeZone.horizontal * scaleX),
+    vertical: Math.round(videoSafeZone.vertical * scaleY),
+    contentWidth: Math.round(videoSafeZone.contentWidth * scaleX),
+    contentHeight: Math.round(videoSafeZone.contentHeight * scaleY)
+  };
+}
+var videoPositions = {
+  center: { x: 960, y: 540 },
+  topLeft: { x: 120, y: 80 },
+  topRight: { x: 1800, y: 80 },
+  bottomLeft: { x: 120, y: 1000 },
+  bottomRight: { x: 1800, y: 1000 },
+  bottomCenter: { x: 960, y: 960 }
+};
+function getAllFormatVariants() {
+  return [
+    VIDEO_FORMATS.landscape,
+    VIDEO_FORMATS.square,
+    VIDEO_FORMATS.portrait
+  ];
+}
+export {
+  videoSafeZone,
+  videoPositions,
+  scaleSafeZone,
+  getAllFormatVariants,
+  VIDEO_FORMATS,
+  DEFAULT_FPS
+};

package/dist/design/motion.d.ts

@@ -0,0 +1,72 @@
+import { Easing } from 'remotion';
+/**
+ * Easing functions for video animations.
+ * Remotion's interpolate() accepts these directly.
+ */
+export declare const videoEasing: {
+    /** Smooth entrance -- objects appearing */
+    readonly entrance: (t: number) => number;
+    /** Smooth exit -- objects disappearing */
+    readonly exit: (t: number) => number;
+    /** Emphasis/bounce -- drawing attention */
+    readonly emphasis: (t: number) => number;
+    /** Linear -- constant speed (progress bars, typing) */
+    readonly linear: typeof Easing.linear;
+    /** Gentle ease -- subtle movements */
+    readonly gentle: (t: number) => number;
+    /** Spring-like -- playful movements */
+    readonly spring: (t: number) => number;
+};
+/**
+ * Standard durations in frames.
+ * All values assume 30fps unless noted.
+ */
+export declare const videoDurations: {
+    /** Scene transition (fade, slide, etc.) */
+    readonly sceneTransition: 20;
+    /** Text entrance animation */
+    readonly textEntrance: 15;
+    /** Text exit animation */
+    readonly textExit: 12;
+    /** Code typing speed (frames per character) */
+    readonly codeTypingPerChar: 2;
+    /** Pause after a section/concept */
+    readonly sectionPause: 30;
+    /** Brief pause for emphasis */
+    readonly emphasisPause: 15;
+    /** Logo/brand reveal */
+    readonly brandReveal: 25;
+    /** Minimum scene duration */
+    readonly minScene: 60;
+    /** Standard short scene (2s) */
+    readonly shortScene: 60;
+    /** Standard medium scene (4s) */
+    readonly mediumScene: 120;
+    /** Standard long scene (8s) */
+    readonly longScene: 240;
+};
+/**
+ * Pre-built transition configurations for scene-to-scene transitions.
+ */
+export declare const videoTransitions: {
+    readonly fade: {
+        readonly type: "fade";
+        readonly durationInFrames: 20;
+    };
+    readonly slideLeft: {
+        readonly type: "slide-left";
+        readonly durationInFrames: 20;
+    };
+    readonly slideRight: {
+        readonly type: "slide-right";
+        readonly durationInFrames: 20;
+    };
+    readonly wipe: {
+        readonly type: "wipe";
+        readonly durationInFrames: 15;
+    };
+    readonly none: {
+        readonly type: "none";
+        readonly durationInFrames: 0;
+    };
+};

package/dist/design/motion.js

@@ -0,0 +1,38 @@
+// @bun
+var __require = import.meta.require;
+
+// src/design/motion.ts
+import { Easing } from "remotion";
+var videoEasing = {
+  entrance: Easing.out(Easing.exp),
+  exit: Easing.in(Easing.exp),
+  emphasis: Easing.out(Easing.back(1.4)),
+  linear: Easing.linear,
+  gentle: Easing.bezier(0.25, 0.1, 0.25, 1),
+  spring: Easing.out(Easing.back(1.7))
+};
+var videoDurations = {
+  sceneTransition: 20,
+  textEntrance: 15,
+  textExit: 12,
+  codeTypingPerChar: 2,
+  sectionPause: 30,
+  emphasisPause: 15,
+  brandReveal: 25,
+  minScene: 60,
+  shortScene: 60,
+  mediumScene: 120,
+  longScene: 240
+};
+var videoTransitions = {
+  fade: { type: "fade", durationInFrames: 20 },
+  slideLeft: { type: "slide-left", durationInFrames: 20 },
+  slideRight: { type: "slide-right", durationInFrames: 20 },
+  wipe: { type: "wipe", durationInFrames: 15 },
+  none: { type: "none", durationInFrames: 0 }
+};
+export {
+  videoTransitions,
+  videoEasing,
+  videoDurations
+};

package/dist/design/tokens.d.ts

@@ -0,0 +1,31 @@
+import type { ThemeTokens } from '@contractspec/lib.design-system';
+import { defaultTokens } from '@contractspec/lib.design-system';
+export type { ThemeTokens };
+export { defaultTokens };
+/**
+ * Video-specific color extensions built on top of brand tokens.
+ */
+export interface VideoColorTokens {
+    /** Background for video frames (may differ from web background) */
+    canvasBackground: string;
+    /** Code block background */
+    codeBackground: string;
+    /** Terminal background */
+    terminalBackground: string;
+    /** Terminal text color */
+    terminalForeground: string;
+    /** Highlight / emphasis color */
+    highlight: string;
+    /** Gradient start (for branded backgrounds) */
+    gradientStart: string;
+    /** Gradient end */
+    gradientEnd: string;
+}
+export declare const defaultVideoColors: VideoColorTokens;
+/**
+ * Combine brand tokens with video color extensions.
+ */
+export interface VideoThemeTokens extends ThemeTokens {
+    video: VideoColorTokens;
+}
+export declare const defaultVideoTheme: VideoThemeTokens;

package/dist/design/tokens.js

@@ -0,0 +1,23 @@
+// @bun
+var __require = import.meta.require;
+
+// src/design/tokens.ts
+import { defaultTokens } from "@contractspec/lib.design-system";
+var defaultVideoColors = {
+  canvasBackground: defaultTokens.colors.background,
+  codeBackground: "#1e1e2e",
+  terminalBackground: "#0d1117",
+  terminalForeground: "#c9d1d9",
+  highlight: defaultTokens.colors.accent,
+  gradientStart: defaultTokens.colors.primary,
+  gradientEnd: defaultTokens.colors.accent
+};
+var defaultVideoTheme = {
+  ...defaultTokens,
+  video: defaultVideoColors
+};
+export {
+  defaultVideoTheme,
+  defaultVideoColors,
+  defaultTokens
+};

package/dist/design/typography.d.ts

@@ -0,0 +1,61 @@
+export interface VideoTypeStyle {
+    fontSize: number;
+    lineHeight: number;
+    fontWeight: number;
+    letterSpacing?: number;
+}
+/**
+ * Typography scale for 1920x1080 (landscape) videos.
+ * Scale down proportionally for smaller formats.
+ */
+export declare const videoTypography: {
+    /** Main title -- large, bold */
+    readonly title: {
+        readonly fontSize: 72;
+        readonly lineHeight: 1.1;
+        readonly fontWeight: 700;
+        readonly letterSpacing: -1;
+    };
+    /** Section heading */
+    readonly heading: {
+        readonly fontSize: 56;
+        readonly lineHeight: 1.2;
+        readonly fontWeight: 600;
+        readonly letterSpacing: -0.5;
+    };
+    /** Subheading */
+    readonly subheading: {
+        readonly fontSize: 40;
+        readonly lineHeight: 1.25;
+        readonly fontWeight: 500;
+    };
+    /** Body text */
+    readonly body: {
+        readonly fontSize: 32;
+        readonly lineHeight: 1.5;
+        readonly fontWeight: 400;
+    };
+    /** Code / monospace text */
+    readonly code: {
+        readonly fontSize: 28;
+        readonly lineHeight: 1.6;
+        readonly fontWeight: 400;
+    };
+    /** Small caption text */
+    readonly caption: {
+        readonly fontSize: 24;
+        readonly lineHeight: 1.4;
+        readonly fontWeight: 400;
+    };
+    /** Badge / label text */
+    readonly label: {
+        readonly fontSize: 20;
+        readonly lineHeight: 1.3;
+        readonly fontWeight: 600;
+        readonly letterSpacing: 1;
+    };
+};
+/**
+ * Scale typography for a target width relative to 1920px landscape.
+ */
+export declare function scaleTypography(style: VideoTypeStyle, targetWidth: number): VideoTypeStyle;

package/dist/design/typography.js

@@ -0,0 +1,56 @@
+// @bun
+var __require = import.meta.require;
+
+// src/design/typography.ts
+var videoTypography = {
+  title: {
+    fontSize: 72,
+    lineHeight: 1.1,
+    fontWeight: 700,
+    letterSpacing: -1
+  },
+  heading: {
+    fontSize: 56,
+    lineHeight: 1.2,
+    fontWeight: 600,
+    letterSpacing: -0.5
+  },
+  subheading: {
+    fontSize: 40,
+    lineHeight: 1.25,
+    fontWeight: 500
+  },
+  body: {
+    fontSize: 32,
+    lineHeight: 1.5,
+    fontWeight: 400
+  },
+  code: {
+    fontSize: 28,
+    lineHeight: 1.6,
+    fontWeight: 400
+  },
+  caption: {
+    fontSize: 24,
+    lineHeight: 1.4,
+    fontWeight: 400
+  },
+  label: {
+    fontSize: 20,
+    lineHeight: 1.3,
+    fontWeight: 600,
+    letterSpacing: 1
+  }
+};
+function scaleTypography(style, targetWidth) {
+  const scale = targetWidth / 1920;
+  return {
+    ...style,
+    fontSize: Math.round(style.fontSize * scale),
+    letterSpacing: style.letterSpacing ? Math.round(style.letterSpacing * scale * 10) / 10 : undefined
+  };
+}
+export {
+  videoTypography,
+  scaleTypography
+};

package/dist/docs/compositions.docblock.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/docs/compositions.docblock.js

@@ -0,0 +1,183 @@
+// @bun
+// src/docs/compositions.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts-spec/docs";
+var compositionsDocBlocks = [
+  {
+    id: "docs.video-gen.compositions",
+    title: "Video Compositions & Primitives",
+    summary: "Remotion composition components and reusable primitives for building programmatic videos.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/video-gen/compositions",
+    tags: ["video", "remotion", "compositions", "primitives", "react"],
+    owners: ["@contractspec/lib.video-gen"],
+    body: `# Video Compositions & Primitives
+
+Compositions are React components rendered by Remotion. They use \`useCurrentFrame()\`, \`useVideoConfig()\`, and \`interpolate()\` to produce frame-accurate animations. All compositions must be **deterministic**: same props = same visual output.
+
+## Primitive Components
+
+Primitives are reusable building blocks for constructing full compositions.
+
+\`\`\`ts
+import {
+  AnimatedText,
+  CodeBlock,
+  Terminal,
+  BrandFrame,
+  ProgressBar,
+  SceneTransitionWrapper,
+} from "@contractspec/lib.video-gen/compositions/primitives";
+\`\`\`
+
+### AnimatedText
+
+Text with entrance/exit slide + fade animations.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| \`text\` | \`string\` | -- | Text content |
+| \`variant\` | \`keyof videoTypography\` | \`"body"\` | Typography preset (title, heading, subheading, body, code, caption, label) |
+| \`enterAt\` | \`number\` | \`0\` | Frame at which text enters |
+| \`exitAt\` | \`number\` | -- | Frame at which text exits (omit to keep visible) |
+| \`color\` | \`string\` | \`"#ffffff"\` | Text color |
+| \`align\` | \`"left" \\| "center" \\| "right"\` | \`"left"\` | Text alignment |
+
+### CodeBlock
+
+Syntax-aware code display with typing animation and macOS-style title bar.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| \`code\` | \`string\` | -- | Code string to display |
+| \`language\` | \`string\` | \`"typescript"\` | Language label in the title bar |
+| \`startAt\` | \`number\` | \`0\` | Frame at which typing starts |
+| \`typeAnimation\` | \`boolean\` | \`true\` | Animate character-by-character typing |
+| \`filename\` | \`string\` | -- | Filename in the title bar (overrides language) |
+
+### Terminal
+
+CLI simulator with command typing, output lines, and cursor animation.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| \`lines\` | \`TerminalLine[]\` | -- | Lines to display in sequence |
+| \`startAt\` | \`number\` | \`0\` | Frame at which terminal appears |
+| \`prompt\` | \`string\` | \`"$ "\` | Prompt string before commands |
+| \`title\` | \`string\` | \`"Terminal"\` | Title bar text |
+| \`typingSpeed\` | \`number\` | \`2\` | Frames per character for commands |
+
+\`TerminalLine\` types: \`command\` (typed), \`output\` (faded in), \`error\` (red), \`success\` (green), \`comment\` (dimmed with \`#\` prefix).
+
+### BrandFrame
+
+Branded container with safe-zone padding, gradient/solid/dark backgrounds, and optional watermark.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| \`variant\` | \`"solid" \\| "gradient" \\| "dark"\` | \`"gradient"\` | Background style |
+| \`showBranding\` | \`boolean\` | \`true\` | Show "ContractSpec" watermark |
+| \`animateEntrance\` | \`boolean\` | \`true\` | Fade-in on first frames |
+| \`styleOverrides\` | \`VideoStyleOverrides\` | -- | Override colors, fonts, dark mode |
+
+### ProgressBar
+
+Thin progress indicator at the top or bottom of the frame.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| \`height\` | \`number\` | \`4\` | Bar height in pixels |
+| \`color\` | \`string\` | primary color | Bar fill color |
+| \`position\` | \`"top" \\| "bottom"\` | \`"bottom"\` | Placement |
+
+### SceneTransitionWrapper
+
+Wraps children with entrance/exit transitions (fade, slide-left, slide-right, wipe).
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| \`type\` | \`SceneTransitionType\` | -- | Transition type |
+| \`durationInFrames\` | \`number\` | -- | Transition duration |
+| \`direction\` | \`"in" \\| "out"\` | -- | Entering or exiting |
+
+## Full Compositions
+
+Full compositions combine primitives into complete video templates. They are registered in Remotion Studio via \`RemotionRoot\`.
+
+### ApiOverview
+
+Visualizes a ContractSpec definition generating a full API surface. Used for homepage demos and documentation.
+
+\`\`\`tsx
+import { ApiOverview } from "@contractspec/lib.video-gen/compositions/api-overview";
+
+<ApiOverview
+  specName="CreateUser"
+  method="POST"
+  endpoint="/api/users"
+  specCode={\`export const createUser = defineCommand({...})\`}
+  generatedOutputs={["REST Endpoint", "GraphQL Mutation", "Prisma Model"]}
+  tagline="One spec. Every surface."
+/>
+\`\`\`
+
+**Scenes**: Title + method badge -> Code typing animation -> Generated outputs fan-out -> Tagline.
+
+### SocialClip
+
+Short-form marketing content for LinkedIn, X, YouTube Shorts. Adapts layout for landscape (16:9), square (1:1), and portrait (9:16).
+
+\`\`\`tsx
+import { SocialClip } from "@contractspec/lib.video-gen/compositions/social-clip";
+
+<SocialClip
+  hook="Stop rewriting the same API logic."
+  message="Generate REST, GraphQL, DB, SDK from a single spec."
+  points={["Deterministic output", "Fully ejectable", "No lock-in"]}
+  cta="Try ContractSpec"
+  ctaUrl="contractspec.dev"
+/>
+\`\`\`
+
+**Scenes**: Hook (attention grabber) -> Main message -> Supporting points -> CTA button.
+
+### TerminalDemo
+
+CLI command walkthrough with animated terminal. Used in documentation and tutorial videos.
+
+\`\`\`tsx
+import { TerminalDemo } from "@contractspec/lib.video-gen/compositions/terminal-demo";
+
+<TerminalDemo
+  title="Getting Started with ContractSpec"
+  subtitle="Define once, generate everything."
+  lines={[
+    { type: "command", text: "npx contractspec init my-api" },
+    { type: "output", text: "Created my-api/ with 3 sample contracts" },
+    { type: "command", text: "npx contractspec build" },
+    { type: "success", text: "Built 3 contracts -> 18 generated files" },
+  ]}
+  summary="Ship faster. Stay coherent."
+/>
+\`\`\`
+
+**Scenes**: Title + subtitle -> Terminal typing animation -> Summary.
+
+## Creating New Compositions
+
+1. Create a new \`.tsx\` file in \`src/compositions/\`.
+2. Use primitives from \`./primitives/\` and design tokens from \`../design/\`.
+3. Use \`useCurrentFrame()\` and \`interpolate()\` for frame-based animations.
+4. Register in \`src/remotion/Root.tsx\` with a \`<Composition>\` entry.
+5. Export from \`src/compositions/index.ts\`.
+6. Add the export path to \`package.json\` (both workspace and publishConfig).
+
+### Guardrails
+
+- Keep compositions **pure**: no side effects, no network calls, no randomness.
+- Use \`scaleSafeZone()\` and \`scaleTypography()\` to support multiple formats.
+- All timing should be frame-based (not time-based) for deterministic output.
+`
+  }
+];
+registerDocBlocks(compositionsDocBlocks);

package/dist/docs/design.docblock.d.ts

@@ -0,0 +1 @@
+export {};