mulmocast 2.9.1 → 2.10.0

package/lib/index.browser.d.ts

@@ -1,3 +1,10 @@
 export * from "./index.common.js";
+/**
+ * Beat markup for a browser host. Exported from the browser entry point rather than the
+ * common one because `test_browser_safety.ts` guards this module's import graph — a Node
+ * import creeping in fails there, not at a user's build.
+ */
+export { beatToHtml, supportedBeatTypes } from "./utils/beat_html/index.js";
+export type { BeatHtmlFragment, BeatHtmlOptions, BeatRuntime } from "./utils/beat_html/type.js";
 import validateSchemaAgent from "./agents/validate_schema_agent.js";
 export { validateSchemaAgent };

package/lib/index.browser.js

@@ -1,4 +1,10 @@
 // Entry point for browser code
 export * from "./index.common.js";
+/**
+ * Beat markup for a browser host. Exported from the browser entry point rather than the
+ * common one because `test_browser_safety.ts` guards this module's import graph — a Node
+ * import creeping in fails there, not at a user's build.
+ */
+export { beatToHtml, supportedBeatTypes } from "./utils/beat_html/index.js";
 import validateSchemaAgent from "./agents/validate_schema_agent.js";
 export { validateSchemaAgent };

package/lib/types/const.d.ts

@@ -13,3 +13,10 @@ export declare const storyToScriptGenerateMode: {
 export declare const bundleTargetLang: string[];
 export declare const ASPECT_RATIOS: string[];
 export declare const PRO_ASPECT_RATIOS: string[];
+/**
+ * Element ids that generated markup interpolates. Restricting the set — rather than escaping
+ * per context — is what makes one id safe in an HTML attribute, a JavaScript string literal
+ * inside a `<script>`, and a CSS selector at once. Lives here because `schema.ts` compiles
+ * standalone in the types package and can only reach files under `src/types/`.
+ */
+export declare const SAFE_ELEMENT_ID: RegExp;

package/lib/types/const.js

@@ -13,3 +13,10 @@ export const storyToScriptGenerateMode = {
 export const bundleTargetLang = ["ja", "en"];
 export const ASPECT_RATIOS = ["1:1", "9:16", "16:9"];
 export const PRO_ASPECT_RATIOS = ["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9"];
+/**
+ * Element ids that generated markup interpolates. Restricting the set — rather than escaping
+ * per context — is what makes one id safe in an HTML attribute, a JavaScript string literal
+ * inside a `<script>`, and a CSS selector at once. Lives here because `schema.ts` compiles
+ * standalone in the types package and can only reach files under `src/types/`.
+ */
+export const SAFE_ELEMENT_ID = /^[A-Za-z_][A-Za-z0-9_-]*$/;

package/lib/types/schema.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { htmlLLMProvider, provider2TTSAgent, provider2ImageAgent, provider2MovieAgent, defaultProviders, provider2SoundEffectAgent } from "./provider2agent.js";
-import { currentMulmoScriptVersion } from "./const.js";
+import { currentMulmoScriptVersion, SAFE_ELEMENT_ID } from "./const.js";
 import { mulmoVideoFilterSchema } from "./schema_video_filter.js";
 import { mulmoSlideMediaSchema, slideThemeSchema, slideBrandingSchema } from "@mulmocast/deck";
 // Re-export video filter schema
@@ -248,7 +248,11 @@ const swipeShadowSchema = z
     .strict();
 export const swipeElementSchema = z.lazy(() => z
     .object({
-    id: z.string().optional(),
+    id: z
+        .string()
+        .regex(SAFE_ELEMENT_ID, "must start with a letter or underscore, then letters, digits, hyphens or underscores")
+        .optional()
+        .describe("Element id. Used as an HTML id and as a CSS selector in the generated animation script, so it must match [A-Za-z_][A-Za-z0-9_-]*."),
     // Position & size
     x: swipePositionValue.optional(),
     y: swipePositionValue.optional(),

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

@@ -0,0 +1,15 @@
+import type { MulmoChartMedia } from "../../types/index.js";
+import type { BeatHtmlFragment } from "./type.js";
+/**
+ * A chart beat as markup a host can inject.
+ *
+ * The config rides on the canvas as `data-mulmo-chart` rather than in an inline `<script>`:
+ * a script injected through `innerHTML` does not execute, and does not survive sanitizing
+ * either. The attribute shape matches `@mulmocast/deck`'s, so a host that already drives
+ * `[data-mulmo-chart]` for slides drives this too without a second code path.
+ *
+ * The markup itself comes from `image_plugins/chart_html.ts`, the same module the Node
+ * render path uses — a second copy of it would drift, and the two paths have to draw the
+ * same chart.
+ */
+export declare const chartToHtml: (image: MulmoChartMedia, idPrefix: string) => BeatHtmlFragment;

package/lib/utils/beat_html/chart.js

@@ -0,0 +1,21 @@
+import { chartFragmentHtml, chartPluginCdns, chartTypeOf } from "../image_plugins/chart_html.js";
+/**
+ * A chart beat as markup a host can inject.
+ *
+ * The config rides on the canvas as `data-mulmo-chart` rather than in an inline `<script>`:
+ * a script injected through `innerHTML` does not execute, and does not survive sanitizing
+ * either. The attribute shape matches `@mulmocast/deck`'s, so a host that already drives
+ * `[data-mulmo-chart]` for slides drives this too without a second code path.
+ *
+ * The markup itself comes from `image_plugins/chart_html.ts`, the same module the Node
+ * render path uses — a second copy of it would drift, and the two paths have to draw the
+ * same chart.
+ */
+export const chartToHtml = (image, idPrefix) => {
+    const plugins = chartPluginCdns(chartTypeOf(image.chartData));
+    return {
+        html: chartFragmentHtml(image.chartData, image.title, `${idPrefix}-chart`),
+        requires: ["chart"],
+        ...(plugins.length > 0 ? { chartPlugins: plugins } : {}),
+    };
+};

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

@@ -0,0 +1,19 @@
+import type { z } from "zod";
+import type { mulmoHtmlTailwindMediaSchema } from "../../types/schema.js";
+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.
+ *
+ * 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
+ * capability the author lacks. `BeatHtmlFragment.html` says the markup is not sanitized;
+ * this is the beat type where that matters most.
+ */
+export declare const htmlTailwindToHtml: (image: z.infer<typeof mulmoHtmlTailwindMediaSchema>) => BeatHtmlFragment | undefined;

package/lib/utils/beat_html/html_tailwind.js

@@ -0,0 +1,20 @@
+import { htmlTailwindMarkup } from "../image_plugins/html_tailwind_markup.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.
+ *
+ * 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
+ * capability the author lacks. `BeatHtmlFragment.html` says the markup is not sanitized;
+ * this is the beat type where that matters most.
+ */
+export const htmlTailwindToHtml = (image) => {
+    const html = htmlTailwindMarkup(image);
+    return html === "" ? undefined : { html };
+};

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

@@ -0,0 +1,33 @@
+import type { MulmoBeat } from "../../types/index.js";
+import type { BeatHtmlFragment, BeatHtmlOptions } from "./type.js";
+export type { BeatHtmlFragment, BeatHtmlOptions, BeatRuntime } from "./type.js";
+export { textSlideToMarkdown, textSlideToHtml } from "./text_slide.js";
+export { markdownToHtml } from "./markdown.js";
+/**
+ * Beat image types this module can turn into markup, extended one type at a time.
+ * `test_dispatch.ts` asserts this list and `beatToHtml` agree in both directions, so
+ * a type added here without a case — or vice versa — fails rather than silently
+ * rendering nothing.
+ */
+export declare const supportedBeatTypes: readonly ["textSlide", "markdown", "chart", "mermaid", "image", "movie", "slide", "html_tailwind"];
+/**
+ * Render a beat as markup for a browser host.
+ *
+ * **The markup is not sanitized** — see `BeatHtmlFragment.html`. Sanitize before inserting
+ * it into a DOM.
+ *
+ * `options.idPrefix` is required and must match `[A-Za-z_][A-Za-z0-9_-]*`: fragments generate
+ * element ids, only the caller knows which beat this is, and a beat's own `id` comes from
+ * the script and is unrestricted. Throws on anything else rather than guessing a repair,
+ * because a guess can collapse two beats onto one id. See `BeatHtmlOptions`.
+ *
+ * Returns `undefined` for a beat this module cannot render — a type not yet supported,
+ * or one whose media it cannot reach from a browser (a local file path, say). Callers
+ * decide what to show in its place; this module does not invent a placeholder.
+ *
+ * Everything here must stay browser-safe: no `node:*`, no filesystem, no
+ * `MulmoStudioContext`. `test_browser_safety.ts` walks the import graph and fails on
+ * anything that would drag Node into a bundle — the failure mode is a runtime error in
+ * the browser, not a compile error, so it has to be checked mechanically.
+ */
+export declare const beatToHtml: (beat: MulmoBeat, options: BeatHtmlOptions) => BeatHtmlFragment | undefined;

package/lib/utils/beat_html/index.js

@@ -0,0 +1,65 @@
+import { textSlideToHtml } from "./text_slide.js";
+import { chartToHtml } from "./chart.js";
+import { markdownToHtml } from "./markdown.js";
+import { htmlTailwindToHtml } from "./html_tailwind.js";
+import { imageToHtml, movieToHtml } from "./media.js";
+import { mermaidToHtml } from "./mermaid.js";
+import { slideToHtml } from "./slide.js";
+import { assertSafeElementId } from "../element_id.js";
+export { textSlideToMarkdown, textSlideToHtml } from "./text_slide.js";
+export { markdownToHtml } from "./markdown.js";
+/**
+ * Beat image types this module can turn into markup, extended one type at a time.
+ * `test_dispatch.ts` asserts this list and `beatToHtml` agree in both directions, so
+ * a type added here without a case — or vice versa — fails rather than silently
+ * rendering nothing.
+ */
+export const supportedBeatTypes = ["textSlide", "markdown", "chart", "mermaid", "image", "movie", "slide", "html_tailwind"];
+/**
+ * Render a beat as markup for a browser host.
+ *
+ * **The markup is not sanitized** — see `BeatHtmlFragment.html`. Sanitize before inserting
+ * it into a DOM.
+ *
+ * `options.idPrefix` is required and must match `[A-Za-z_][A-Za-z0-9_-]*`: fragments generate
+ * element ids, only the caller knows which beat this is, and a beat's own `id` comes from
+ * the script and is unrestricted. Throws on anything else rather than guessing a repair,
+ * because a guess can collapse two beats onto one id. See `BeatHtmlOptions`.
+ *
+ * Returns `undefined` for a beat this module cannot render — a type not yet supported,
+ * or one whose media it cannot reach from a browser (a local file path, say). Callers
+ * decide what to show in its place; this module does not invent a placeholder.
+ *
+ * Everything here must stay browser-safe: no `node:*`, no filesystem, no
+ * `MulmoStudioContext`. `test_browser_safety.ts` walks the import graph and fails on
+ * anything that would drag Node into a bundle — the failure mode is a runtime error in
+ * the browser, not a compile error, so it has to be checked mechanically.
+ */
+export const beatToHtml = (beat, options) => {
+    const image = beat.image;
+    if (!image)
+        return undefined;
+    assertSafeElementId(options.idPrefix);
+    switch (image.type) {
+        case "textSlide":
+            return textSlideToHtml(image);
+        case "markdown":
+            return markdownToHtml(image, options.idPrefix);
+        case "chart":
+            return chartToHtml(image, options.idPrefix);
+        case "mermaid":
+            return mermaidToHtml(image, options.idPrefix);
+        case "image":
+            // The only description of the picture this module can reach. A host with more should
+            // set its own alt; an <img> with none makes a screen reader read the file name.
+            return imageToHtml(image, beat.description ?? beat.text ?? "");
+        case "movie":
+            return movieToHtml(image);
+        case "slide":
+            return slideToHtml(image, options);
+        case "html_tailwind":
+            return htmlTailwindToHtml(image);
+        default:
+            return undefined;
+    }
+};

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

@@ -0,0 +1,20 @@
+import type { MulmoMarkdownMedia } from "../../types/index.js";
+import type { BeatHtmlFragment } from "./type.js";
+/**
+ * A `markdown` beat as markup for a browser host.
+ *
+ * The rendering itself is `image_plugins/markdown_layout.ts` — the same code the Node
+ * render path uses, not a second implementation of it. This file supplies the two things
+ * that are actually browser-specific: deterministic element ids, and the `requires`
+ * report the host needs.
+ *
+ * Either markdown shape can embed a mermaid fence, which is why this can come back
+ * requiring the mermaid runtime. A markdown beat is not obviously a diagram beat, and a
+ * host that only loads mermaid for `mermaid` beats would render the diagram as nothing.
+ * `requires` and the markup come from the same decision inside the renderer, so they
+ * cannot disagree about what is a diagram.
+ *
+ * `idPrefix` has no default on purpose: a page-wide default gives two markdown beats the
+ * same element ids, which is invalid HTML and sends mermaid at the wrong element.
+ */
+export declare const markdownToHtml: (image: MulmoMarkdownMedia, idPrefix: string) => BeatHtmlFragment;

package/lib/utils/beat_html/markdown.js

@@ -0,0 +1,25 @@
+import { renderMarkdownContent, renderMarkdownLayout, isMarkdownLayout } from "../image_plugins/markdown_layout.js";
+/**
+ * A `markdown` beat as markup for a browser host.
+ *
+ * The rendering itself is `image_plugins/markdown_layout.ts` — the same code the Node
+ * render path uses, not a second implementation of it. This file supplies the two things
+ * that are actually browser-specific: deterministic element ids, and the `requires`
+ * report the host needs.
+ *
+ * Either markdown shape can embed a mermaid fence, which is why this can come back
+ * requiring the mermaid runtime. A markdown beat is not obviously a diagram beat, and a
+ * host that only loads mermaid for `mermaid` beats would render the diagram as nothing.
+ * `requires` and the markup come from the same decision inside the renderer, so they
+ * cannot disagree about what is a diagram.
+ *
+ * `idPrefix` has no default on purpose: a page-wide default gives two markdown beats the
+ * same element ids, which is invalid HTML and sends mermaid at the wrong element.
+ */
+export const markdownToHtml = (image, idPrefix) => {
+    let counter = 0;
+    const nextId = () => `${idPrefix}-mermaid-${counter++}`;
+    const md = image.markdown;
+    const { html, hasMermaid } = isMarkdownLayout(md) ? renderMarkdownLayout(md, nextId) : renderMarkdownContent(md, nextId);
+    return { html, ...(hasMermaid ? { requires: ["mermaid"] } : {}) };
+};

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

@@ -0,0 +1,14 @@
+import type { MulmoImageMedia, MulmoMovieMedia } from "../../types/index.js";
+import type { BeatHtmlFragment } from "./type.js";
+/**
+ * Image and movie beats as markup a host can inject.
+ *
+ * The src comes straight from the beat's source: a url is used as written, a path is
+ * emitted for the host to resolve against its own page, and a base64 source renders
+ * nothing because the schema carries no media type to build a `data:` URI from.
+ *
+ * Neither needs a runtime, so neither sets `requires` — an `<img>` and a `<video>` are
+ * markup the browser already knows.
+ */
+export declare const imageToHtml: (image: MulmoImageMedia, alt: string) => BeatHtmlFragment | undefined;
+export declare const movieToHtml: (image: MulmoMovieMedia) => BeatHtmlFragment | undefined;

package/lib/utils/beat_html/media.js

@@ -0,0 +1,19 @@
+import { imageHtml, mediaSrc, movieHtml } from "../image_plugins/media_html.js";
+/**
+ * Image and movie beats as markup a host can inject.
+ *
+ * The src comes straight from the beat's source: a url is used as written, a path is
+ * emitted for the host to resolve against its own page, and a base64 source renders
+ * nothing because the schema carries no media type to build a `data:` URI from.
+ *
+ * Neither needs a runtime, so neither sets `requires` — an `<img>` and a `<video>` are
+ * markup the browser already knows.
+ */
+export const imageToHtml = (image, alt) => {
+    const src = mediaSrc(image.source);
+    return src === undefined ? undefined : { html: imageHtml(src, alt) };
+};
+export const movieToHtml = (image) => {
+    const src = mediaSrc(image.source);
+    return src === undefined ? undefined : { html: movieHtml(src) };
+};

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

@@ -0,0 +1,14 @@
+import type { MulmoMermaidMedia } from "../../types/index.js";
+import type { BeatHtmlFragment } from "./type.js";
+/**
+ * A mermaid beat as markup a host can inject.
+ *
+ * Only `code.kind === "text"` renders. The other kinds — `url`, `path`, `base64` — are
+ * resolved by `MulmoMediaSourceMethods.getText`, which fetches and reads files, so they
+ * cannot be reached from here and `beatToHtml` returns undefined rather than inventing a
+ * placeholder. `mermaid.ts`'s own markdown dump already draws the same line.
+ *
+ * The markup comes from `image_plugins/mermaid_html.ts`, the module the Node render path
+ * uses, so the browser and the PNG draw the same diagram.
+ */
+export declare const mermaidToHtml: (image: MulmoMermaidMedia, idPrefix: string) => BeatHtmlFragment | undefined;

package/lib/utils/beat_html/mermaid.js

@@ -0,0 +1,22 @@
+import { mermaidHtml } from "../image_plugins/mermaid_html.js";
+/**
+ * A mermaid beat as markup a host can inject.
+ *
+ * Only `code.kind === "text"` renders. The other kinds — `url`, `path`, `base64` — are
+ * resolved by `MulmoMediaSourceMethods.getText`, which fetches and reads files, so they
+ * cannot be reached from here and `beatToHtml` returns undefined rather than inventing a
+ * placeholder. `mermaid.ts`'s own markdown dump already draws the same line.
+ *
+ * The markup comes from `image_plugins/mermaid_html.ts`, the module the Node render path
+ * uses, so the browser and the PNG draw the same diagram.
+ */
+export const mermaidToHtml = (image, idPrefix) => {
+    if (image.code.kind !== "text")
+        return undefined;
+    const appendix = image.appendix?.join("\n") ?? "";
+    const code = `${image.code.text}\n${appendix}`.trim();
+    return {
+        html: mermaidHtml(code, `${idPrefix}-mermaid`, image.title || "Diagram"),
+        requires: ["mermaid"],
+    };
+};

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

@@ -0,0 +1,21 @@
+import type { MulmoSlideMedia } from "@mulmocast/deck";
+import type { BeatHtmlFragment, BeatHtmlOptions } from "./type.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 declare const slideToHtml: (image: MulmoSlideMedia, options: BeatHtmlOptions) => BeatHtmlFragment;

package/lib/utils/beat_html/slide.js

@@ -0,0 +1,33 @@
+// Deep import: the package barrel bundles every layout plus all of zod — measured 101 inputs
+// 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` });
+    return {
+        html: fragment.html,
+        css: fragment.css,
+        ...(fragment.requires.length > 0 ? { requires: fragment.requires } : {}),
+        ...(fragment.chartPlugins.length > 0 ? { chartPlugins: fragment.chartPlugins } : {}),
+        ...(fragment.mermaidTheme ? { mermaidTheme: fragment.mermaidTheme } : {}),
+    };
+};

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

@@ -0,0 +1,17 @@
+import type { MulmoTextSlideMedia } from "../../types/index.js";
+import type { BeatHtmlFragment } from "./type.js";
+/**
+ * A textSlide as markdown: title, then subtitle, then bullets.
+ * Kept separate from the HTML so `mulmo markdown` and `mulmo html` can share one
+ * definition of what a textSlide *says*, independently of how it is rendered.
+ */
+export declare const textSlideToMarkdown: (image: MulmoTextSlideMedia) => string;
+/**
+ * `async: false` keeps `parse` returning a string rather than a promise, so a browser
+ * host can render a beat inside a computed property instead of an effect.
+ *
+ * The result is NOT sanitized: marked renders raw HTML through by design, so a title of
+ * `<script>alert(1)</script>` reaches the caller intact. That is the documented contract
+ * on `BeatHtmlFragment.html`, and `test_text_slide.ts` pins it in both directions.
+ */
+export declare const textSlideToHtml: (image: MulmoTextSlideMedia) => BeatHtmlFragment;

package/lib/utils/beat_html/text_slide.js

@@ -0,0 +1,24 @@
+import { marked } from "marked";
+/**
+ * A textSlide as markdown: title, then subtitle, then bullets.
+ * Kept separate from the HTML so `mulmo markdown` and `mulmo html` can share one
+ * definition of what a textSlide *says*, independently of how it is rendered.
+ */
+export const textSlideToMarkdown = (image) => {
+    const { slide } = image;
+    const title = slide.title ? `# ${slide.title}\n` : "";
+    const subtitle = slide.subtitle ? `## ${slide.subtitle}\n` : "";
+    const bullets = (slide.bullets ?? []).map((text) => `- ${text}`).join("\n");
+    return `${title}${subtitle}${bullets}`;
+};
+/**
+ * `async: false` keeps `parse` returning a string rather than a promise, so a browser
+ * host can render a beat inside a computed property instead of an effect.
+ *
+ * The result is NOT sanitized: marked renders raw HTML through by design, so a title of
+ * `<script>alert(1)</script>` reaches the caller intact. That is the documented contract
+ * on `BeatHtmlFragment.html`, and `test_text_slide.ts` pins it in both directions.
+ */
+export const textSlideToHtml = (image) => ({
+    html: marked.parse(textSlideToMarkdown(image), { async: false }),
+});

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

@@ -0,0 +1,73 @@
+import type { SlideTheme } from "@mulmocast/deck";
+/**
+ * A beat rendered as markup for a browser host.
+ *
+ * Deliberately body-only. Tailwind, Chart.js, mermaid and fonts are shared across
+ * beats, so emitting them per beat means N duplicate loads in a list view — which is
+ * why `requires` names what the host needs instead of pulling it in. `src/actions/html.ts`
+ * already works this way: it puts those CDNs in the document head once.
+ */
+export type BeatHtmlFragment = {
+    /**
+     * Body markup only — no `<html>`, `<head>` or `<style>`, and no `<script>` that this
+     * module generated. An author's own script is a different matter: one written into an
+     * `html_tailwind` beat's markup, into raw HTML inside a `markdown` beat, or into a
+     * `textSlide` field arrives here verbatim, because nothing below sanitizes.
+     *
+     * **Not sanitized.** A beat is user data and `marked` does not sanitize: raw elements,
+     * `onerror=` handlers and `javascript:` URLs written into a beat survive into this
+     * string. Sanitize before inserting it into a DOM. Sanitizing here instead would be
+     * worse than useless — it would read as a safety guarantee this module cannot make,
+     * 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. */
+    css?: string;
+    /** External runtimes the host must load once for the page, not once per beat. */
+    requires?: BeatRuntime[];
+    /**
+     * Extra Chart.js plugin CDNs this beat's chart type needs, on top of Chart.js itself.
+     * Same shape as `@mulmocast/deck`'s `SlideFragment.chartPlugins`, so one host can load
+     * for both. Absent when the beat needs none.
+     */
+    chartPlugins?: string[];
+    /**
+     * Which mermaid theme suits this beat's background. A dark slide with a light diagram is
+     * unreadable, and the host initialises mermaid once for the page, so it has to be told.
+     * Absent unless the beat both requires mermaid and has an opinion.
+     */
+    mermaidTheme?: "dark" | "default";
+};
+/** External runtimes a fragment can depend on. */
+export type BeatRuntime = "chart" | "mermaid";
+export type BeatHtmlOptions = {
+    /**
+     * Prefix for element ids generated inside a fragment (mermaid containers, and chart
+     * canvases later). Required, and deliberately so.
+     *
+     * A page-wide default was the first design, and review found what it does: two markdown
+     * beats each start their counter at zero, so both emit `<div id="…-mermaid-0">`. That is
+     * invalid HTML and sends mermaid at whichever element it finds first. There is no value
+     * a library can pick that is unique per beat AND stable across re-renders — only the
+     * caller knows which beat this is, so the caller says.
+     *
+     * Must match `[A-Za-z_][A-Za-z0-9_-]*`: the id ends up in an HTML attribute and, for some
+     * beat types, in a JavaScript string literal inside a `<script>` where HTML entities are
+     * not decoded, and it has to stay usable from a CSS selector. Restricting the set is what
+     * makes one id safe in all of them — see `element_id.ts`.
+     *
+     * A beat's `id` comes from the script and is not restricted, so pass something derived
+     * from its index — `beat-3`, not `3`, since it must not start with a digit — or sanitize
+     * the id yourself. `beatToHtml` throws rather than guessing.
+     */
+    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
+     * `MulmoPresentationStyleMethods.getResolvedSlideTheme` uses on the Node side.
+     *
+     * Optional because only slide beats read it, and because the host may not have a deck
+     * theme to give.
+     */
+    slideTheme?: SlideTheme;
+};

package/lib/utils/beat_html/type.js

@@ -0,0 +1 @@
+export {};

package/lib/utils/element_id.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The rule for element ids that generated markup interpolates. Pure — no Node, no
+ * filesystem — because the Node render path and the browser fragment path build the same
+ * markup and must agree on it.
+ *
+ * This enumerates what is PERMITTED rather than escaping what is not. An id drawn from this
+ * set is safe in every context the markup uses it in — an HTML attribute, a JavaScript
+ * string literal inside a `<script>` where HTML entities are not decoded, a CSS selector, a
+ * URL fragment — so a new context cannot introduce a hole the way a per-context escaper can.
+ * Escaping would also have to keep the contexts in sync: entity-escaping `<canvas id>` while
+ * the `getElementById` beside it stays raw makes the two disagree and the lookup fail.
+ *
+ * The leading character is restricted because a CSS id selector is the strictest of those
+ * contexts. Measured in a browser: `querySelector("#0")`, `"#-"`, `"#0a"` and `"#-0"` all
+ * throw, while `getElementById` accepts every one of them — so an id that works today can
+ * still be unusable the moment anything reaches for it with a selector. This set is a little
+ * narrower than CSS allows (it rejects `-a`, which is valid) in exchange for being stateable
+ * in one line.
+ */
+export declare const isSafeElementId: (id: string) => boolean;
+/**
+ * Throws unless the id is safe in every context. A caller reaching this with a bad id has a
+ * bug, not bad user input: values that come from a script have to be turned into an id
+ * before they get here.
+ */
+export declare const assertSafeElementId: (id: string) => void;

package/lib/utils/element_id.js

@@ -0,0 +1,31 @@
+import { SAFE_ELEMENT_ID } from "../types/const.js";
+/**
+ * The rule for element ids that generated markup interpolates. Pure — no Node, no
+ * filesystem — because the Node render path and the browser fragment path build the same
+ * markup and must agree on it.
+ *
+ * This enumerates what is PERMITTED rather than escaping what is not. An id drawn from this
+ * set is safe in every context the markup uses it in — an HTML attribute, a JavaScript
+ * string literal inside a `<script>` where HTML entities are not decoded, a CSS selector, a
+ * URL fragment — so a new context cannot introduce a hole the way a per-context escaper can.
+ * Escaping would also have to keep the contexts in sync: entity-escaping `<canvas id>` while
+ * the `getElementById` beside it stays raw makes the two disagree and the lookup fail.
+ *
+ * The leading character is restricted because a CSS id selector is the strictest of those
+ * contexts. Measured in a browser: `querySelector("#0")`, `"#-"`, `"#0a"` and `"#-0"` all
+ * throw, while `getElementById` accepts every one of them — so an id that works today can
+ * still be unusable the moment anything reaches for it with a selector. This set is a little
+ * narrower than CSS allows (it rejects `-a`, which is valid) in exchange for being stateable
+ * in one line.
+ */
+export const isSafeElementId = (id) => SAFE_ELEMENT_ID.test(id);
+/**
+ * Throws unless the id is safe in every context. A caller reaching this with a bad id has a
+ * bug, not bad user input: values that come from a script have to be turned into an id
+ * before they get here.
+ */
+export const assertSafeElementId = (id) => {
+    if (!isSafeElementId(id)) {
+        throw new Error(`element id must match ${SAFE_ELEMENT_ID.source}, got ${JSON.stringify(id)}. Derive it from the beat's index (beat-3, not 3 — it must not start with a digit), or sanitize the beat's id, before passing it.`);
+    }
+};