mulmocast 2.21.0 → 2.22.1

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;

package/lib/utils/image_plugins/html_tailwind_script.js

@@ -0,0 +1,111 @@
+import { isAnimationEnabled, isAnimationObject } from "../animation_config.js";
+import { isSwipeElements, swipeElementsToHtml, swipeElementsToScript } from "../swipe_to_html.js";
+import { animationRuntime } from "../../data/animationRuntime.js";
+/**
+ * The scripts an html_tailwind beat runs. Pure — no Node, no filesystem — because the PNG render
+ * and the browser fragment path run the same author script, swipe driver and animation runtime,
+ * and must assemble them the same way.
+ */
+const DEFAULT_ANIMATION_FPS = 30;
+/** How long the final frame waits for `<video>` elements to be playable, as the PNG render does. */
+export const VIDEO_LOAD_TIMEOUT_MS = 15000;
+/** `tailwind_animated.html`'s rules: CSS animations and transitions stay still, so frames come from `render` alone. */
+export const ANIMATED_DOCUMENT_CSS = `*, *::before, *::after {
+  animation-play-state: paused !important;
+  transition: none !important;
+}`;
+// How long scripts added to an already-loaded document wait for a module author script to define `render`.
+const LATE_RENDER_WAIT_MS = 5000;
+const LATE_RENDER_POLL_MS = 50;
+/** Large frame count to ensure all animations reach their end state when exact duration is unknown */
+export const FINAL_FRAME_TOTAL = 9000;
+/** Frames per second of an enabled `animation` config. */
+export const animationFps = (animation) => (isAnimationObject(animation) ? (animation.fps ?? DEFAULT_ANIMATION_FPS) : DEFAULT_ANIMATION_FPS);
+/** Join html field into a single string (handles both string and string[]) */
+const joinHtml = (html) => {
+    return Array.isArray(html) ? html.join("\n") : html;
+};
+// A `</script` anywhere in the code ends the element early, even inside a string; `<\/script` is the same JS.
+const neutralizeScriptTerminator = (code) => code.replace(/<\/script/gi, (terminator) => `<\\${terminator.slice(1)}`);
+export const buildUserScript = (script) => {
+    if (!script)
+        return "";
+    const code = neutralizeScriptTerminator(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 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 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 inlineScript = (code) => `<script>\n${neutralizeScriptTerminator(code)}\n</script>`;
+/**
+ * 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 const htmlTailwindDocumentScript = (image) => {
+    // The schema leaves `elements` unknown[]; the markup reads it through the same guard.
+    const elements = isSwipeElements(image.elements) ? image.elements : undefined;
+    const userScript = buildUserScript(resolveHtmlAndScript({ script: image.script, ...(elements ? { elements } : {}) }).script);
+    if (!isAnimationEnabled(image.animation))
+        return userScript || undefined;
+    const frameState = `window.__MULMO = { frame: 0, totalFrames: ${FINAL_FRAME_TOTAL}, fps: ${animationFps(image.animation)} };`;
+    // On `load` when the scripts are part of the document as it loads. Added to a loaded document, a module author
+    // script (one with imports above all) may run later, so wait for its `render`, bounded, before drawing. Either
+    // way the videos get to be playable first, as `waitForVideosReady` lets them before the PNG's final frame.
+    const finalFrame = [
+        "(function () {",
+        "  var whenVideosReady = function (done) {",
+        '    var pending = Array.prototype.slice.call(document.querySelectorAll("video")).filter(function (video) { return video.readyState < 3; });',
+        "    if (pending.length === 0) return done();",
+        "    var remaining = pending.length, finished = false;",
+        "    var finish = function () { if (!finished) { finished = true; done(); } };",
+        `    setTimeout(finish, ${VIDEO_LOAD_TIMEOUT_MS});`,
+        '    pending.forEach(function (video) { video.addEventListener("canplaythrough", function () { remaining -= 1; if (remaining <= 0) finish(); }, { once: true }); });',
+        "  };",
+        "  var drawFinal = function () { whenVideosReady(function () { Promise.resolve(window.renderFinal()).catch(console.error); }); };",
+        "  var whenRenderReady = function (startedAt) {",
+        `    if (typeof window.render === "function" || Date.now() - startedAt > ${LATE_RENDER_WAIT_MS}) drawFinal();`,
+        `    else setTimeout(function () { whenRenderReady(startedAt); }, ${LATE_RENDER_POLL_MS});`,
+        "  };",
+        '  if (document.readyState === "complete") whenRenderReady(Date.now());',
+        '  else window.addEventListener("load", drawFinal);',
+        "})();",
+    ].join("\n");
+    return [
+        inlineScript(`${animationRuntime.animation_runtime}\n${frameState}`),
+        userScript,
+        inlineScript(animationRuntime.data_attribute_registration),
+        inlineScript(animationRuntime.auto_render),
+        inlineScript(finalFrame),
+    ]
+        .filter(Boolean)
+        .join("\n");
+};
+/** `documentCss` for an html_tailwind beat: the animated template's pause rules, when it animates. */
+export const htmlTailwindDocumentCss = (image) => isAnimationEnabled(image.animation) ? ANIMATED_DOCUMENT_CSS : undefined;

package/lib/utils/image_plugins/slide.js

@@ -8,6 +8,7 @@ import { MulmoMediaSourceMethods } from "../../methods/mulmo_media_source.js";
 import { MulmoPresentationStyleMethods } from "../../methods/mulmo_presentation_style.js";
 import { imageAction, imageFileTarget, unknownMediaType } from "../error_cause.js";
 import { MulmoStudioContextMethods } from "../../methods/mulmo_studio_context.js";
+import { pickBranding } from "./slide_branding.js";
 export const imageType = "slide";
 const slideImageRefError = (refKey) => ({
     type: unknownMediaType,
@@ -124,11 +125,7 @@ const resolveBranding = (params) => {
     const { beat, context } = params;
     if (!beat.image || beat.image.type !== imageType)
         return undefined;
-    const beatBranding = beat.image.branding;
-    // null means explicitly disabled
-    if (beatBranding === null)
-        return undefined;
-    return beatBranding ?? context.presentationStyle.slideParams?.branding;
+    return pickBranding(beat.image.branding, context.presentationStyle.slideParams?.branding);
 };
 /**
  * Convert SlideBranding to ResolvedBranding (all sources → data URLs).

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

@@ -0,0 +1,7 @@
+import type { SlideBranding } from "@mulmocast/deck";
+/**
+ * Which branding a slide beat gets. Pure — the PNG render and the browser fragment path pick it
+ * the same way: the beat's own wins, a beat-level `null` switches the deck's off, and otherwise
+ * the deck's `slideParams.branding` applies.
+ */
+export declare const pickBranding: (beatBranding: SlideBranding | null | undefined, deckBranding: SlideBranding | undefined) => SlideBranding | undefined;

package/lib/utils/image_plugins/slide_branding.js

@@ -0,0 +1,10 @@
+/**
+ * Which branding a slide beat gets. Pure — the PNG render and the browser fragment path pick it
+ * the same way: the beat's own wins, a beat-level `null` switches the deck's off, and otherwise
+ * the deck's `slideParams.branding` applies.
+ */
+export const pickBranding = (beatBranding, deckBranding) => {
+    if (beatBranding === null)
+        return undefined;
+    return beatBranding ?? deckBranding;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mulmocast",
-  "version": "2.21.0",
+  "version": "2.22.1",
   "description": "",
   "type": "module",
   "main": "lib/index.node.js",