mulmocast 2.13.0 → 2.14.0

package/assets/schemas/mulmo_script.json

@@ -13517,29 +13517,95 @@
                 "additionalProperties": false
               },
               {
-                "type": "object",
-                "properties": {
-                  "type": {
-                    "type": "string",
-                    "const": "remotion"
-                  },
-                  "prompt": {
-                    "type": "string",
-                    "minLength": 1,
-                    "description": "What the scene shows. Claude Code (claude -p) writes a Remotion component from it."
+                "anyOf": [
+                  {
+                    "type": "object",
+                    "properties": {
+                      "type": {
+                        "type": "string",
+                        "const": "remotion"
+                      },
+                      "fps": {
+                        "description": "Frame rate of the rendered video. Default: 30.",
+                        "type": "number",
+                        "minimum": 1,
+                        "maximum": 60
+                      },
+                      "prompt": {
+                        "type": "string",
+                        "minLength": 1,
+                        "description": "What the scene shows. Claude Code (claude -p) writes a Remotion component from it."
+                      }
+                    },
+                    "required": [
+                      "type",
+                      "prompt"
+                    ],
+                    "additionalProperties": false
                   },
-                  "fps": {
-                    "description": "Frame rate of the rendered video. Default: 30.",
-                    "type": "number",
-                    "minimum": 1,
-                    "maximum": 60
+                  {
+                    "type": "object",
+                    "properties": {
+                      "type": {
+                        "type": "string",
+                        "const": "remotion"
+                      },
+                      "fps": {
+                        "description": "Frame rate of the rendered video. Default: 30.",
+                        "type": "number",
+                        "minimum": 1,
+                        "maximum": 60
+                      },
+                      "code": {
+                        "oneOf": [
+                          {
+                            "type": "object",
+                            "properties": {
+                              "kind": {
+                                "type": "string",
+                                "const": "text"
+                              },
+                              "text": {
+                                "type": "string",
+                                "minLength": 1
+                              }
+                            },
+                            "required": [
+                              "kind",
+                              "text"
+                            ],
+                            "additionalProperties": false
+                          },
+                          {
+                            "type": "object",
+                            "properties": {
+                              "kind": {
+                                "type": "string",
+                                "const": "path"
+                              },
+                              "path": {
+                                "type": "string",
+                                "minLength": 1,
+                                "description": "Relative to the script"
+                              }
+                            },
+                            "required": [
+                              "kind",
+                              "path"
+                            ],
+                            "additionalProperties": false
+                          }
+                        ],
+                        "description": "A finished Remotion component (TSX that default-exports the scene). It is rendered as is, without claude -p."
+                      }
+                    },
+                    "required": [
+                      "type",
+                      "code"
+                    ],
+                    "additionalProperties": false
                   }
-                },
-                "required": [
-                  "type",
-                  "prompt"
-                ],
-                "additionalProperties": false
+                ]
               }
             ]
           },

package/lib/index.remotion.d.ts

@@ -0,0 +1,3 @@
+export { REMOTION_COMPONENT_GUIDE } from "./utils/remotion/system_prompt.js";
+export { REMOTION_PACKAGES, REMOTION_RENDER_PACKAGES, REMOTION_SCENE_PACKAGES, remotionInstallCommand } from "./utils/remotion/packages.js";
+export { ensureRemotionPackages, missingInstalledRemotionPackages } from "./utils/remotion/render.js";

package/lib/index.remotion.js

@@ -0,0 +1,4 @@
+// Entry point for hosts whose own agent writes the remotion beat's component and passes it as `code`.
+export { REMOTION_COMPONENT_GUIDE } from "./utils/remotion/system_prompt.js";
+export { REMOTION_PACKAGES, REMOTION_RENDER_PACKAGES, REMOTION_SCENE_PACKAGES, remotionInstallCommand } from "./utils/remotion/packages.js";
+export { ensureRemotionPackages, missingInstalledRemotionPackages } from "./utils/remotion/render.js";

package/lib/types/schema.d.ts

@@ -545,11 +545,28 @@ export declare const mulmoVisionMediaSchema: z.ZodObject<{
     style: z.ZodString;
     data: z.ZodRecord<z.ZodString, z.ZodAny>;
 }, z.core.$strict>;
-export declare const mulmoRemotionMediaSchema: z.ZodObject<{
-    type: z.ZodLiteral<"remotion">;
+export declare const remotionCodeSourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"text">;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"path">;
+    path: z.ZodString;
+}, z.core.$strict>], "kind">;
+export declare const mulmoRemotionMediaSchema: z.ZodUnion<readonly [z.ZodObject<{
     prompt: z.ZodString;
+    type: z.ZodLiteral<"remotion">;
     fps: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    code: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"path">;
+        path: z.ZodString;
+    }, z.core.$strict>], "kind">;
+    type: z.ZodLiteral<"remotion">;
+    fps: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>]>;
 export declare const mulmoRemotionParamsSchema: z.ZodObject<{
     brief: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
@@ -4233,11 +4250,21 @@ export declare const mulmoImageAssetSchema: z.ZodUnion<readonly [z.ZodObject<{
             bgOpacity: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
     }, z.core.$strict>>>;
+}, z.core.$strict>, z.ZodUnion<readonly [z.ZodObject<{
+    prompt: z.ZodString;
+    type: z.ZodLiteral<"remotion">;
+    fps: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>, z.ZodObject<{
+    code: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"path">;
+        path: z.ZodString;
+    }, z.core.$strict>], "kind">;
     type: z.ZodLiteral<"remotion">;
-    prompt: z.ZodString;
     fps: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strict>]>;
+}, z.core.$strict>]>]>;
 export declare const mulmoAudioAssetSchema: z.ZodUnion<readonly [z.ZodObject<{
     type: z.ZodLiteral<"audio">;
     source: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -8644,11 +8671,21 @@ export declare const mulmoBeatSchema: z.ZodObject<{
                 bgOpacity: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>>;
         }, z.core.$strict>>>;
+    }, z.core.$strict>, z.ZodUnion<readonly [z.ZodObject<{
+        prompt: z.ZodString;
+        type: z.ZodLiteral<"remotion">;
+        fps: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>, z.ZodObject<{
+        code: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"text">;
+            text: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"path">;
+            path: z.ZodString;
+        }, z.core.$strict>], "kind">;
         type: z.ZodLiteral<"remotion">;
-        prompt: z.ZodString;
         fps: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strict>]>>;
+    }, z.core.$strict>]>]>>;
     audio: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
         type: z.ZodLiteral<"audio">;
         source: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -13901,11 +13938,21 @@ export declare const mulmoScriptSchema: z.ZodObject<{
                     bgOpacity: z.ZodOptional<z.ZodNumber>;
                 }, z.core.$strip>>;
             }, z.core.$strict>>>;
+        }, z.core.$strict>, z.ZodUnion<readonly [z.ZodObject<{
+            prompt: z.ZodString;
+            type: z.ZodLiteral<"remotion">;
+            fps: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>, z.ZodObject<{
+            code: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"text">;
+                text: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"path">;
+                path: z.ZodString;
+            }, z.core.$strict>], "kind">;
             type: z.ZodLiteral<"remotion">;
-            prompt: z.ZodString;
             fps: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$strict>]>>;
+        }, z.core.$strict>]>]>>;
         audio: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
             type: z.ZodLiteral<"audio">;
             source: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -18682,11 +18729,21 @@ export declare const mulmoStudioSchema: z.ZodObject<{
                         bgOpacity: z.ZodOptional<z.ZodNumber>;
                     }, z.core.$strip>>;
                 }, z.core.$strict>>>;
+            }, z.core.$strict>, z.ZodUnion<readonly [z.ZodObject<{
+                prompt: z.ZodString;
+                type: z.ZodLiteral<"remotion">;
+                fps: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strict>, z.ZodObject<{
+                code: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    kind: z.ZodLiteral<"text">;
+                    text: z.ZodString;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"path">;
+                    path: z.ZodString;
+                }, z.core.$strict>], "kind">;
                 type: z.ZodLiteral<"remotion">;
-                prompt: z.ZodString;
                 fps: z.ZodOptional<z.ZodNumber>;
-            }, z.core.$strict>]>>;
+            }, z.core.$strict>]>]>>;
             audio: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
                 type: z.ZodLiteral<"audio">;
                 source: z.ZodDiscriminatedUnion<[z.ZodObject<{

package/lib/types/schema.js

@@ -359,13 +359,29 @@ export const mulmoVisionMediaSchema = z
     data: z.record(z.string(), z.any()),
 })
     .strict();
-export const mulmoRemotionMediaSchema = z
-    .object({
+export const remotionCodeSourceSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("text"), text: z.string().min(1) }).strict(),
+    z.object({ kind: z.literal("path"), path: z.string().min(1).describe("Relative to the script") }).strict(),
+]);
+const remotionMediaShape = {
     type: z.literal(ImageMediaType.Remotion),
-    prompt: z.string().min(1).describe("What the scene shows. Claude Code (claude -p) writes a Remotion component from it."),
     fps: z.number().min(1).max(60).optional().describe("Frame rate of the rendered video. Default: 30."),
-})
-    .strict();
+};
+// Two strict shapes rather than one object with a refine, so the bundled JSON schema states "prompt or code, not both" too.
+export const mulmoRemotionMediaSchema = z.union([
+    z
+        .object({
+        ...remotionMediaShape,
+        prompt: z.string().min(1).describe("What the scene shows. Claude Code (claude -p) writes a Remotion component from it."),
+    })
+        .strict(),
+    z
+        .object({
+        ...remotionMediaShape,
+        code: remotionCodeSourceSchema.describe("A finished Remotion component (TSX that default-exports the scene). It is rendered as is, without claude -p."),
+    })
+        .strict(),
+]);
 export const mulmoRemotionParamsSchema = z
     .object({
     brief: z.string().optional().describe("Whole-video art direction shared by every remotion beat (palette, type, mood), so all scenes look like one film."),

package/lib/types/type.d.ts

@@ -1,6 +1,6 @@
 import { type CallbackFunction } from "graphai";
 import type { UsageCollectorAPI } from "./usage.js";
-import { langSchema, localizedTextSchema, mulmoBeatSchema, mulmoScriptSchema, mulmoStudioSchema, mulmoStudioBeatSchema, mulmoStoryboardSchema, mulmoStoryboardSceneSchema, mulmoStudioMultiLingualSchema, mulmoStudioMultiLingualArraySchema, mulmoStudioMultiLingualDataSchema, mulmoStudioMultiLingualFileSchema, speakerDictionarySchema, speakerSchema, mulmoSpeechParamsSchema, mulmoImageParamsSchema, mulmoImageParamsImagesValueSchema, mulmoImageParamsImagesSchema, mulmoFillOptionSchema, mulmoTransitionSchema, mulmoVideoFilterSchema, mulmoMovieParamsSchema, mulmoSoundEffectParamsSchema, mulmoLipSyncParamsSchema, textSlideParamsSchema, speechOptionsSchema, speakerDataSchema, mulmoCanvasDimensionSchema, mulmoPromptTemplateSchema, mulmoPromptTemplateFileSchema, text2ImageProviderSchema, text2HtmlImageProviderSchema, text2MovieProviderSchema, text2SpeechProviderSchema, mulmoPresentationStyleSchema, multiLingualTextsSchema, mulmoImageAssetSchema, mulmoMermaidMediaSchema, mulmoRemotionMediaSchema, mulmoTextSlideMediaSchema, mulmoMarkdownMediaSchema, mulmoImageMediaSchema, mulmoChartMediaSchema, mediaSourceSchema, mediaSourceMermaidSchema, backgroundImageSchema, backgroundImageSourceSchema, mulmoSessionStateSchema, mulmoOpenAIImageModelSchema, mulmoGoogleImageModelSchema, mulmoGoogleMovieModelSchema, mulmoReplicateMovieModelSchema, mulmoImagePromptMediaSchema, mulmoImageReferenceSchema, mulmoMovieMediaSchema, mulmoMoviePromptMediaSchema, markdownLayoutSchema, row2Schema, grid2x2Schema, mulmoAvatarParamsSchema, avatarPositionSchema, speakerAvatarSchema, mulmoAvatarTrackSchema } from "./schema.js";
+import { langSchema, localizedTextSchema, mulmoBeatSchema, mulmoScriptSchema, mulmoStudioSchema, mulmoStudioBeatSchema, mulmoStoryboardSchema, mulmoStoryboardSceneSchema, mulmoStudioMultiLingualSchema, mulmoStudioMultiLingualArraySchema, mulmoStudioMultiLingualDataSchema, mulmoStudioMultiLingualFileSchema, speakerDictionarySchema, speakerSchema, mulmoSpeechParamsSchema, mulmoImageParamsSchema, mulmoImageParamsImagesValueSchema, mulmoImageParamsImagesSchema, mulmoFillOptionSchema, mulmoTransitionSchema, mulmoVideoFilterSchema, mulmoMovieParamsSchema, mulmoSoundEffectParamsSchema, mulmoLipSyncParamsSchema, textSlideParamsSchema, speechOptionsSchema, speakerDataSchema, mulmoCanvasDimensionSchema, mulmoPromptTemplateSchema, mulmoPromptTemplateFileSchema, text2ImageProviderSchema, text2HtmlImageProviderSchema, text2MovieProviderSchema, text2SpeechProviderSchema, mulmoPresentationStyleSchema, multiLingualTextsSchema, mulmoImageAssetSchema, mulmoMermaidMediaSchema, mulmoRemotionMediaSchema, remotionCodeSourceSchema, mulmoTextSlideMediaSchema, mulmoMarkdownMediaSchema, mulmoImageMediaSchema, mulmoChartMediaSchema, mediaSourceSchema, mediaSourceMermaidSchema, backgroundImageSchema, backgroundImageSourceSchema, mulmoSessionStateSchema, mulmoOpenAIImageModelSchema, mulmoGoogleImageModelSchema, mulmoGoogleMovieModelSchema, mulmoReplicateMovieModelSchema, mulmoImagePromptMediaSchema, mulmoImageReferenceSchema, mulmoMovieMediaSchema, mulmoMoviePromptMediaSchema, markdownLayoutSchema, row2Schema, grid2x2Schema, mulmoAvatarParamsSchema, avatarPositionSchema, speakerAvatarSchema, mulmoAvatarTrackSchema } from "./schema.js";
 import { pdf_modes, pdf_sizes, storyToScriptGenerateMode } from "./const.js";
 import type { LLM } from "./provider2agent.js";
 import { z } from "zod";
@@ -66,6 +66,7 @@ export type MulmoMovieMedia = z.infer<typeof mulmoMovieMediaSchema>;
 export type MulmoChartMedia = z.infer<typeof mulmoChartMediaSchema>;
 export type MulmoMermaidMedia = z.infer<typeof mulmoMermaidMediaSchema>;
 export type MulmoRemotionMedia = z.infer<typeof mulmoRemotionMediaSchema>;
+export type MulmoRemotionCodeSource = z.infer<typeof remotionCodeSourceSchema>;
 export type MulmoSessionState = z.infer<typeof mulmoSessionStateSchema>;
 export type MulmoStudioContext = {
     fileDirs: FileObject;

package/lib/utils/context.d.ts

@@ -549,8 +549,18 @@ export declare const createStudioData: (_mulmoScript: MulmoScript, fileName: str
                 style: string;
                 data: Record<string, any>;
             } | {
-                type: "remotion";
                 prompt: string;
+                type: "remotion";
+                fps?: number | undefined;
+            } | {
+                code: {
+                    kind: "text";
+                    text: string;
+                } | {
+                    kind: "path";
+                    path: string;
+                };
+                type: "remotion";
                 fps?: number | undefined;
             } | {
                 type: "slide";
@@ -3178,8 +3188,18 @@ export declare const initializeContextFromFiles: (files: FileObject, raiseError:
                     style: string;
                     data: Record<string, any>;
                 } | {
-                    type: "remotion";
                     prompt: string;
+                    type: "remotion";
+                    fps?: number | undefined;
+                } | {
+                    code: {
+                        kind: "text";
+                        text: string;
+                    } | {
+                        kind: "path";
+                        path: string;
+                    };
+                    type: "remotion";
                     fps?: number | undefined;
                 } | {
                     type: "slide";

package/lib/utils/image_plugins/remotion.d.ts

@@ -1,4 +1,4 @@
-import { ImageProcessorParams } from "../../types/index.js";
+import { ImageProcessorParams, MulmoRemotionCodeSource, MulmoStudioContext } from "../../types/index.js";
 import { ComponentReviewer, ComponentWriter } from "../remotion/claude_runner.js";
 import { SceneRenderer } from "../remotion/render.js";
 export declare const imageType: "remotion";
@@ -11,6 +11,7 @@ export type RemotionDeps = {
 export declare const remotionWorkDir: (imagePath: string) => string;
 export declare const remotionStillPath: (imagePath: string) => string;
 export declare const reviewCandidatePath: (filePath: string) => string;
+export declare const remotionCodeLocation: (code: MulmoRemotionCodeSource, context: MulmoStudioContext, beatIndex: number) => string;
 export declare const createRemotionProcess: (deps: RemotionDeps) => (params: ImageProcessorParams) => Promise<string | undefined>;
 export declare const process: (params: ImageProcessorParams) => Promise<string | undefined>;
 export declare const path: (params: import("../../types/type.js").BeatPathParams) => string;

package/lib/utils/image_plugins/remotion.js

@@ -3,6 +3,7 @@ import nodePath from "node:path";
 import { GraphAILogger } from "graphai";
 import { ImageMediaType } from "../../types/index.js";
 import { localizedText } from "../utils.js";
+import { getFullPath } from "../file.js";
 import { REMOTION_COMPONENT_FILE, buildRepairPrompt, buildReviewPrompt, buildScenePrompt, remotionCacheKey, } from "../remotion/claude_prompt.js";
 import { reviewComponentWithClaude, writeComponentWithClaude } from "../remotion/claude_runner.js";
 import { ensureRemotionPackages, renderRemotionScene } from "../remotion/render.js";
@@ -114,9 +115,18 @@ const toFrameCount = (durationSec, fps) => {
 const scenePosition = (beats, index) => (index < 0 ? undefined : { index, count: beats.length });
 // The words actually spoken over the scene: the translation when the video is rendered in another language.
 const spokenNarration = (context, beat, index) => (index < 0 ? beat.text : localizedText(beat, context.multiLingual?.[index], context.lang, context.studio.script.lang)) || undefined;
-const buildJob = (params, prompt, fps) => {
-    const { beat, context, imagePath, canvasSize } = params;
+const buildSceneOutput = (params, fps) => {
+    const { beat, imagePath, canvasSize } = params;
     const duration = params.beatDuration ?? beat.duration;
+    return {
+        workDir: remotionWorkDir(imagePath),
+        props: { durationInFrames: toFrameCount(duration ?? STILL_ONLY_DURATION_SEC, fps), fps, width: canvasSize.width, height: canvasSize.height },
+        videoPath: duration !== undefined ? imagePath : undefined,
+        stillPath: remotionStillPath(imagePath),
+    };
+};
+const buildJob = (params, prompt, fps) => {
+    const { beat, context, canvasSize } = params;
     const index = context.studio.script.beats.indexOf(beat);
     const spec = {
         prompt,
@@ -127,21 +137,49 @@ const buildJob = (params, prompt, fps) => {
         width: canvasSize.width,
         height: canvasSize.height,
     };
-    const workDir = remotionWorkDir(imagePath);
-    return {
-        spec,
-        workDir,
-        codePath: nodePath.join(workDir, `${remotionCacheKey(spec)}.tsx`),
-        props: { durationInFrames: toFrameCount(duration ?? STILL_ONLY_DURATION_SEC, fps), fps, width: spec.width, height: spec.height },
-        videoPath: duration !== undefined ? imagePath : undefined,
-        stillPath: remotionStillPath(imagePath),
-    };
+    const output = buildSceneOutput(params, fps);
+    return { ...output, spec, codePath: nodePath.join(output.workDir, `${remotionCacheKey(spec)}.tsx`) };
+};
+// Named in errors, so whoever wrote the component (usually the host's agent) knows what to fix.
+export const remotionCodeLocation = (code, context, beatIndex) => {
+    if (code.kind === "path")
+        return getFullPath(context.fileDirs.mulmoFileDirPath, code.path);
+    return beatIndex < 0 ? "inline code" : `inline code of beat ${beatIndex + 1}`;
+};
+const readGivenComponent = (code, location) => {
+    if (code.kind === "text")
+        return code.text;
+    try {
+        return fs.readFileSync(location, "utf8");
+    }
+    catch (error) {
+        throw new Error(`remotion: cannot read the component file ${location}`, { cause: error });
+    }
+};
+// A given component is the caller's to fix, so a failed render stops here instead of asking claude -p to repair it.
+const renderGivenComponent = async (params, code, fps, deps) => {
+    const output = buildSceneOutput(params, fps);
+    const location = remotionCodeLocation(code, params.context, params.context.studio.script.beats.indexOf(params.beat));
+    deps.ensurePackages();
+    const source = readGivenComponent(code, location);
+    fs.mkdirSync(output.workDir, { recursive: true });
+    fs.writeFileSync(nodePath.join(output.workDir, REMOTION_COMPONENT_FILE), source);
+    try {
+        await deps.renderScene({ workDir: output.workDir, props: output.props, videoPath: output.videoPath, stillPath: output.stillPath });
+    }
+    catch (error) {
+        throw new Error(`remotion beat failed to render the given component (code: ${location}): ${errorMessage(error)}`, { cause: error });
+    }
+    return output.videoPath ?? output.stillPath;
 };
 export const createRemotionProcess = (deps) => async (params) => {
     const { beat, context } = params;
     if (!beat.image || beat.image.type !== imageType)
         return;
-    const job = buildJob(params, beat.image.prompt, beat.image.fps ?? DEFAULT_FPS);
+    const fps = beat.image.fps ?? DEFAULT_FPS;
+    if ("code" in beat.image)
+        return await renderGivenComponent(params, beat.image.code, fps, deps);
+    const job = buildJob(params, beat.image.prompt, fps);
     deps.ensurePackages();
     fs.mkdirSync(job.workDir, { recursive: true });
     const { code, isNew } = await loadOrWriteComponent(job, context.force, deps);

package/lib/utils/remotion/render.d.ts

@@ -15,5 +15,6 @@ export type RemotionRenderRequest = {
     }[];
 };
 export type SceneRenderer = (request: RemotionRenderRequest) => Promise<void>;
+export declare const missingInstalledRemotionPackages: () => string[];
 export declare const ensureRemotionPackages: () => void;
 export declare const renderRemotionScene: SceneRenderer;

package/lib/utils/remotion/render.js

@@ -24,10 +24,12 @@ const isPackageInstalled = (name) => {
         return !(error instanceof Error && "code" in error && error.code === "MODULE_NOT_FOUND");
     }
 };
+// Resolved from mulmocast's own location, which is where the renderer looks for them.
+export const missingInstalledRemotionPackages = () => missingRemotionPackages(isPackageInstalled);
 // Checked before asking claude -p for a component: a generated import of a missing optional peer
 // would otherwise surface as an opaque bundling error after the generation was already paid for.
 export const ensureRemotionPackages = () => {
-    const missing = missingRemotionPackages(isPackageInstalled);
+    const missing = missingInstalledRemotionPackages();
     if (missing.length > 0) {
         throw new Error(`The remotion beat needs packages that are not installed (${missing.join(", ")}). Install them with: ${remotionInstallCommand()}`);
     }

package/lib/utils/remotion/system_prompt.d.ts

@@ -1,3 +1,4 @@
 export declare const REMOTION_SYSTEM_PROMPT: string;
+export declare const REMOTION_COMPONENT_GUIDE: string;
 export declare const REMOTION_REVIEW_MARKER = "LGTM";
 export declare const REMOTION_REVIEW_SYSTEM_PROMPT: string;

package/lib/utils/remotion/system_prompt.js

@@ -2,13 +2,13 @@ import { REMOTION_SCENE_PACKAGES } from "./packages.js";
 const ALLOWED_IMPORTS = ["react", "remotion", ...REMOTION_SCENE_PACKAGES].map((name) => `"${name}"`).join(", ");
 // The contract and the house style for the component `claude -p` writes for one remotion beat.
 // Every snippet in the toolkit section was rendered with this repository's renderer settings.
-const OUTPUT_CONTRACT = `You are a senior motion designer and Remotion (v4.0.533) engineer. You write ONE React component in TypeScript (TSX) that renders one scene of a commercial-quality video.
-
-# Output contract
-- Reply with ONLY the TSX source in one \`\`\`tsx code block. No explanation before or after.
-- \`export default\` the scene component. It receives props \`{ durationInFrames: number; fps: number; width: number; height: number }\`; read them with \`useVideoConfig()\`.
+const ROLE = `You are a senior motion designer and Remotion (v4.0.533) engineer. You write ONE React component in TypeScript (TSX) that renders one scene of a commercial-quality video.`;
+const REPLY_FORMAT = `- Reply with ONLY the TSX source in one \`\`\`tsx code block. No explanation before or after.`;
+const COMPONENT_RULES = `- One self-contained file: no relative imports, since it is rendered on its own.`;
+const CONTRACT_BODY = `- \`export default\` the scene component. It receives props \`{ durationInFrames: number; fps: number; width: number; height: number }\`; read them with \`useVideoConfig()\`.
 - Allowed imports, nothing else: ${ALLOWED_IMPORTS}. Subpaths of these packages are allowed too, e.g. "@remotion/transitions/fade" (also "/slide", "/wipe", "/iris", "/cross-zoom", "/film-burn", "/dissolve", "/clock-wipe") and "@remotion/effects/<name>".
 - No network, no external URLs, no image/video/audio files, no web fonts. Draw everything with DOM, SVG, canvas or three.js.`;
+const OUTPUT_CONTRACT = [ROLE, "", "# Output contract", REPLY_FORMAT, CONTRACT_BODY].join("\n");
 const TIMING_RULES = `# Timing (hard rules — breaking them causes flicker or broken renders)
 - Everything is a pure function of \`useCurrentFrame()\`. NEVER use CSS animations/transitions, \`setTimeout\`, \`requestAnimationFrame\`, \`Date\`, or three.js \`useFrame\`.
 - NEVER use \`Math.random()\`; use \`random("seed-" + i)\` from "remotion" or \`noise2D/noise3D\` from "@remotion/noise".
@@ -51,6 +51,10 @@ const SELF_CHECK = `# Before you answer, check silently
 - At 30%, 60% and 100% of the duration the frame is fully composed, readable, balanced, and nothing overflows the safe margins or overlaps.
 - The scene matches the brief and the narration, and looks like a frame from a premium brand film.`;
 export const REMOTION_SYSTEM_PROMPT = [OUTPUT_CONTRACT, TIMING_RULES, DESIGN_SYSTEM, MOTION_LANGUAGE, TOOLKIT, SELF_CHECK].join("\n\n");
+// The same contract for a host's agent that writes the component file itself and passes it as \`code\`.
+// The system prompt stays byte-identical, since it is part of every cached component's key.
+const COMPONENT_CONTRACT = ["# Component contract", COMPONENT_RULES, CONTRACT_BODY].join("\n");
+export const REMOTION_COMPONENT_GUIDE = [COMPONENT_CONTRACT, TIMING_RULES, DESIGN_SYSTEM, MOTION_LANGUAGE, TOOLKIT, SELF_CHECK].join("\n\n");
 export const REMOTION_REVIEW_MARKER = "LGTM";
 export const REMOTION_REVIEW_SYSTEM_PROMPT = [
     REMOTION_SYSTEM_PROMPT,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mulmocast",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "description": "",
   "type": "module",
   "main": "lib/index.node.js",
@@ -16,6 +16,10 @@
     "./data": {
       "default": "./lib/data/index.js"
     },
+    "./remotion": {
+      "types": "./lib/index.remotion.d.ts",
+      "default": "./lib/index.remotion.js"
+    },
     "./assets/*": "./assets/*",
     "./scripts/*": "./scripts/*",
     "./tools/complete_script": {