mulmocast 2.21.0 → 2.22.1

package/lib/methods/mulmo_beat.js

@@ -1,16 +1,5 @@
 import { ImageMediaType } from "../types/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);
-};
-/** Check if a value is a valid animation config (true or non-array object) */
-const isAnimationEnabled = (animation) => {
-    return animation === true || isAnimationObject(animation);
-};
-/** Check if movie mode (CDP screencast) is enabled */
-const isMovieMode = (animation) => {
-    return isAnimationObject(animation) && animation.movie === true;
-};
+import { isAnimationEnabled, isAnimationObject, isMovieMode } from "../utils/animation_config.js";
 /** Check if a beat has html_tailwind animation enabled */
 const isAnimatedHtmlTailwind = (beat) => {
     if (!beat.image || beat.image.type !== "html_tailwind")

package/lib/methods/mulmo_beat_node.d.ts

@@ -7,14 +7,8 @@ export declare const MulmoBeatMethods: {
         markdown?: (params: import("../types/type.js").BeatRenderParams) => string | undefined;
         html?: (params: import("../types/type.js").BeatRenderParams) => Promise<string | undefined>;
     };
-    isAnimationEnabled: (animation: unknown) => animation is true | {
-        fps?: number;
-        movie?: boolean;
-    };
-    isAnimationObject: (animation: unknown) => animation is {
-        fps?: number;
-        movie?: boolean;
-    };
+    isAnimationEnabled: (animation: unknown) => animation is true | import("../utils/animation_config.js").AnimationConfig;
+    isAnimationObject: (animation: unknown) => animation is import("../utils/animation_config.js").AnimationConfig;
     isAnimatedHtmlTailwind: (beat: MulmoBeat) => boolean;
     isPluginVideo: (beat: MulmoBeat) => boolean;
     isMovieMode: (animation: unknown) => boolean;

package/lib/utils/animation_config.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Reading an html_tailwind `animation` value. Pure and dependency-free — the PNG render and the
+ * browser fragment path decide "is this animated, at what fps" the same way, and the browser
+ * bundle must not reach the schema module to do it.
+ */
+export type AnimationConfig = {
+    fps?: number;
+    movie?: boolean;
+};
+/** Type guard: checks if animation value is an object config like { fps: 30 } */
+export declare const isAnimationObject: (animation: unknown) => animation is AnimationConfig;
+/** Check if a value is a valid animation config (true or non-array object) */
+export declare const isAnimationEnabled: (animation: unknown) => animation is true | AnimationConfig;
+/** Check if movie mode (CDP screencast) is enabled */
+export declare const isMovieMode: (animation: unknown) => boolean;

package/lib/utils/animation_config.js

@@ -0,0 +1,17 @@
+/**
+ * Reading an html_tailwind `animation` value. Pure and dependency-free — the PNG render and the
+ * browser fragment path decide "is this animated, at what fps" the same way, and the browser
+ * bundle must not reach the schema module to do it.
+ */
+/** Type guard: checks if animation value is an object config like { fps: 30 } */
+export const isAnimationObject = (animation) => {
+    return typeof animation === "object" && animation !== null && !Array.isArray(animation);
+};
+/** Check if a value is a valid animation config (true or non-array object) */
+export const isAnimationEnabled = (animation) => {
+    return animation === true || isAnimationObject(animation);
+};
+/** Check if movie mode (CDP screencast) is enabled */
+export const isMovieMode = (animation) => {
+    return isAnimationObject(animation) && animation.movie === true;
+};

package/lib/utils/audio_probe_source.d.ts

@@ -0,0 +1,5 @@
+export declare const isStillImageFile: (filePath: string) => boolean;
+export declare const audioProbeSource: (files: {
+    movieFile?: string;
+    imageFile?: string;
+}) => string | undefined;

package/lib/utils/audio_probe_source.js

@@ -0,0 +1,16 @@
+import path from "node:path";
+// A still image never carries an audio track, so probing it only makes ffprobe a requirement for image-only renders.
+const STILL_IMAGE_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".svg"]);
+export const isStillImageFile = (filePath) => {
+    const withoutQuery = filePath.split(/[?#]/)[0];
+    return STILL_IMAGE_EXTENSIONS.has(path.extname(withoutQuery).toLowerCase());
+};
+export const audioProbeSource = (files) => {
+    if (files.movieFile) {
+        return files.movieFile;
+    }
+    if (!files.imageFile || isStillImageFile(files.imageFile)) {
+        return undefined;
+    }
+    return files.imageFile;
+};

package/lib/utils/beat_html/chart.js

@@ -1,4 +1,5 @@
 import { deckSlideToHtml } from "./slide.js";
+import { backgroundDecoration } from "./decoration.js";
 /**
  * A chart beat as a deck `figure` slide, so it shares the `slide` beat's theme and its one
  * host code path: `slideUtilityCss`, and the `[data-mulmo-chart]` canvas driven from the
@@ -7,4 +8,4 @@ import { deckSlideToHtml } from "./slide.js";
  *
  * The PNG path still draws from its own template, so the browser and the PNG differ in look.
  */
-export const chartToHtml = (image, options) => deckSlideToHtml({ layout: "figure", title: image.title, figure: { type: "chart", chartData: image.chartData } }, undefined, options);
+export const chartToHtml = (image, options) => deckSlideToHtml({ layout: "figure", title: image.title, figure: { type: "chart", chartData: image.chartData } }, undefined, options, backgroundDecoration(image, options));

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

@@ -0,0 +1,16 @@
+import type { ResolvedBranding, SlideBranding } from "@mulmocast/deck";
+import type { BackgroundImage } from "../../types/index.js";
+import type { BeatHtmlFragment, BeatHtmlOptions } from "./type.js";
+export declare const safeMediaUrl: (url: string) => string;
+/** A textSlide / markdown fragment with `documentCss` for the background the PNG paints on `body`. */
+export declare const withDocumentBackground: (fragment: BeatHtmlFragment | undefined, image: {
+    backgroundImage?: BackgroundImage;
+}, options: BeatHtmlOptions) => BeatHtmlFragment | undefined;
+/** A chart / mermaid beat's background, as the branding layer of the figure slide deck draws it on. */
+export declare const backgroundDecoration: (image: {
+    backgroundImage?: BackgroundImage;
+}, options: BeatHtmlOptions) => {
+    branding?: ResolvedBranding;
+};
+/** A slide beat's branding, resolved as `convertBrandingToResolved` does on the Node side. */
+export declare const slideBranding: (beatBranding: SlideBranding | null | undefined, options: BeatHtmlOptions) => ResolvedBranding | undefined;

package/lib/utils/beat_html/decoration.js

@@ -0,0 +1,55 @@
+import { backgroundImageCss, backgroundImageLayout, resolveBackgroundImage } from "../image_plugins/bg_image_css.js";
+import { pickBranding } from "../image_plugins/slide_branding.js";
+import { mediaSrc } from "../image_plugins/media_html.js";
+import { neutralizeStyleTerminator } from "../html_escape.js";
+/**
+ * The decorations the PNG render adds around a beat's content — a background image, a slide's
+ * branding — resolved for the browser. The PNG path turns each image into a `data:` URI on disk;
+ * here the host says how its page reaches the file (`resolveMediaUrl`).
+ */
+// deck writes these urls into `style="…url('…')"` and `src="…"` unescaped, and a url from a script can carry a quote
+// (`z.url()` accepts one). Percent-encoding leaves a url that still loads and cannot leave either context.
+const UNSAFE_URL_CHARACTERS = /["'()\\<>\s]/g;
+export const safeMediaUrl = (url) => url.replace(UNSAFE_URL_CHARACTERS, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`);
+const mediaUrl = (source, options) => {
+    const url = (options.resolveMediaUrl ?? mediaSrc)(source);
+    return url === undefined ? undefined : safeMediaUrl(url);
+};
+const paintedBackground = (beatBackgroundImage, options) => {
+    const backgroundImage = resolveBackgroundImage(beatBackgroundImage, options.backgroundImage);
+    if (!backgroundImage)
+        return undefined;
+    const url = typeof backgroundImage === "string" ? safeMediaUrl(backgroundImage) : mediaUrl(backgroundImage.source, options);
+    return url === undefined ? undefined : { url, ...backgroundImageLayout(backgroundImage) };
+};
+/** A textSlide / markdown fragment with `documentCss` for the background the PNG paints on `body`. */
+export const withDocumentBackground = (fragment, image, options) => {
+    const background = paintedBackground(image.backgroundImage, options);
+    if (!fragment || !background)
+        return fragment;
+    return { ...fragment, documentCss: neutralizeStyleTerminator(backgroundImageCss(background.url, background.size, background.opacity)) };
+};
+/** A chart / mermaid beat's background, as the branding layer of the figure slide deck draws it on. */
+export const backgroundDecoration = (image, options) => {
+    const background = paintedBackground(image.backgroundImage, options);
+    return background ? { branding: { backgroundImage: { dataUrl: background.url, size: background.size, opacity: background.opacity } } } : {};
+};
+const resolvedLogo = (logo, options) => {
+    const dataUrl = mediaUrl(logo.source, options);
+    return dataUrl === undefined ? undefined : { dataUrl, position: logo.position, width: logo.width };
+};
+const resolvedBrandingBackground = (backgroundImage, options) => {
+    const dataUrl = mediaUrl(backgroundImage.source, options);
+    if (dataUrl === undefined)
+        return undefined;
+    return { dataUrl, size: backgroundImage.size ?? "cover", opacity: backgroundImage.opacity ?? 1, bgOpacity: backgroundImage.bgOpacity };
+};
+/** A slide beat's branding, resolved as `convertBrandingToResolved` does on the Node side. */
+export const slideBranding = (beatBranding, options) => {
+    const branding = pickBranding(beatBranding, options.branding);
+    if (!branding)
+        return undefined;
+    const logo = branding.logo && resolvedLogo(branding.logo, options);
+    const backgroundImage = branding.backgroundImage && resolvedBrandingBackground(branding.backgroundImage, options);
+    return { ...(logo ? { logo } : {}), ...(backgroundImage ? { backgroundImage } : {}) };
+};

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

@@ -4,12 +4,12 @@ import type { BeatHtmlFragment } from "./type.js";
 /**
  * An html_tailwind beat as markup a host can inject.
  *
- * The beat at rest — the same thing the Node dump path shows. This module generates no
- * `<script>`: the author's `script` FIELD, the swipe animation driver and the frame-based
- * `animation` all need script execution, which a fragment injected through `innerHTML`
- * cannot do and which the dump path has never emitted either. A `<script>` the author wrote
- * inside `html` is markup, and passes through unsanitized — see below. A beat whose only content is an animation therefore shows
- * its elements in their starting positions rather than nothing.
+ * `html` is the beat at rest — the same thing the Node dump path shows, with no generated
+ * `<script>`: a fragment injected through `innerHTML` cannot run one. The author's `script`
+ * FIELD, the swipe driver and the frame-based `animation` come back separately as
+ * `documentScript`, for a host that gives the beat a document of its own and can run them; it
+ * brings the beat to what the PNG shows (an animation's final frame). A `<script>` the author
+ * wrote inside `html` is markup, and passes through unsanitized — see below.
  *
  * The author's html is emitted as written. On this beat type markup IS the content — the
  * schema also accepts `script` — so escaping it would remove the feature rather than a

package/lib/utils/beat_html/html_tailwind.js

@@ -1,13 +1,14 @@
 import { htmlTailwindMarkup } from "../image_plugins/html_tailwind_markup.js";
+import { htmlTailwindDocumentCss, htmlTailwindDocumentScript } from "../image_plugins/html_tailwind_script.js";
 /**
  * An html_tailwind beat as markup a host can inject.
  *
- * The beat at rest — the same thing the Node dump path shows. This module generates no
- * `<script>`: the author's `script` FIELD, the swipe animation driver and the frame-based
- * `animation` all need script execution, which a fragment injected through `innerHTML`
- * cannot do and which the dump path has never emitted either. A `<script>` the author wrote
- * inside `html` is markup, and passes through unsanitized — see below. A beat whose only content is an animation therefore shows
- * its elements in their starting positions rather than nothing.
+ * `html` is the beat at rest — the same thing the Node dump path shows, with no generated
+ * `<script>`: a fragment injected through `innerHTML` cannot run one. The author's `script`
+ * FIELD, the swipe driver and the frame-based `animation` come back separately as
+ * `documentScript`, for a host that gives the beat a document of its own and can run them; it
+ * brings the beat to what the PNG shows (an animation's final frame). A `<script>` the author
+ * wrote inside `html` is markup, and passes through unsanitized — see below.
  *
  * The author's html is emitted as written. On this beat type markup IS the content — the
  * schema also accepts `script` — so escaping it would remove the feature rather than a
@@ -16,5 +17,10 @@ import { htmlTailwindMarkup } from "../image_plugins/html_tailwind_markup.js";
  */
 export const htmlTailwindToHtml = (image) => {
     const html = htmlTailwindMarkup(image);
-    return html === "" ? undefined : { html };
+    const documentScript = htmlTailwindDocumentScript(image);
+    const documentCss = htmlTailwindDocumentCss(image);
+    // A script-only beat draws itself, so it is a fragment with empty markup rather than nothing.
+    if (!documentScript && html === "")
+        return undefined;
+    return { html, ...(documentCss ? { documentCss } : {}), ...(documentScript ? { documentScript } : {}) };
 };

package/lib/utils/beat_html/index.js

@@ -6,6 +6,7 @@ import { imageToHtml, movieToHtml } from "./media.js";
 import { mermaidToHtml } from "./mermaid.js";
 import { slideToHtml } from "./slide.js";
 import { assertSafeElementId } from "../element_id.js";
+import { withDocumentBackground } from "./decoration.js";
 export { textSlideToMarkdown, textSlideToHtml } from "./text_slide.js";
 export { markdownToHtml } from "./markdown.js";
 /**
@@ -42,9 +43,9 @@ export const beatToHtml = (beat, options) => {
     assertSafeElementId(options.idPrefix);
     switch (image.type) {
         case "textSlide":
-            return textSlideToHtml(image);
+            return withDocumentBackground(textSlideToHtml(image), image, options);
         case "markdown":
-            return markdownToHtml(image, options.idPrefix);
+            return withDocumentBackground(markdownToHtml(image, options.idPrefix), image, options);
         case "chart":
             return chartToHtml(image, options);
         case "mermaid":

package/lib/utils/beat_html/mermaid.js

@@ -1,4 +1,5 @@
 import { deckSlideToHtml } from "./slide.js";
+import { backgroundDecoration } from "./decoration.js";
 /**
  * A mermaid beat as a deck `figure` slide — see `chart.ts` for why deck draws it.
  *
@@ -12,5 +13,5 @@ export const mermaidToHtml = (image, options) => {
         return undefined;
     const appendix = image.appendix?.join("\n") ?? "";
     const code = `${image.code.text}\n${appendix}`.trim();
-    return deckSlideToHtml({ layout: "figure", title: image.title || "Diagram", figure: { type: "mermaid", code } }, undefined, options);
+    return deckSlideToHtml({ layout: "figure", title: image.title || "Diagram", figure: { type: "mermaid", code } }, undefined, options, backgroundDecoration(image, options));
 };

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

@@ -1,4 +1,4 @@
-import type { MulmoSlideMedia, SlideLayout, SlideTheme } from "@mulmocast/deck";
+import type { MulmoSlideMedia, ResolvedBranding, SlideLayout, SlideTheme } from "@mulmocast/deck";
 import type { BeatHtmlFragment, BeatHtmlOptions } from "./type.js";
 /**
  * A deck slide as markup a host can inject. Shared by the beat types deck draws: `slide`,
@@ -19,5 +19,10 @@ import type { BeatHtmlFragment, BeatHtmlOptions } from "./type.js";
  * it on the root of `html`, verified in a browser: injecting `html` and attaching `css`, with
  * no wrapper class of the host's own, resolves `--d-bg` to the beat's theme.
  */
-export declare const deckSlideToHtml: (slide: SlideLayout, beatTheme: SlideTheme | undefined, options: BeatHtmlOptions) => BeatHtmlFragment;
+/** What the PNG render draws around a slide's layout: the branding layers and the reference line. */
+export type SlideDecoration = {
+    branding?: ResolvedBranding;
+    reference?: string;
+};
+export declare const deckSlideToHtml: (slide: SlideLayout, beatTheme: SlideTheme | undefined, options: BeatHtmlOptions, decoration?: SlideDecoration) => BeatHtmlFragment;
 export declare const slideToHtml: (image: MulmoSlideMedia, options: BeatHtmlOptions) => BeatHtmlFragment;

package/lib/utils/beat_html/slide.js

@@ -2,28 +2,10 @@
 // and 602kb against 20 and 54kb for this module — and this file is bundled for the browser.
 import { generateSlideFragment } from "@mulmocast/deck/lib/fragment.js";
 import { slideThemes } from "../../data/slideThemes.js";
-/**
- * A deck slide as markup a host can inject. Shared by the beat types deck draws: `slide`,
- * and `chart` / `mermaid` as a one-block `figure` slide.
- *
- * `generateSlideFragment` is the body-only counterpart of the `generateSlideHTML` the Node
- * render path uses, so the two draw the same slide from the same layouts — the fragment is
- * not a second renderer.
- *
- * The theme order matches `MulmoPresentationStyleMethods.getResolvedSlideTheme` on the Node
- * side: the beat's own theme, then the deck's, then the built-in corporate one. Repeating
- * the order here rather than calling that method keeps this file off `MulmoPresentationStyle`,
- * which the browser bundle does not need.
- *
- * The scope class is derived from `idPrefix` so a re-render of the same beat keeps it: the
- * css is written against that class, and deck derives chart / mermaid ids from it, so a
- * generated one would change every render. It is not returned separately — deck already puts
- * it on the root of `html`, verified in a browser: injecting `html` and attaching `css`, with
- * no wrapper class of the host's own, resolves `--d-bg` to the beat's theme.
- */
-export const deckSlideToHtml = (slide, beatTheme, options) => {
+import { slideBranding } from "./decoration.js";
+export const deckSlideToHtml = (slide, beatTheme, options, decoration = {}) => {
     const theme = beatTheme ?? options.slideTheme ?? slideThemes.corporate;
-    const fragment = generateSlideFragment(theme, slide, { scopeClass: `${options.idPrefix}-slide` });
+    const fragment = generateSlideFragment(theme, slide, { scopeClass: `${options.idPrefix}-slide`, ...decoration });
     return {
         html: fragment.html,
         css: fragment.css,
@@ -32,4 +14,7 @@ export const deckSlideToHtml = (slide, beatTheme, options) => {
         ...(fragment.mermaidTheme ? { mermaidTheme: fragment.mermaidTheme } : {}),
     };
 };
-export const slideToHtml = (image, options) => deckSlideToHtml(image.slide, image.theme, options);
+export const slideToHtml = (image, options) => {
+    const branding = slideBranding(image.branding, options);
+    return deckSlideToHtml(image.slide, image.theme, options, { ...(branding ? { branding } : {}), ...(image.reference ? { reference: image.reference } : {}) });
+};

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

@@ -1,4 +1,5 @@
-import type { SlideTheme } from "@mulmocast/deck";
+import type { SlideBranding, SlideTheme } from "@mulmocast/deck";
+import type { BackgroundImage, MulmoMediaSource } from "../../types/index.js";
 /**
  * A beat rendered as markup for a browser host.
  *
@@ -30,6 +31,27 @@ export type BeatHtmlFragment = {
      * and a host that does not gets an empty box, silently.
      */
     css?: string;
+    /**
+     * Rules for the whole document, as the PNG render applies them: a textSlide / markdown beat's
+     * background image on `html` / `body`, or an animated html_tailwind beat's rules pausing CSS
+     * animations and transitions. Absent when the beat needs neither.
+     *
+     * Apply it only where the beat owns the document (an iframe, a print page). Injected into a
+     * page shared with anything else it restyles that page: it cannot be scoped to the markup,
+     * because a text beat's markup has no root of its own and the PNG paints the background on
+     * `body`, behind the body's margin as well.
+     */
+    documentCss?: string;
+    /**
+     * `<script>` elements for the end of the beat's own document: an `html_tailwind` beat's author
+     * `script`, swipe driver and animation runtime, which bring it to what the PNG shows — for an
+     * animation, the final frame. Absent when the beat runs none.
+     *
+     * Only for a host that gives the beat a document of its own and lets it run scripts (an iframe
+     * with `allow-scripts`); `html` alone is the beat at rest. Not sanitized: the author script is
+     * the beat's content, as on the PNG path.
+     */
+    documentScript?: string;
     /** External runtimes the host must load once for the page, not once per beat. */
     requires?: BeatRuntime[];
     /**
@@ -78,4 +100,24 @@ export type BeatHtmlOptions = {
      * theme to give.
      */
     slideTheme?: SlideTheme;
+    /**
+     * The deck's `imageParams.backgroundImage`. A beat's own `backgroundImage` wins over it and a
+     * beat-level `null` switches it off — the order `resolveBackgroundImage` uses on the Node side.
+     * textSlide and markdown beats get it as `documentCss`; chart and mermaid beats, which deck
+     * draws as a figure slide, as that slide's background layer.
+     */
+    backgroundImage?: BackgroundImage;
+    /**
+     * The deck's `slideParams.branding` (logo and background) for slide beats. A beat's own
+     * `branding` wins over it and a beat-level `null` switches it off, as on the Node side.
+     */
+    branding?: SlideBranding;
+    /**
+     * Turns a background or branding image into a URL the host's page can load. The default uses
+     * a url as written and a path as written, and skips a base64 source — the schema carries no
+     * media type to build a `data:` URI from. A host whose scripts sit next to local files
+     * resolves paths here. What it returns is percent-encoded where it would otherwise break out
+     * of a CSS string or an HTML attribute.
+     */
+    resolveMediaUrl?: (source: MulmoMediaSource) => string | undefined;
 };

package/lib/utils/html_render.js

@@ -7,8 +7,8 @@ import puppeteer from "puppeteer";
 import { guardRenderPage } from "./render_network_guard.js";
 import { strictNetworkLaunchArgs, withRenderContentSecurityPolicy } from "./render_network_policy.js";
 import { GraphAILogger } from "graphai";
+import { VIDEO_LOAD_TIMEOUT_MS } from "./image_plugins/html_tailwind_script.js";
 const isCI = process.env.CI === "true";
-const VIDEO_LOAD_TIMEOUT_MS = 15000;
 const VIDEO_SEEK_TIMEOUT_MS = 3000;
 /** Wait for all <video> elements on the page to be ready for playback */
 const waitForVideosReady = async (page) => {

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

@@ -0,0 +1,19 @@
+import type { BackgroundImage } from "../../types/index.js";
+/**
+ * Background-image rules, without fetching or reading anything. Pure — no Node, no filesystem —
+ * because the PNG render and the browser fragment path paint the same background and must
+ * resolve and write it the same way.
+ */
+/**
+ * Resolve background image from beat level and global level settings.
+ * Beat level takes precedence over global level.
+ * null explicitly disables background image.
+ */
+export declare const resolveBackgroundImage: (beatBackgroundImage: BackgroundImage | undefined, globalBackgroundImage: BackgroundImage | undefined) => BackgroundImage | undefined;
+/** How a resolved background is laid out: a plain url string is always `cover` at full opacity. */
+export declare const backgroundImageLayout: (backgroundImage: NonNullable<BackgroundImage>) => {
+    size: string;
+    opacity: number;
+};
+/** Rules painting `imageUrl` behind the whole document (`html` / `body`), as the PNG render does. */
+export declare const backgroundImageCss: (imageUrl: string, size: string, opacity: number) => string;

package/lib/utils/image_plugins/bg_image_css.js

@@ -0,0 +1,75 @@
+import { escapeCssString } from "../html_escape.js";
+/**
+ * Background-image rules, without fetching or reading anything. Pure — no Node, no filesystem —
+ * because the PNG render and the browser fragment path paint the same background and must
+ * resolve and write it the same way.
+ */
+/**
+ * Resolve background image from beat level and global level settings.
+ * Beat level takes precedence over global level.
+ * null explicitly disables background image.
+ */
+export const resolveBackgroundImage = (beatBackgroundImage, globalBackgroundImage) => {
+    // null means explicitly disabled
+    if (beatBackgroundImage === null) {
+        return undefined;
+    }
+    // Beat level takes precedence
+    if (beatBackgroundImage !== undefined) {
+        return beatBackgroundImage;
+    }
+    // Fall back to global
+    if (globalBackgroundImage === null) {
+        return undefined;
+    }
+    return globalBackgroundImage;
+};
+/** How a resolved background is laid out: a plain url string is always `cover` at full opacity. */
+export const backgroundImageLayout = (backgroundImage) => {
+    if (typeof backgroundImage === "string")
+        return { size: "cover", opacity: 1 };
+    return { size: backgroundImage.size ?? "cover", opacity: backgroundImage.opacity ?? 1 };
+};
+// Convert size option to CSS background-size value
+const sizeToCSS = (size) => {
+    return size === "fill" ? "100% 100%" : size;
+};
+/** Rules painting `imageUrl` behind the whole document (`html` / `body`), as the PNG render does. */
+export const backgroundImageCss = (imageUrl, size, opacity) => {
+    const cssSize = sizeToCSS(size);
+    // Use pseudo-element for opacity to not affect content
+    if (opacity < 1) {
+        return `
+      html, body {
+        height: 100%;
+        margin: 0;
+      }
+      body::before {
+        content: '';
+        position: fixed;
+        top: 0;
+        left: 0;
+        right: 0;
+        bottom: 0;
+        background-image: url('${escapeCssString(imageUrl)}');
+        background-size: ${cssSize};
+        background-position: center;
+        background-repeat: no-repeat;
+        opacity: ${opacity};
+        z-index: -1;
+      }
+    `;
+    }
+    return `
+    html, body {
+      height: 100%;
+      margin: 0;
+    }
+    body {
+      background-image: url('${escapeCssString(imageUrl)}');
+      background-size: ${cssSize};
+      background-position: center;
+      background-repeat: no-repeat;
+    }
+  `;
+};

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

@@ -1,10 +1,4 @@
 import { BackgroundImage, MulmoStudioContext, ImageProcessorParams } from "../../types/index.js";
-/**
- * Resolve background image from beat level and global level settings.
- * Beat level takes precedence over global level.
- * null explicitly disables background image.
- */
-export declare const resolveBackgroundImage: (beatBackgroundImage: BackgroundImage | undefined, globalBackgroundImage: BackgroundImage | undefined) => BackgroundImage | undefined;
 /** The background image comes from the script, the style from the beat; the paths and sizes `process()` needs are not read here. */
 type CombinedStyleParams = Pick<ImageProcessorParams, "context" | "textSlideStyle">;
 /**

package/lib/utils/image_plugins/bg_image_util.js

@@ -1,27 +1,8 @@
 import { MulmoMediaSourceMethods } from "../../methods/mulmo_media_source.js";
 import { resolveStyle } from "./utils.js";
 import { safeFetch, DEFAULT_FETCH_TIMEOUT_MS } from "../fetch.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.
- * null explicitly disables background image.
- */
-export const resolveBackgroundImage = (beatBackgroundImage, globalBackgroundImage) => {
-    // null means explicitly disabled
-    if (beatBackgroundImage === null) {
-        return undefined;
-    }
-    // Beat level takes precedence
-    if (beatBackgroundImage !== undefined) {
-        return beatBackgroundImage;
-    }
-    // Fall back to global
-    if (globalBackgroundImage === null) {
-        return undefined;
-    }
-    return globalBackgroundImage;
-};
+import { neutralizeStyleTerminator } from "../html_escape.js";
+import { backgroundImageCss, backgroundImageLayout, resolveBackgroundImage } from "./bg_image_css.js";
 /**
  * Fetch URL and convert to data URL with timeout
  */
@@ -34,13 +15,6 @@ const fetchUrlAsDataUrl = async (url, timeoutMs = DEFAULT_FETCH_TIMEOUT_MS) => {
     const contentType = response.headers.get("content-type") || "image/png";
     return `data:${contentType};base64,${buffer.toString("base64")}`;
 };
-/**
- * Convert BackgroundImage to CSS string
- */
-// Convert size option to CSS background-size value
-const sizeToCSS = (size) => {
-    return size === "fill" ? "100% 100%" : size;
-};
 /**
  * Resolve combined style from background image and custom style.
  * Common pattern used by markdown, textSlide, mermaid plugins.
@@ -57,45 +31,9 @@ export const backgroundImageToCSS = async (backgroundImage, context) => {
     if (!backgroundImage) {
         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);
-    // Use pseudo-element for opacity to not affect content
-    if (opacity < 1) {
-        return `
-      html, body {
-        height: 100%;
-        margin: 0;
-      }
-      body::before {
-        content: '';
-        position: fixed;
-        top: 0;
-        left: 0;
-        right: 0;
-        bottom: 0;
-        background-image: url('${escapeCssString(imageUrl)}');
-        background-size: ${size};
-        background-position: center;
-        background-repeat: no-repeat;
-        opacity: ${opacity};
-        z-index: -1;
-      }
-    `;
-    }
-    return `
-    html, body {
-      height: 100%;
-      margin: 0;
-    }
-    body {
-      background-image: url('${escapeCssString(imageUrl)}');
-      background-size: ${size};
-      background-position: center;
-      background-repeat: no-repeat;
-    }
-  `;
+    // Escaped where it is written (backgroundImageCss) 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 = typeof backgroundImage === "string" ? await fetchUrlAsDataUrl(backgroundImage) : await MulmoMediaSourceMethods.toDataUrl(backgroundImage.source, context);
+    const { size, opacity } = backgroundImageLayout(backgroundImage);
+    return backgroundImageCss(imageUrl, size, opacity);
 };