@contractspec/lib.video-gen 1.42.0

package/dist/docs/design.docblock.js

@@ -0,0 +1,188 @@
+// @bun
+// src/docs/design.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts-spec/docs";
+var designDocBlocks = [
+  {
+    id: "docs.video-gen.design",
+    title: "Video Design System",
+    summary: "Design tokens, motion primitives, typography scale, and layout system optimized for programmatic video.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/video-gen/design",
+    tags: ["video", "design-tokens", "motion", "typography", "layout"],
+    owners: ["@contractspec/lib.video-gen"],
+    body: `# Video Design System
+
+The design layer bridges \`@contractspec/lib.design-system\` brand tokens with video-specific extensions for motion, typography, and spatial layout. All values are optimized for 1920x1080 (landscape) and scale proportionally for other formats.
+
+\`\`\`ts
+import {
+  defaultVideoTheme,
+  videoEasing,
+  videoDurations,
+  videoTypography,
+  videoSafeZone,
+  scaleSafeZone,
+} from "@contractspec/lib.video-gen/design";
+\`\`\`
+
+## Tokens
+
+### Brand Bridge
+
+\`VideoThemeTokens\` extends the design-system \`ThemeTokens\` with a \`video\` namespace for video-specific colors:
+
+\`\`\`ts
+import { defaultVideoTheme } from "@contractspec/lib.video-gen/design/tokens";
+
+// Brand tokens (from @contractspec/lib.design-system)
+defaultVideoTheme.colors.primary;    // brand primary
+defaultVideoTheme.colors.accent;     // brand accent
+
+// Video-specific extensions
+defaultVideoTheme.video.canvasBackground;    // frame background
+defaultVideoTheme.video.codeBackground;      // "#1e1e2e"
+defaultVideoTheme.video.terminalBackground;  // "#0d1117"
+defaultVideoTheme.video.terminalForeground;  // "#c9d1d9"
+defaultVideoTheme.video.highlight;           // accent color
+defaultVideoTheme.video.gradientStart;       // primary
+defaultVideoTheme.video.gradientEnd;         // accent
+\`\`\`
+
+> Do not duplicate brand color values. Import and extend from \`@contractspec/lib.design-system\`.
+
+## Motion
+
+### Easing Functions
+
+Pre-configured easing curves for use with Remotion's \`interpolate()\`:
+
+| Key | Easing | Use Case |
+|-----|--------|----------|
+| \`entrance\` | \`Easing.out(Easing.exp)\` | Objects appearing |
+| \`exit\` | \`Easing.in(Easing.exp)\` | Objects disappearing |
+| \`emphasis\` | \`Easing.out(Easing.back(1.4))\` | Drawing attention, bounce |
+| \`linear\` | \`Easing.linear\` | Progress bars, typing |
+| \`gentle\` | \`Easing.bezier(0.25, 0.1, 0.25, 1)\` | Subtle movements |
+| \`spring\` | \`Easing.out(Easing.back(1.7))\` | Playful movements |
+
+\`\`\`ts
+import { interpolate } from "remotion";
+import { videoEasing } from "@contractspec/lib.video-gen/design/motion";
+
+const opacity = interpolate(frame, [0, 15], [0, 1], {
+  easing: videoEasing.entrance,
+  extrapolateLeft: "clamp",
+  extrapolateRight: "clamp",
+});
+\`\`\`
+
+### Durations (frames at 30fps)
+
+| Key | Frames | Seconds | Use Case |
+|-----|--------|---------|----------|
+| \`sceneTransition\` | 20 | 0.67s | Between scenes |
+| \`textEntrance\` | 15 | 0.5s | Text slide-in |
+| \`textExit\` | 12 | 0.4s | Text slide-out |
+| \`codeTypingPerChar\` | 2 | 0.07s | Code typing speed |
+| \`sectionPause\` | 30 | 1.0s | Pause after concept |
+| \`emphasisPause\` | 15 | 0.5s | Brief emphasis |
+| \`brandReveal\` | 25 | 0.83s | Logo/watermark |
+| \`minScene\` | 60 | 2.0s | Minimum scene length |
+| \`shortScene\` | 60 | 2.0s | Short scene |
+| \`mediumScene\` | 120 | 4.0s | Medium scene |
+| \`longScene\` | 240 | 8.0s | Long scene |
+
+### Transition Presets
+
+\`\`\`ts
+import { videoTransitions } from "@contractspec/lib.video-gen/design/motion";
+
+// { type: "fade", durationInFrames: 20 }
+videoTransitions.fade;
+
+// { type: "slide-left", durationInFrames: 20 }
+videoTransitions.slideLeft;
+\`\`\`
+
+## Typography
+
+### Type Scale (1920x1080 baseline)
+
+| Key | Size | Weight | Use Case |
+|-----|------|--------|----------|
+| \`title\` | 72px | 700 | Main title |
+| \`heading\` | 56px | 600 | Section heading |
+| \`subheading\` | 40px | 500 | Subheading |
+| \`body\` | 32px | 400 | Body text |
+| \`code\` | 28px | 400 | Monospace code |
+| \`caption\` | 24px | 400 | Small caption |
+| \`label\` | 20px | 600 | Badge / label |
+
+### Scaling for Other Formats
+
+Use \`scaleTypography()\` to proportionally scale for non-landscape formats:
+
+\`\`\`ts
+import {
+  videoTypography,
+  scaleTypography,
+} from "@contractspec/lib.video-gen/design/typography";
+
+// Scale heading for 1080x1080 (square)
+const squareHeading = scaleTypography(videoTypography.heading, 1080);
+// -> fontSize: 32, lineHeight: 1.2, fontWeight: 600
+\`\`\`
+
+## Layouts
+
+### Safe Zones
+
+Content-safe padding for text within video frames (1920x1080 baseline):
+
+\`\`\`ts
+import {
+  videoSafeZone,
+  scaleSafeZone,
+} from "@contractspec/lib.video-gen/design/layouts";
+
+videoSafeZone.horizontal;   // 120px
+videoSafeZone.vertical;     // 80px
+videoSafeZone.contentWidth;  // 1680px
+videoSafeZone.contentHeight; // 920px
+
+// Scale for portrait (1080x1920)
+const portrait = scaleSafeZone({ type: "portrait", width: 1080, height: 1920 });
+\`\`\`
+
+### Standard Positions
+
+\`\`\`ts
+import { videoPositions } from "@contractspec/lib.video-gen/design/layouts";
+
+videoPositions.center;       // { x: 960, y: 540 }
+videoPositions.topLeft;      // { x: 120, y: 80 }
+videoPositions.bottomRight;  // { x: 1800, y: 1000 } -- logos, watermarks
+videoPositions.bottomCenter; // { x: 960, y: 960 } -- captions
+\`\`\`
+
+### Format Variants
+
+\`\`\`ts
+import {
+  VIDEO_FORMATS,
+  getAllFormatVariants,
+  DEFAULT_FPS,
+} from "@contractspec/lib.video-gen/design/layouts";
+
+VIDEO_FORMATS.landscape; // { type: "landscape", width: 1920, height: 1080 }
+VIDEO_FORMATS.portrait;  // { type: "portrait",  width: 1080, height: 1920 }
+VIDEO_FORMATS.square;    // { type: "square",    width: 1080, height: 1080 }
+
+getAllFormatVariants();   // [landscape, square, portrait]
+DEFAULT_FPS;             // 30
+\`\`\`
+`
+  }
+];
+registerDocBlocks(designDocBlocks);

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

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

package/dist/docs/generators.docblock.js

@@ -0,0 +1,188 @@
+// @bun
+// src/docs/generators.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts-spec/docs";
+var generatorsDocBlocks = [
+  {
+    id: "docs.video-gen.generators",
+    title: "Video Generation Pipeline",
+    summary: "VideoGenerator, ScenePlanner, and ScriptGenerator -- from content brief to video project with optional LLM enhancement.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/video-gen/generators",
+    tags: [
+      "video",
+      "generators",
+      "scene-planner",
+      "script-generator",
+      "llm",
+      "content-pipeline"
+    ],
+    owners: ["@contractspec/lib.video-gen"],
+    body: `# Video Generation Pipeline
+
+The generators layer converts a \`VideoBrief\` (content brief + video config) into a fully specified \`VideoProject\` (scene graph ready for rendering). It follows the \`@contractspec/lib.content-gen\` pattern: optional LLM, deterministic fallback.
+
+\`\`\`
+VideoBrief
+    |
+    v
+ScenePlanner.plan(brief)       --> ScenePlan (scenes + durations)
+    |
+    v
+ScriptGenerator.generate(brief) --> NarrationScript (text + segments)
+    |
+    v
+VoiceProvider.synthesize(text)  --> AudioTrack (optional)
+    |
+    v
+VideoGenerator.generate(brief)  --> VideoProject (complete scene graph)
+\`\`\`
+
+## VideoGenerator
+
+The main orchestrator. Wires ScenePlanner, ScriptGenerator, and optional VoiceProvider into a single pipeline.
+
+\`\`\`ts
+import { VideoGenerator } from "@contractspec/lib.video-gen/generators";
+import type { VideoBrief } from "@contractspec/lib.video-gen/types";
+
+// Minimal (deterministic, no LLM, no voice)
+const generator = new VideoGenerator({ fps: 30 });
+
+// Full (with LLM for richer scenes + voice narration)
+const generator = new VideoGenerator({
+  llm: myLLMProvider,
+  voice: myVoiceProvider,
+  model: "gpt-4o",
+  temperature: 0.4,
+  defaultVoiceId: "rachel",
+  fps: 30,
+});
+
+const project = await generator.generate(brief);
+\`\`\`
+
+### Pipeline Steps
+
+1. **Scene planning** -- \`ScenePlanner.plan(brief)\` breaks the brief into concrete \`PlannedScene[]\` with composition IDs, props, and durations.
+2. **Script generation** -- If \`brief.narration.enabled\`, \`ScriptGenerator.generate()\` produces a \`NarrationScript\` with per-scene text segments.
+3. **Voice synthesis** -- If a \`VoiceProvider\` is configured and narration is enabled, synthesizes audio via \`voice.synthesize()\`.
+4. **Assembly** -- Combines scenes, audio, and metadata into a \`VideoProject\`.
+
+### Constructor Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| \`llm\` | \`LLMProvider\` | -- | Optional LLM for enhanced generation |
+| \`voice\` | \`VoiceProvider\` | -- | Optional voice synthesis provider |
+| \`model\` | \`string\` | -- | LLM model override |
+| \`temperature\` | \`number\` | \`0.4\` | LLM temperature (lower = more deterministic) |
+| \`defaultVoiceId\` | \`string\` | -- | Default voice for narration |
+| \`fps\` | \`number\` | \`30\` | Frames per second |
+
+## ScenePlanner
+
+Breaks a \`VideoBrief\` into concrete scenes mapped to registered compositions.
+
+\`\`\`ts
+import { ScenePlanner } from "@contractspec/lib.video-gen/generators";
+
+const planner = new ScenePlanner({ fps: 30 });
+const plan = await planner.plan(brief);
+
+plan.scenes;                    // PlannedScene[]
+plan.estimatedDurationSeconds;  // total estimated duration
+plan.narrationScript;           // combined narration text
+\`\`\`
+
+### Deterministic Path (no LLM)
+
+Maps brief sections to \`SocialClip\` compositions:
+
+| Brief Section | Scene | Duration |
+|---------------|-------|----------|
+| \`title\` + \`summary\` | Hook / title | 3s |
+| \`problems\` | Problem statement | 4s |
+| \`solutions\` | Solution showcase | 5s |
+| \`metrics\` | Proof / results | 3s |
+| \`callToAction\` | CTA | 2s |
+
+If \`brief.targetDurationSeconds\` is set, all scene durations are scaled proportionally.
+
+### LLM-Enhanced Path
+
+With an \`LLMProvider\`, the planner sends the brief to the LLM and requests a scene breakdown as JSON. The LLM can choose from \`ApiOverview\`, \`SocialClip\`, or \`TerminalDemo\` compositions. Falls back to deterministic on any failure.
+
+## ScriptGenerator
+
+Produces narration text from a \`ContentBrief\` with style control.
+
+\`\`\`ts
+import { ScriptGenerator } from "@contractspec/lib.video-gen/generators";
+
+const scriptGen = new ScriptGenerator({ temperature: 0.5 });
+const script = await scriptGen.generate(brief.content, brief.narration);
+
+script.fullText;                // complete narration
+script.segments;                // NarrationSegment[] (per-scene text)
+script.estimatedDurationSeconds; // at ~150 words/min
+script.style;                   // "professional" | "casual" | "technical"
+\`\`\`
+
+### Narration Styles
+
+| Style | Tone |
+|-------|------|
+| \`professional\` | Clear, authoritative, concise |
+| \`casual\` | Friendly, conversational, approachable |
+| \`technical\` | Precise, detailed, accurate |
+
+### NarrationSegment
+
+Each segment maps to a scene and provides timing estimates:
+
+\`\`\`ts
+interface NarrationSegment {
+  sceneId: string;                // "intro", "problems", "solutions", "metrics", "cta"
+  text: string;                   // narration text for this segment
+  estimatedDurationSeconds: number; // at ~150 words/min
+}
+\`\`\`
+
+## Input Types
+
+### VideoBrief
+
+\`\`\`ts
+interface VideoBrief {
+  content: ContentBrief;            // from @contractspec/lib.content-gen
+  format: VideoFormat;              // landscape, portrait, square, or custom
+  targetDurationSeconds?: number;   // auto-calculated if omitted
+  narration?: NarrationConfig;      // { enabled, voiceId, language, style }
+  style?: VideoStyleOverrides;      // colors, fonts, dark mode
+  compositionId?: string;           // force a specific composition
+}
+\`\`\`
+
+### PlannedScene
+
+\`\`\`ts
+interface PlannedScene {
+  compositionId: string;            // maps to a registered Remotion composition
+  props: Record<string, unknown>;   // input props for the composition
+  durationInFrames: number;         // scene duration
+  narrationText?: string;           // narrator text for this scene
+  notes?: string;                   // planning notes (LLM path only)
+}
+\`\`\`
+
+## Guardrails
+
+- Generators are **stateless** -- no side effects, no caching. Call \`generate()\` / \`plan()\` for each video.
+- LLM responses are parsed as JSON; any parse failure falls back to deterministic.
+- Temperature defaults are conservative (0.3-0.5) for reproducibility.
+- Duration estimates use 150 words/min speaking rate.
+`
+  }
+];
+registerDocBlocks(generatorsDocBlocks);

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

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

package/dist/docs/rendering.docblock.js

@@ -0,0 +1,198 @@
+// @bun
+// src/docs/rendering.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts-spec/docs";
+var renderingDocBlocks = [
+  {
+    id: "docs.video-gen.rendering",
+    title: "Video Rendering & Playback",
+    summary: "LocalRenderer for MP4 output, render configuration, quality presets, DemoPlayer for web embedding, and Remotion Studio setup.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/video-gen/rendering",
+    tags: [
+      "video",
+      "rendering",
+      "remotion",
+      "player",
+      "mp4",
+      "quality-presets"
+    ],
+    owners: ["@contractspec/lib.video-gen"],
+    body: `# Video Rendering & Playback
+
+The rendering layer wraps \`@remotion/renderer\` for MP4/WebM output and \`@remotion/player\` for interactive web embedding. It implements the \`VideoProvider\` contract from \`@contractspec/lib.contracts-integrations\`.
+
+## LocalRenderer
+
+Renders a \`VideoProject\` to a video file using the local Remotion renderer. Requires **Node.js** (not Bun-compatible).
+
+\`\`\`ts
+import { LocalRenderer } from "@contractspec/lib.video-gen/renderers/local";
+
+const renderer = new LocalRenderer({
+  entryPoint: "./src/remotion/index.ts",
+});
+
+const result = await renderer.render(project, {
+  outputPath: "out/video.mp4",
+  codec: "h264",
+  crf: 18,
+});
+
+result.outputPath;      // "out/video.mp4"
+result.format;          // "mp4"
+result.durationSeconds; // total duration
+result.fileSizeBytes;   // file size
+result.dimensions;      // { width: 1920, height: 1080 }
+\`\`\`
+
+> **Important**: Import \`LocalRenderer\` from the \`/renderers/local\` subpath, not from the main entry. It dynamically imports \`@remotion/bundler\` and \`@remotion/renderer\` which are Node.js-only.
+
+### Auto-Variants
+
+Set \`autoVariants: true\` to generate landscape + square + portrait versions:
+
+\`\`\`ts
+const result = await renderer.render(project, {
+  outputPath: "out/video.mp4",
+  autoVariants: true,
+});
+
+result.variants; // [
+//   { outputPath: "out/video-square.mp4", dimensions: { width: 1080, height: 1080 } },
+//   { outputPath: "out/video-portrait.mp4", dimensions: { width: 1080, height: 1920 } },
+// ]
+\`\`\`
+
+## Render Configuration
+
+### Defaults
+
+\`\`\`ts
+import {
+  defaultRenderConfig,
+  resolveRenderConfig,
+  qualityPresets,
+  codecFormatMap,
+} from "@contractspec/lib.video-gen/renderers/config";
+
+defaultRenderConfig.codec;       // "h264"
+defaultRenderConfig.outputFormat; // "mp4"
+defaultRenderConfig.crf;         // 18
+defaultRenderConfig.pixelFormat; // "yuv420p"
+\`\`\`
+
+### RenderConfig Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| \`outputPath\` | \`string\` | -- | **Required**. Output file path |
+| \`codec\` | \`"h264" \\| "h265" \\| "vp8" \\| "vp9"\` | \`"h264"\` | Video codec |
+| \`outputFormat\` | \`"mp4" \\| "webm" \\| "gif"\` | \`"mp4"\` | Container format |
+| \`crf\` | \`number\` | \`18\` | Constant Rate Factor (lower = better quality) |
+| \`pixelFormat\` | \`string\` | \`"yuv420p"\` | Pixel format |
+| \`concurrency\` | \`number\` | CPU count | Rendering threads |
+| \`autoVariants\` | \`boolean\` | \`false\` | Generate format variants |
+
+### Quality Presets
+
+\`\`\`ts
+import { resolveRenderConfig } from "@contractspec/lib.video-gen/renderers/config";
+
+// Draft (fastest, for previews)
+resolveRenderConfig({ outputPath: "out/preview.mp4" }, "draft");
+// -> crf: 28, concurrency: 1
+
+// Standard (balanced)
+resolveRenderConfig({ outputPath: "out/video.mp4" }, "standard");
+// -> crf: 18
+
+// High (best quality, for final output)
+resolveRenderConfig({ outputPath: "out/final.mp4" }, "high");
+// -> crf: 12
+\`\`\`
+
+### Codec-to-Format Mapping
+
+| Codec | Format |
+|-------|--------|
+| \`h264\` | \`mp4\` |
+| \`h265\` | \`mp4\` |
+| \`vp8\` | \`webm\` |
+| \`vp9\` | \`webm\` |
+
+## DemoPlayer (Web Embedding)
+
+Embeddable Remotion Player for interactive video demos in React apps. Wraps \`@remotion/player\` with ContractSpec compositions.
+
+\`\`\`tsx
+import { DemoPlayer } from "@contractspec/lib.video-gen/player";
+
+<DemoPlayer
+  compositionId="ApiOverview"
+  inputProps={{
+    specName: "CreateUser",
+    specCode: "export const createUser = defineCommand({...})",
+  }}
+  controls
+  autoPlay
+  loop
+  width="100%"
+  clickToPlay
+  doubleClickToFullscreen
+/>
+\`\`\`
+
+### DemoPlayer Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| \`compositionId\` | \`"ApiOverview" \\| "SocialClip" \\| "TerminalDemo"\` | -- | Composition to play |
+| \`inputProps\` | composition props type | -- | Props for the selected composition |
+| \`controls\` | \`boolean\` | \`true\` | Show playback controls |
+| \`autoPlay\` | \`boolean\` | \`false\` | Auto-play on mount |
+| \`loop\` | \`boolean\` | \`false\` | Loop playback |
+| \`width\` | \`string \\| number\` | \`"100%"\` | Player width |
+| \`height\` | \`string \\| number\` | \`"auto"\` | Player height |
+| \`clickToPlay\` | \`boolean\` | \`true\` | Click to toggle playback |
+| \`doubleClickToFullscreen\` | \`boolean\` | \`true\` | Double-click for fullscreen |
+
+> \`@remotion/player\` is a peer dependency. Install it in your app if you use \`DemoPlayer\`.
+
+## Remotion Studio
+
+The \`@contractspec/app.video-studio\` package provides a Remotion Studio entry point for previewing compositions interactively.
+
+\`\`\`bash
+# Start Remotion Studio
+bun run dev:video
+
+# Render a specific composition
+npx remotion render src/index.ts ApiOverview out/api-overview.mp4
+
+# Render all compositions
+bun run render:all
+\`\`\`
+
+### Registered Compositions
+
+| ID | Component | Dimensions | Duration | Description |
+|----|-----------|------------|----------|-------------|
+| \`ApiOverview\` | \`ApiOverview\` | 1920x1080 | 450 frames (15s) | Homepage API demo |
+| \`SocialClip\` | \`SocialClip\` | 1920x1080 | 300 frames (10s) | Landscape social clip |
+| \`SocialClipSquare\` | \`SocialClip\` | 1080x1080 | 300 frames (10s) | Square social clip |
+| \`SocialClipPortrait\` | \`SocialClip\` | 1080x1920 | 300 frames (10s) | Portrait social clip |
+| \`TerminalDemo\` | \`TerminalDemo\` | 1920x1080 | 600 frames (20s) | CLI walkthrough |
+
+All compositions run at 30fps.
+
+## Guardrails
+
+- \`LocalRenderer\` requires Node.js -- do not attempt to use it in browser or Bun environments.
+- Import \`LocalRenderer\` from the \`/renderers/local\` subpath to avoid bundling \`@remotion/renderer\` in browser builds.
+- The \`remotion\` entry point (\`@contractspec/lib.video-gen/remotion\`) is a **side-effect module** that calls \`registerRoot()\`. Only import it from Remotion Studio or render scripts.
+- Use quality presets for consistency: \`draft\` for development, \`standard\` for CI, \`high\` for releases.
+`
+  }
+];
+registerDocBlocks(renderingDocBlocks);

package/dist/docs/video-gen.docblock.d.ts

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