@mulmoclaude/mulmoscript-plugin 0.1.0 → 0.2.0

package/dist/server.js

@@ -0,0 +1,955 @@
+import { i as executeUpdateScript, n as executeMulmoScriptSave, r as executeUpdateBeat } from "./plugin-W1ppnyhR.js";
+import { t as GENERATION_EVENT } from "./contract-vY0niHkh.js";
+import { existsSync, mkdirSync, realpathSync, statSync, unlinkSync } from "fs";
+import path from "path";
+import { addSessionProgressCallback, audio, generateBeatAudio, generateBeatImage, generateReferenceImage, getBeatAnimatedVideoPath, getBeatAudioPathOrUrl, getBeatMoviePaths, getBeatPngImagePath, getFileObject, getReferenceImagePath, images, initializeContextFromFiles, movie, movieFilePath, pdf, pdfFilePath, removeSessionProgressCallback, setGraphAILogger } from "mulmocast";
+import { readFile } from "node:fs/promises";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { GraphAILogger } from "graphai";
+//#region src/server/support.ts
+function errorText(err) {
+	if (err instanceof Error) return err.message;
+	if (err !== null && typeof err === "object") {
+		const obj = err;
+		if (typeof obj.details === "string" && obj.details) return obj.details;
+		if (typeof obj.message === "string" && obj.message) return obj.message;
+	}
+	return String(err);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stripDataUri(dataUri) {
+	return dataUri.replace(/^data:image\/[^;]+;base64,/, "");
+}
+/** Realpath-based containment: resolve `relPath` against the ROOT's
+*  realpath and require the target's realpath to stay inside it. Returns
+*  null on ENOENT or traversal (symlink escapes included). */
+function resolveWithinRoot(rootReal, relPath) {
+	const normalized = path.normalize(relPath || "");
+	const resolved = path.resolve(rootReal, normalized);
+	let resolvedReal;
+	try {
+		resolvedReal = realpathSync(resolved);
+	} catch {
+		return null;
+	}
+	if (resolvedReal !== rootReal && !resolvedReal.startsWith(rootReal + path.sep)) return null;
+	return resolvedReal;
+}
+async function fileToDataUri(filePath, mimeType) {
+	return `data:${mimeType};base64,${(await readFile(filePath)).toString("base64")}`;
+}
+//#endregion
+//#region src/server/mulmoErrorCapture.ts
+var capturedErrors = new AsyncLocalStorage();
+var loggerInstalled = false;
+var captureLog = null;
+/** Route captured GraphAI errors into the host logger. Set once by
+*  `createMulmoScriptServerOps`; the GraphAILogger sink is global, so the
+*  last-configured host logger wins (one ops instance per process). */
+function setMulmoErrorCaptureLogger(log) {
+	captureLog = log;
+}
+function formatLogArg(arg) {
+	if (typeof arg === "string") return arg;
+	if (arg instanceof Error) return arg.message;
+	try {
+		return JSON.stringify(arg);
+	} catch {
+		return String(arg);
+	}
+}
+/**
+* Re-enable GraphAI's error level (everything else stays silenced) and
+* route it into the host logger + the per-operation capture store.
+* Call after every `setGraphAILogger(false)` — that helper disables all
+* levels including error. Idempotent.
+*/
+function enableGraphAIErrorCapture() {
+	GraphAILogger.setLevelEnabled("error", true);
+	if (loggerInstalled) return;
+	loggerInstalled = true;
+	GraphAILogger.setLogger((level, ...args) => {
+		if (level !== "error") return;
+		const message = args.map(formatLogArg).join(" ");
+		captureLog?.warn("mulmocast generation error", { message });
+		capturedErrors.getStore()?.push(message);
+	});
+}
+var CAUSE_FIELDS = [
+	"type",
+	"agentName",
+	"envVarName",
+	"errorCode",
+	"errorType"
+];
+/** Render mulmocast's structured error `cause` as "field=value" pairs. */
+function describeMulmoCause(err) {
+	if (!(err instanceof Error) || !isRecord(err.cause)) return null;
+	const { cause } = err;
+	const parts = CAUSE_FIELDS.flatMap((field) => {
+		const value = cause[field];
+		return typeof value === "string" && value !== "" ? [`${field}=${value}`] : [];
+	});
+	return parts.length > 0 ? parts.join(" ") : null;
+}
+/**
+* Compose the enriched message for a failed mulmocast operation:
+* mulmocast's own message, then its structured cause, then the
+* captured underlying provider error(s). Deduped — GraphAI retries
+* log the same error more than once.
+*/
+function composeMulmoErrorMessage(err, captured) {
+	const base = errorText(err);
+	const details = [...new Set(captured)].filter((message) => message !== "" && message !== base);
+	return [
+		base,
+		describeMulmoCause(err),
+		...details
+	].filter(Boolean).join(" — ");
+}
+/**
+* Run a mulmocast operation, capturing GraphAI error logs emitted while
+* it executes. On failure, rethrows with the captured provider error(s)
+* appended to the message (original error kept as `cause`). Uses
+* AsyncLocalStorage so concurrent operations don't cross-attribute.
+*/
+async function withMulmoErrorCapture(operation) {
+	return capturedErrors.run([], async () => {
+		try {
+			return await operation();
+		} catch (err) {
+			throw new Error(composeMulmoErrorMessage(err, capturedErrors.getStore() ?? []), { cause: err });
+		}
+	});
+}
+//#endregion
+//#region src/server/ops.ts
+var PDF_MODE = "slide";
+var PDF_SIZE = "a4";
+function opBadRequest(error) {
+	return {
+		ok: false,
+		code: "bad_request",
+		error
+	};
+}
+function opNotFound(error) {
+	return {
+		ok: false,
+		code: "not_found",
+		error
+	};
+}
+function opServerError(error) {
+	return {
+		ok: false,
+		code: "server_error",
+		error
+	};
+}
+var NOOP_LOG = {
+	info: () => {},
+	warn: () => {},
+	error: () => {}
+};
+async function buildContext(absoluteFilePath, force = false) {
+	setGraphAILogger(false);
+	enableGraphAIErrorCapture();
+	return initializeContextFromFiles(getFileObject({
+		file: absoluteFilePath,
+		basedir: path.dirname(absoluteFilePath),
+		grouped: true
+	}), true, force);
+}
+function buildBeatIdIndex(beats) {
+	const idToIndex = /* @__PURE__ */ new Map();
+	beats.forEach((beat, index) => {
+		const key = beat.id ?? `__index__${index}`;
+		idToIndex.set(key, index);
+	});
+	return idToIndex;
+}
+/** Map identity for the in-flight tracker. JSON array keeps the three
+*  fields unambiguous (a human-visible delimiter could collide). */
+function generationMapKey(kind, filePath, key) {
+	return JSON.stringify([
+		kind,
+		filePath,
+		key
+	]);
+}
+/**
+* Build the per-host mulmoScript server ops instance. One instance per
+* process — it owns the in-flight movie/PDF dedup sets and the
+* generation-state tracker, and binds the injected host backend.
+*/
+function createMulmoScriptServerOps(backend) {
+	const log = backend.log ?? NOOP_LOG;
+	setMulmoErrorCaptureLogger(log);
+	const storiesDir = path.resolve(backend.storiesDir);
+	function toStoryRef(absolutePath) {
+		const root = ensureStoriesReal() ?? storiesDir;
+		const rel = path.relative(root, absolutePath).split(path.sep).join("/");
+		return rel ? `stories/${rel}` : "stories";
+	}
+	let storiesRealCache = null;
+	function ensureStoriesReal() {
+		if (storiesRealCache) return storiesRealCache;
+		try {
+			mkdirSync(storiesDir, { recursive: true });
+			storiesRealCache = realpathSync(storiesDir);
+			return storiesRealCache;
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Resolve and validate a stories wire path to its absolute realpath.
+	*
+	* Uses the realpath-based resolveWithinRoot helper to defeat
+	* symlink-based escapes. Callers pass workspace-relative paths like
+	* "stories/foo.json" or "stories/__movies__/bar.mp4". We strip the
+	* leading "stories/" segment and resolve the remainder against the
+	* realpath of the stories directory itself — this works whether
+	* stories/ is a regular directory or a legitimate symlink to another
+	* location. ENOENT and traversal are distinguished (404 vs 400).
+	*/
+	function resolveStory(filePath) {
+		const storiesReal = ensureStoriesReal();
+		if (!storiesReal) return opServerError("stories directory not available");
+		if (path.isAbsolute(filePath)) return opBadRequest("Invalid filePath");
+		const STORIES_PREFIX = `stories${path.sep}`;
+		const relFromStories = filePath === "stories" ? "" : filePath.startsWith(STORIES_PREFIX) || filePath.startsWith("stories/") ? filePath.slice(8) : filePath;
+		const resolved = resolveWithinRoot(storiesReal, relFromStories);
+		if (!resolved) {
+			const candidate = path.resolve(storiesReal, relFromStories);
+			if ((candidate === storiesReal || candidate.startsWith(storiesReal + path.sep)) && !existsSync(candidate)) return opNotFound(`File not found: ${filePath}`);
+			return opBadRequest("Invalid filePath");
+		}
+		return {
+			ok: true,
+			absolutePath: resolved
+		};
+	}
+	/**
+	* Realpath containment pre-guard for wire paths handed to the phase-1
+	* core's save/reopen/update executes. The core's own path guard is
+	* lexical (it runs against the generic FileOps, whose read/write follows
+	* symlinks), so hosts re-assert the realpath boundary here before
+	* invoking it — a symlink planted below the stories dir can't read or
+	* write outside the tree (Codex P1 on MulmoClaude#2133).
+	*
+	* Returns null when `filePath` isn't a non-empty string — shape
+	* validation (including the script-vs-filePath mode check) belongs to
+	* the core.
+	*/
+	function guardStoryWirePath(filePath) {
+		if (typeof filePath !== "string" || filePath === "") return null;
+		const resolved = resolveStory(filePath);
+		return resolved.ok ? null : resolved;
+	}
+	function ffmpegGuard() {
+		if (backend.isFfmpegAvailable?.() === false) return {
+			ok: false,
+			code: "unavailable",
+			error: "ffmpeg is not installed — movie and beat rendering are unavailable. Install ffmpeg and restart the server."
+		};
+		return null;
+	}
+	const inFlightGenerations = /* @__PURE__ */ new Map();
+	function publishGeneration(chatSessionId, kind, filePath, key, finished, error) {
+		const mapKey = generationMapKey(kind, filePath, key);
+		const existing = inFlightGenerations.get(mapKey);
+		if (finished) {
+			if (existing && existing.count > 1) {
+				existing.count -= 1;
+				return;
+			}
+			inFlightGenerations.delete(mapKey);
+		} else {
+			if (existing) {
+				existing.count += 1;
+				return;
+			}
+			inFlightGenerations.set(mapKey, {
+				kind,
+				filePath,
+				key,
+				count: 1
+			});
+		}
+		const event = {
+			kind,
+			filePath,
+			key,
+			done: finished,
+			...error ? { error } : {}
+		};
+		backend.onGenerationEvent?.(chatSessionId, event);
+	}
+	/** Snapshot of generations currently in flight for one script — the
+	*  View's mount-time catch-up, filtered to its wire `filePath`. */
+	function pendingGenerations(filePath) {
+		return [...inFlightGenerations.values()].filter((entry) => entry.filePath === filePath).map(({ kind, key }) => ({
+			kind,
+			filePath,
+			key,
+			done: false
+		}));
+	}
+	/**
+	* Shared scaffolding for mulmoScript ops. Resolves the wire filePath,
+	* builds the mulmo context, and folds unexpected handler errors into a
+	* server_error failure (with a warn breadcrumb). Accepts a `deps` param
+	* so unit tests can inject fakes without the full mulmocast stack.
+	*/
+	async function runStoryOp(filePath, options, handler, deps = {}) {
+		const resolver = deps.resolveStory ?? resolveStory;
+		const build = deps.buildContext ?? buildContext;
+		const resolved = resolver(filePath);
+		if (!resolved.ok) return resolved;
+		try {
+			const context = await build(resolved.absolutePath, options.force ?? false);
+			if (!context) {
+				if (options.onContextMissing) return options.onContextMissing();
+				return opServerError("Failed to initialize mulmo context");
+			}
+			return await withMulmoErrorCapture(() => handler({
+				absoluteFilePath: resolved.absolutePath,
+				context
+			}));
+		} catch (err) {
+			log.warn("op failed", {
+				...options.operation ? { operation: options.operation } : {},
+				filePath,
+				error: errorText(err)
+			});
+			return opServerError(errorText(err));
+		}
+	}
+	async function beatImageOp(filePath, beatIndex) {
+		return runStoryOp(filePath, { operation: "beat-image" }, async ({ context }) => {
+			const { imagePath } = getBeatPngImagePath(context, beatIndex);
+			if (!existsSync(imagePath)) return {
+				ok: true,
+				image: null
+			};
+			return {
+				ok: true,
+				image: await fileToDataUri(imagePath, "image/png")
+			};
+		});
+	}
+	async function beatAudioOp(filePath, beatIndex) {
+		return runStoryOp(filePath, {
+			operation: "beat-audio",
+			onContextMissing: () => ({
+				ok: true,
+				audio: null
+			})
+		}, async ({ context }) => {
+			const beat = context.studio.script.beats[beatIndex];
+			const audioPath = getBeatAudioPathOrUrl(beat.text ?? "", context, beat, context.lang);
+			if (!audioPath || !existsSync(audioPath)) return {
+				ok: true,
+				audio: null
+			};
+			return {
+				ok: true,
+				audio: await fileToDataUri(audioPath, "audio/mpeg")
+			};
+		});
+	}
+	async function beatMovieOp(filePath, beatIndex) {
+		return runStoryOp(filePath, { operation: "beat-movie" }, async ({ context }) => {
+			const { movieFile, soundEffectFile, lipSyncFile } = getBeatMoviePaths(context, beatIndex);
+			const existing = [
+				lipSyncFile,
+				soundEffectFile,
+				movieFile,
+				getBeatAnimatedVideoPath(context, beatIndex)
+			].find((candidate) => existsSync(candidate));
+			return {
+				ok: true,
+				moviePath: existing ? toStoryRef(existing) : null
+			};
+		});
+	}
+	async function characterImageOp(filePath, key) {
+		return runStoryOp(filePath, { operation: "character-image" }, async ({ context }) => {
+			const imagePath = getReferenceImagePath(context, key, "png");
+			if (!existsSync(imagePath)) return {
+				ok: true,
+				image: null
+			};
+			return {
+				ok: true,
+				image: await fileToDataUri(imagePath, "image/png")
+			};
+		});
+	}
+	/** Shared "output exists and is newer than the source script" gate for
+	*  movie / PDF status. A stale artifact (script edited after it was
+	*  generated) reports null so the UI re-offers the Generate button. */
+	function freshOutputRef(outputPath, absoluteFilePath) {
+		if (!existsSync(outputPath)) return null;
+		if (statSync(outputPath).mtimeMs < statSync(absoluteFilePath).mtimeMs) return null;
+		return toStoryRef(outputPath);
+	}
+	async function movieStatusOp(filePath) {
+		return runStoryOp(filePath, {
+			operation: "movie-status",
+			onContextMissing: () => ({
+				ok: true,
+				moviePath: null
+			})
+		}, async ({ absoluteFilePath, context }) => ({
+			ok: true,
+			moviePath: freshOutputRef(movieFilePath(context), absoluteFilePath)
+		}));
+	}
+	async function pdfStatusOp(filePath) {
+		return runStoryOp(filePath, {
+			operation: "pdf-status",
+			onContextMissing: () => ({
+				ok: true,
+				pdfPath: null
+			})
+		}, async ({ absoluteFilePath, context }) => ({
+			ok: true,
+			pdfPath: freshOutputRef(pdfFilePath(context, PDF_MODE), absoluteFilePath)
+		}));
+	}
+	async function renderBeatOp(args) {
+		const { filePath, beatIndex, force, chatSessionId } = args;
+		const ffmpeg = ffmpegGuard();
+		if (ffmpeg) return ffmpeg;
+		const mapKey = String(beatIndex);
+		publishGeneration(chatSessionId, "beatImage", filePath, mapKey, false);
+		let genError;
+		try {
+			const result = await runStoryOp(filePath, {
+				force,
+				operation: "render-beat"
+			}, async ({ context }) => {
+				await generateBeatImage({
+					index: beatIndex,
+					context,
+					args: force ? { forceImage: true } : void 0
+				});
+				const { imagePath } = getBeatPngImagePath(context, beatIndex);
+				if (!existsSync(imagePath)) return opServerError("Image was not generated");
+				return {
+					ok: true,
+					image: await fileToDataUri(imagePath, "image/png")
+				};
+			});
+			if (!result.ok) genError = result.error;
+			return result;
+		} finally {
+			publishGeneration(chatSessionId, "beatImage", filePath, mapKey, true, genError);
+		}
+	}
+	async function generateBeatAudioOp(args) {
+		const { filePath, beatIndex, force, chatSessionId } = args;
+		const mapKey = String(beatIndex);
+		publishGeneration(chatSessionId, "beatAudio", filePath, mapKey, false);
+		let genError;
+		try {
+			const result = await runStoryOp(filePath, {
+				force,
+				operation: "generate-beat-audio"
+			}, async ({ context }) => {
+				await generateBeatAudio(beatIndex, context, { settings: process.env });
+				const beat = context.studio.script.beats[beatIndex];
+				const audioPath = context.studio.beats[beatIndex]?.audioFile ?? getBeatAudioPathOrUrl(beat.text ?? "", context, beat, context.lang);
+				if (!audioPath || !existsSync(audioPath)) {
+					log.error("audio was not generated", {
+						beatIndex,
+						audioPath,
+						exists: audioPath ? existsSync(audioPath) : false,
+						beatTextLength: typeof beat?.text === "string" ? beat.text.length : 0,
+						audioFilePresent: Boolean(context.studio.beats[beatIndex]?.audioFile)
+					});
+					return opServerError("Audio was not generated");
+				}
+				return {
+					ok: true,
+					audio: await fileToDataUri(audioPath, "audio/mpeg")
+				};
+			});
+			if (!result.ok) genError = result.error;
+			return result;
+		} finally {
+			publishGeneration(chatSessionId, "beatAudio", filePath, mapKey, true, genError);
+		}
+	}
+	async function renderCharacterOp(args) {
+		const { filePath, key, force, chatSessionId } = args;
+		publishGeneration(chatSessionId, "characterImage", filePath, key, false);
+		let genError;
+		try {
+			const result = await runStoryOp(filePath, {
+				force,
+				operation: "render-character"
+			}, async ({ context }) => {
+				const imageEntries = context.studio.script.imageParams?.images ?? {};
+				const imageEntry = imageEntries[key];
+				if (!imageEntry || imageEntry.type !== "imagePrompt") return opBadRequest(`No imagePrompt entry for key: ${key}`);
+				const index = Object.keys(imageEntries).indexOf(key);
+				const imagePath = getReferenceImagePath(context, key, "png");
+				mkdirSync(path.dirname(imagePath), { recursive: true });
+				await generateReferenceImage({
+					context,
+					key,
+					index,
+					image: imageEntry,
+					force
+				});
+				if (!existsSync(imagePath)) return opServerError("Character image was not generated");
+				return {
+					ok: true,
+					image: await fileToDataUri(imagePath, "image/png")
+				};
+			});
+			if (!result.ok) genError = result.error;
+			return result;
+		} finally {
+			publishGeneration(chatSessionId, "characterImage", filePath, key, true, genError);
+		}
+	}
+	async function uploadBeatImageOp(filePath, beatIndex, imageData) {
+		return runStoryOp(filePath, { operation: "upload-beat-image" }, async ({ context }) => {
+			const { imagePath } = getBeatPngImagePath(context, beatIndex);
+			const base64 = stripDataUri(imageData);
+			await backend.writeFileAtomic(imagePath, Buffer.from(base64, "base64"));
+			return {
+				ok: true,
+				image: await fileToDataUri(imagePath, "image/png")
+			};
+		});
+	}
+	async function uploadCharacterImageOp(filePath, key, imageData) {
+		return runStoryOp(filePath, { operation: "upload-character-image" }, async ({ context }) => {
+			const imagePath = getReferenceImagePath(context, key, "png");
+			const base64 = stripDataUri(imageData);
+			await backend.writeFileAtomic(imagePath, Buffer.from(base64, "base64"));
+			return {
+				ok: true,
+				image: await fileToDataUri(imagePath, "image/png")
+			};
+		});
+	}
+	const inFlightMovies = /* @__PURE__ */ new Set();
+	const inFlightPdfs = /* @__PURE__ */ new Set();
+	async function runMovieGeneration(absoluteFilePath, onProgressEvent) {
+		return withMulmoErrorCapture(() => runMoviePipeline(absoluteFilePath, onProgressEvent));
+	}
+	async function runMoviePipeline(absoluteFilePath, onProgressEvent) {
+		const context = await buildContext(absoluteFilePath);
+		if (!context) return {
+			ok: false,
+			error: "Failed to initialize mulmo context"
+		};
+		const idToIndex = buildBeatIdIndex(context.studio.script.beats);
+		const onProgress = (event) => {
+			if (event.kind !== "beat" || event.inSession || event.id === void 0) return;
+			const beatIndex = idToIndex.get(event.id);
+			if (beatIndex === void 0) return;
+			if (event.sessionType !== "image" && event.sessionType !== "audio") return;
+			onProgressEvent({
+				kind: event.sessionType,
+				beatIndex
+			});
+		};
+		addSessionProgressCallback(onProgress);
+		try {
+			const imagesContext = await images(await audio(context));
+			await movie(imagesContext);
+			const outputPath = movieFilePath(imagesContext);
+			if (!existsSync(outputPath)) return {
+				ok: false,
+				error: "Movie was not generated"
+			};
+			return {
+				ok: true,
+				outputPath
+			};
+		} finally {
+			removeSessionProgressCallback(onProgress);
+		}
+	}
+	/**
+	* Long-held foreground movie generation (the package View's
+	* `generateMovie` dispatch). Resolves when the whole pipeline finishes.
+	* Per-beat completions are mirrored to the generation channels so the
+	* initiating View (and any other mounted View) reloads assets off disk
+	* as they land — the successor of the SSE per-beat events.
+	*/
+	async function generateMovieOp(filePath, chatSessionId) {
+		const ffmpeg = ffmpegGuard();
+		if (ffmpeg) return ffmpeg;
+		const resolved = resolveStory(filePath);
+		if (!resolved.ok) return resolved;
+		const absoluteFilePath = resolved.absolutePath;
+		if (inFlightMovies.has(absoluteFilePath)) return opBadRequest("Movie generation is already in progress for this script");
+		inFlightMovies.add(absoluteFilePath);
+		publishGeneration(chatSessionId, "movie", filePath, "", false);
+		let genError;
+		try {
+			const result = await runMovieGeneration(absoluteFilePath, (event) => {
+				publishGeneration(chatSessionId, event.kind === "image" ? "beatImage" : "beatAudio", filePath, String(event.beatIndex), true);
+			});
+			if (!result.ok) {
+				genError = result.error;
+				return opServerError(result.error);
+			}
+			return {
+				ok: true,
+				moviePath: toStoryRef(result.outputPath)
+			};
+		} catch (err) {
+			genError = errorText(err);
+			return opServerError(genError);
+		} finally {
+			inFlightMovies.delete(absoluteFilePath);
+			publishGeneration(chatSessionId, "movie", filePath, "", true, genError);
+		}
+	}
+	function triggerAutoBackgroundMovie(absoluteFilePath, wireFilePath, chatSessionId) {
+		if (inFlightMovies.has(absoluteFilePath)) return;
+		inFlightMovies.add(absoluteFilePath);
+		runBackgroundMovieGeneration(absoluteFilePath, wireFilePath, chatSessionId);
+	}
+	async function runBackgroundMovieGeneration(absoluteFilePath, wireFilePath, chatSessionId) {
+		const errorSidecarPath = `${absoluteFilePath}.error.txt`;
+		try {
+			unlinkSync(errorSidecarPath);
+		} catch {}
+		publishGeneration(chatSessionId, "movie", wireFilePath, "", false);
+		let genError;
+		try {
+			const result = await runMovieGeneration(absoluteFilePath, (event) => {
+				const eventKind = event.kind === "image" ? "beatImage" : "beatAudio";
+				const key = String(event.beatIndex);
+				publishGeneration(chatSessionId, eventKind, wireFilePath, key, false);
+				setImmediate(() => publishGeneration(chatSessionId, eventKind, wireFilePath, key, true));
+			});
+			if (!result.ok) {
+				genError = result.error;
+				await writeErrorSidecar(errorSidecarPath, result.error);
+				log.warn("background movie generation failed", {
+					filePath: wireFilePath,
+					error: result.error
+				});
+				return;
+			}
+			log.info("background movie generation done", {
+				filePath: wireFilePath,
+				outputPath: result.outputPath
+			});
+		} catch (err) {
+			genError = errorText(err);
+			await writeErrorSidecar(errorSidecarPath, genError);
+			log.error("background movie generation crashed", {
+				filePath: wireFilePath,
+				error: genError
+			});
+		} finally {
+			inFlightMovies.delete(absoluteFilePath);
+			publishGeneration(chatSessionId, "movie", wireFilePath, "", true, genError);
+		}
+	}
+	async function writeErrorSidecar(errorSidecarPath, message) {
+		try {
+			await backend.writeFileAtomic(errorSidecarPath, message);
+		} catch (writeErr) {
+			log.error("failed to write error sidecar", {
+				errorSidecarPath,
+				error: errorText(writeErr)
+			});
+		}
+	}
+	async function runPdfGeneration(context, onImageBeatDone) {
+		return withMulmoErrorCapture(() => runPdfPipeline(context, onImageBeatDone));
+	}
+	async function runPdfPipeline(context, onImageBeatDone) {
+		const idToIndex = buildBeatIdIndex(context.studio.script.beats);
+		const onProgress = (event) => {
+			if (event.kind !== "beat" || event.inSession || event.id === void 0) return;
+			const beatIndex = idToIndex.get(event.id);
+			if (beatIndex === void 0) return;
+			if (event.sessionType !== "image") return;
+			onImageBeatDone(beatIndex);
+		};
+		addSessionProgressCallback(onProgress);
+		try {
+			const imagesContext = await images(context);
+			await pdf(imagesContext, PDF_MODE, "a4");
+			const outputPath = pdfFilePath(imagesContext, PDF_MODE);
+			if (!existsSync(outputPath)) return {
+				ok: false,
+				error: "PDF was not generated"
+			};
+			return {
+				ok: true,
+				outputPath
+			};
+		} finally {
+			removeSessionProgressCallback(onProgress);
+		}
+	}
+	/** Long-held foreground PDF generation (the package View's `generatePdf`
+	*  dispatch) — the PDF sibling of `generateMovieOp`. */
+	async function generatePdfOp(filePath, chatSessionId) {
+		const ffmpeg = ffmpegGuard();
+		if (ffmpeg) return ffmpeg;
+		const resolved = resolveStory(filePath);
+		if (!resolved.ok) return resolved;
+		const absoluteFilePath = resolved.absolutePath;
+		if (inFlightPdfs.has(absoluteFilePath)) return opBadRequest("PDF generation is already in progress for this script");
+		inFlightPdfs.add(absoluteFilePath);
+		publishGeneration(chatSessionId, "pdf", filePath, "", false);
+		let genError;
+		try {
+			const context = await buildContext(absoluteFilePath);
+			if (!context) {
+				genError = "Failed to initialize mulmo context";
+				return opServerError(genError);
+			}
+			const result = await runPdfGeneration(context, (beatIndex) => {
+				publishGeneration(chatSessionId, "beatImage", filePath, String(beatIndex), true);
+			});
+			if (!result.ok) {
+				genError = result.error;
+				return opServerError(result.error);
+			}
+			return {
+				ok: true,
+				pdfPath: toStoryRef(result.outputPath)
+			};
+		} catch (err) {
+			genError = errorText(err);
+			return opServerError(genError);
+		} finally {
+			inFlightPdfs.delete(absoluteFilePath);
+			publishGeneration(chatSessionId, "pdf", filePath, "", true, genError);
+		}
+	}
+	return {
+		backend,
+		toStoryRef,
+		resolveStory,
+		guardStoryWirePath,
+		ffmpegGuard,
+		runStoryOp,
+		publishGeneration,
+		pendingGenerations,
+		beatImageOp,
+		beatAudioOp,
+		beatMovieOp,
+		characterImageOp,
+		movieStatusOp,
+		pdfStatusOp,
+		renderBeatOp,
+		generateBeatAudioOp,
+		renderCharacterOp,
+		uploadBeatImageOp,
+		uploadCharacterImageOp,
+		inFlightMovies,
+		inFlightPdfs,
+		runMovieGeneration,
+		runPdfGeneration,
+		generateMovieOp,
+		generatePdfOp,
+		triggerAutoBackgroundMovie
+	};
+}
+//#endregion
+//#region src/server/dispatch.ts
+function fromOpFailure(failure) {
+	return {
+		ok: false,
+		code: failure.code === "unavailable" ? "server_error" : failure.code,
+		error: failure.error
+	};
+}
+function fromPackageFailure(failure) {
+	return {
+		ok: false,
+		code: failure.code,
+		error: failure.error
+	};
+}
+function invalidArgs(kind) {
+	return {
+		ok: false,
+		code: "bad_request",
+		error: `invalid arguments for mulmoScript dispatch kind "${kind}"`
+	};
+}
+function str(value) {
+	return typeof value === "string" && value !== "" ? value : void 0;
+}
+function num(value) {
+	return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : void 0;
+}
+/** Pass ok results through untouched; normalize failures for the wire. */
+function envelope(result) {
+	return result.ok ? result : fromOpFailure(result);
+}
+function beatArgs(args) {
+	const filePath = str(args.filePath);
+	const beatIndex = num(args.beatIndex);
+	if (!filePath || beatIndex === void 0) return null;
+	return {
+		filePath,
+		beatIndex
+	};
+}
+function keyArgs(args) {
+	const filePath = str(args.filePath);
+	const key = str(args.key);
+	if (!filePath || !key) return null;
+	return {
+		filePath,
+		key
+	};
+}
+var PROBE_KINDS = /* @__PURE__ */ new Set([
+	"beatImage",
+	"beatAudio",
+	"beatMovie",
+	"characterImage",
+	"movieStatus",
+	"pdfStatus"
+]);
+var GENERATE_KINDS = /* @__PURE__ */ new Set([
+	"renderBeat",
+	"generateBeatAudio",
+	"renderCharacter",
+	"generateMovie",
+	"generatePdf"
+]);
+var UPLOAD_KINDS = /* @__PURE__ */ new Set(["uploadBeatImage", "uploadCharacterImage"]);
+/**
+* Build the kind router over an ops instance. The save / reopen / update
+* kinds run the phase-1 core executes against the backend's artifacts
+* FileOps, guarded by the instance's realpath containment
+* (`guardStoryWirePath`) — the core's own guard is lexical.
+*/
+function createMulmoScriptDispatchHandler(ops) {
+	const executeContext = { files: { artifacts: ops.backend.artifacts } };
+	async function saveKind(args) {
+		const guard = ops.guardStoryWirePath(args.filePath);
+		if (guard) return fromOpFailure(guard);
+		const outcome = await executeMulmoScriptSave(executeContext, {
+			script: args.script,
+			filename: str(args.filename),
+			filePath: str(args.filePath)
+		});
+		if (!outcome.ok) return fromPackageFailure(outcome);
+		return {
+			ok: true,
+			script: outcome.script,
+			filePath: outcome.filePath,
+			message: outcome.message
+		};
+	}
+	async function updateKind(kind, args) {
+		const guard = ops.guardStoryWirePath(args.filePath);
+		if (guard) return fromOpFailure(guard);
+		const outcome = kind === "updateBeat" ? await executeUpdateBeat(executeContext, args) : await executeUpdateScript(executeContext, args);
+		return outcome.ok ? { ok: true } : fromPackageFailure(outcome);
+	}
+	const STATUS_OPS = {
+		movieStatus: ops.movieStatusOp,
+		pdfStatus: ops.pdfStatusOp
+	};
+	const BEAT_PROBE_OPS = {
+		beatImage: ops.beatImageOp,
+		beatAudio: ops.beatAudioOp,
+		beatMovie: ops.beatMovieOp
+	};
+	async function probeKind(kind, args) {
+		const statusOp = STATUS_OPS[kind];
+		if (statusOp) {
+			const filePath = str(args.filePath);
+			return filePath ? envelope(await statusOp(filePath)) : invalidArgs(kind);
+		}
+		if (kind === "characterImage") {
+			const parsed = keyArgs(args);
+			return parsed ? envelope(await ops.characterImageOp(parsed.filePath, parsed.key)) : invalidArgs(kind);
+		}
+		const parsed = beatArgs(args);
+		if (!parsed) return invalidArgs(kind);
+		return envelope(await BEAT_PROBE_OPS[kind](parsed.filePath, parsed.beatIndex));
+	}
+	async function generateKind(kind, args) {
+		const chatSessionId = str(args.chatSessionId);
+		const force = args.force === true;
+		if (kind === "generateMovie" || kind === "generatePdf") {
+			const filePath = str(args.filePath);
+			if (!filePath) return invalidArgs(kind);
+			return envelope(kind === "generateMovie" ? await ops.generateMovieOp(filePath, chatSessionId) : await ops.generatePdfOp(filePath, chatSessionId));
+		}
+		if (kind === "renderCharacter") {
+			const parsed = keyArgs(args);
+			return parsed ? envelope(await ops.renderCharacterOp({
+				...parsed,
+				force,
+				chatSessionId
+			})) : invalidArgs(kind);
+		}
+		const parsed = beatArgs(args);
+		if (!parsed) return invalidArgs(kind);
+		return envelope(kind === "renderBeat" ? await ops.renderBeatOp({
+			...parsed,
+			force,
+			chatSessionId
+		}) : await ops.generateBeatAudioOp({
+			...parsed,
+			force,
+			chatSessionId
+		}));
+	}
+	async function uploadKind(kind, args) {
+		const imageData = str(args.imageData);
+		if (!imageData) return invalidArgs(kind);
+		if (kind === "uploadCharacterImage") {
+			const parsed = keyArgs(args);
+			return parsed ? envelope(await ops.uploadCharacterImageOp(parsed.filePath, parsed.key, imageData)) : invalidArgs(kind);
+		}
+		const parsed = beatArgs(args);
+		if (!parsed) return invalidArgs(kind);
+		return envelope(await ops.uploadBeatImageOp(parsed.filePath, parsed.beatIndex, imageData));
+	}
+	return async (args) => {
+		const kind = str(args.kind);
+		if (!kind) return invalidArgs("<missing>");
+		if (kind === "save") return saveKind(args);
+		if (kind === "updateBeat" || kind === "updateScript") return updateKind(kind, args);
+		if (PROBE_KINDS.has(kind)) return probeKind(kind, args);
+		if (GENERATE_KINDS.has(kind)) return generateKind(kind, args);
+		if (UPLOAD_KINDS.has(kind)) return uploadKind(kind, args);
+		if (kind === "pendingGenerations") {
+			const filePath = str(args.filePath);
+			if (!filePath) return invalidArgs(kind);
+			return {
+				ok: true,
+				pending: ops.pendingGenerations(filePath)
+			};
+		}
+		return {
+			ok: false,
+			code: "bad_request",
+			error: `unknown mulmoScript dispatch kind "${kind}"`
+		};
+	};
+}
+//#endregion
+export { GENERATION_EVENT, PDF_MODE, PDF_SIZE, buildBeatIdIndex, buildContext, composeMulmoErrorMessage, createMulmoScriptDispatchHandler, createMulmoScriptServerOps, describeMulmoCause, enableGraphAIErrorCapture, executeMulmoScriptSave, executeUpdateBeat, executeUpdateScript, withMulmoErrorCapture };
+
+//# sourceMappingURL=server.js.map