@lssm-tech/lib.video-gen 3.0.10

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,2 @@
+// @bun
+var h=import.meta.require;import{Easing as d}from"remotion";var p={entrance:d.out(d.exp),exit:d.in(d.exp),emphasis:d.out(d.back(1.4)),linear:d.linear,gentle:d.bezier(0.25,0.1,0.25,1),spring:d.out(d.back(1.7))},q={sceneTransition:20,textEntrance:15,textExit:12,codeTypingPerChar:2,sectionPause:30,emphasisPause:15,brandReveal:25,minScene:60,shortScene:60,mediumScene:120,longScene:240},v={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{v as videoTransitions,p as videoEasing,q as 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,2 @@
+// @bun
+var z=import.meta.require;import{defaultTokens as j}from"@contractspec/lib.design-system";var q={canvasBackground:j.colors.background,codeBackground:"#1e1e2e",terminalBackground:"#0d1117",terminalForeground:"#c9d1d9",highlight:j.colors.accent,gradientStart:j.colors.primary,gradientEnd:j.colors.accent},D={...j,video:q};export{D as defaultVideoTheme,q as defaultVideoColors,j as 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,2 @@
+// @bun
+var m=import.meta.require;var u={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 z(b,k){let j=k/1920;return{...b,fontSize:Math.round(b.fontSize*j),letterSpacing:b.letterSpacing?Math.round(b.letterSpacing*j*10)/10:void 0}}export{u as videoTypography,z as scaleTypography};

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

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

package/dist/docs/compositions.docblock.js

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

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

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

package/dist/docs/design.docblock.js

@@ -0,0 +1,173 @@
+// @bun
+import{registerDocBlocks as f}from"@contractspec/lib.contracts-spec/docs";var h=[{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
+\`\`\`
+`}];f(h);

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

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

package/dist/docs/generators.docblock.js

@@ -0,0 +1,166 @@
+// @bun
+import{registerDocBlocks as f}from"@contractspec/lib.contracts-spec/docs";var h=[{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.
+`}];f(h);

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

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