mulmocast 2.16.0 → 2.18.0

package/lib/utils/estimate_usage.js

@@ -4,10 +4,12 @@
 // assume every asset is generated fresh.
 import { Tiktoken } from "js-tiktoken/lite";
 import o200k_base from "js-tiktoken/ranks/o200k_base";
-import { provider2TTSAgent, provider2MovieAgent, gptImageOutputTokens, getModelDuration, defaultMovieModel, veoExtendedSeconds, VEO_EXTENSION_MODEL, VEO_SEGMENT_SEC, getModelPricing, defaultProviders, } from "../types/provider2agent.js";
+import { provider2TTSAgent, provider2MovieAgent, gptImageOutputTokens, isGptImage25Model, getModelDuration, defaultMovieModel, getModelPricing, defaultProviders, } from "../types/provider2agent.js";
 import { text2SpeechProviderSchema, text2MovieProviderSchema } from "../types/schema.js";
 import { MulmoPresentationStyleMethods } from "../methods/mulmo_presentation_style.js";
 import { MulmoBeatMethods } from "../methods/mulmo_beat.js";
+import { geminiTtsInputText } from "./gemini_tts.js";
+import { geminiOmniTotalSec, isGeminiOmniVideoModel } from "./gemini_omni_video.js";
 import { imagePrompt, htmlImageSystemPrompt, translateSystemPrompt, translatePrompts } from "./prompt.js";
 const MILLION = 1_000_000;
 const LATIN_CHARS_PER_TOKEN = 4;
@@ -92,15 +94,14 @@ const buildOpenAITts = ({ speaker, text, textIsFinal, beatIndex, lang }) => {
     return { process: "tts", beatIndex, lang, provider: "openai", model, inputChars: metric(text.length, textIsFinal), ...tokenMetrics };
 };
 const buildGeminiTts = ({ speaker, speechOptions, text, beatIndex, lang }) => {
-    // The gemini TTS agent wraps the transcript in a "Director's Notes" prompt when an instruction is set.
-    const prompt = speechOptions?.instruction ? `### DIRECTOR'S NOTES\n${speechOptions.instruction}\n\n#### TRANSCRIPT\n${text}` : text;
+    const model = speaker.model ?? provider2TTSAgent.gemini.defaultModel;
     return {
         process: "tts",
         beatIndex,
         lang,
         provider: "gemini",
-        model: speaker.model ?? provider2TTSAgent.gemini.defaultModel,
-        inputTokens: estimated(countHeuristicTokens(prompt)),
+        model,
+        inputTokens: estimated(countHeuristicTokens(geminiTtsInputText(model, text, speechOptions?.instruction))),
         outputTokens: estimated(estimateSpeechSec(text) * GEMINI_TTS_AUDIO_TOKENS_PER_SEC),
     };
 };
@@ -162,8 +163,8 @@ const gptImageSize = (canvasSize) => {
 const gptImageOutputMetric = (model, canvasSize, quality) => {
     const table = gptImageOutputTokens[gptImageSize(canvasSize)];
     const knownQuality = quality === "low" || quality === "medium" || quality === "high" ? quality : undefined;
-    // Unspecified quality means API "auto"; assume "high" as the conservative upper bound.
-    const tokens = table[knownQuality ?? "high"];
+    // Anything else renders at "high" (the upper bound), except an explicit "auto" on 2.5, which renders at "low".
+    const tokens = table[knownQuality ?? (quality === "auto" && isGptImage25Model(model) ? "low" : "high")];
     return metric(tokens, GPT_IMAGE_FIXED_TOKEN_MODELS.includes(model) && knownQuality !== undefined);
 };
 const buildImageRecord = ({ process, provider, model, prompt, canvasSize, quality, beatIndex, refKey }) => {
@@ -217,8 +218,8 @@ const beatDurationMetric = (beat) => {
     }
     return estimated(beat.text ? estimateSpeechSec(beat.text) : DEFAULT_MOVIE_DURATION_SEC);
 };
-// The movie agent extends these clips past one segment instead of capping them, and Google bills every generated second.
-const isVeoExtension = (provider, model, duration) => provider === "google" && model === VEO_EXTENSION_MODEL && duration.value > VEO_SEGMENT_SEC;
+// Gemini Omni beats past one segment are extended rather than capped, and Google bills every generated second.
+const isGeminiOmniMovie = (provider, model) => provider === "google" && isGeminiOmniVideoModel(model);
 const snapMovieDuration = (provider, model, duration) => {
     if (!isKeyOf(provider2MovieAgent[provider].modelParams, model)) {
         return duration;
@@ -234,8 +235,8 @@ const estimateMovieGeneration = (style, beat, beatIndex, refKey) => {
     }
     const model = info.movieParams?.model ?? defaultMovieModel(provider, info.movieParams);
     const duration = beat ? beatDurationMetric(beat) : estimated(DEFAULT_MOVIE_DURATION_SEC);
-    const predictSec = isVeoExtension(provider, model, duration)
-        ? metric(veoExtendedSeconds(duration.value), duration.precision === "exact")
+    const predictSec = isGeminiOmniMovie(provider, model)
+        ? metric(geminiOmniTotalSec(duration.value), duration.precision === "exact")
         : snapMovieDuration(provider, model, duration);
     return attachCost({ process: refKey === undefined ? "movie" : "movieReference", beatIndex, refKey, provider, model, predictSec });
 };

package/lib/utils/gemini_omni_video.d.ts

@@ -0,0 +1,49 @@
+export declare const GEMINI_OMNI_MIN_SEGMENT_SEC = 3;
+export declare const GEMINI_OMNI_MAX_SEGMENT_SEC = 10;
+export declare const GEMINI_OMNI_MAX_TOTAL_SEC = 40;
+export declare const GEMINI_OMNI_RESOLUTION = "720p";
+export declare const isGeminiOmniVideoModel: (model: string) => boolean;
+export declare const geminiOmniTotalSec: (requestedSec: number) => number;
+export declare const geminiOmniSegments: (requestedSec: number) => number[];
+export declare const geminiOmniAspectRatio: (canvasSize: {
+    width: number;
+    height: number;
+}) => string;
+export type GeminiOmniImage = {
+    data: string;
+    mime_type: string;
+};
+export type GeminiOmniVideoRequestInput = {
+    model: string;
+    prompt: string;
+    aspectRatio: string;
+    durationSec: number;
+    frames?: GeminiOmniImage[];
+    previousInteractionId?: string;
+};
+export declare const geminiOmniExtensionPrompt: (prompt: string) => string;
+export declare const buildGeminiOmniVideoRequest: ({ model, prompt, aspectRatio, durationSec, frames, previousInteractionId }: GeminiOmniVideoRequestInput) => {
+    response_format: {
+        type: "video";
+        aspect_ratio: string;
+        resolution: string;
+        duration: string;
+    };
+    previous_interaction_id?: string | undefined;
+    model: string;
+    input: string | ({
+        data: string;
+        mime_type: string;
+        type: "image";
+    } | {
+        type: "text";
+        text: string;
+    })[];
+};
+export type GeminiOmniVideoRequest = ReturnType<typeof buildGeminiOmniVideoRequest>;
+type InteractionVideo = {
+    data?: string;
+    mime_type?: string;
+};
+export declare const videoFromInteraction: (video: InteractionVideo | undefined) => Buffer;
+export {};

package/lib/utils/gemini_omni_video.js

@@ -0,0 +1,36 @@
+import { getAspectRatio } from "./utils.js";
+// Gemini Omni video goes through the Interactions API: one call makes 3 to 10 whole seconds, and a call that
+// names the previous interaction extends that video, up to 40 seconds in all.
+export const GEMINI_OMNI_MIN_SEGMENT_SEC = 3;
+export const GEMINI_OMNI_MAX_SEGMENT_SEC = 10;
+export const GEMINI_OMNI_MAX_TOTAL_SEC = 40;
+export const GEMINI_OMNI_RESOLUTION = "720p";
+const GEMINI_OMNI_ASPECT_RATIOS = ["16:9", "9:16"];
+export const isGeminiOmniVideoModel = (model) => model.startsWith("gemini-omni-");
+export const geminiOmniTotalSec = (requestedSec) => {
+    if (!Number.isFinite(requestedSec))
+        throw new RangeError(`Invalid video duration: ${requestedSec}`);
+    return Math.min(Math.max(Math.ceil(requestedSec), GEMINI_OMNI_MIN_SEGMENT_SEC), GEMINI_OMNI_MAX_TOTAL_SEC);
+};
+// Split evenly so no segment falls under the 3-second minimum (11s is 6 + 5, not 10 + 1).
+export const geminiOmniSegments = (requestedSec) => {
+    const totalSec = geminiOmniTotalSec(requestedSec);
+    const count = Math.ceil(totalSec / GEMINI_OMNI_MAX_SEGMENT_SEC);
+    const baseSec = Math.floor(totalSec / count);
+    return Array.from({ length: count }, (_, index) => baseSec + (index < totalSec % count ? 1 : 0));
+};
+export const geminiOmniAspectRatio = (canvasSize) => getAspectRatio(canvasSize, GEMINI_OMNI_ASPECT_RATIOS);
+export const geminiOmniExtensionPrompt = (prompt) => `The scene continues: ${prompt}`;
+export const buildGeminiOmniVideoRequest = ({ model, prompt, aspectRatio, durationSec, frames = [], previousInteractionId }) => ({
+    model,
+    input: frames.length > 0 ? [...frames.map((frame) => ({ type: "image", ...frame })), { type: "text", text: prompt }] : prompt,
+    ...(previousInteractionId ? { previous_interaction_id: previousInteractionId } : {}),
+    response_format: { type: "video", aspect_ratio: aspectRatio, resolution: GEMINI_OMNI_RESOLUTION, duration: `${durationSec}s` },
+});
+export const videoFromInteraction = (video) => {
+    if (!video?.data)
+        throw new Error("No video data returned");
+    if (video.mime_type !== "video/mp4")
+        throw new Error(`Gemini Omni returned ${video.mime_type ?? "video of an unknown type"}, expected video/mp4`);
+    return Buffer.from(video.data, "base64");
+};

package/lib/utils/gemini_tts.d.ts

@@ -0,0 +1,45 @@
+export declare const GEMINI_INTERACTIONS_TTS_MODELS: ReadonlySet<string>;
+export declare const GEMINI_TTS_SAMPLE_RATE = 24000;
+export declare const geminiDirectorsNotesPrompt: (text: string, instructions?: string) => string;
+export declare const geminiTtsInputText: (model: string, text: string, instructions?: string) => string;
+export declare const usesGeminiInteractionsTts: (model: string) => boolean;
+export type GeminiInteractionsTtsInput = {
+    model: string;
+    text: string;
+    voice: string;
+    instructions?: string;
+};
+export declare const buildGeminiInteractionsTtsRequest: ({ model, text, voice, instructions }: GeminiInteractionsTtsInput) => {
+    model: string;
+    input: {
+        type: "user_input";
+        content: {
+            annotations?: {
+                type: "speech_metadata";
+                style: string;
+            }[] | undefined;
+            type: "text";
+            text: string;
+        }[];
+    }[];
+    response_format: {
+        type: "audio";
+        mime_type: string;
+        sample_rate: number;
+    };
+    generation_config: {
+        speech_config: {
+            voice: string;
+        }[];
+    };
+};
+type InteractionAudio = {
+    data?: string;
+    mime_type?: string;
+    sample_rate?: number;
+};
+export declare const pcmFromInteractionAudio: (audio: InteractionAudio | undefined) => {
+    rawPcm: Buffer;
+    sampleRate: number;
+};
+export {};

package/lib/utils/gemini_tts.js

@@ -0,0 +1,35 @@
+// Gemini 3.8 TTS takes the Interactions API: the text is read verbatim, so speaker direction goes in a
+// speech_metadata annotation instead of the prompt, and raw PCM must be asked for (the unary default is WAV).
+export const GEMINI_INTERACTIONS_TTS_MODELS = new Set(["gemini-3.8-flash-tts", "gemini-3.8-flash-lite-tts"]);
+export const GEMINI_TTS_SAMPLE_RATE = 24000;
+// 2.5 TTS has no field for direction, so it goes in the prompt: https://ai.google.dev/gemini-api/docs/speech-generation#controllable
+export const geminiDirectorsNotesPrompt = (text, instructions) => instructions ? ["### DIRECTOR'S NOTES", instructions, "", "#### TRANSCRIPT", text].join("\n") : text;
+// The text the model is given for one line: 3.8 gets the transcript plus the style annotation, 2.5 the wrapped prompt.
+export const geminiTtsInputText = (model, text, instructions) => usesGeminiInteractionsTts(model) ? [text, instructions].filter(Boolean).join("\n") : geminiDirectorsNotesPrompt(text, instructions);
+export const usesGeminiInteractionsTts = (model) => GEMINI_INTERACTIONS_TTS_MODELS.has(model);
+export const buildGeminiInteractionsTtsRequest = ({ model, text, voice, instructions }) => ({
+    model,
+    input: [
+        {
+            type: "user_input",
+            content: [{ type: "text", text, ...(instructions ? { annotations: [{ type: "speech_metadata", style: instructions }] } : {}) }],
+        },
+    ],
+    response_format: { type: "audio", mime_type: "audio/l16", sample_rate: GEMINI_TTS_SAMPLE_RATE },
+    generation_config: { speech_config: [{ voice }] },
+});
+const sampleRateOf = (audio) => {
+    if (typeof audio.sample_rate === "number" && audio.sample_rate > 0)
+        return audio.sample_rate;
+    const match = audio.mime_type?.match(/rate=(\d+)/);
+    return match ? Number(match[1]) : GEMINI_TTS_SAMPLE_RATE;
+};
+// Anything but headerless 16-bit PCM would be fed to the PCM encoder as noise, so it is an error, not a guess.
+export const pcmFromInteractionAudio = (audio) => {
+    if (!audio?.data)
+        throw new Error("No audio data returned");
+    if (!audio.mime_type?.toLowerCase().startsWith("audio/l16")) {
+        throw new Error(`Gemini TTS returned ${audio.mime_type ?? "audio of an unknown type"}, expected audio/l16`);
+    }
+    return { rawPcm: Buffer.from(audio.data, "base64"), sampleRate: sampleRateOf(audio) };
+};

package/lib/utils/html_render.d.ts

@@ -1,4 +1,5 @@
-export declare const renderHTMLToImage: (html: string, outputPath: string, width: number, height: number, isMermaid?: boolean, omitBackground?: boolean) => Promise<void>;
+import { type RenderNetworkOptions } from "./render_network_policy.js";
+export declare const renderHTMLToImage: (html: string, outputPath: string, width: number, height: number, isMermaid?: boolean, omitBackground?: boolean, network?: RenderNetworkOptions) => Promise<void>;
 /**
  * Render an animated HTML page frame-by-frame using Puppeteer.
  *
@@ -9,18 +10,18 @@ export declare const renderHTMLToImage: (html: string, outputPath: string, width
  *
  * The user-defined render() function may be sync or async.
  */
-export declare const renderHTMLToFrames: (html: string, outputDir: string, width: number, height: number, totalFrames: number, fps: number) => Promise<string[]>;
+export declare const renderHTMLToFrames: (html: string, outputDir: string, width: number, height: number, totalFrames: number, fps: number, network?: RenderNetworkOptions) => Promise<string[]>;
 /**
  * Record an animated HTML page as video using Puppeteer's screencast API.
  * The animation plays in real-time via requestAnimationFrame, and
  * page.screencast() captures frames directly to an mp4 file.
  */
-export declare const renderHTMLToVideo: (html: string, videoPath: string, width: number, height: number, totalFrames: number, fps: number) => Promise<void>;
+export declare const renderHTMLToVideo: (html: string, videoPath: string, width: number, height: number, totalFrames: number, fps: number, network?: RenderNetworkOptions) => Promise<void>;
 /**
  * Render the final frame of an animated HTML page as a static image.
  * Loads the animated HTML, calls window.renderFinal() to set all animations
  * to their end state, then takes a screenshot. Used for PDF/thumbnail generation.
  */
-export declare const renderHTMLToFinalFrame: (html: string, outputPath: string, width: number, height: number) => Promise<void>;
-export declare const renderMarkdownToImage: (markdown: string, style: string, outputPath: string, width: number, height: number) => Promise<void>;
+export declare const renderHTMLToFinalFrame: (html: string, outputPath: string, width: number, height: number, network?: RenderNetworkOptions) => Promise<void>;
+export declare const renderMarkdownToImage: (markdown: string, style: string, outputPath: string, width: number, height: number, network?: RenderNetworkOptions) => Promise<void>;
 export declare const interpolate: (template: string, data: Record<string, string>) => string;

package/lib/utils/html_render.js

@@ -4,6 +4,8 @@ import nodePath from "node:path";
 import crypto from "node:crypto";
 import { marked } from "marked";
 import puppeteer from "puppeteer";
+import { guardRenderPage } from "./render_network_guard.js";
+import { strictNetworkLaunchArgs, withRenderContentSecurityPolicy } from "./render_network_policy.js";
 import { GraphAILogger } from "graphai";
 const isCI = process.env.CI === "true";
 const VIDEO_LOAD_TIMEOUT_MS = 15000;
@@ -83,15 +85,16 @@ const resolveWaitUntil = (html) => {
  * and navigate via page.goto (setContent uses about:blank origin
  * which blocks file:// loading).
  */
-const loadHtmlIntoPage = async (page, html, timeout_ms) => {
+const renderTempPagePath = () => nodePath.join(os.tmpdir(), `mulmocast_render_${crypto.randomUUID()}.html`);
+const loadHtmlIntoPage = async (page, html, timeout_ms, forcedFilePath) => {
     const waitUntil = resolveWaitUntil(html);
     const hasFileUrls = /file:\/\//.test(html);
     const hasExternalScripts = /script src=["']https?:\/\//.test(html);
     // puppeteer's setContent does not accept "networkidle0" (no navigation, so network-idle states aren't meaningful in types).
     // Route any HTML that needs network-idle semantics through the page.goto path to preserve the original wait behavior.
     const needsNetworkIdle = waitUntil === "networkidle0";
-    if (hasFileUrls || hasExternalScripts || needsNetworkIdle) {
-        const tmpFile = nodePath.join(os.tmpdir(), `mulmocast_render_${crypto.randomUUID()}.html`);
+    if (forcedFilePath || hasFileUrls || hasExternalScripts || needsNetworkIdle) {
+        const tmpFile = forcedFilePath ?? renderTempPagePath();
         fs.writeFileSync(tmpFile, html);
         try {
             await page.goto(`file://${tmpFile}`, { waitUntil, timeout: timeout_ms });
@@ -109,14 +112,28 @@ const loadHtmlIntoPage = async (page, html, timeout_ms) => {
         await page.setContent(html, { waitUntil, timeout: timeout_ms });
     }
 };
-export const renderHTMLToImage = async (html, outputPath, width, height, isMermaid = false, omitBackground = false) => {
+const RENDER_LOAD_TIMEOUT_MS = 30000;
+const renderLaunchArgs = ({ strictNetwork = false }) => [
+    ...(isCI ? ["--no-sandbox"] : []),
+    "--allow-file-access-from-files",
+    ...(strictNetwork ? strictNetworkLaunchArgs() : []),
+];
+// Strict mode always loads through a file: the guard's WebRTC removal never reaches a setContent document.
+const loadGuardedPage = async (page, html, allowedFileRoots) => {
+    const pagePath = renderTempPagePath();
+    await guardRenderPage(page, [pagePath, ...allowedFileRoots]);
+    await loadHtmlIntoPage(page, withRenderContentSecurityPolicy(html), RENDER_LOAD_TIMEOUT_MS, pagePath);
+};
+const openRenderPage = async (browser, html, { strictNetwork = false, allowedFileRoots = [] }) => {
+    const page = await browser.newPage();
+    await (strictNetwork ? loadGuardedPage(page, html, allowedFileRoots) : loadHtmlIntoPage(page, html, RENDER_LOAD_TIMEOUT_MS));
+    return page;
+};
+export const renderHTMLToImage = async (html, outputPath, width, height, isMermaid = false, omitBackground = false, network = {}) => {
     // Use Puppeteer to render HTML to an image
-    const browser = await puppeteer.launch({
-        args: isCI ? ["--no-sandbox", "--allow-file-access-from-files"] : ["--allow-file-access-from-files"],
-    });
+    const browser = await puppeteer.launch({ args: renderLaunchArgs(network) });
     try {
-        const page = await browser.newPage();
-        await loadHtmlIntoPage(page, html, 30000);
+        const page = await openRenderPage(browser, html, network);
         // Adjust page settings if needed (like width, height, etc.)
         await page.setViewport({ width, height });
         // height:100% ensures background fills viewport; only reset html, let body styles come from custom CSS
@@ -158,14 +175,10 @@ export const renderHTMLToImage = async (html, outputPath, width, height, isMerma
  *
  * The user-defined render() function may be sync or async.
  */
-export const renderHTMLToFrames = async (html, outputDir, width, height, totalFrames, fps) => {
-    const browser = await puppeteer.launch({
-        args: isCI ? ["--no-sandbox", "--allow-file-access-from-files"] : ["--allow-file-access-from-files"],
-    });
+export const renderHTMLToFrames = async (html, outputDir, width, height, totalFrames, fps, network = {}) => {
+    const browser = await puppeteer.launch({ args: renderLaunchArgs(network) });
     try {
-        const page = await browser.newPage();
-        // Wait for Tailwind CSS CDN to load
-        await loadHtmlIntoPage(page, html, 30000);
+        const page = await openRenderPage(browser, html, network);
         await page.setViewport({ width, height });
         await page.addStyleTag({ content: "html{height:100%;margin:0;padding:0;overflow:hidden}" });
         // Scale content to fit viewport (same logic as renderHTMLToImage)
@@ -199,14 +212,11 @@ export const renderHTMLToFrames = async (html, outputDir, width, height, totalFr
  * The animation plays in real-time via requestAnimationFrame, and
  * page.screencast() captures frames directly to an mp4 file.
  */
-export const renderHTMLToVideo = async (html, videoPath, width, height, totalFrames, fps) => {
+export const renderHTMLToVideo = async (html, videoPath, width, height, totalFrames, fps, network = {}) => {
     const duration_ms = (totalFrames / fps) * 1000;
-    const browser = await puppeteer.launch({
-        args: isCI ? ["--no-sandbox", "--allow-file-access-from-files"] : ["--allow-file-access-from-files"],
-    });
+    const browser = await puppeteer.launch({ args: renderLaunchArgs(network) });
     try {
-        const page = await browser.newPage();
-        await loadHtmlIntoPage(page, html, 30000);
+        const page = await openRenderPage(browser, html, network);
         await page.setViewport({ width, height });
         await page.addStyleTag({ content: "html{height:100%;margin:0;padding:0;overflow:hidden}" });
         await scaleContentToFit(page, width, height);
@@ -242,13 +252,10 @@ export const renderHTMLToVideo = async (html, videoPath, width, height, totalFra
  * Loads the animated HTML, calls window.renderFinal() to set all animations
  * to their end state, then takes a screenshot. Used for PDF/thumbnail generation.
  */
-export const renderHTMLToFinalFrame = async (html, outputPath, width, height) => {
-    const browser = await puppeteer.launch({
-        args: isCI ? ["--no-sandbox", "--allow-file-access-from-files"] : ["--allow-file-access-from-files"],
-    });
+export const renderHTMLToFinalFrame = async (html, outputPath, width, height, network = {}) => {
+    const browser = await puppeteer.launch({ args: renderLaunchArgs(network) });
     try {
-        const page = await browser.newPage();
-        await loadHtmlIntoPage(page, html, 30000);
+        const page = await openRenderPage(browser, html, network);
         await page.setViewport({ width, height });
         await page.addStyleTag({ content: "html{height:100%;margin:0;padding:0;overflow:hidden}" });
         await scaleContentToFit(page, width, height);
@@ -266,11 +273,11 @@ export const renderHTMLToFinalFrame = async (html, outputPath, width, height) =>
         await browser.close();
     }
 };
-export const renderMarkdownToImage = async (markdown, style, outputPath, width, height) => {
+export const renderMarkdownToImage = async (markdown, style, outputPath, width, height, network = {}) => {
     const header = `<head><style>${style}</style></head>`;
     const body = await marked(markdown);
     const html = `<html>${header}<body>${body}</body></html>`;
-    await renderHTMLToImage(html, outputPath, width, height);
+    await renderHTMLToImage(html, outputPath, width, height, false, false, network);
 };
 export const interpolate = (template, data) => {
     return template.replace(/\$\{(.*?)\}/g, (_, key) => data[key.trim()] ?? "");

package/lib/utils/image_plugins/chart.js

@@ -3,6 +3,7 @@ import { renderHTMLToImage, interpolate } from "../html_render.js";
 import { parrotingImagePath, generateUniqueId } from "./utils.js";
 import { resolveCombinedStyle } from "./bg_image_util.js";
 import { chartHtml, escapedChartTemplateValues, resolveChartPlugins, stringifyChartData } from "./chart_html.js";
+import { MulmoStudioContextMethods } from "../../methods/mulmo_studio_context.js";
 export const imageType = "chart";
 const processChart = async (params) => {
     const { beat, imagePath, canvasSize } = params;
@@ -19,7 +20,7 @@ const processChart = async (params) => {
         chart_width: chart_width.toString(),
         chart_plugins: resolveChartPlugins(chartType),
     });
-    await renderHTMLToImage(htmlData, imagePath, canvasSize.width, canvasSize.height);
+    await renderHTMLToImage(htmlData, imagePath, canvasSize.width, canvasSize.height, false, false, MulmoStudioContextMethods.getRenderNetworkOptions(params.context));
     return imagePath;
 };
 const dumpHtml = async (params) => {

package/lib/utils/image_plugins/html_tailwind.js

@@ -7,6 +7,7 @@ import { framesToVideo } from "../ffmpeg_utils.js";
 import { parrotingImagePath } from "./utils.js";
 import { swipeElementsToHtml, swipeElementsToScript } from "../swipe_to_html.js";
 import { htmlTailwindMarkup } from "./html_tailwind_markup.js";
+import { MulmoStudioContextMethods } from "../../methods/mulmo_studio_context.js";
 export const imageType = "html_tailwind";
 /**
  * Resolve image:name references to file:// absolute paths using imageRefs.
@@ -178,13 +179,13 @@ const processHtmlTailwindAnimated = async (params) => {
         // imagePath is set to the .mp4 path by imagePluginAgent for animated beats
         const videoPath = imagePath;
         if (animConfig.movie) {
-            await renderHTMLToVideo(htmlData, videoPath, canvasSize.width, canvasSize.height, totalFrames, fps);
+            await renderHTMLToVideo(htmlData, videoPath, canvasSize.width, canvasSize.height, totalFrames, fps, MulmoStudioContextMethods.getRenderNetworkOptions(params.context));
         }
         else {
             const framesDir = videoPath.replace(/\.[^/.]+$/, "_frames");
             fs.mkdirSync(framesDir, { recursive: true });
             try {
-                await renderHTMLToFrames(htmlData, framesDir, canvasSize.width, canvasSize.height, totalFrames, fps);
+                await renderHTMLToFrames(htmlData, framesDir, canvasSize.width, canvasSize.height, totalFrames, fps, MulmoStudioContextMethods.getRenderNetworkOptions(params.context));
                 await framesToVideo(framesDir, videoPath, fps, canvasSize.width, canvasSize.height);
             }
             finally {
@@ -197,7 +198,7 @@ const processHtmlTailwindAnimated = async (params) => {
     // even when exact duration is unknown (e.g., PDF generation without audio).
     const finalFramePath = imagePath.replace(/_animated\.mp4$/, ".png");
     const finalHtml = buildAnimatedHtml(params, FINAL_FRAME_TOTAL, fps);
-    await renderHTMLToFinalFrame(finalHtml, finalFramePath, canvasSize.width, canvasSize.height);
+    await renderHTMLToFinalFrame(finalHtml, finalFramePath, canvasSize.width, canvasSize.height, MulmoStudioContextMethods.getRenderNetworkOptions(params.context));
     // Return video path when video was generated, otherwise return the static PNG path
     return duration !== undefined ? imagePath : finalFramePath;
 };
@@ -216,7 +217,7 @@ const processHtmlTailwindStatic = async (params) => {
     const resolvedAllRefs = resolveMovieRefs(resolvedImageRefs, params.movieRefs ?? {});
     const resolvedImages = resolveRelativeImagePaths(resolvedAllRefs, context.fileDirs.mulmoFileDirPath);
     const htmlData = resolveRelativeModelPathsInScript(resolvedImages, context.fileDirs.mulmoFileDirPath);
-    await renderHTMLToImage(htmlData, imagePath, canvasSize.width, canvasSize.height);
+    await renderHTMLToImage(htmlData, imagePath, canvasSize.width, canvasSize.height, false, false, MulmoStudioContextMethods.getRenderNetworkOptions(params.context));
     return imagePath;
 };
 const processHtmlTailwind = async (params) => {

package/lib/utils/image_plugins/markdown.js

@@ -5,6 +5,7 @@ import { resolveCombinedStyle } from "./bg_image_util.js";
 import { renderMarkdownContent, renderMarkdownLayout, layoutToMarkdown, toMarkdownString } from "./markdown_layout.js";
 import { resolveImageRefs, resolveMovieRefs } from "./html_tailwind.js";
 import { isObject } from "graphai";
+import { MulmoStudioContextMethods } from "../../methods/mulmo_studio_context.js";
 /**
  * This path renders once to a PNG, so a random element id is fine. The browser path needs
  * a stable one and supplies its own — that generator is the only thing the two callers of
@@ -77,7 +78,7 @@ const processMarkdown = async (params) => {
     const { html: rawHtml, hasMermaid } = await generateHtml(params);
     const resolvedImages = resolveImageRefs(rawHtml, params.imageRefs ?? {});
     const html = resolveMovieRefs(resolvedImages, params.movieRefs ?? {});
-    await renderHTMLToImage(html, imagePath, canvasSize.width, canvasSize.height, hasMermaid);
+    await renderHTMLToImage(html, imagePath, canvasSize.width, canvasSize.height, hasMermaid, false, MulmoStudioContextMethods.getRenderNetworkOptions(params.context));
     return imagePath;
 };
 const dumpHtml = async (params) => {

package/lib/utils/image_plugins/mermaid.js

@@ -5,6 +5,7 @@ import { parrotingImagePath, generateUniqueId } from "./utils.js";
 import { escapedMermaidTemplateValues, mermaidHtml } from "./mermaid_html.js";
 import { resolveCombinedStyle } from "./bg_image_util.js";
 import { resolveImageRefs, resolveMovieRefs, resolveRelativeImagePaths } from "./html_tailwind.js";
+import { MulmoStudioContextMethods } from "../../methods/mulmo_studio_context.js";
 export const imageType = "mermaid";
 /** Mermaid markup for this path. The markup itself is shared with the browser path. */
 export const generateMermaidHtml = (code, title) => mermaidHtml(code, generateUniqueId("mermaid"), title);
@@ -23,7 +24,7 @@ const processMermaid = async (params) => {
         const resolvedImageRefs = resolveImageRefs(rawHtml, params.imageRefs ?? {});
         const resolvedAllRefs = resolveMovieRefs(resolvedImageRefs, params.movieRefs ?? {});
         const htmlData = resolveRelativeImagePaths(resolvedAllRefs, context.fileDirs.mulmoFileDirPath);
-        await renderHTMLToImage(htmlData, imagePath, canvasSize.width, canvasSize.height, true);
+        await renderHTMLToImage(htmlData, imagePath, canvasSize.width, canvasSize.height, true, false, MulmoStudioContextMethods.getRenderNetworkOptions(context));
     }
     return imagePath;
 };

package/lib/utils/image_plugins/slide.js

@@ -7,6 +7,7 @@ import { pathToDataUrl } from "../../methods/mulmo_media_source.js";
 import { MulmoMediaSourceMethods } from "../../methods/mulmo_media_source.js";
 import { MulmoPresentationStyleMethods } from "../../methods/mulmo_presentation_style.js";
 import { imageAction, imageFileTarget, unknownMediaType } from "../error_cause.js";
+import { MulmoStudioContextMethods } from "../../methods/mulmo_studio_context.js";
 export const imageType = "slide";
 const slideImageRefError = (refKey) => ({
     type: unknownMediaType,
@@ -167,7 +168,7 @@ const processSlide = async (params) => {
     const reference = beat.image.reference;
     const resolvedBranding = await resolveAndConvertBranding(params);
     const html = generateSlideHTML(theme, slide, reference, resolvedBranding);
-    await renderHTMLToImage(html, imagePath, canvasSize.width, canvasSize.height);
+    await renderHTMLToImage(html, imagePath, canvasSize.width, canvasSize.height, false, false, MulmoStudioContextMethods.getRenderNetworkOptions(params.context));
     return imagePath;
 };
 /**

package/lib/utils/image_plugins/text_slide.js

@@ -2,6 +2,7 @@ import { renderMarkdownToImage } from "../html_render.js";
 import { parrotingImagePath } from "./utils.js";
 import { resolveCombinedStyle } from "./bg_image_util.js";
 import { marked } from "marked";
+import { MulmoStudioContextMethods } from "../../methods/mulmo_studio_context.js";
 export const imageType = "textSlide";
 const processTextSlide = async (params) => {
     const { beat, imagePath, canvasSize } = params;
@@ -17,7 +18,7 @@ const processTextSlide = async (params) => {
         const marginTop = slide.subtitle ? canvasSize.height * 0.4 : canvasSize.height * 0.45;
         return `body {margin-top: ${marginTop}px;}`;
     })();
-    await renderMarkdownToImage(markdown, combinedStyle + topMargin, imagePath, canvasSize.width, canvasSize.height);
+    await renderMarkdownToImage(markdown, combinedStyle + topMargin, imagePath, canvasSize.width, canvasSize.height, MulmoStudioContextMethods.getRenderNetworkOptions(params.context));
     return imagePath;
 };
 const dumpMarkdown = (params) => {

package/lib/utils/image_plugins/vision.js

@@ -1,12 +1,19 @@
 import { parrotingImagePath } from "./utils.js";
 import { htmlPlugin, templateNameTofunctionName } from "mulmocast-vision";
 import { resolve as resolvePath } from "path";
+import { agentGenerationError, imageAction, unsupportedImageTypeTarget } from "../error_cause.js";
 export const imageType = "vision";
 const processVision = async (params) => {
     const { beat, imagePath, context } = params;
     const rootDir = context.fileDirs.nodeModuleRootPath ? resolvePath(context.fileDirs.nodeModuleRootPath, "mulmocast-vision") : undefined;
     if (!beat?.image || beat.image.type !== imageType)
         return;
+    // mulmocast-vision launches its own browser, which the strict network guard cannot reach.
+    if (context.strictNetwork) {
+        throw new Error("vision beats cannot be rendered with --strict-network: mulmocast-vision renders in its own browser, outside the network guard", {
+            cause: agentGenerationError("visionPlugin", imageAction, unsupportedImageTypeTarget),
+        });
+    }
     const handler = new htmlPlugin({ rootDir });
     await handler.callNamedFunction(templateNameTofunctionName(beat.image.style), beat.image.data, {
         functionName: beat.image.style,

package/lib/utils/render_network_guard.d.ts

@@ -0,0 +1,2 @@
+import type { Page } from "puppeteer";
+export declare const guardRenderPage: (page: Page, allowedFileRoots: readonly string[]) => Promise<void>;

package/lib/utils/render_network_guard.js

@@ -0,0 +1,36 @@
+import fs from "node:fs";
+import { GraphAILogger } from "graphai";
+import { WEBRTC_REMOVAL_SCRIPT } from "./remotion/network_policy.js";
+import { POPUP_BLOCK_SCRIPT, isAllowedRenderRequest, realRoot } from "./render_network_policy.js";
+const fileRealPath = (filePath) => {
+    try {
+        return fs.realpathSync.native(filePath);
+    }
+    catch {
+        return undefined;
+    }
+};
+// Must run before the page loads anything. The WebRTC removal only reaches documents created after this call,
+// which is why strict mode always navigates to a file instead of using setContent.
+export const guardRenderPage = async (page, allowedFileRoots) => {
+    const realRoots = allowedFileRoots.map((root) => realRoot(root, fileRealPath));
+    const reported = new Set();
+    await page.setRequestInterception(true);
+    page.on("request", (request) => {
+        if (request.isInterceptResolutionHandled())
+            return;
+        const url = request.url();
+        // The page can close while a request is still pending; that rejection is not a failure of the render.
+        if (isAllowedRenderRequest(url, realRoots, fileRealPath)) {
+            request.continue().catch(() => undefined);
+            return;
+        }
+        if (!reported.has(url)) {
+            reported.add(url);
+            GraphAILogger.info(`strict network: blocked ${url}`);
+        }
+        request.abort("blockedbyclient").catch(() => undefined);
+    });
+    await page.evaluateOnNewDocument(WEBRTC_REMOVAL_SCRIPT);
+    await page.evaluateOnNewDocument(POPUP_BLOCK_SCRIPT);
+};

package/lib/utils/render_network_policy.d.ts

@@ -0,0 +1,15 @@
+export declare const RENDER_CDN_HOSTS: string[];
+export declare const RENDER_JSDELIVR_PATHS: string[];
+export type RenderNetworkOptions = {
+    strictNetwork?: boolean;
+    allowedFileRoots?: readonly string[];
+};
+export declare const STRICT_NETWORK_ENV = "MULMO_STRICT_NETWORK";
+export declare const strictNetworkFromEnv: (env: Record<string, string | undefined>) => boolean;
+export type RealPath = (filePath: string) => string | undefined;
+export declare const isAllowedRenderRequest: (url: string, realRoots?: readonly string[], realPath?: RealPath) => boolean;
+export declare const realRoot: (root: string, realPath: RealPath) => string;
+export declare const strictNetworkLaunchArgs: () => string[];
+export declare const POPUP_BLOCK_SCRIPT = "Object.defineProperty(globalThis, \"open\", { value: () => null, writable: false, configurable: false });";
+export declare const RENDER_CONTENT_SECURITY_POLICY = "connect-src 'self' data: blob:";
+export declare const withRenderContentSecurityPolicy: (html: string) => string;