@lssm-tech/lib.video-gen 3.0.10

package/dist/docs/rendering.docblock.js

@@ -0,0 +1,176 @@
+// @bun
+import{registerDocBlocks as f}from"@contractspec/lib.contracts-spec/docs";var h=[{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. Works with **Node.js** and **Bun** (via \`remotionb\`). Bun caveat: SSR scripts may not auto-quit (see [Remotion Bun docs](https://www.remotion.dev/docs/bun)).
+
+\`\`\`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\` to avoid bundling them in browser builds.
+
+### 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
+bunx remotionb 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 or Bun -- do not attempt to use it in browser environments. On Bun, SSR scripts may not auto-quit (see [Remotion Bun docs](https://www.remotion.dev/docs/bun)).
+- 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.
+`}];f(h);

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

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

package/dist/docs/video-gen.docblock.js

@@ -0,0 +1,127 @@
+// @bun
+import{registerDocBlocks as f}from"@contractspec/lib.contracts-spec/docs";var h=[{id:"docs.video-gen.overview",title:"Video Generation Library",summary:"Programmatic video generation with Remotion -- from content brief to rendered MP4 in a single pipeline.",kind:"reference",visibility:"public",route:"/docs/video-gen/overview",tags:["video","remotion","generation","content-pipeline"],owners:["@contractspec/lib.video-gen"],body:`# Video Generation Library
+
+\`@contractspec/lib.video-gen\` provides **programmatic video generation** using [Remotion](https://remotion.dev). It follows the same generator pattern as \`@contractspec/lib.content-gen\` and consumes provider contracts from \`@contractspec/lib.contracts-integrations/integrations/providers/video\`.
+
+## Architecture
+
+The library is organized into five layers, each buildable and testable independently:
+
+\`\`\`
+Content Brief
+    |
+    v
+Generators -----> ScenePlanner (brief -> scenes)
+    |              ScriptGenerator (brief -> narration)
+    |              VideoGenerator (orchestrator)
+    v
+Compositions ---> Primitives (AnimatedText, CodeBlock, Terminal, ...)
+    |              Full Compositions (ApiOverview, SocialClip, TerminalDemo)
+    v
+Design ---------> Tokens, Motion, Typography, Layouts
+    |
+    v
+Renderers ------> LocalRenderer (@remotion/renderer)
+                   DemoPlayer (@remotion/player, web embedding)
+\`\`\`
+
+### Layer Responsibilities
+
+| Layer | Import Path | Purpose |
+|-------|-------------|---------|
+| **Types** | \`@contractspec/lib.video-gen/types\` | VideoBrief, ScenePlan, GeneratedVideo, re-exported contract types |
+| **Design** | \`@contractspec/lib.video-gen/design\` | Video-optimized tokens, motion primitives, typography, layouts |
+| **Compositions** | \`@contractspec/lib.video-gen/compositions\` | Remotion components (primitives + full compositions) |
+| **Generators** | \`@contractspec/lib.video-gen/generators\` | VideoGenerator, ScenePlanner, ScriptGenerator |
+| **Renderers** | \`@contractspec/lib.video-gen/renderers\` | LocalRenderer, render config, quality presets |
+| **Player** | \`@contractspec/lib.video-gen/player\` | Embeddable DemoPlayer for web apps |
+| **Remotion** | \`@contractspec/lib.video-gen/remotion\` | Remotion Studio entry point (registerRoot) |
+
+## Getting Started
+
+### 1. Generate a video project from a content brief
+
+\`\`\`ts
+import { VideoGenerator } from "@contractspec/lib.video-gen/generators";
+import { VIDEO_FORMATS } from "@contractspec/lib.video-gen/types";
+import type { VideoBrief } from "@contractspec/lib.video-gen/types";
+
+const generator = new VideoGenerator({ fps: 30 });
+
+const brief: VideoBrief = {
+  content: {
+    title: "Ship APIs 10x Faster",
+    summary: "ContractSpec generates everything from a single spec.",
+    problems: ["Manual API maintenance", "Inconsistent surfaces"],
+    solutions: ["One spec, every surface", "Safe regeneration"],
+    callToAction: "Try ContractSpec",
+  },
+  format: VIDEO_FORMATS.landscape,
+  targetDurationSeconds: 30,
+};
+
+const project = await generator.generate(brief);
+\`\`\`
+
+### 2. Render to MP4
+
+\`\`\`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",
+});
+\`\`\`
+
+### 3. Embed in a web app
+
+\`\`\`tsx
+import { DemoPlayer } from "@contractspec/lib.video-gen/player";
+
+<DemoPlayer
+  compositionId="ApiOverview"
+  inputProps={{ specName: "CreateUser", specCode: "..." }}
+  controls
+  autoPlay
+  loop
+/>
+\`\`\`
+
+## Contract Bridge
+
+The library consumes provider contracts defined in \`@contractspec/lib.contracts-integrations\`:
+
+| Contract | Purpose |
+|----------|---------|
+| \`VideoProvider\` | Renderer abstraction (local, Lambda, Cloud Run) |
+| \`VideoProject\` | Scene graph with format, fps, audio tracks |
+| \`RenderConfig\` / \`RenderResult\` | Codec, quality, output path, dimensions |
+| \`CompositionRegistry\` | Metadata for registered Remotion compositions |
+| \`VideoFormat\` | Landscape / portrait / square / custom dimensions |
+
+Types are re-exported from the main entry for convenience:
+
+\`\`\`ts
+import type { VideoProject, RenderConfig } from "@contractspec/lib.video-gen";
+\`\`\`
+
+## Deterministic by Default
+
+All generators support two modes:
+
+- **Without LLM**: Fully deterministic, template-based output. Same brief always produces the same video project.
+- **With LLM**: Richer scene planning and narration scripts via an optional \`LLMProvider\`. Falls back to deterministic on any failure.
+
+This matches the content-gen pattern: \`constructor({ llm? })\` -> \`generate(brief)\`.
+
+## Guardrails
+
+- Compositions must be **deterministic**: same props = same visual output.
+- Design tokens bridge from \`@contractspec/lib.design-system\` -- do not duplicate brand values.
+- \`LocalRenderer\` works with Node.js and Bun. On Bun, SSR scripts may not auto-quit (see [Remotion Bun docs](https://www.remotion.dev/docs/bun)).
+- The \`remotion\` entry point is a side-effect module (calls \`registerRoot\`) -- import it only from Remotion Studio or render scripts.
+`}];f(h);

package/dist/generators/index.d.ts

@@ -0,0 +1,3 @@
+export type { ScenePlannerOptions } from './scene-planner';
+export { ScenePlanner } from './scene-planner';
+export { VideoGenerator } from './video-generator';

package/dist/generators/index.js

@@ -0,0 +1,83 @@
+// @bun
+var d=import.meta.require;import{VIDEO_FORMATS as W}from"@contractspec/lib.contracts-integrations/integrations/providers/video";var Q=30,J={horizontal:120,vertical:80,contentWidth:1680,contentHeight:920};function b(x){let G=x.width/1920,K=x.height/1080;return{horizontal:Math.round(J.horizontal*G),vertical:Math.round(J.vertical*K),contentWidth:Math.round(J.contentWidth*G),contentHeight:Math.round(J.contentHeight*K)}}var p={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 r(){return[W.landscape,W.square,W.portrait]}import{defineTranslation as M}from"@contractspec/lib.contracts-spec/translations";var $=M({meta:{key:"video-gen.messages",version:"1.0.0",domain:"video-gen",description:"All user-facing, LLM-facing, and developer-facing strings for the video-gen package",owners:["platform"],stability:"experimental"},locale:"en",fallback:"en",messages:{"prompt.script.system":{value:`You are a video narration script writer.
+Write a narration script for a short video (30-60 seconds).
+{styleGuide}
+
+Return JSON with shape:
+{
+  "segments": [{ "sceneId": string, "text": string }],
+  "fullText": string
+}
+
+Scene IDs should be: "intro", "problems", "solutions", "metrics", "cta".
+Only include segments that are relevant to the brief content.`,description:"Script generator LLM system prompt",placeholders:[{name:"styleGuide",type:"string"}]},"prompt.scenePlanner.system":{value:`You are a video scene planner for ContractSpec marketing/documentation videos.
+Given a content brief, break it into video scenes.
+
+Each scene must have:
+- compositionId: one of "ApiOverview", "SocialClip", "TerminalDemo"
+- props: the input props for that composition (see type definitions)
+- durationInFrames: duration at {fps}fps
+- narrationText: what the narrator says during this scene
+
+Return a JSON object with shape:
+{
+  "scenes": [{ "compositionId": string, "props": object, "durationInFrames": number, "narrationText": string }],
+  "narrationScript": string
+}
+
+Keep the total duration around {targetSeconds} seconds.
+Prioritize clarity and pacing. Each scene should communicate one idea.`,description:"Scene planner LLM system prompt",placeholders:[{name:"fps",type:"number"},{name:"targetSeconds",type:"number"}]},"prompt.style.professional":{value:"Use a clear, authoritative, professional tone. Be concise and direct.",description:"Style guide for professional narration"},"prompt.style.casual":{value:"Use a friendly, conversational tone. Be approachable and relatable.",description:"Style guide for casual narration"},"prompt.style.technical":{value:"Use precise technical language. Be detailed and accurate.",description:"Style guide for technical narration"},"script.segment.challenge":{value:"The challenge: {content}",description:"Narration segment prefix for problems",placeholders:[{name:"content",type:"string"}]},"script.segment.solution":{value:"The solution: {content}",description:"Narration segment prefix for solutions",placeholders:[{name:"content",type:"string"}]},"script.segment.results":{value:"The results: {content}",description:"Narration segment prefix for metrics",placeholders:[{name:"content",type:"string"}]},"scene.cta.default":{value:"Learn more",description:"Default call-to-action text for scenes"},"scene.hook.problem":{value:"The Problem",description:"Scene hook label for problem statement"},"scene.narration.problem":{value:"The problem: {content}",description:"Scene narration for problem statement",placeholders:[{name:"content",type:"string"}]},"scene.hook.solution":{value:"The Solution",description:"Scene hook label for solution"},"scene.narration.solution":{value:"The solution: {content}",description:"Scene narration for solution",placeholders:[{name:"content",type:"string"}]},"scene.hook.results":{value:"Results",description:"Scene hook label for results/metrics"},"composition.apiOverview.generates":{value:"Generates:",description:"ApiOverview heading for generated outputs"},"composition.apiOverview.tagline":{value:"One spec. Every surface.",description:"ApiOverview default tagline"},"composition.apiOverview.output.rest":{value:"REST Endpoint",description:"Generated output label: REST"},"composition.apiOverview.output.graphql":{value:"GraphQL Mutation",description:"Generated output label: GraphQL"},"composition.apiOverview.output.prisma":{value:"Prisma Model",description:"Generated output label: Prisma"},"composition.apiOverview.output.typescript":{value:"TypeScript SDK",description:"Generated output label: TypeScript SDK"},"composition.apiOverview.output.mcp":{value:"MCP Tool",description:"Generated output label: MCP Tool"},"composition.apiOverview.output.openapi":{value:"OpenAPI Spec",description:"Generated output label: OpenAPI"},"composition.socialClip.cta":{value:"Learn more",description:"SocialClip default CTA"},"composition.terminal.title":{value:"Terminal",description:"TerminalDemo default window title"}}});import{defineTranslation as O}from"@contractspec/lib.contracts-spec/translations";var I=O({meta:{key:"video-gen.messages",version:"1.0.0",domain:"video-gen",description:"Spanish translations for the video-gen package",owners:["platform"],stability:"experimental"},locale:"es",fallback:"en",messages:{"prompt.script.system":{value:`Eres un redactor de guiones de narraci\xF3n para v\xEDdeo.
+Escribe un gui\xF3n de narraci\xF3n para un v\xEDdeo corto (30-60 segundos).
+{styleGuide}
+
+Devuelve JSON con la forma:
+{
+  "segments": [{ "sceneId": string, "text": string }],
+  "fullText": string
+}
+
+Los identificadores de escena deben ser: "intro", "problems", "solutions", "metrics", "cta".
+Incluye solo los segmentos relevantes para el brief.`,description:"Script generator LLM system prompt",placeholders:[{name:"styleGuide",type:"string"}]},"prompt.scenePlanner.system":{value:`Eres un planificador de escenas de v\xEDdeo para v\xEDdeos de marketing/documentaci\xF3n de ContractSpec.
+Dado un brief de contenido, div\xEDdelo en escenas de v\xEDdeo.
+
+Cada escena debe tener:
+- compositionId: uno de "ApiOverview", "SocialClip", "TerminalDemo"
+- props: las propiedades de entrada de esa composici\xF3n
+- durationInFrames: duraci\xF3n a {fps} fps
+- narrationText: lo que dice el narrador durante esta escena
+
+Devuelve un objeto JSON con la forma:
+{
+  "scenes": [{ "compositionId": string, "props": object, "durationInFrames": number, "narrationText": string }],
+  "narrationScript": string
+}
+
+Mant\xE9n la duraci\xF3n total alrededor de {targetSeconds} segundos.
+Prioriza la claridad y el ritmo. Cada escena debe comunicar una idea.`,description:"Scene planner LLM system prompt",placeholders:[{name:"fps",type:"number"},{name:"targetSeconds",type:"number"}]},"prompt.style.professional":{value:"Usa un tono claro, autoritario y profesional. S\xE9 conciso y directo.",description:"Style guide for professional narration"},"prompt.style.casual":{value:"Usa un tono amigable y conversacional. S\xE9 accesible y cercano.",description:"Style guide for casual narration"},"prompt.style.technical":{value:"Usa un lenguaje t\xE9cnico preciso. S\xE9 detallado y exacto.",description:"Style guide for technical narration"},"script.segment.challenge":{value:"El desaf\xEDo: {content}",description:"Narration segment prefix for problems",placeholders:[{name:"content",type:"string"}]},"script.segment.solution":{value:"La soluci\xF3n: {content}",description:"Narration segment prefix for solutions",placeholders:[{name:"content",type:"string"}]},"script.segment.results":{value:"Los resultados: {content}",description:"Narration segment prefix for metrics",placeholders:[{name:"content",type:"string"}]},"scene.cta.default":{value:"M\xE1s informaci\xF3n",description:"Default call-to-action text for scenes"},"scene.hook.problem":{value:"El problema",description:"Scene hook label for problem statement"},"scene.narration.problem":{value:"El problema: {content}",description:"Scene narration for problem statement",placeholders:[{name:"content",type:"string"}]},"scene.hook.solution":{value:"La soluci\xF3n",description:"Scene hook label for solution"},"scene.narration.solution":{value:"La soluci\xF3n: {content}",description:"Scene narration for solution",placeholders:[{name:"content",type:"string"}]},"scene.hook.results":{value:"Resultados",description:"Scene hook label for results/metrics"},"composition.apiOverview.generates":{value:"Genera:",description:"ApiOverview heading for generated outputs"},"composition.apiOverview.tagline":{value:"Una spec. Todas las superficies.",description:"ApiOverview default tagline"},"composition.apiOverview.output.rest":{value:"Endpoint REST",description:"Generated output label: REST"},"composition.apiOverview.output.graphql":{value:"Mutaci\xF3n GraphQL",description:"Generated output label: GraphQL"},"composition.apiOverview.output.prisma":{value:"Modelo Prisma",description:"Generated output label: Prisma"},"composition.apiOverview.output.typescript":{value:"SDK TypeScript",description:"Generated output label: TypeScript SDK"},"composition.apiOverview.output.mcp":{value:"Herramienta MCP",description:"Generated output label: MCP Tool"},"composition.apiOverview.output.openapi":{value:"Spec OpenAPI",description:"Generated output label: OpenAPI"},"composition.socialClip.cta":{value:"M\xE1s informaci\xF3n",description:"SocialClip default CTA"},"composition.terminal.title":{value:"Terminal",description:"TerminalDemo default window title"}}});import{defineTranslation as S}from"@contractspec/lib.contracts-spec/translations";var Y=S({meta:{key:"video-gen.messages",version:"1.0.0",domain:"video-gen",description:"French translations for the video-gen package",owners:["platform"],stability:"experimental"},locale:"fr",fallback:"en",messages:{"prompt.script.system":{value:`Vous \xEAtes un r\xE9dacteur de scripts de narration vid\xE9o.
+\xC9crivez un script de narration pour une courte vid\xE9o (30-60 secondes).
+{styleGuide}
+
+Retournez du JSON avec la forme\xA0:
+{
+  "segments": [{ "sceneId": string, "text": string }],
+  "fullText": string
+}
+
+Les identifiants de sc\xE8ne doivent \xEAtre\xA0: "intro", "problems", "solutions", "metrics", "cta".
+N'incluez que les segments pertinents au brief.`,description:"Script generator LLM system prompt",placeholders:[{name:"styleGuide",type:"string"}]},"prompt.scenePlanner.system":{value:`Vous \xEAtes un planificateur de sc\xE8nes vid\xE9o pour les vid\xE9os marketing/documentation de ContractSpec.
+\xC0 partir d'un brief, d\xE9composez-le en sc\xE8nes vid\xE9o.
+
+Chaque sc\xE8ne doit avoir\xA0:
+- compositionId\xA0: un parmi "ApiOverview", "SocialClip", "TerminalDemo"
+- props\xA0: les propri\xE9t\xE9s d'entr\xE9e de cette composition
+- durationInFrames\xA0: dur\xE9e \xE0 {fps}\xA0fps
+- narrationText\xA0: ce que le narrateur dit pendant cette sc\xE8ne
+
+Retournez un objet JSON avec la forme\xA0:
+{
+  "scenes": [{ "compositionId": string, "props": object, "durationInFrames": number, "narrationText": string }],
+  "narrationScript": string
+}
+
+Gardez la dur\xE9e totale autour de {targetSeconds} secondes.
+Privil\xE9giez la clart\xE9 et le rythme. Chaque sc\xE8ne doit communiquer une id\xE9e.`,description:"Scene planner LLM system prompt",placeholders:[{name:"fps",type:"number"},{name:"targetSeconds",type:"number"}]},"prompt.style.professional":{value:"Utilisez un ton clair, autoritaire et professionnel. Soyez concis et direct.",description:"Style guide for professional narration"},"prompt.style.casual":{value:"Utilisez un ton amical et conversationnel. Soyez accessible et proche.",description:"Style guide for casual narration"},"prompt.style.technical":{value:"Utilisez un langage technique pr\xE9cis. Soyez d\xE9taill\xE9 et exact.",description:"Style guide for technical narration"},"script.segment.challenge":{value:"Le d\xE9fi\xA0: {content}",description:"Narration segment prefix for problems",placeholders:[{name:"content",type:"string"}]},"script.segment.solution":{value:"La solution\xA0: {content}",description:"Narration segment prefix for solutions",placeholders:[{name:"content",type:"string"}]},"script.segment.results":{value:"Les r\xE9sultats\xA0: {content}",description:"Narration segment prefix for metrics",placeholders:[{name:"content",type:"string"}]},"scene.cta.default":{value:"En savoir plus",description:"Default call-to-action text for scenes"},"scene.hook.problem":{value:"Le probl\xE8me",description:"Scene hook label for problem statement"},"scene.narration.problem":{value:"Le probl\xE8me\xA0: {content}",description:"Scene narration for problem statement",placeholders:[{name:"content",type:"string"}]},"scene.hook.solution":{value:"La solution",description:"Scene hook label for solution"},"scene.narration.solution":{value:"La solution\xA0: {content}",description:"Scene narration for solution",placeholders:[{name:"content",type:"string"}]},"scene.hook.results":{value:"R\xE9sultats",description:"Scene hook label for results/metrics"},"composition.apiOverview.generates":{value:"G\xE9n\xE8re\xA0:",description:"ApiOverview heading for generated outputs"},"composition.apiOverview.tagline":{value:"Un spec. Toutes les surfaces.",description:"ApiOverview default tagline"},"composition.apiOverview.output.rest":{value:"Endpoint REST",description:"Generated output label: REST"},"composition.apiOverview.output.graphql":{value:"Mutation GraphQL",description:"Generated output label: GraphQL"},"composition.apiOverview.output.prisma":{value:"Mod\xE8le Prisma",description:"Generated output label: Prisma"},"composition.apiOverview.output.typescript":{value:"SDK TypeScript",description:"Generated output label: TypeScript SDK"},"composition.apiOverview.output.mcp":{value:"Outil MCP",description:"Generated output label: MCP Tool"},"composition.apiOverview.output.openapi":{value:"Spec OpenAPI",description:"Generated output label: OpenAPI"},"composition.socialClip.cta":{value:"En savoir plus",description:"SocialClip default CTA"},"composition.terminal.title":{value:"Terminal",description:"TerminalDemo default window title"}}});var X={"prompt.script.system":"prompt.script.system","prompt.scenePlanner.system":"prompt.scenePlanner.system","prompt.style.professional":"prompt.style.professional","prompt.style.casual":"prompt.style.casual","prompt.style.technical":"prompt.style.technical"},h={"script.segment.challenge":"script.segment.challenge","script.segment.solution":"script.segment.solution","script.segment.results":"script.segment.results"},R={"scene.cta.default":"scene.cta.default","scene.hook.problem":"scene.hook.problem","scene.narration.problem":"scene.narration.problem","scene.hook.solution":"scene.hook.solution","scene.narration.solution":"scene.narration.solution","scene.hook.results":"scene.hook.results"},U={"composition.apiOverview.generates":"composition.apiOverview.generates","composition.apiOverview.tagline":"composition.apiOverview.tagline","composition.apiOverview.output.rest":"composition.apiOverview.output.rest","composition.apiOverview.output.graphql":"composition.apiOverview.output.graphql","composition.apiOverview.output.prisma":"composition.apiOverview.output.prisma","composition.apiOverview.output.typescript":"composition.apiOverview.output.typescript","composition.apiOverview.output.mcp":"composition.apiOverview.output.mcp","composition.apiOverview.output.openapi":"composition.apiOverview.output.openapi","composition.socialClip.cta":"composition.socialClip.cta","composition.terminal.title":"composition.terminal.title"},v={...X,...h,...R,...U};import{DEFAULT_LOCALE as A,isSupportedLocale as D,resolveLocale as m,SUPPORTED_LOCALES as T}from"@contractspec/lib.contracts-spec/translations";import{createI18nFactory as g}from"@contractspec/lib.contracts-spec/translations";var y=g({specKey:"video-gen.messages",catalogs:[$,Y,I]}),E=y.create,j=y.getDefault,F=y.resetRegistry;class V{llm;model;temperature;fps;i18n;modelSelector;selectionContext;constructor(x){this.llm=x?.llm,this.model=x?.model,this.temperature=x?.temperature??0.3,this.fps=x?.fps??Q,this.i18n=E(x?.locale),this.modelSelector=x?.modelSelector,this.selectionContext=x?.selectionContext}async plan(x){if(this.llm)return this.planWithLlm(x);return this.planDeterministic(x)}planDeterministic(x){let{content:G}=x,{t:K}=this.i18n,L=[],z=this.fps;if(L.push({compositionId:"SocialClip",props:{hook:G.title,message:G.summary,points:G.solutions.slice(0,3),cta:G.callToAction??K("scene.cta.default")},durationInFrames:3*z,narrationText:`${G.title}. ${G.summary}`}),G.problems.length>0)L.push({compositionId:"SocialClip",props:{hook:K("scene.hook.problem"),message:G.problems[0]??"",points:G.problems.slice(1,4)},durationInFrames:4*z,narrationText:K("scene.narration.problem",{content:G.problems.join(". ")})});if(G.solutions.length>0)L.push({compositionId:"SocialClip",props:{hook:K("scene.hook.solution"),message:G.solutions[0]??"",points:G.solutions.slice(1,4)},durationInFrames:5*z,narrationText:K("scene.narration.solution",{content:G.solutions.join(". ")})});if(G.metrics&&G.metrics.length>0)L.push({compositionId:"SocialClip",props:{hook:K("scene.hook.results"),message:G.metrics[0]??"",points:G.metrics.slice(1,3)},durationInFrames:3*z,narrationText:G.metrics.join(". ")});if(G.callToAction)L.push({compositionId:"SocialClip",props:{hook:G.callToAction,message:"",cta:G.callToAction},durationInFrames:2*z,narrationText:G.callToAction});if(x.targetDurationSeconds){let N=x.targetDurationSeconds*z,q=L.reduce((C,k)=>C+k.durationInFrames,0),H=N/q;for(let C of L)C.durationInFrames=Math.round(C.durationInFrames*H)}let w=L.reduce((N,q)=>N+q.durationInFrames,0),B=L.filter((N)=>N.narrationText).map((N)=>N.narrationText).join(" ");return{scenes:L,estimatedDurationSeconds:w/z,narrationScript:B}}async resolveModel(){if(this.model)return this.model;if(this.modelSelector){let x=this.selectionContext??{taskDimension:"reasoning"};return(await this.modelSelector.select(x)).modelId}return}async planWithLlm(x){let{t:G}=this.i18n,K=[{role:"system",content:[{type:"text",text:G("prompt.scenePlanner.system",{fps:this.fps,targetSeconds:x.targetDurationSeconds??30})}]},{role:"user",content:[{type:"text",text:JSON.stringify(x.content)}]}];if(!this.llm)return this.planDeterministic(x);try{let L=await this.resolveModel(),w=(await this.llm.chat(K,{model:L,temperature:this.temperature,responseFormat:"json"})).message.content.find((q)=>q.type==="text");if(!w||w.type!=="text")return this.planDeterministic(x);let B=JSON.parse(w.text),N=B.scenes.reduce((q,H)=>q+H.durationInFrames,0);return{scenes:B.scenes,estimatedDurationSeconds:N/this.fps,narrationScript:B.narrationScript}}catch{return this.planDeterministic(x)}}}import{VIDEO_FORMATS as P}from"@contractspec/lib.contracts-integrations/integrations/providers/video";class Z{scenePlanner;voice;transcriber;image;fps;constructor(x){this.fps=x?.fps??Q,this.voice=x?.voice,this.transcriber=x?.transcriber,this.image=x?.image,this.scenePlanner=new V({llm:x?.llm,model:x?.model,temperature:x?.temperature,fps:this.fps,locale:x?.locale,modelSelector:x?.modelSelector,selectionContext:x?.selectionContext})}async generate(x){let G=await this.scenePlanner.plan(x),K=G.scenes.map((C,k)=>({id:`scene-${k}`,compositionId:C.compositionId,props:C.props,durationInFrames:C.durationInFrames,narrationText:C.narrationText})),L,z;if(x.narration?.enabled&&this.voice)try{if(L=await this.voice.synthesizeForVideo({content:x.content,scenePlan:{scenes:K.map((C)=>({id:C.id,compositionId:C.compositionId,durationInFrames:C.durationInFrames,narrationText:C.narrationText})),estimatedDurationSeconds:G.estimatedDurationSeconds},voice:{voiceId:x.narration.voiceId??""},pacing:{strategy:"scene-matched"},fps:this.fps}),L.timingMap)for(let C of L.timingMap.segments){let k=K.find((_)=>_.id===C.sceneId);if(k)k.durationInFrames=C.recommendedSceneDurationInFrames}if(L.assembledAudio)z={data:L.assembledAudio.data,format:L.assembledAudio.format==="wav"?"wav":"mp3",durationSeconds:(L.assembledAudio.durationMs??0)/1000,volume:1}}catch{}let w;if(this.transcriber&&L?.assembledAudio)try{w=(await this.transcriber.transcribe({audio:L.assembledAudio,subtitleFormat:"vtt"})).subtitles}catch{}let B;if(this.image)try{let C=await this.image.generate({content:x.content,purpose:"video-thumbnail",format:"png",style:"photorealistic"}),k=C.results?.images[0]?.url;B={prompt:C.prompt.text,...k?{imageUrl:k}:{}}}catch{}let N=x.format??P.landscape,q=K.reduce((C,k)=>C+k.durationInFrames,0);return{id:u(),scenes:K,totalDurationInFrames:q,fps:this.fps,format:N,audio:z?{narration:z}:void 0,subtitles:w,voiceTimingMap:L?.timingMap,thumbnail:B}}}function u(){let x=Date.now().toString(36),G=Math.random().toString(36).slice(2,8);return`vp_${x}_${G}`}export{Z as VideoGenerator,V as ScenePlanner};

package/dist/generators/scene-planner.d.ts

@@ -0,0 +1,31 @@
+import type { ModelSelectionContext, ModelSelector } from '@contractspec/lib.ai-providers/selector-types';
+import type { LLMProvider } from '@contractspec/lib.contracts-integrations/integrations/providers/llm';
+import type { ScenePlan, VideoBrief } from '../types';
+export interface ScenePlannerOptions {
+    llm?: LLMProvider;
+    model?: string;
+    temperature?: number;
+    fps?: number;
+    locale?: string;
+    modelSelector?: ModelSelector;
+    selectionContext?: ModelSelectionContext;
+}
+export declare class ScenePlanner {
+    private readonly llm?;
+    private readonly model?;
+    private readonly temperature;
+    private readonly fps;
+    private readonly i18n;
+    private readonly modelSelector?;
+    private readonly selectionContext?;
+    constructor(options?: ScenePlannerOptions);
+    /**
+     * Plan scenes for a video brief.
+     * With LLM: produces richer, context-aware scene breakdowns.
+     * Without LLM: deterministic template-based planning.
+     */
+    plan(brief: VideoBrief): Promise<ScenePlan>;
+    private planDeterministic;
+    private resolveModel;
+    private planWithLlm;
+}

package/dist/generators/scene-planner.js

@@ -0,0 +1,83 @@
+// @bun
+var O=import.meta.require;import{VIDEO_FORMATS as k}from"@contractspec/lib.contracts-integrations/integrations/providers/video";var J=30,P={horizontal:120,vertical:80,contentWidth:1680,contentHeight:920};function d(L){let x=L.width/1920,C=L.height/1080;return{horizontal:Math.round(P.horizontal*x),vertical:Math.round(P.vertical*C),contentWidth:Math.round(P.contentWidth*x),contentHeight:Math.round(P.contentHeight*C)}}var F={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 l(){return[k.landscape,k.square,k.portrait]}import{defineTranslation as Y}from"@contractspec/lib.contracts-spec/translations";var q=Y({meta:{key:"video-gen.messages",version:"1.0.0",domain:"video-gen",description:"All user-facing, LLM-facing, and developer-facing strings for the video-gen package",owners:["platform"],stability:"experimental"},locale:"en",fallback:"en",messages:{"prompt.script.system":{value:`You are a video narration script writer.
+Write a narration script for a short video (30-60 seconds).
+{styleGuide}
+
+Return JSON with shape:
+{
+  "segments": [{ "sceneId": string, "text": string }],
+  "fullText": string
+}
+
+Scene IDs should be: "intro", "problems", "solutions", "metrics", "cta".
+Only include segments that are relevant to the brief content.`,description:"Script generator LLM system prompt",placeholders:[{name:"styleGuide",type:"string"}]},"prompt.scenePlanner.system":{value:`You are a video scene planner for ContractSpec marketing/documentation videos.
+Given a content brief, break it into video scenes.
+
+Each scene must have:
+- compositionId: one of "ApiOverview", "SocialClip", "TerminalDemo"
+- props: the input props for that composition (see type definitions)
+- durationInFrames: duration at {fps}fps
+- narrationText: what the narrator says during this scene
+
+Return a JSON object with shape:
+{
+  "scenes": [{ "compositionId": string, "props": object, "durationInFrames": number, "narrationText": string }],
+  "narrationScript": string
+}
+
+Keep the total duration around {targetSeconds} seconds.
+Prioritize clarity and pacing. Each scene should communicate one idea.`,description:"Scene planner LLM system prompt",placeholders:[{name:"fps",type:"number"},{name:"targetSeconds",type:"number"}]},"prompt.style.professional":{value:"Use a clear, authoritative, professional tone. Be concise and direct.",description:"Style guide for professional narration"},"prompt.style.casual":{value:"Use a friendly, conversational tone. Be approachable and relatable.",description:"Style guide for casual narration"},"prompt.style.technical":{value:"Use precise technical language. Be detailed and accurate.",description:"Style guide for technical narration"},"script.segment.challenge":{value:"The challenge: {content}",description:"Narration segment prefix for problems",placeholders:[{name:"content",type:"string"}]},"script.segment.solution":{value:"The solution: {content}",description:"Narration segment prefix for solutions",placeholders:[{name:"content",type:"string"}]},"script.segment.results":{value:"The results: {content}",description:"Narration segment prefix for metrics",placeholders:[{name:"content",type:"string"}]},"scene.cta.default":{value:"Learn more",description:"Default call-to-action text for scenes"},"scene.hook.problem":{value:"The Problem",description:"Scene hook label for problem statement"},"scene.narration.problem":{value:"The problem: {content}",description:"Scene narration for problem statement",placeholders:[{name:"content",type:"string"}]},"scene.hook.solution":{value:"The Solution",description:"Scene hook label for solution"},"scene.narration.solution":{value:"The solution: {content}",description:"Scene narration for solution",placeholders:[{name:"content",type:"string"}]},"scene.hook.results":{value:"Results",description:"Scene hook label for results/metrics"},"composition.apiOverview.generates":{value:"Generates:",description:"ApiOverview heading for generated outputs"},"composition.apiOverview.tagline":{value:"One spec. Every surface.",description:"ApiOverview default tagline"},"composition.apiOverview.output.rest":{value:"REST Endpoint",description:"Generated output label: REST"},"composition.apiOverview.output.graphql":{value:"GraphQL Mutation",description:"Generated output label: GraphQL"},"composition.apiOverview.output.prisma":{value:"Prisma Model",description:"Generated output label: Prisma"},"composition.apiOverview.output.typescript":{value:"TypeScript SDK",description:"Generated output label: TypeScript SDK"},"composition.apiOverview.output.mcp":{value:"MCP Tool",description:"Generated output label: MCP Tool"},"composition.apiOverview.output.openapi":{value:"OpenAPI Spec",description:"Generated output label: OpenAPI"},"composition.socialClip.cta":{value:"Learn more",description:"SocialClip default CTA"},"composition.terminal.title":{value:"Terminal",description:"TerminalDemo default window title"}}});import{defineTranslation as g}from"@contractspec/lib.contracts-spec/translations";var w=g({meta:{key:"video-gen.messages",version:"1.0.0",domain:"video-gen",description:"Spanish translations for the video-gen package",owners:["platform"],stability:"experimental"},locale:"es",fallback:"en",messages:{"prompt.script.system":{value:`Eres un redactor de guiones de narraci\xF3n para v\xEDdeo.
+Escribe un gui\xF3n de narraci\xF3n para un v\xEDdeo corto (30-60 segundos).
+{styleGuide}
+
+Devuelve JSON con la forma:
+{
+  "segments": [{ "sceneId": string, "text": string }],
+  "fullText": string
+}
+
+Los identificadores de escena deben ser: "intro", "problems", "solutions", "metrics", "cta".
+Incluye solo los segmentos relevantes para el brief.`,description:"Script generator LLM system prompt",placeholders:[{name:"styleGuide",type:"string"}]},"prompt.scenePlanner.system":{value:`Eres un planificador de escenas de v\xEDdeo para v\xEDdeos de marketing/documentaci\xF3n de ContractSpec.
+Dado un brief de contenido, div\xEDdelo en escenas de v\xEDdeo.
+
+Cada escena debe tener:
+- compositionId: uno de "ApiOverview", "SocialClip", "TerminalDemo"
+- props: las propiedades de entrada de esa composici\xF3n
+- durationInFrames: duraci\xF3n a {fps} fps
+- narrationText: lo que dice el narrador durante esta escena
+
+Devuelve un objeto JSON con la forma:
+{
+  "scenes": [{ "compositionId": string, "props": object, "durationInFrames": number, "narrationText": string }],
+  "narrationScript": string
+}
+
+Mant\xE9n la duraci\xF3n total alrededor de {targetSeconds} segundos.
+Prioriza la claridad y el ritmo. Cada escena debe comunicar una idea.`,description:"Scene planner LLM system prompt",placeholders:[{name:"fps",type:"number"},{name:"targetSeconds",type:"number"}]},"prompt.style.professional":{value:"Usa un tono claro, autoritario y profesional. S\xE9 conciso y directo.",description:"Style guide for professional narration"},"prompt.style.casual":{value:"Usa un tono amigable y conversacional. S\xE9 accesible y cercano.",description:"Style guide for casual narration"},"prompt.style.technical":{value:"Usa un lenguaje t\xE9cnico preciso. S\xE9 detallado y exacto.",description:"Style guide for technical narration"},"script.segment.challenge":{value:"El desaf\xEDo: {content}",description:"Narration segment prefix for problems",placeholders:[{name:"content",type:"string"}]},"script.segment.solution":{value:"La soluci\xF3n: {content}",description:"Narration segment prefix for solutions",placeholders:[{name:"content",type:"string"}]},"script.segment.results":{value:"Los resultados: {content}",description:"Narration segment prefix for metrics",placeholders:[{name:"content",type:"string"}]},"scene.cta.default":{value:"M\xE1s informaci\xF3n",description:"Default call-to-action text for scenes"},"scene.hook.problem":{value:"El problema",description:"Scene hook label for problem statement"},"scene.narration.problem":{value:"El problema: {content}",description:"Scene narration for problem statement",placeholders:[{name:"content",type:"string"}]},"scene.hook.solution":{value:"La soluci\xF3n",description:"Scene hook label for solution"},"scene.narration.solution":{value:"La soluci\xF3n: {content}",description:"Scene narration for solution",placeholders:[{name:"content",type:"string"}]},"scene.hook.results":{value:"Resultados",description:"Scene hook label for results/metrics"},"composition.apiOverview.generates":{value:"Genera:",description:"ApiOverview heading for generated outputs"},"composition.apiOverview.tagline":{value:"Una spec. Todas las superficies.",description:"ApiOverview default tagline"},"composition.apiOverview.output.rest":{value:"Endpoint REST",description:"Generated output label: REST"},"composition.apiOverview.output.graphql":{value:"Mutaci\xF3n GraphQL",description:"Generated output label: GraphQL"},"composition.apiOverview.output.prisma":{value:"Modelo Prisma",description:"Generated output label: Prisma"},"composition.apiOverview.output.typescript":{value:"SDK TypeScript",description:"Generated output label: TypeScript SDK"},"composition.apiOverview.output.mcp":{value:"Herramienta MCP",description:"Generated output label: MCP Tool"},"composition.apiOverview.output.openapi":{value:"Spec OpenAPI",description:"Generated output label: OpenAPI"},"composition.socialClip.cta":{value:"M\xE1s informaci\xF3n",description:"SocialClip default CTA"},"composition.terminal.title":{value:"Terminal",description:"TerminalDemo default window title"}}});import{defineTranslation as y}from"@contractspec/lib.contracts-spec/translations";var B=y({meta:{key:"video-gen.messages",version:"1.0.0",domain:"video-gen",description:"French translations for the video-gen package",owners:["platform"],stability:"experimental"},locale:"fr",fallback:"en",messages:{"prompt.script.system":{value:`Vous \xEAtes un r\xE9dacteur de scripts de narration vid\xE9o.
+\xC9crivez un script de narration pour une courte vid\xE9o (30-60 secondes).
+{styleGuide}
+
+Retournez du JSON avec la forme\xA0:
+{
+  "segments": [{ "sceneId": string, "text": string }],
+  "fullText": string
+}
+
+Les identifiants de sc\xE8ne doivent \xEAtre\xA0: "intro", "problems", "solutions", "metrics", "cta".
+N'incluez que les segments pertinents au brief.`,description:"Script generator LLM system prompt",placeholders:[{name:"styleGuide",type:"string"}]},"prompt.scenePlanner.system":{value:`Vous \xEAtes un planificateur de sc\xE8nes vid\xE9o pour les vid\xE9os marketing/documentation de ContractSpec.
+\xC0 partir d'un brief, d\xE9composez-le en sc\xE8nes vid\xE9o.
+
+Chaque sc\xE8ne doit avoir\xA0:
+- compositionId\xA0: un parmi "ApiOverview", "SocialClip", "TerminalDemo"
+- props\xA0: les propri\xE9t\xE9s d'entr\xE9e de cette composition
+- durationInFrames\xA0: dur\xE9e \xE0 {fps}\xA0fps
+- narrationText\xA0: ce que le narrateur dit pendant cette sc\xE8ne
+
+Retournez un objet JSON avec la forme\xA0:
+{
+  "scenes": [{ "compositionId": string, "props": object, "durationInFrames": number, "narrationText": string }],
+  "narrationScript": string
+}
+
+Gardez la dur\xE9e totale autour de {targetSeconds} secondes.
+Privil\xE9giez la clart\xE9 et le rythme. Chaque sc\xE8ne doit communiquer une id\xE9e.`,description:"Scene planner LLM system prompt",placeholders:[{name:"fps",type:"number"},{name:"targetSeconds",type:"number"}]},"prompt.style.professional":{value:"Utilisez un ton clair, autoritaire et professionnel. Soyez concis et direct.",description:"Style guide for professional narration"},"prompt.style.casual":{value:"Utilisez un ton amical et conversationnel. Soyez accessible et proche.",description:"Style guide for casual narration"},"prompt.style.technical":{value:"Utilisez un langage technique pr\xE9cis. Soyez d\xE9taill\xE9 et exact.",description:"Style guide for technical narration"},"script.segment.challenge":{value:"Le d\xE9fi\xA0: {content}",description:"Narration segment prefix for problems",placeholders:[{name:"content",type:"string"}]},"script.segment.solution":{value:"La solution\xA0: {content}",description:"Narration segment prefix for solutions",placeholders:[{name:"content",type:"string"}]},"script.segment.results":{value:"Les r\xE9sultats\xA0: {content}",description:"Narration segment prefix for metrics",placeholders:[{name:"content",type:"string"}]},"scene.cta.default":{value:"En savoir plus",description:"Default call-to-action text for scenes"},"scene.hook.problem":{value:"Le probl\xE8me",description:"Scene hook label for problem statement"},"scene.narration.problem":{value:"Le probl\xE8me\xA0: {content}",description:"Scene narration for problem statement",placeholders:[{name:"content",type:"string"}]},"scene.hook.solution":{value:"La solution",description:"Scene hook label for solution"},"scene.narration.solution":{value:"La solution\xA0: {content}",description:"Scene narration for solution",placeholders:[{name:"content",type:"string"}]},"scene.hook.results":{value:"R\xE9sultats",description:"Scene hook label for results/metrics"},"composition.apiOverview.generates":{value:"G\xE9n\xE8re\xA0:",description:"ApiOverview heading for generated outputs"},"composition.apiOverview.tagline":{value:"Un spec. Toutes les surfaces.",description:"ApiOverview default tagline"},"composition.apiOverview.output.rest":{value:"Endpoint REST",description:"Generated output label: REST"},"composition.apiOverview.output.graphql":{value:"Mutation GraphQL",description:"Generated output label: GraphQL"},"composition.apiOverview.output.prisma":{value:"Mod\xE8le Prisma",description:"Generated output label: Prisma"},"composition.apiOverview.output.typescript":{value:"SDK TypeScript",description:"Generated output label: TypeScript SDK"},"composition.apiOverview.output.mcp":{value:"Outil MCP",description:"Generated output label: MCP Tool"},"composition.apiOverview.output.openapi":{value:"Spec OpenAPI",description:"Generated output label: OpenAPI"},"composition.socialClip.cta":{value:"En savoir plus",description:"SocialClip default CTA"},"composition.terminal.title":{value:"Terminal",description:"TerminalDemo default window title"}}});var Q={"prompt.script.system":"prompt.script.system","prompt.scenePlanner.system":"prompt.scenePlanner.system","prompt.style.professional":"prompt.style.professional","prompt.style.casual":"prompt.style.casual","prompt.style.technical":"prompt.style.technical"},U={"script.segment.challenge":"script.segment.challenge","script.segment.solution":"script.segment.solution","script.segment.results":"script.segment.results"},V={"scene.cta.default":"scene.cta.default","scene.hook.problem":"scene.hook.problem","scene.narration.problem":"scene.narration.problem","scene.hook.solution":"scene.hook.solution","scene.narration.solution":"scene.narration.solution","scene.hook.results":"scene.hook.results"},W={"composition.apiOverview.generates":"composition.apiOverview.generates","composition.apiOverview.tagline":"composition.apiOverview.tagline","composition.apiOverview.output.rest":"composition.apiOverview.output.rest","composition.apiOverview.output.graphql":"composition.apiOverview.output.graphql","composition.apiOverview.output.prisma":"composition.apiOverview.output.prisma","composition.apiOverview.output.typescript":"composition.apiOverview.output.typescript","composition.apiOverview.output.mcp":"composition.apiOverview.output.mcp","composition.apiOverview.output.openapi":"composition.apiOverview.output.openapi","composition.socialClip.cta":"composition.socialClip.cta","composition.terminal.title":"composition.terminal.title"},A={...Q,...U,...V,...W};import{DEFAULT_LOCALE as R,isSupportedLocale as X,resolveLocale as _,SUPPORTED_LOCALES as D}from"@contractspec/lib.contracts-spec/translations";import{createI18nFactory as M}from"@contractspec/lib.contracts-spec/translations";var E=M({specKey:"video-gen.messages",catalogs:[q,B,w]}),H=E.create,Z=E.getDefault,u=E.resetRegistry;class v{llm;model;temperature;fps;i18n;modelSelector;selectionContext;constructor(L){this.llm=L?.llm,this.model=L?.model,this.temperature=L?.temperature??0.3,this.fps=L?.fps??J,this.i18n=H(L?.locale),this.modelSelector=L?.modelSelector,this.selectionContext=L?.selectionContext}async plan(L){if(this.llm)return this.planWithLlm(L);return this.planDeterministic(L)}planDeterministic(L){let{content:x}=L,{t:C}=this.i18n,G=[],I=this.fps;if(G.push({compositionId:"SocialClip",props:{hook:x.title,message:x.summary,points:x.solutions.slice(0,3),cta:x.callToAction??C("scene.cta.default")},durationInFrames:3*I,narrationText:`${x.title}. ${x.summary}`}),x.problems.length>0)G.push({compositionId:"SocialClip",props:{hook:C("scene.hook.problem"),message:x.problems[0]??"",points:x.problems.slice(1,4)},durationInFrames:4*I,narrationText:C("scene.narration.problem",{content:x.problems.join(". ")})});if(x.solutions.length>0)G.push({compositionId:"SocialClip",props:{hook:C("scene.hook.solution"),message:x.solutions[0]??"",points:x.solutions.slice(1,4)},durationInFrames:5*I,narrationText:C("scene.narration.solution",{content:x.solutions.join(". ")})});if(x.metrics&&x.metrics.length>0)G.push({compositionId:"SocialClip",props:{hook:C("scene.hook.results"),message:x.metrics[0]??"",points:x.metrics.slice(1,3)},durationInFrames:3*I,narrationText:x.metrics.join(". ")});if(x.callToAction)G.push({compositionId:"SocialClip",props:{hook:x.callToAction,message:"",cta:x.callToAction},durationInFrames:2*I,narrationText:x.callToAction});if(L.targetDurationSeconds){let m=L.targetDurationSeconds*I,K=G.reduce((N,$)=>N+$.durationInFrames,0),j=m/K;for(let N of G)N.durationInFrames=Math.round(N.durationInFrames*j)}let h=G.reduce((m,K)=>m+K.durationInFrames,0),z=G.filter((m)=>m.narrationText).map((m)=>m.narrationText).join(" ");return{scenes:G,estimatedDurationSeconds:h/I,narrationScript:z}}async resolveModel(){if(this.model)return this.model;if(this.modelSelector){let L=this.selectionContext??{taskDimension:"reasoning"};return(await this.modelSelector.select(L)).modelId}return}async planWithLlm(L){let{t:x}=this.i18n,C=[{role:"system",content:[{type:"text",text:x("prompt.scenePlanner.system",{fps:this.fps,targetSeconds:L.targetDurationSeconds??30})}]},{role:"user",content:[{type:"text",text:JSON.stringify(L.content)}]}];if(!this.llm)return this.planDeterministic(L);try{let G=await this.resolveModel(),h=(await this.llm.chat(C,{model:G,temperature:this.temperature,responseFormat:"json"})).message.content.find((K)=>K.type==="text");if(!h||h.type!=="text")return this.planDeterministic(L);let z=JSON.parse(h.text),m=z.scenes.reduce((K,j)=>K+j.durationInFrames,0);return{scenes:z.scenes,estimatedDurationSeconds:m/this.fps,narrationScript:z.narrationScript}}catch{return this.planDeterministic(L)}}}export{v as ScenePlanner};

package/dist/generators/script-generator.d.ts

@@ -0,0 +1,57 @@
+import type { ModelSelectionContext, ModelSelector } from '@contractspec/lib.ai-providers/selector-types';
+import type { ContentBrief } from '@contractspec/lib.content-gen/types';
+import type { LLMProvider } from '@contractspec/lib.contracts-integrations/integrations/providers/llm';
+import type { NarrationConfig } from '@contractspec/lib.contracts-integrations/integrations/providers/video';
+export interface NarrationScript {
+    /** Full narration text */
+    fullText: string;
+    /** Per-scene narration segments */
+    segments: NarrationSegment[];
+    /** Estimated speaking duration in seconds (at ~150 words/min) */
+    estimatedDurationSeconds: number;
+    /** Style used */
+    style: NarrationConfig['style'];
+}
+export interface NarrationSegment {
+    /** Scene identifier this segment maps to */
+    sceneId: string;
+    /** Narration text for this segment */
+    text: string;
+    /** Estimated duration in seconds */
+    estimatedDurationSeconds: number;
+}
+export interface ScriptGeneratorOptions {
+    llm?: LLMProvider;
+    model?: string;
+    temperature?: number;
+    locale?: string;
+    modelSelector?: ModelSelector;
+    selectionContext?: ModelSelectionContext;
+}
+export declare class ScriptGenerator {
+    private readonly llm?;
+    private readonly model?;
+    private readonly temperature;
+    private readonly i18n;
+    private readonly modelSelector?;
+    private readonly selectionContext?;
+    constructor(options?: ScriptGeneratorOptions);
+    /**
+     * Generate a narration script from a content brief.
+     */
+    generate(brief: ContentBrief, config?: NarrationConfig): Promise<NarrationScript>;
+    private generateDeterministic;
+    private resolveModel;
+    private generateWithLlm;
+    /**
+     * Adjust text tone based on style.
+     * In the deterministic path, this is a simple pass-through.
+     * The LLM path handles style natively.
+     */
+    private formatForStyle;
+    /**
+     * Estimate speaking duration based on word count.
+     * Average speaking rate: ~150 words per minute.
+     */
+    private estimateDuration;
+}