mulmocast 2.11.0 → 2.12.0

package/lib/actions/html.js

@@ -1,9 +1,21 @@
 import fs from "fs";
 import path from "path";
 import { isNull } from "graphai";
+import { escapeHtml, slideUtilityCss } from "@mulmocast/deck";
 import { localizedText } from "../utils/utils.js";
 import { writingMessage } from "../utils/file.js";
 import { MulmoStudioContextMethods } from "../methods/mulmo_studio_context.js";
+/**
+ * The HTML document for a studio.
+ *
+ * Every value that reaches an attribute or `<title>` comes from the script, and a beat with a
+ * `source: { kind: "path" }` image puts the author's own path into `src`, so each one is
+ * escaped for the context it lands in.
+ *
+ * Not exported: `actions/index.ts` re-exports this module with `export *` and `index.node.ts`
+ * re-exports that, so anything exported here becomes public API of the published package. The
+ * tests drive it through `html()` instead.
+ */
 const generateHtmlContent = (context, imageWidth) => {
     const { studio, multiLingual, lang = "en" } = context;
     const title = studio.script.title || "MulmoCast Content";
@@ -20,11 +32,14 @@ const generateHtmlContent = (context, imageWidth) => {
                 html += `${studioBeat.html}\n\n`;
             }
             else if (studioBeat?.imageFile && isNull(studioBeat.html)) {
-                const imagePath = path.relative(context.fileDirs.outDirPath, studioBeat.imageFile);
-                const altText = `Beat ${index + 1}`;
+                // A `source: { kind: "path" }` beat puts the author's own path here, so it reaches an
+                // HTML attribute unfiltered unless it is escaped. Every value in these attributes goes
+                // through the same rule rather than each being argued safe on its own.
+                const imagePath = escapeHtml(path.relative(context.fileDirs.outDirPath, studioBeat.imageFile));
+                const altText = escapeHtml(`Beat ${index + 1}`);
                 if (imageWidth) {
                     // Use HTML img tag for width control
-                    html += `<img src="${imagePath}" alt="${altText}" width="${imageWidth}" />\n\n`;
+                    html += `<img src="${imagePath}" alt="${altText}" width="${escapeHtml(imageWidth)}" />\n\n`;
                 }
                 else {
                     // Use standard html image syntax
@@ -42,13 +57,16 @@ const generateHtmlContent = (context, imageWidth) => {
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>${title}</title>
+    <title>${escapeHtml(title)}</title>
     <!-- Tailwind CSS CDN -->
     <script src="https://cdn.tailwindcss.com"></script>
     <!-- Chart.js CDN -->
     <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
     <!-- Mermaid CDN -->
     <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
+    <!-- The utilities every slide fragment is written against. Shared, so it belongs to the
+         page: a slide beat emits only its own scoped rules. -->
+    <style>${slideUtilityCss}</style>
   </head>
   <body class="min-h-screen flex flex-col">
 ${html}

package/lib/actions/markdown.js

@@ -3,6 +3,7 @@ import { localizedText } from "../utils/utils.js";
 import { writingMessage } from "../utils/file.js";
 import { MulmoStudioContextMethods } from "../methods/mulmo_studio_context.js";
 import path from "path";
+import { escapeHtml } from "@mulmocast/deck";
 const generateMarkdownContent = (context, imageWidth) => {
     const { studio, multiLingual, lang = "en" } = context;
     const title = studio.script.title || "MulmoCast Content";
@@ -21,9 +22,11 @@ const generateMarkdownContent = (context, imageWidth) => {
             else if (studioBeat?.imageFile) {
                 const imagePath = path.relative(context.fileDirs.outDirPath, studioBeat.imageFile);
                 if (imageWidth) {
-                    // Use HTML img tag for width control
+                    // An HTML tag is HTML wherever the markdown is rendered, and a
+                    // `source: { kind: "path" }` beat puts the author's own path here — the same shape
+                    // and the same input as the `<img>` in actions/html.ts.
                     const altText = `Beat ${index + 1}`;
-                    markdown += `<img src="${imagePath}" alt="${altText}" width="${imageWidth}" />\n\n`;
+                    markdown += `<img src="${escapeHtml(imagePath)}" alt="${escapeHtml(altText)}" width="${escapeHtml(imageWidth)}" />\n\n`;
                 }
                 else {
                     // Use standard markdown image syntax

package/lib/mcp/server.js

@@ -15,8 +15,10 @@ import { MulmoScriptMethods } from "../methods/index.js";
 dotenv.config({ quiet: true });
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-// Load MulmoScript JSON Schema from file
-const MULMO_SCRIPT_JSON_SCHEMA = JSON.parse(fs.readFileSync(path.resolve(__dirname, "../../assets/schemas/html_prompt.json"), "utf8"));
+// The `mulmoScript` argument's shape, as advertised to an MCP client. It is html_prompt.json,
+// not mulmo_script.json — the switch was deliberate, but the old name outlived it and is why
+// nobody noticed that mulmo_script.json had no reader left for fourteen months.
+const HTML_PROMPT_JSON_SCHEMA = JSON.parse(fs.readFileSync(path.resolve(__dirname, "../../assets/schemas/html_prompt.json"), "utf8"));
 const server = new Server({
     name: "mulmocast-mcp",
     version: "0.1.0",
@@ -53,7 +55,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             enum: ["movie", "pdf"],
                             description: "Command to execute: 'movie' to generate video, 'pdf' to generate PDF",
                         },
-                        mulmoScript: MULMO_SCRIPT_JSON_SCHEMA,
+                        mulmoScript: HTML_PROMPT_JSON_SCHEMA,
                         options: {
                             type: "object",
                             description: "Optional generation parameters",

package/lib/utils/beat_html/type.d.ts

@@ -21,7 +21,14 @@ export type BeatHtmlFragment = {
      * since it has no DOM and must stay dependency-light to remain bundleable.
      */
     html: string;
-    /** Rules the markup needs, scoped by the caller. Absent when the markup needs none. */
+    /**
+     * Rules the markup needs, scoped by the caller. Absent when the markup needs none.
+     *
+     * It cannot carry everything: an `html_tailwind` beat written with `elements` is a root
+     * asking for 100% of its parent, and how tall that parent should be is the host's layout,
+     * not the beat's. The root is marked `data-mulmo-swipe-root` so a host can give it one —
+     * and a host that does not gets an empty box, silently.
+     */
     css?: string;
     /** External runtimes the host must load once for the page, not once per beat. */
     requires?: BeatRuntime[];

package/lib/utils/html_escape.d.ts

@@ -11,4 +11,6 @@
  */
 /** Neutralize the output of JSON.stringify for embedding inside an inline `<script>`. */
 export declare const escapeJsonForScript: (json: string) => string;
+/** Neutralize a value placed inside a quoted CSS string, such as the argument of `url()`. */
+export declare const escapeCssString: (value: string) => string;
 export declare const neutralizeStyleTerminator: (css: string) => string;

package/lib/utils/html_escape.js

@@ -22,6 +22,22 @@ const SCRIPT_JSON_ESCAPES = new Map([
 ]);
 /** Neutralize the output of JSON.stringify for embedding inside an inline `<script>`. */
 export const escapeJsonForScript = (json) => json.replace(/[<>&\u2028\u2029]/g, (character) => SCRIPT_JSON_ESCAPES.get(character) ?? character);
+// A CSS string ends at the first unescaped quote of the kind that opened it, and a raw
+// newline ends the declaration outright, so a value carrying either escapes the string it
+// was placed in. Backslash is what CSS defines for both; a line break becomes its hex escape
+// with the terminating space CSS requires. Both quote characters are escaped so a caller may
+// use either, and every other character — including the base64 body of a data URL — is left
+// exactly as it was.
+const CSS_STRING_ESCAPES = new Map([
+    ["\\", "\\\\"],
+    ["'", "\\'"],
+    ['"', '\\"'],
+    ["\n", "\\a "],
+    ["\r", "\\d "],
+    ["\f", "\\c "],
+]);
+/** Neutralize a value placed inside a quoted CSS string, such as the argument of `url()`. */
+export const escapeCssString = (value) => value.replace(/[\\'"\n\r\f]/g, (character) => CSS_STRING_ESCAPES.get(character) ?? character);
 // A <style> element holds raw text: nothing inside it is parsed as markup except the closing
 // tag, so `</style` is the only sequence that can end it. Neutralizing just that keeps
 // author-supplied CSS working, which escaping the whole string would not. `\3c ` is the CSS

package/lib/utils/image_plugins/bg_image_util.js

@@ -1,7 +1,7 @@
 import { MulmoMediaSourceMethods } from "../../methods/mulmo_media_source.js";
 import { resolveStyle } from "./utils.js";
 import { safeFetch, DEFAULT_FETCH_TIMEOUT_MS } from "../fetch.js";
-import { neutralizeStyleTerminator } from "../html_escape.js";
+import { escapeCssString, neutralizeStyleTerminator } from "../html_escape.js";
 /**
  * Resolve background image from beat level and global level settings.
  * Beat level takes precedence over global level.
@@ -58,6 +58,8 @@ export const backgroundImageToCSS = async (backgroundImage, context) => {
         return "";
     }
     const isSimpleUrl = typeof backgroundImage === "string";
+    // Escaped at each use rather than here: the base64 body cannot carry a quote, but the
+    // content-type in front of it is whatever the remote server's response header said.
     const imageUrl = isSimpleUrl ? await fetchUrlAsDataUrl(backgroundImage) : await MulmoMediaSourceMethods.toDataUrl(backgroundImage.source, context);
     const size = sizeToCSS(isSimpleUrl ? "cover" : (backgroundImage.size ?? "cover"));
     const opacity = isSimpleUrl ? 1 : (backgroundImage.opacity ?? 1);
@@ -75,7 +77,7 @@ export const backgroundImageToCSS = async (backgroundImage, context) => {
         left: 0;
         right: 0;
         bottom: 0;
-        background-image: url('${imageUrl}');
+        background-image: url('${escapeCssString(imageUrl)}');
         background-size: ${size};
         background-position: center;
         background-repeat: no-repeat;
@@ -90,7 +92,7 @@ export const backgroundImageToCSS = async (backgroundImage, context) => {
       margin: 0;
     }
     body {
-      background-image: url('${imageUrl}');
+      background-image: url('${escapeCssString(imageUrl)}');
       background-size: ${size};
       background-position: center;
       background-repeat: no-repeat;

package/lib/utils/image_plugins/slide.js

@@ -1,6 +1,6 @@
 import nodePath from "node:path";
 import { pathToFileURL } from "node:url";
-import { generateSlideHTML } from "@mulmocast/deck";
+import { generateSlideFragment, generateSlideHTML } from "@mulmocast/deck";
 import { renderHTMLToImage } from "../html_render.js";
 import { parrotingImagePath } from "./utils.js";
 import { pathToDataUrl } from "../../methods/mulmo_media_source.js";
@@ -170,6 +170,24 @@ const processSlide = async (params) => {
     await renderHTMLToImage(html, imagePath, canvasSize.width, canvasSize.height);
     return imagePath;
 };
+/**
+ * A slide beat as markup for the export document, not as a document of its own.
+ *
+ * `generateSlideHTML` above is right for the PNG path, where the slide IS the page. Here the
+ * result is concatenated into one `<body>` alongside every other beat, so a full document per
+ * slide meant N Tailwind CDN loads, N `tailwind.config` assignments racing each other, and an
+ * `html, body { overflow: hidden }` escaping into the export page — which made a document of
+ * stacked slides unscrollable. `beat_html/slide.ts` already draws the browser path from
+ * `generateSlideFragment`; this is the same change for the dump path.
+ *
+ * The fragment's own css is emitted next to it because it is confined to `scopeClass`, which
+ * deck makes unique per call. What is SHARED — Tailwind, the chart and mermaid runtimes,
+ * `slideUtilityCss` — belongs to the page and is `actions/html.ts`'s job, once.
+ *
+ * The box is here rather than left to the host: the fragment is `w-full h-full`, so without
+ * one it collapses to nothing, and `actions/html.ts` concatenates beats without knowing which
+ * of them is a slide.
+ */
 const dumpHtml = async (params) => {
     const { beat } = params;
     if (!beat.image || beat.image.type !== imageType)
@@ -178,7 +196,8 @@ const dumpHtml = async (params) => {
     const slide = resolveSlide(params);
     const reference = beat.image.reference;
     const resolvedBranding = await resolveAndConvertBranding(params);
-    return generateSlideHTML(theme, slide, reference, resolvedBranding);
+    const fragment = generateSlideFragment(theme, slide, { reference, branding: resolvedBranding });
+    return `<style>${fragment.css}</style>\n<div style="aspect-ratio: 16 / 9;">${fragment.html}</div>`;
 };
 export const process = processSlide;
 export const path = parrotingImagePath;

package/lib/utils/swipe_to_html.d.ts

@@ -67,6 +67,13 @@ export interface SwipeElement {
  * this a sound narrowing rather than a cast wearing a guard's clothes.
  */
 export declare const isSwipeElements: (value: unknown) => value is SwipeElement[];
+/**
+ * The root the elements are positioned inside. Named so a browser host can give it a height:
+ * the root asks for 100% of its parent, and an inline height wins over any rule aimed at the
+ * root itself, so the parent is where the box has to come from. The document path has a
+ * viewport to fill and needs nothing.
+ */
+export declare const SWIPE_ROOT_ATTRIBUTE = "data-mulmo-swipe-root";
 /** Generate HTML from Swipe elements */
 export declare const swipeElementsToHtml: (elements: SwipeElement[]) => string;
 /** Generate render() script from Swipe element animations */

package/lib/utils/swipe_to_html.js

@@ -113,10 +113,17 @@ const elementToHtml = (el, index) => {
     lines.push("</div>");
     return lines.join("\n");
 };
+/**
+ * The root the elements are positioned inside. Named so a browser host can give it a height:
+ * the root asks for 100% of its parent, and an inline height wins over any rule aimed at the
+ * root itself, so the parent is where the box has to come from. The document path has a
+ * viewport to fill and needs nothing.
+ */
+export const SWIPE_ROOT_ATTRIBUTE = "data-mulmo-swipe-root";
 /** Generate HTML from Swipe elements */
 export const swipeElementsToHtml = (elements) => {
     const html = elements.map((el, i) => elementToHtml(el, i)).join("\n");
-    return `<div style="position:relative; width:100%; height:100%; overflow:hidden;">\n${html}\n</div>`;
+    return `<div ${SWIPE_ROOT_ATTRIBUTE} style="position:relative; width:100%; height:100%; overflow:hidden;">\n${html}\n</div>`;
 };
 const collectAnimations = (elements, entries, indexBase = 0) => {
     elements.forEach((el, i) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mulmocast",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "",
   "type": "module",
   "main": "lib/index.node.js",
@@ -66,6 +66,7 @@
     "scripting": "npx tsx ./src/cli/bin.ts tool scripting",
     "prompt": "npx tsx ./src/cli/bin.ts tool prompt",
     "schema": "npx tsx ./src/cli/bin.ts tool schema",
+    "schema:write": "npx tsx ./src/cli/bin.ts tool schema > assets/schemas/mulmo_script.json",
     "markdown": "npx tsx ./src/cli/bin.ts markdown",
     "html": "npx tsx ./src/cli/bin.ts html",
     "story_to_script": "npx tsx ./src/cli/bin.ts tool story_to_script",
@@ -127,6 +128,7 @@
     "@receptron/test_utils": "^2.0.3",
     "@types/archiver": "^8.0.0",
     "@types/jsdom": "^28.0.3",
+    "@types/node": "^26.0.0",
     "@types/yargs": "^17.0.35",
     "cross-env": "^10.1.0",
     "esbuild": "^0.28.2",