mulmocast 2.7.0 → 2.7.2

package/lib/actions/bundle.js

@@ -7,8 +7,9 @@ import { ZipBuilder } from "../utils/zip.js";
 import { bundleTargetLang } from "../types/const.js";
 import { createSilentAudio } from "../utils/ffmpeg_utils.js";
 import { silentMp3 } from "../utils/context.js";
+import { safeFetch, FETCH_MEDIA_DOWNLOAD_TIMEOUT_MS } from "../utils/fetch.js";
 const downloadFile = async (url, destPath) => {
-    const response = await fetch(url);
+    const response = await safeFetch(url, {}, FETCH_MEDIA_DOWNLOAD_TIMEOUT_MS);
     if (!response.ok) {
         throw new Error(`Failed to download file from ${url}: ${response.statusText}`);
     }

package/lib/actions/pdf.js

@@ -6,6 +6,7 @@ import { MulmoPresentationStyleMethods } from "../methods/index.js";
 import { localizedText, isHttp } from "../utils/utils.js";
 import { getOutputPdfFilePath, writingMessage, getHTMLFile, mulmoCreditPath } from "../utils/file.js";
 import { interpolate } from "../utils/html_render.js";
+import { safeFetch, FETCH_DOWNLOAD_TIMEOUT_MS } from "../utils/fetch.js";
 import { MulmoStudioContextMethods } from "../methods/mulmo_studio_context.js";
 const isCI = process.env.CI === "true";
 const getPdfSize = (pdfSize) => {
@@ -13,7 +14,9 @@ const getPdfSize = (pdfSize) => {
 };
 const loadImage = async (imagePath, index) => {
     try {
-        const imageData = isHttp(imagePath) ? Buffer.from(await (await fetch(imagePath)).arrayBuffer()) : fs.readFileSync(imagePath);
+        const imageData = isHttp(imagePath)
+            ? Buffer.from(await (await safeFetch(imagePath, {}, FETCH_DOWNLOAD_TIMEOUT_MS)).arrayBuffer())
+            : fs.readFileSync(imagePath);
         const ext = path.extname(imagePath).toLowerCase().replace(".", "");
         const mimeType = ext === "jpg" ? "jpeg" : ext;
         return `data:image/${mimeType};base64,${imageData.toString("base64")}`;

package/lib/agents/image_genai_agent.js

@@ -5,6 +5,9 @@ import { apiKeyMissingError, agentIncorrectAPIKeyError, agentGenerationError, ag
 import { getAspectRatio } from "../utils/utils.js";
 import { ASPECT_RATIOS, PRO_ASPECT_RATIOS } from "../types/const.js";
 import { GoogleGenAI, PersonGeneration } from "@google/genai";
+// Per-request timeout so a stalled GenAI image call rejects (and GraphAI retry
+// can recover) instead of hanging. Generous vs. normal generation time.
+const GENAI_REQUEST_TIMEOUT_MS = 120_000;
 const isDeprecatedGoogleImageModel = (model) => model in deprecatedGoogleImageModelHints;
 export const buildDeprecatedGoogleImageModelMessage = (model) => {
     if (!isDeprecatedGoogleImageModel(model))
@@ -86,7 +89,7 @@ export const imageGenAIAgent = async ({ namedInputs, params, config, }) => {
             if (vertexAIGlobalOnlyImageModels.has(model) && location !== "global") {
                 GraphAILogger.warn(`imageGenAIAgent: model "${model}" on Vertex AI is only available in location "global", but got "${location}". Set imageParams.vertexai_location to "global".`);
             }
-            return new GoogleGenAI({ vertexai: true, project: params.vertexai_project, location });
+            return new GoogleGenAI({ vertexai: true, project: params.vertexai_project, location, httpOptions: { timeout: GENAI_REQUEST_TIMEOUT_MS } });
         })()
         : (() => {
             if (!apiKey) {
@@ -94,7 +97,7 @@ export const imageGenAIAgent = async ({ namedInputs, params, config, }) => {
                     cause: apiKeyMissingError("imageGenAIAgent", imageAction, "GEMINI_API_KEY"),
                 });
             }
-            return new GoogleGenAI({ apiKey });
+            return new GoogleGenAI({ apiKey, httpOptions: { timeout: GENAI_REQUEST_TIMEOUT_MS } });
         })();
     if (model === "gemini-2.5-flash-image" || model === "gemini-3.1-flash-image-preview" || model === "gemini-3-pro-image-preview") {
         const contentParams = (() => {

package/lib/agents/image_openai_agent.js

@@ -3,6 +3,7 @@ import path from "path";
 import { GraphAILogger } from "graphai";
 import { toFile, AuthenticationError, RateLimitError, APIError } from "openai";
 import { createOpenAIClient } from "../utils/openai_client.js";
+import { safeFetch, FETCH_DOWNLOAD_TIMEOUT_MS } from "../utils/fetch.js";
 import { provider2ImageAgent, gptImages, deprecatedOpenAIImageModelHints } from "../types/provider2agent.js";
 import { apiKeyMissingError, agentGenerationError, openAIAgentGenerationError, agentIncorrectAPIKeyError, agentAPIRateLimitError, agentInvalidResponseError, imageAction, imageFileTarget, unsupportedModelTarget, } from "../utils/error_cause.js";
 const isDeprecatedOpenAIImageModel = (model) => model in deprecatedOpenAIImageModelHints;
@@ -142,7 +143,7 @@ export const imageOpenaiAgent = async ({ namedInputs, params, config, }) => {
         return { buffer: Buffer.from(image_base64, "base64"), usage };
     }
     // URL response handling (legacy OpenAI image API response format)
-    const res = await fetch(url);
+    const res = await safeFetch(url, {}, FETCH_DOWNLOAD_TIMEOUT_MS);
     if (!res.ok) {
         throw new Error(`Failed to fetch ${url}: ${res.status} ${res.statusText}`, {
             cause: agentGenerationError("imageOpenaiAgent", imageAction, imageFileTarget),

package/lib/agents/image_replicate_agent.js

@@ -5,6 +5,7 @@ import { getAspectRatio } from "./movie_replicate_agent.js";
 import { apiKeyMissingError, agentIncorrectAPIKeyError, agentGenerationError, agentInvalidResponseError, imageAction, imageFileTarget, hasCause, } from "../utils/error_cause.js";
 import { provider2ImageAgent } from "../types/provider2agent.js";
 import { runReplicateWithMetrics } from "../utils/replicate_usage.js";
+import { safeFetch, FETCH_DOWNLOAD_TIMEOUT_MS } from "../utils/fetch.js";
 // Replicate image models return one of: FileOutput (object with url() method),
 // Array<FileOutput>, string URL, or { url: string }. Normalize to URL string/URL.
 const extractImageUrl = (output) => {
@@ -52,7 +53,7 @@ export const imageReplicateAgent = async ({ namedInputs, params, config, }) => {
                 cause: agentInvalidResponseError("imageReplicateAgent", imageAction, imageFileTarget),
             });
         }
-        const imageResponse = await fetch(imageUrl);
+        const imageResponse = await safeFetch(imageUrl, {}, FETCH_DOWNLOAD_TIMEOUT_MS);
         if (!imageResponse.ok) {
             throw new Error(`Error downloading image: ${imageResponse.status} - ${imageResponse.statusText}`, {
                 cause: agentGenerationError("imageReplicateAgent", imageAction, imageFileTarget),

package/lib/agents/lipsync_replicate_agent.js

@@ -4,6 +4,7 @@ import Replicate from "replicate";
 import { provider2LipSyncAgent } from "../types/provider2agent.js";
 import { apiKeyMissingError, agentGenerationError, agentFileNotExistError, imageAction, movieFileTarget, audioFileTarget, hasCause, } from "../utils/error_cause.js";
 import { runReplicateWithMetrics } from "../utils/replicate_usage.js";
+import { safeFetch, FETCH_MEDIA_DOWNLOAD_TIMEOUT_MS } from "../utils/fetch.js";
 export const lipSyncReplicateAgent = async ({ namedInputs, params, config, }) => {
     const { movieFile, audioFile, imageFile } = namedInputs;
     const apiKey = config?.apiKey;
@@ -64,7 +65,7 @@ export const lipSyncReplicateAgent = async ({ namedInputs, params, config, }) =>
         const { output, predictSec } = await runReplicateWithMetrics(replicate, model_identifier, input);
         if (output && typeof output === "object" && "url" in output) {
             const videoUrl = output.url();
-            const videoResponse = await fetch(videoUrl);
+            const videoResponse = await safeFetch(videoUrl, {}, FETCH_MEDIA_DOWNLOAD_TIMEOUT_MS);
             if (!videoResponse.ok) {
                 throw new Error(`Error downloading video: ${videoResponse.status} - ${videoResponse.statusText}`, {
                     cause: agentGenerationError("lipSyncReplicateAgent", imageAction, movieFileTarget),

package/lib/agents/media_mock_agent.js

@@ -1,6 +1,7 @@
 import { GraphAILogger } from "graphai";
 import fs from "fs";
 import { silent60secPath, mulmoCreditPath } from "../utils/file.js";
+import { safeFetch, FETCH_DOWNLOAD_TIMEOUT_MS } from "../utils/fetch.js";
 export const mediaMockAgent = async ({ namedInputs }) => {
     if (namedInputs.media === "audio") {
         const buffer = fs.readFileSync(silent60secPath());
@@ -12,7 +13,7 @@ export const mediaMockAgent = async ({ namedInputs }) => {
     }
     if (namedInputs.media === "movie") {
         const url = "https://github.com/receptron/mulmocast-media/raw/refs/heads/main/test/pingpong.mov";
-        const res = await fetch(url);
+        const res = await safeFetch(url, {}, FETCH_DOWNLOAD_TIMEOUT_MS);
         if (!res.ok) {
             throw new Error(`Failed to fetch: ${res.status} ${res.statusText}`);
         }

package/lib/agents/movie_genai_agent.js

@@ -6,9 +6,19 @@ import { getAspectRatio } from "../utils/utils.js";
 import { ffmpegGetMediaDuration } from "../utils/ffmpeg_utils.js";
 import { ASPECT_RATIOS } from "../types/const.js";
 import { getModelDuration, provider2MovieAgent, AUDIO_MODE_NEVER, AUDIO_MODE_ALWAYS } from "../types/provider2agent.js";
+// Per-request timeout so a stalled GenAI video API call rejects instead of hanging.
+const GENAI_REQUEST_TIMEOUT_MS = 120_000;
+// Wall-clock cap on the long-running video operation poll loop (Veo runs minutes).
+const VIDEO_POLL_TIMEOUT_MS = 1_200_000;
 const pollUntilDone = async (ai, operation) => {
     const response = { operation };
+    const deadline = Date.now() + VIDEO_POLL_TIMEOUT_MS;
     while (!response.operation.done) {
+        if (Date.now() > deadline) {
+            throw new Error(`Video generation did not complete within ${VIDEO_POLL_TIMEOUT_MS}ms`, {
+                cause: agentGenerationError("movieGenAIAgent", imageAction, movieFileTarget),
+            });
+        }
         await sleep(5000);
         response.operation = await ai.operations.getVideosOperation(response);
     }
@@ -190,6 +200,7 @@ export const movieGenAIAgent = async ({ namedInputs, params, config, }) => {
                 vertexai: true,
                 project: params.vertexai_project,
                 location: params.vertexai_location ?? "us-central1",
+                httpOptions: { timeout: GENAI_REQUEST_TIMEOUT_MS },
             })
             : (() => {
                 if (!apiKey) {
@@ -197,7 +208,7 @@ export const movieGenAIAgent = async ({ namedInputs, params, config, }) => {
                         cause: apiKeyMissingError("movieGenAIAgent", imageAction, "GEMINI_API_KEY"),
                     });
                 }
-                return new GoogleGenAI({ apiKey });
+                return new GoogleGenAI({ apiKey, httpOptions: { timeout: GENAI_REQUEST_TIMEOUT_MS } });
             })();
         // Veo 3.1: Video extension mode for videos longer than 8s
         if (model === "veo-3.1-generate-preview" && requestedDuration > 8 && params.canvasSize) {
@@ -207,11 +218,14 @@ export const movieGenAIAgent = async ({ namedInputs, params, config, }) => {
         return generateStandardVideo(ai, model, prompt, aspectRatio, imagePath, lastFrameImagePath, referenceImages, duration, movieFile, isVertexAI);
     }
     catch (error) {
-        GraphAILogger.info("Failed to generate movie:", error.message);
         if (hasCause(error) && error.cause) {
             throw error;
         }
-        throw new Error("Failed to generate movie with Google GenAI", {
+        GraphAILogger.info("Failed to generate movie:", error.message);
+        // Preserve the underlying message (e.g. a timeout/abort deadline) instead of
+        // collapsing every failure to a static label. (Same template as #1452.)
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to generate movie with Google GenAI: ${detail}`, {
             cause: agentGenerationError("movieGenAIAgent", imageAction, movieFileTarget),
         });
     }

package/lib/agents/movie_replicate_agent.js

@@ -4,6 +4,7 @@ import Replicate from "replicate";
 import { apiKeyMissingError, agentGenerationError, agentInvalidResponseError, hasCause, imageAction, movieFileTarget, videoDurationTarget, unsupportedModelTarget, } from "../utils/error_cause.js";
 import { provider2MovieAgent, getModelDuration, AUDIO_MODE_OPTIONAL, AUDIO_MODE_NEVER, AUDIO_MODE_ALWAYS } from "../types/provider2agent.js";
 import { runReplicateWithMetrics } from "../utils/replicate_usage.js";
+import { safeFetch, FETCH_MEDIA_DOWNLOAD_TIMEOUT_MS } from "../utils/fetch.js";
 function replicate_get_videoUrl(output) {
     if (typeof output === "string")
         return output;
@@ -99,7 +100,7 @@ async function generateMovie(model, apiKey, prompt, imagePath, lastFrameImagePat
         // Some models return a FileOutput object with a url() method; others return a plain string URL.
         const videoUrl = replicate_get_videoUrl(output);
         if (videoUrl) {
-            const videoResponse = await fetch(videoUrl);
+            const videoResponse = await safeFetch(videoUrl, {}, FETCH_MEDIA_DOWNLOAD_TIMEOUT_MS);
             if (!videoResponse.ok) {
                 throw new Error(`Error downloading video: ${videoResponse.status} - ${videoResponse.statusText}`, {
                     cause: agentGenerationError("movieReplicateAgent", imageAction, movieFileTarget),

package/lib/agents/sound_effect_replicate_agent.js

@@ -4,6 +4,7 @@ import Replicate from "replicate";
 import { provider2SoundEffectAgent } from "../types/provider2agent.js";
 import { apiKeyMissingError, agentGenerationError, imageAction, movieFileTarget, hasCause } from "../utils/error_cause.js";
 import { runReplicateWithMetrics } from "../utils/replicate_usage.js";
+import { safeFetch, FETCH_MEDIA_DOWNLOAD_TIMEOUT_MS } from "../utils/fetch.js";
 export const soundEffectReplicateAgent = async ({ namedInputs, params, config }) => {
     const { prompt, movieFile } = namedInputs;
     const apiKey = config?.apiKey;
@@ -32,7 +33,7 @@ export const soundEffectReplicateAgent = async ({ namedInputs, params, config })
         const { output, predictSec } = await runReplicateWithMetrics(replicate, model_identifier, input);
         if (output && typeof output === "object" && "url" in output) {
             const videoUrl = output.url();
-            const videoResponse = await fetch(videoUrl);
+            const videoResponse = await safeFetch(videoUrl, {}, FETCH_MEDIA_DOWNLOAD_TIMEOUT_MS);
             if (!videoResponse.ok) {
                 throw new Error(`Error downloading video: ${videoResponse.status} - ${videoResponse.statusText}`, {
                     cause: agentGenerationError("soundEffectReplicateAgent", imageAction, movieFileTarget),
@@ -49,7 +50,10 @@ export const soundEffectReplicateAgent = async ({ namedInputs, params, config })
         if (hasCause(error) && error.cause) {
             throw error;
         }
-        throw new Error("Failed to generate sound effect with Replicate", {
+        // Preserve the underlying message (e.g. a safeFetch timeout) rather than
+        // collapsing every failure to a static label. (Same template as #1452.)
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to generate sound effect with Replicate: ${detail}`, {
             cause: agentGenerationError("soundEffectReplicateAgent", imageAction, movieFileTarget),
         });
     }

package/lib/agents/tts_elevenlabs_agent.js

@@ -1,6 +1,7 @@
 import { GraphAILogger } from "graphai";
 import { provider2TTSAgent } from "../types/provider2agent.js";
 import { apiKeyMissingError, agentVoiceLimitReachedError, agentIncorrectAPIKeyError, agentGenerationError, audioAction, audioFileTarget, } from "../utils/error_cause.js";
+import { safeFetch, FETCH_API_TIMEOUT_MS } from "../utils/fetch.js";
 export const ttsElevenlabsAgent = async ({ namedInputs, params, config, }) => {
     const { text } = namedInputs;
     const { voice, model, stability, similarityBoost, speed, suppressError } = params;
@@ -27,7 +28,7 @@ export const ttsElevenlabsAgent = async ({ namedInputs, params, config, }) => {
     GraphAILogger.log("ElevenLabs TTS options", requestBody);
     const response = await (async () => {
         try {
-            return await fetch(`https://api.elevenlabs.io/v1/text-to-speech/${voice}`, {
+            return await safeFetch(`https://api.elevenlabs.io/v1/text-to-speech/${voice}`, {
                 method: "POST",
                 headers: {
                     Accept: "audio/mpeg",
@@ -35,7 +36,7 @@ export const ttsElevenlabsAgent = async ({ namedInputs, params, config, }) => {
                     "xi-api-key": apiKey,
                 },
                 body: JSON.stringify(requestBody),
-            });
+            }, FETCH_API_TIMEOUT_MS);
         }
         catch (e) {
             if (suppressError) {
@@ -64,7 +65,7 @@ export const ttsElevenlabsAgent = async ({ namedInputs, params, config, }) => {
             });
         }
         const errorDetail = await response.json();
-        if (errorDetail.detail.status === "voice_limit_reached") {
+        if (errorDetail.detail?.status === "voice_limit_reached") {
             throw new Error("Failed to generate audio: 400 You have reached your maximum amount of custom voices with ElevenLabs", {
                 cause: agentVoiceLimitReachedError("ttsElevenlabsAgent", audioAction, audioFileTarget),
             });

package/lib/agents/tts_gemini_agent.js

@@ -3,6 +3,9 @@ import { GoogleGenAI } from "@google/genai";
 import { provider2TTSAgent } from "../types/provider2agent.js";
 import { agentIncorrectAPIKeyError, apiKeyMissingError, agentGenerationError, audioAction, audioFileTarget, getGenAIErrorReason, } from "../utils/error_cause.js";
 import { pcmToMp3 } from "../utils/ffmpeg_utils.js";
+// Per-request timeout so a stalled GenAI TTS call rejects (and GraphAI retry can
+// recover) instead of hanging. Generous vs. normal generation time.
+const GENAI_REQUEST_TIMEOUT_MS = 120_000;
 const getPrompt = (text, instructions) => {
     // https://ai.google.dev/gemini-api/docs/speech-generation?hl=ja#controllable
     if (instructions) {
@@ -21,7 +24,7 @@ export const ttsGeminiAgent = async ({ namedInputs, params, config, }) => {
     }
     const geminiResult = await (async () => {
         try {
-            const ai = new GoogleGenAI({ apiKey });
+            const ai = new GoogleGenAI({ apiKey, httpOptions: { timeout: GENAI_REQUEST_TIMEOUT_MS } });
             const response = await ai.models.generateContent({
                 model: model ?? provider2TTSAgent.gemini.defaultModel,
                 contents: [{ parts: [{ text: getPrompt(text, instructions) }] }],

package/lib/agents/tts_kotodama_agent.js

@@ -1,6 +1,7 @@
 import { GraphAILogger } from "graphai";
 import { provider2TTSAgent } from "../types/provider2agent.js";
 import { apiKeyMissingError, agentIncorrectAPIKeyError, agentGenerationError, audioAction, audioFileTarget } from "../utils/error_cause.js";
+import { safeFetch, FETCH_API_TIMEOUT_MS } from "../utils/fetch.js";
 export const ttsKotodamaAgent = async ({ namedInputs, params, config, }) => {
     const { text } = namedInputs;
     const { voice, decoration, suppressError } = params;
@@ -18,14 +19,14 @@ export const ttsKotodamaAgent = async ({ namedInputs, params, config, }) => {
         audio_format: "mp3",
     };
     try {
-        const response = await fetch(url, {
+        const response = await safeFetch(url, {
             method: "POST",
             headers: {
                 "Content-Type": "application/json",
                 "X-API-Key": apiKey,
             },
             body: JSON.stringify(body),
-        });
+        }, FETCH_API_TIMEOUT_MS);
         if (!response.ok) {
             if (response.status === 401) {
                 throw new Error("Failed to generate audio: 401 Incorrect API key provided with Kotodama", {
@@ -64,7 +65,10 @@ export const ttsKotodamaAgent = async ({ namedInputs, params, config, }) => {
         if (error && typeof error === "object" && "cause" in error) {
             throw error;
         }
-        throw new Error("TTS Kotodama Error", {
+        // Preserve the underlying message (e.g. a safeFetch timeout) rather than
+        // collapsing every failure to a static label. (Same template as #1452.)
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`TTS Kotodama Error: ${detail}`, {
             cause: agentGenerationError("ttsKotodamaAgent", audioAction, audioFileTarget),
         });
     }

package/lib/methods/index.d.ts

@@ -1,5 +1,5 @@
 export * from "./mulmo_presentation_style.js";
 export * from "./mulmo_studio_context.js";
 export * from "./mulmo_media_source.js";
-export * from "./mulmo_beat.js";
+export * from "./mulmo_beat_node.js";
 export * from "./mulmo_script.js";

package/lib/methods/index.js

@@ -1,5 +1,7 @@
 export * from "./mulmo_presentation_style.js";
 export * from "./mulmo_studio_context.js";
 export * from "./mulmo_media_source.js";
-export * from "./mulmo_beat.js";
+// Node-only MulmoBeatMethods (includes getPlugin). The browser-safe subset lives in
+// ./mulmo_beat.js and is re-exported by ../index.common.js for mulmocast/browser.
+export * from "./mulmo_beat_node.js";
 export * from "./mulmo_script.js";

package/lib/methods/mulmo_beat.d.ts

@@ -9,13 +9,6 @@ export declare const MulmoBeatMethods: {
     isAnimatedHtmlTailwind: (beat: MulmoBeat) => boolean;
     isMovieMode: (animation: unknown) => boolean;
     getHtmlPrompt(beat: MulmoBeat): string | undefined;
-    getPlugin(beat: MulmoBeat): {
-        imageType: string;
-        process: (params: import("../types/type.js").ImageProcessorParams) => Promise<string | undefined> | void;
-        path: (params: import("../types/type.js").ImageProcessorParams) => string | undefined;
-        markdown?: (params: import("../types/type.js").ImageProcessorParams) => string | undefined;
-        html?: (params: import("../types/type.js").ImageProcessorParams) => Promise<string | undefined>;
-    };
     getImageReferenceForImageGenerator(beat: MulmoBeat, imageRefs: Record<string, string>): string[];
 };
 export {};

package/lib/methods/mulmo_beat.js

@@ -1,4 +1,3 @@
-import { findImagePlugin } from "../utils/image_plugins/index.js";
 /** Type guard: checks if animation value is an object config like { fps: 30 } */
 const isAnimationObject = (animation) => {
     return typeof animation === "object" && animation !== null && !Array.isArray(animation);
@@ -29,13 +28,6 @@ export const MulmoBeatMethods = {
         }
         return beat?.htmlPrompt?.prompt;
     },
-    getPlugin(beat) {
-        const plugin = findImagePlugin(beat?.image?.type);
-        if (!plugin) {
-            throw new Error(`invalid beat image type: ${beat.image}`); // TODO: cause
-        }
-        return plugin;
-    },
     getImageReferenceForImageGenerator(beat, imageRefs) {
         const imageNames = beat.imageNames ?? Object.keys(imageRefs); // use all images if imageNames is not specified
         const sources = imageNames.map((name) => imageRefs[name]);

package/lib/methods/mulmo_beat_node.d.ts

@@ -0,0 +1,22 @@
+import { MulmoBeat } from "../types/index.js";
+export declare const MulmoBeatMethods: {
+    getPlugin(beat: MulmoBeat): {
+        imageType: string;
+        process: (params: import("../types/type.js").ImageProcessorParams) => Promise<string | undefined> | void;
+        path: (params: import("../types/type.js").ImageProcessorParams) => string | undefined;
+        markdown?: (params: import("../types/type.js").ImageProcessorParams) => string | undefined;
+        html?: (params: import("../types/type.js").ImageProcessorParams) => Promise<string | undefined>;
+    };
+    isAnimationEnabled: (animation: unknown) => animation is true | {
+        fps?: number;
+        movie?: boolean;
+    };
+    isAnimationObject: (animation: unknown) => animation is {
+        fps?: number;
+        movie?: boolean;
+    };
+    isAnimatedHtmlTailwind: (beat: MulmoBeat) => boolean;
+    isMovieMode: (animation: unknown) => boolean;
+    getHtmlPrompt(beat: MulmoBeat): string | undefined;
+    getImageReferenceForImageGenerator(beat: MulmoBeat, imageRefs: Record<string, string>): string[];
+};

package/lib/methods/mulmo_beat_node.js

@@ -0,0 +1,10 @@
+import { MulmoBeatMethods as MulmoBeatMethodsBrowser } from "./mulmo_beat.js";
+import { getBeatPlugin } from "../utils/image_plugins/index.js";
+// Node-only extension of MulmoBeatMethods. Kept out of methods/mulmo_beat.ts so
+// browser bundles (mulmocast/browser) do not pull in image_plugins → mulmocast-vision → puppeteer.
+export const MulmoBeatMethods = {
+    ...MulmoBeatMethodsBrowser,
+    getPlugin(beat) {
+        return getBeatPlugin(beat);
+    },
+};

package/lib/methods/mulmo_media_source.js

@@ -1,6 +1,7 @@
 import fs from "fs";
 import { GraphAILogger, assert } from "graphai";
 import { getFullPath, getReferenceImagePath, resolveAssetPath } from "../utils/file.js";
+import { safeFetch, DEFAULT_FETCH_TIMEOUT_MS } from "../utils/fetch.js";
 import { downLoadReferenceImageError, getTextError, imageReferenceUnknownMediaError, downloadImagePluginError, imagePluginUnknownMediaError, mediaSourceToDataUrlError, mediaSourceFileNotFoundError, mediaSourceUnknownKindError, } from "../utils/error_cause.js";
 // for image reference
 export const getExtention = (contentType, url) => {
@@ -18,7 +19,7 @@ export const getExtention = (contentType, url) => {
     return "png"; // default
 };
 const downLoadReferenceImage = async (context, key, url) => {
-    const response = await fetch(url);
+    const response = await safeFetch(url);
     assert(response.ok, `Failed to download reference image: ${url}`, false, downLoadReferenceImageError(key, url));
     const buffer = Buffer.from(await response.arrayBuffer());
     // Detect file extension from Content-Type header or URL
@@ -38,26 +39,21 @@ function pluginSourceFixExtention(path, imageType) {
     return path;
 }
 // end of util
-const DEFAULT_FETCH_TIMEOUT_MS = 30000;
 // Convert URL to data URL (base64 encoded)
 const urlToDataUrl = async (url, timeoutMs = DEFAULT_FETCH_TIMEOUT_MS) => {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
     try {
-        const response = await fetch(url, { signal: controller.signal });
+        const response = await safeFetch(url, {}, timeoutMs);
         assert(response.ok, `Failed to fetch: ${url}`, false, mediaSourceToDataUrlError(url));
         const buffer = Buffer.from(await response.arrayBuffer());
         const contentType = response.headers.get("content-type") || "image/png";
         return `data:${contentType};base64,${buffer.toString("base64")}`;
     }
     catch (error) {
-        if (error instanceof Error && error.name === "AbortError") {
-            throw new Error(`Fetch timeout: ${url}`, { cause: mediaSourceToDataUrlError(url) });
+        // assert() failures already carry the structured cause — keep it as-is.
+        if (error instanceof Error && error.cause) {
+            throw error;
         }
-        throw new Error(`Fetch failed: ${url}`, { cause: mediaSourceToDataUrlError(url) });
-    }
-    finally {
-        clearTimeout(timeoutId);
+        throw new Error(`Fetch failed: ${url}: ${error instanceof Error ? error.message : String(error)}`, { cause: mediaSourceToDataUrlError(url) });
     }
 };
 /** Map file extension to MIME type for data URLs */
@@ -92,7 +88,7 @@ export const MulmoMediaSourceMethods = {
             return mediaSource.text;
         }
         if (mediaSource.kind === "url") {
-            const response = await fetch(mediaSource.url);
+            const response = await safeFetch(mediaSource.url);
             assert(response.ok, `Failed to download mermaid code text: ${mediaSource.url}`, false, getTextError(mediaSource.url)); // TODO: index
             return await response.text();
         }
@@ -126,7 +122,7 @@ export const MulmoMediaSourceMethods = {
     },
     async imagePluginSource(mediaSource, context, expectImagePath, imageType) {
         if (mediaSource.kind === "url") {
-            const response = await fetch(mediaSource.url);
+            const response = await safeFetch(mediaSource.url);
             assert(response.ok, `Failed to download image plugin: ${imageType} ${mediaSource.url}`, false, downloadImagePluginError(mediaSource.url, imageType)); // TODO: key, id, index
             const buffer = Buffer.from(await response.arrayBuffer());
             // Detect file extension from Content-Type header or URL

package/lib/types/schema.js

@@ -423,8 +423,16 @@ export const audioParamsSchema = z
     .object({
     padding: z.number().optional().default(0.3).describe("Padding between beats"), // seconds
     introPadding: z.number().optional().default(1.0).describe("Padding at the beginning of the audio"), // seconds
-    closingPadding: z.number().optional().default(0.8).describe("Padding before the last beat"), // seconds
-    outroPadding: z.number().optional().default(1.0).describe("Padding at the end of the audio"), // seconds
+    closingPadding: z
+        .number()
+        .optional()
+        .default(0.8)
+        .describe("Padding before the last beat (typically the closing credit). For padding after the last beat, use outroPadding"), // seconds
+    outroPadding: z
+        .number()
+        .optional()
+        .default(1.0)
+        .describe("Padding after the last beat, at the very end of the audio where the BGM fades out (distinct from closingPadding, which comes before the last beat)"), // seconds
     bgm: mediaSourceSchema.optional(),
     bgmVolume: z.number().optional().default(0.2).describe("Volume of the background music"),
     audioVolume: z.number().optional().default(1.0).describe("Volume of the audio"),

package/lib/utils/fetch.d.ts

@@ -0,0 +1,28 @@
+export declare const DEFAULT_FETCH_TIMEOUT_MS = 30000;
+export declare const FETCH_DOWNLOAD_TIMEOUT_MS = 60000;
+export declare const FETCH_MEDIA_DOWNLOAD_TIMEOUT_MS = 180000;
+export declare const FETCH_API_TIMEOUT_MS = 120000;
+export type SafeFetchResponse = {
+    ok: boolean;
+    status: number;
+    statusText: string;
+    headers: {
+        get(name: string): string | null;
+    };
+    arrayBuffer(): Promise<ArrayBuffer>;
+    text(): Promise<string>;
+    json<T = unknown>(): Promise<T>;
+};
+/**
+ * fetch() with an AbortController timeout that covers the whole exchange —
+ * headers AND body.
+ *
+ * A stalled connection otherwise yields a promise that never resolves or
+ * rejects; callers relying on GraphAI `retry` never recover because retry only
+ * fires on rejection. The body is read once under the same deadline (a server
+ * that sends headers and then stalls mid-body would otherwise hang the caller's
+ * body read), and the bytes are handed back through a lightweight result so the
+ * caller does not buffer them a second time. An optional caller `signal` is
+ * composed with the timeout so upstream cancellation still works.
+ */
+export declare const safeFetch: (url: string | URL, init?: Parameters<typeof fetch>[1], timeoutMs?: number) => Promise<SafeFetchResponse>;

package/lib/utils/fetch.js

@@ -0,0 +1,52 @@
+// Timeout budgets for the different kinds of network waits. Generous safety
+// nets against a stalled socket — NOT tight deadlines — so legitimate slow
+// responses still succeed while a genuine hang becomes a rejection.
+export const DEFAULT_FETCH_TIMEOUT_MS = 30_000; // small assets (reference/background images, JSON)
+export const FETCH_DOWNLOAD_TIMEOUT_MS = 60_000; // generated image download
+export const FETCH_MEDIA_DOWNLOAD_TIMEOUT_MS = 180_000; // large video/audio download
+export const FETCH_API_TIMEOUT_MS = 120_000; // generation API POST (e.g. TTS text -> audio)
+/**
+ * fetch() with an AbortController timeout that covers the whole exchange —
+ * headers AND body.
+ *
+ * A stalled connection otherwise yields a promise that never resolves or
+ * rejects; callers relying on GraphAI `retry` never recover because retry only
+ * fires on rejection. The body is read once under the same deadline (a server
+ * that sends headers and then stalls mid-body would otherwise hang the caller's
+ * body read), and the bytes are handed back through a lightweight result so the
+ * caller does not buffer them a second time. An optional caller `signal` is
+ * composed with the timeout so upstream cancellation still works.
+ */
+export const safeFetch = async (url, init = {}, timeoutMs = DEFAULT_FETCH_TIMEOUT_MS) => {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    const externalSignal = init?.signal ?? undefined;
+    const forwardAbort = () => controller.abort();
+    externalSignal?.addEventListener("abort", forwardAbort, { once: true });
+    if (externalSignal?.aborted)
+        controller.abort();
+    try {
+        const response = await fetch(url, { ...init, signal: controller.signal });
+        const body = await response.arrayBuffer();
+        const decode = () => new TextDecoder().decode(body);
+        return {
+            ok: response.ok,
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+            arrayBuffer: async () => body,
+            text: async () => decode(),
+            json: async () => JSON.parse(decode()),
+        };
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+            throw new Error(`Fetch timeout after ${timeoutMs}ms: ${url}`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeoutId);
+        externalSignal?.removeEventListener("abort", forwardAbort);
+    }
+};

package/lib/utils/file.js

@@ -8,6 +8,7 @@ import { MulmoStudioContextMethods } from "../methods/index.js";
 import { mulmoPromptTemplateSchema } from "../types/schema.js";
 import { getMulmoScriptTemplateSystemPrompt } from "./prompt.js";
 import { resolveAssetFile } from "./asset_import.js";
+import { safeFetch } from "./fetch.js";
 const promptTemplateDirName = "./assets/templates";
 const scriptTemplateDirName = "./scripts/templates";
 const __filename = fileURLToPath(import.meta.url);
@@ -43,7 +44,7 @@ export function readMulmoScriptFile(arg2, errorMessage) {
 }
 export const fetchMulmoScriptFile = async (url) => {
     try {
-        const res = await fetch(url);
+        const res = await safeFetch(url);
         if (!res.ok) {
             return { result: false, status: res.status };
         }

package/lib/utils/image_plugins/bg_image_util.js

@@ -1,6 +1,6 @@
 import { MulmoMediaSourceMethods } from "../../methods/mulmo_media_source.js";
 import { resolveStyle } from "./utils.js";
-const DEFAULT_FETCH_TIMEOUT_MS = 30000;
+import { safeFetch, DEFAULT_FETCH_TIMEOUT_MS } from "../fetch.js";
 /**
  * Resolve background image from beat level and global level settings.
  * Beat level takes precedence over global level.
@@ -25,26 +25,13 @@ export const resolveBackgroundImage = (beatBackgroundImage, globalBackgroundImag
  * Fetch URL and convert to data URL with timeout
  */
 const fetchUrlAsDataUrl = async (url, timeoutMs = DEFAULT_FETCH_TIMEOUT_MS) => {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-        const response = await fetch(url, { signal: controller.signal });
-        if (!response.ok) {
-            throw new Error(`Failed to fetch background image: ${url} (${response.status})`);
-        }
-        const buffer = Buffer.from(await response.arrayBuffer());
-        const contentType = response.headers.get("content-type") || "image/png";
-        return `data:${contentType};base64,${buffer.toString("base64")}`;
-    }
-    catch (error) {
-        if (error instanceof Error && error.name === "AbortError") {
-            throw new Error(`Fetch timeout for background image: ${url}`);
-        }
-        throw error;
-    }
-    finally {
-        clearTimeout(timeoutId);
+    const response = await safeFetch(url, {}, timeoutMs);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch background image: ${url} (${response.status})`);
     }
+    const buffer = Buffer.from(await response.arrayBuffer());
+    const contentType = response.headers.get("content-type") || "image/png";
+    return `data:${contentType};base64,${buffer.toString("base64")}`;
 };
 /**
  * Convert BackgroundImage to CSS string

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

@@ -1,4 +1,4 @@
-import { ImageProcessorParams } from "../../types/index.js";
+import { ImageProcessorParams, MulmoBeat } from "../../types/index.js";
 export declare const findImagePlugin: (imageType?: string) => {
     imageType: string;
     process: (params: ImageProcessorParams) => Promise<string | undefined> | void;
@@ -6,3 +6,10 @@ export declare const findImagePlugin: (imageType?: string) => {
     markdown?: (params: ImageProcessorParams) => string | undefined;
     html?: (params: ImageProcessorParams) => Promise<string | undefined>;
 } | undefined;
+export declare const getBeatPlugin: (beat: MulmoBeat) => {
+    imageType: string;
+    process: (params: ImageProcessorParams) => Promise<string | undefined> | void;
+    path: (params: ImageProcessorParams) => string | undefined;
+    markdown?: (params: ImageProcessorParams) => string | undefined;
+    html?: (params: ImageProcessorParams) => Promise<string | undefined>;
+};

package/lib/utils/image_plugins/index.js

@@ -25,3 +25,10 @@ const imagePlugins = [
 export const findImagePlugin = (imageType) => {
     return imagePlugins.find((plugin) => plugin.imageType === imageType);
 };
+export const getBeatPlugin = (beat) => {
+    const plugin = findImagePlugin(beat?.image?.type);
+    if (!plugin) {
+        throw new Error(`invalid beat image type: ${beat.image}`);
+    }
+    return plugin;
+};

package/lib/utils/openai_client.js

@@ -1,4 +1,8 @@
 import OpenAI, { AzureOpenAI } from "openai";
+// Explicit per-request timeout so a stalled connection rejects (and the SDK's
+// default maxRetries=2 re-issues it) instead of hanging on the SDK's 10-minute
+// default. gpt-image-1 generation is typically well under this.
+const OPENAI_REQUEST_TIMEOUT_MS = 120_000;
 /**
  * Detects if the given URL is an Azure OpenAI endpoint
  * Safely parses the URL and checks if the hostname ends with ".openai.azure.com"
@@ -26,10 +30,12 @@ export const createOpenAIClient = (options) => {
             apiKey,
             endpoint: baseURL,
             apiVersion: apiVersion ?? "2025-04-01-preview",
+            timeout: OPENAI_REQUEST_TIMEOUT_MS,
         });
     }
     return new OpenAI({
         apiKey,
         baseURL,
+        timeout: OPENAI_REQUEST_TIMEOUT_MS,
     });
 };

package/lib/utils/replicate_usage.d.ts

@@ -1,5 +1,8 @@
 import type Replicate from "replicate";
-export declare const runReplicateWithMetrics: (replicate: Replicate, identifier: `${string}/${string}` | `${string}/${string}:${string}`, input: object, signal?: AbortSignal) => Promise<{
+export declare const runReplicateWithMetrics: (replicate: Replicate, identifier: `${string}/${string}` | `${string}/${string}:${string}`, input: object, options?: {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}) => Promise<{
     output: unknown;
     predictSec?: number;
 }>;

package/lib/utils/replicate_usage.js

@@ -1,11 +1,31 @@
+// Generous safety net against a stalled run — video models (seedance/kling)
+// legitimately run for minutes — not a tight deadline.
+const REPLICATE_RUN_TIMEOUT_MS = 600_000;
 // Capture Replicate's exact billed seconds (`metrics.predict_time`) via the
 // progress callback on `replicate.run()`. Avoids switching the four
 // replicate agents from `.run()` to `predictions.create()` + poll, which
 // would be a much bigger blast radius.
-export const runReplicateWithMetrics = async (replicate, identifier, input, signal) => {
+//
+// A timeout aborts the run so a stalled job rejects (and the caller's GraphAI
+// `retry` can recover) instead of hanging forever. An optional caller `signal`
+// is composed with the timeout so upstream cancellation still works.
+export const runReplicateWithMetrics = async (replicate, identifier, input, options = {}) => {
+    const { timeoutMs = REPLICATE_RUN_TIMEOUT_MS, signal: externalSignal } = options;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    const forwardAbort = () => controller.abort();
+    externalSignal?.addEventListener("abort", forwardAbort, { once: true });
+    if (externalSignal?.aborted)
+        controller.abort();
     let lastPrediction;
-    const output = await replicate.run(identifier, { input, signal }, (prediction) => {
-        lastPrediction = prediction;
-    });
-    return { output, predictSec: lastPrediction?.metrics?.predict_time };
+    try {
+        const output = await replicate.run(identifier, { input, signal: controller.signal }, (prediction) => {
+            lastPrediction = prediction;
+        });
+        return { output, predictSec: lastPrediction?.metrics?.predict_time };
+    }
+    finally {
+        clearTimeout(timeoutId);
+        externalSignal?.removeEventListener("abort", forwardAbort);
+    }
 };

package/lib/utils/sdk_timeout.d.ts

@@ -0,0 +1,3 @@
+export declare const GENAI_REQUEST_TIMEOUT_MS = 120000;
+export declare const REPLICATE_RUN_TIMEOUT_MS = 600000;
+export declare const VIDEO_POLL_TIMEOUT_MS = 1200000;

package/lib/utils/sdk_timeout.js

@@ -0,0 +1,7 @@
+// Timeout budgets for provider SDK calls (OpenAI has its own in openai_client.ts).
+// Generous safety nets against a stalled connection or a never-completing
+// operation — NOT tight deadlines. A stall becomes a rejection so the caller's
+// GraphAI `retry` can recover instead of hanging forever.
+export const GENAI_REQUEST_TIMEOUT_MS = 120_000; // per @google/genai API call (kick-off / each poll)
+export const REPLICATE_RUN_TIMEOUT_MS = 600_000; // whole replicate.run() job (video models run minutes)
+export const VIDEO_POLL_TIMEOUT_MS = 1_200_000; // wall-clock cap for a long-running Veo video operation

package/lib/utils/zip.js

@@ -1,5 +1,5 @@
 import fs from "fs";
-import archiver from "archiver";
+import { ZipArchive } from "archiver";
 import path from "path";
 /**
  * Promise-based ZIP archive builder
@@ -18,7 +18,7 @@ export class ZipBuilder {
     constructor(outputPath) {
         this.outputPath = outputPath;
         this.output = fs.createWriteStream(outputPath);
-        this.archive = archiver("zip", {
+        this.archive = new ZipArchive({
             zlib: { level: 9 }, // Maximum compression level
         });
         // Pipe archive data to the file

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mulmocast",
-  "version": "2.7.0",
+  "version": "2.7.2",
   "description": "",
   "type": "module",
   "main": "lib/index.node.js",
@@ -106,7 +106,7 @@
     "@mozilla/readability": "^0.6.0",
     "@mulmocast/deck": "^1.1.0",
     "@tavily/core": "^0.7.6",
-    "archiver": "^7.0.1",
+    "archiver": "^8.0.0",
     "clipboardy": "^5.3.1",
     "dotenv": "^17.4.2",
     "graphai": "^2.0.18",
@@ -124,20 +124,20 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@receptron/test_utils": "^2.0.3",
-    "@types/archiver": "^7.0.0",
+    "@types/archiver": "^8.0.0",
     "@types/jsdom": "^28.0.3",
     "@types/yargs": "^17.0.35",
     "cross-env": "^10.1.0",
-    "eslint": "^10.6.0",
+    "eslint": "^10.7.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-prettier": "^5.5.6",
     "eslint-plugin-sonarjs": "^4.1.0",
     "globals": "^17.7.0",
-    "prettier": "^3.9.4",
-    "tsx": "^4.22.4",
+    "prettier": "^3.9.5",
+    "tsx": "^4.23.0",
     "typescript": "6.0.3",
-    "typescript-eslint": "^8.62.1"
+    "typescript-eslint": "^8.63.0"
   },
   "engines": {
     "node": ">=22.0.0"