mulmocast 2.20.0 → 2.22.0

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

@@ -1,7 +1,8 @@
-import type { MulmoSlideMedia } from "@mulmocast/deck";
+import type { MulmoSlideMedia, ResolvedBranding, SlideLayout, SlideTheme } from "@mulmocast/deck";
 import type { BeatHtmlFragment, BeatHtmlOptions } from "./type.js";
 /**
- * A slide beat as markup a host can inject.
+ * 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
@@ -13,9 +14,15 @@ import type { BeatHtmlFragment, BeatHtmlOptions } from "./type.js";
  * 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 a generated one would change every render, leaving
- * the rules matching nothing. 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.
+ * 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.
  */
+/** 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,27 +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 slide beat as markup a host can inject.
- *
- * `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 a generated one would change every render, leaving
- * the rules matching nothing. 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 slideToHtml = (image, options) => {
-    const theme = image.theme ?? options.slideTheme ?? slideThemes.corporate;
-    const fragment = generateSlideFragment(theme, image.slide, { scopeClass: `${options.idPrefix}-slide` });
+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`, ...decoration });
     return {
         html: fragment.html,
         css: fragment.css,
@@ -31,3 +14,7 @@ export const slideToHtml = (image, options) => {
         ...(fragment.mermaidTheme ? { mermaidTheme: fragment.mermaidTheme } : {}),
     };
 };
+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[];
     /**
@@ -69,12 +91,33 @@ export type BeatHtmlOptions = {
      */
     idPrefix: string;
     /**
-     * The deck-level slide theme, for `slide` beats. A beat's own `image.theme` wins over it,
-     * and the built-in `corporate` theme is the fallback — the same order
+     * The deck-level slide theme, for the beats deck draws: `slide`, `chart` and `mermaid`.
+     * A slide beat's own `image.theme` wins over it, and the built-in `corporate` theme is the
+     * fallback — the same order
      * `MulmoPresentationStyleMethods.getResolvedSlideTheme` uses on the Node side.
      *
-     * Optional because only slide beats read it, and because the host may not have a deck
+     * Optional because only those beats read it, and because the host may not have a deck
      * 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/context.d.ts

@@ -2132,6 +2132,37 @@ export declare const createStudioData: (_mulmoScript: MulmoScript, fileName: str
                     subtitleSize?: "default" | "big" | "lead" | undefined;
                     intro?: "fade" | "fade-up" | "fade-down" | "slide-left" | "slide-right" | "zoom-in" | undefined;
                     staggerMs?: number | undefined;
+                } | {
+                    title: string;
+                    figure: {
+                        type: "chart";
+                        chartData: Record<string, unknown>;
+                        title?: string | undefined;
+                    } | {
+                        type: "mermaid";
+                        code: string;
+                        title?: string | undefined;
+                    };
+                    layout: "figure";
+                    stepLabel?: string | undefined;
+                    subtitle?: string | undefined;
+                    accentColor?: "success" | "info" | "primary" | "accent" | "warning" | "danger" | "highlight" | undefined;
+                    style?: {
+                        bgColor?: string | undefined;
+                        bgGradient?: string | undefined;
+                        decorations?: boolean | undefined;
+                        bgOpacity?: number | undefined;
+                        footer?: string | undefined;
+                    } | undefined;
+                    eyebrow?: {
+                        label: string;
+                        color?: "success" | "info" | "primary" | "accent" | "warning" | "danger" | "highlight" | undefined;
+                    } | undefined;
+                    density?: "default" | "compact" | undefined;
+                    titleSize?: "default" | "small" | "large" | "hero" | undefined;
+                    subtitleSize?: "default" | "big" | "lead" | undefined;
+                    intro?: "fade" | "fade-up" | "fade-down" | "slide-left" | "slide-right" | "zoom-in" | undefined;
+                    staggerMs?: number | undefined;
                 };
                 theme?: {
                     colors: {
@@ -4787,6 +4818,37 @@ export declare const initializeContextFromFiles: (files: FileObject, raiseError:
                         subtitleSize?: "default" | "big" | "lead" | undefined;
                         intro?: "fade" | "fade-up" | "fade-down" | "slide-left" | "slide-right" | "zoom-in" | undefined;
                         staggerMs?: number | undefined;
+                    } | {
+                        title: string;
+                        figure: {
+                            type: "chart";
+                            chartData: Record<string, unknown>;
+                            title?: string | undefined;
+                        } | {
+                            type: "mermaid";
+                            code: string;
+                            title?: string | undefined;
+                        };
+                        layout: "figure";
+                        stepLabel?: string | undefined;
+                        subtitle?: string | undefined;
+                        accentColor?: "success" | "info" | "primary" | "accent" | "warning" | "danger" | "highlight" | undefined;
+                        style?: {
+                            bgColor?: string | undefined;
+                            bgGradient?: string | undefined;
+                            decorations?: boolean | undefined;
+                            bgOpacity?: number | undefined;
+                            footer?: string | undefined;
+                        } | undefined;
+                        eyebrow?: {
+                            label: string;
+                            color?: "success" | "info" | "primary" | "accent" | "warning" | "danger" | "highlight" | undefined;
+                        } | undefined;
+                        density?: "default" | "compact" | undefined;
+                        titleSize?: "default" | "small" | "large" | "hero" | undefined;
+                        subtitleSize?: "default" | "big" | "lead" | undefined;
+                        intro?: "fade" | "fade-up" | "fade-down" | "slide-left" | "slide-right" | "zoom-in" | undefined;
+                        staggerMs?: number | undefined;
                     };
                     theme?: {
                         colors: {

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);
 };

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

@@ -4,16 +4,6 @@ export declare const resolveChartPlugins: (chartType: string) => string;
 export declare const stringifyChartData: (chartData: MulmoChartMedia["chartData"]) => string;
 /** For a standalone document, where the inline script runs. */
 export declare const chartHtml: (chartDataJson: string, title: string, chartId: string) => string;
-/**
- * For a host that injects the markup into its own page, where an injected `<script>`
- * neither survives sanitizing nor executes via innerHTML. The config rides on the canvas
- * instead, in the shape `@mulmocast/deck` already uses so one host runtime drives both.
- */
-export declare const chartFragmentHtml: (chartData: MulmoChartMedia["chartData"], title: string, chartId: string) => string;
-/** `chartData` is a free record, so the type may be absent or not a string. */
-export declare const chartTypeOf: (chartData: MulmoChartMedia["chartData"]) => string;
-/** The Chart.js plugin CDNs a chart type needs, for a host that loads them once per page. */
-export declare const chartPluginCdns: (chartType: string) => string[];
 /**
  * The two values the PNG/PDF/movie template interpolates from user data, escaped for the
  * contexts it drops them into: `<h1>${title}</h1>` and `const chartData = ${chart_data};`.

package/lib/utils/image_plugins/chart_html.js

@@ -1,17 +1,12 @@
 // Deep import: the package barrel pulls in every layout and all of zod, which measured
-// 551kb against 1.5kb for this file, and the browser fragment path bundles this module.
+// 551kb against 1.5kb for this file.
 import { escapeHtml } from "@mulmocast/deck/lib/utils.js";
 import { escapeJsonForScript } from "../html_escape.js";
 import { assertSafeElementId } from "../element_id.js";
 /**
- * Chart.js markup and plugin resolution. Pure — no Node, no filesystem — because both the
- * Node render path and the browser fragment path draw the same chart and must draw it the
- * same way.
- *
- * The canvas id is a parameter rather than generated here: the Node path renders once to a
- * PNG so a random id is fine, while the browser path re-renders and needs the same beat to
- * produce the same markup, or a host diffing fragments sees every chart change identity on
- * every render.
+ * Chart.js markup and plugin resolution for the Node render path. Pure — no Node, no
+ * filesystem — so it can be tested without either. The browser path draws charts through
+ * `@mulmocast/deck` instead (`beat_html/chart.ts`).
  */
 /**
  * Chart.js plugin CDN URLs keyed by chart type. A Map rather than an object literal: the
@@ -30,8 +25,7 @@ export const resolveChartPlugins = (chartType) => {
     return `<script src="${cdn}"></script>`;
 };
 export const stringifyChartData = (chartData) => JSON.stringify(chartData, null, 2);
-/** The card both paths draw: a heading and a fixed-height canvas. `trailing` is where the
- * document path puts its driver script; the fragment path leaves it empty. */
+/** A heading and a fixed-height canvas, followed by `trailing` — the driver script. */
 const chartCard = (title, canvas, trailing) => `
 <div class="chart-container mb-6">
   <h3 class="text-xl font-semibold mb-4">${escapeHtml(title || "Chart")}</h3>
@@ -51,26 +45,6 @@ export const chartHtml = (chartDataJson, title, chartId) => {
   </script>`;
     return chartCard(title, `<canvas id="${chartId}"></canvas>`, script);
 };
-/**
- * For a host that injects the markup into its own page, where an injected `<script>`
- * neither survives sanitizing nor executes via innerHTML. The config rides on the canvas
- * instead, in the shape `@mulmocast/deck` already uses so one host runtime drives both.
- */
-export const chartFragmentHtml = (chartData, title, chartId) => {
-    assertSafeElementId(chartId);
-    const config = escapeHtml(JSON.stringify(chartData));
-    return chartCard(title, `<canvas id="${chartId}" data-chart-ready="false" data-mulmo-chart="${config}"></canvas>`, "");
-};
-/** `chartData` is a free record, so the type may be absent or not a string. */
-export const chartTypeOf = (chartData) => {
-    const type = chartData?.type;
-    return typeof type === "string" ? type : "";
-};
-/** The Chart.js plugin CDNs a chart type needs, for a host that loads them once per page. */
-export const chartPluginCdns = (chartType) => {
-    const cdn = CHART_PLUGIN_CDNS.get(chartType);
-    return cdn ? [cdn] : [];
-};
 /**
  * The two values the PNG/PDF/movie template interpolates from user data, escaped for the
  * contexts it drops them into: `<h1>${title}</h1>` and `const chartData = ${chart_data};`.

package/lib/utils/image_plugins/html_tailwind.js

@@ -5,8 +5,8 @@ import { getHTMLFile, getJSFile } from "../file.js";
 import { renderHTMLToImage, interpolate, renderHTMLToFrames, renderHTMLToVideo, renderHTMLToFinalFrame } from "../html_render.js";
 import { framesToVideo } from "../ffmpeg_utils.js";
 import { parrotingImagePath } from "./utils.js";
-import { swipeElementsToHtml, swipeElementsToScript } from "../swipe_to_html.js";
 import { htmlTailwindMarkup } from "./html_tailwind_markup.js";
+import { FINAL_FRAME_TOTAL, animationFps, buildUserScript, resolveHtmlAndScript } from "./html_tailwind_script.js";
 import { MulmoStudioContextMethods } from "../../methods/mulmo_studio_context.js";
 export const imageType = "html_tailwind";
 /**
@@ -53,22 +53,6 @@ export const resolveRelativeImagePaths = (html, baseDirPath) => {
         return `${prefix}${quote}file://${absolutePath}${quote}`;
     });
 };
-const DEFAULT_ANIMATION_FPS = 30;
-/** Join html field into a single string (handles both string and string[]) */
-const joinHtml = (html) => {
-    return Array.isArray(html) ? html.join("\n") : html;
-};
-const buildUserScript = (script) => {
-    if (!script)
-        return "";
-    const code = Array.isArray(script) ? script.join("\n") : script;
-    // If user script contains ESM import/export, emit module script so imports work.
-    const isModule = code.split("\n").some((line) => {
-        const trimmed = line.trimStart();
-        return trimmed.startsWith("import ") || trimmed.startsWith("export ");
-    });
-    return isModule ? `<script type="module">\n${code}\n</script>` : `<script>\n${code}\n</script>`;
-};
 /**
  * Resolve relative modelUrl assignment in user scripts to file:// absolute paths.
  * e.g. const modelUrl = "models/a.glb" -> const modelUrl = "file:///abs/models/a.glb"
@@ -105,25 +89,6 @@ export const resolveRelativeModelPathsInScript = (html, baseDirPath) => {
     })
         .join("\n");
 };
-/**
- * Resolve HTML and script from beat image data.
- * If `elements` (Swipe-style) is provided, convert to HTML + script.
- * Otherwise, use raw `html` and `script` fields.
- */
-const resolveHtmlAndScript = (imageData) => {
-    if (imageData.elements && Array.isArray(imageData.elements) && imageData.elements.length > 0) {
-        const html = swipeElementsToHtml(imageData.elements);
-        const generatedScript = swipeElementsToScript(imageData.elements);
-        // Merge with user-provided script if any
-        const userScript = imageData.script ? joinHtml(imageData.script) : "";
-        const combinedScript = [generatedScript, userScript].filter(Boolean).join("\n");
-        return { html, script: combinedScript || undefined };
-    }
-    return {
-        html: joinHtml(imageData.html ?? ""),
-        script: imageData.script,
-    };
-};
 const getAnimationConfig = (params) => {
     const { beat } = params;
     if (!beat.image || beat.image.type !== imageType)
@@ -131,12 +96,10 @@ const getAnimationConfig = (params) => {
     const animation = beat.image.animation;
     if (!MulmoBeatMethods.isAnimationEnabled(animation))
         return null;
-    const fps = MulmoBeatMethods.isAnimationObject(animation) ? (animation.fps ?? DEFAULT_ANIMATION_FPS) : DEFAULT_ANIMATION_FPS;
+    const fps = animationFps(animation);
     const movie = MulmoBeatMethods.isMovieMode(animation);
     return { fps, movie };
 };
-/** Large frame count to ensure all animations reach their end state when exact duration is unknown */
-const FINAL_FRAME_TOTAL = 9000;
 /**
  * Build the animated HTML string from beat data and template.
  */

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

@@ -0,0 +1,41 @@
+import { type SwipeElement } from "../swipe_to_html.js";
+/** How long the final frame waits for `<video>` elements to be playable, as the PNG render does. */
+export declare const VIDEO_LOAD_TIMEOUT_MS = 15000;
+/** `tailwind_animated.html`'s rules: CSS animations and transitions stay still, so frames come from `render` alone. */
+export declare const ANIMATED_DOCUMENT_CSS = "*, *::before, *::after {\n  animation-play-state: paused !important;\n  transition: none !important;\n}";
+/** Large frame count to ensure all animations reach their end state when exact duration is unknown */
+export declare const FINAL_FRAME_TOTAL = 9000;
+/** Frames per second of an enabled `animation` config. */
+export declare const animationFps: (animation: unknown) => number;
+export declare const buildUserScript: (script: string | string[] | undefined) => string;
+/**
+ * Resolve HTML and script from beat image data.
+ * If `elements` (Swipe-style) is provided, convert to HTML + script.
+ * Otherwise, use raw `html` and `script` fields.
+ */
+export declare const resolveHtmlAndScript: (imageData: {
+    html?: string | string[];
+    script?: string | string[];
+    elements?: SwipeElement[];
+}) => {
+    html: string;
+    script: string | string[] | undefined;
+};
+export type HtmlTailwindScriptSource = {
+    script?: string | string[];
+    elements?: unknown;
+    animation?: unknown;
+};
+/**
+ * The scripts that bring an html_tailwind beat to the state its PNG shows, as `<script>` elements
+ * for the end of the beat's own document; undefined when it runs none.
+ *
+ * Without `animation` that is the author script and swipe driver, as `tailwind.html` runs them.
+ * With it, the runtime, frame state and registration `tailwind_animated.html` loads, then the
+ * final frame — what `renderHTMLToFinalFrame` captures. The final frame is drawn on `load`, after
+ * a module author script (deferred) has defined its `render`, as Puppeteer calls it after load;
+ * scripts a host adds to an already-loaded document draw it once `render` exists (bounded wait).
+ */
+export declare const htmlTailwindDocumentScript: (image: HtmlTailwindScriptSource) => string | undefined;
+/** `documentCss` for an html_tailwind beat: the animated template's pause rules, when it animates. */
+export declare const htmlTailwindDocumentCss: (image: HtmlTailwindScriptSource) => string | undefined;