@tycoworks/tycoslide 0.8.0 → 0.9.0

package/dist/index.js

@@ -1,99 +1,64 @@
 import { generate, SlotType, } from "./engine/index.js";
-import { isFence, resolveFences } from "./markdown/resolvers/resolver.js";
-import { CompilerSlotType, ParameterType, } from "./markdown/types.js";
+import { ParameterType, } from "./markdown/types.js";
 /**
- * Narrow a resolved content map to the engine-shaped value union. Runs after
- * `resolveFences`, so no CodeFence or MermaidFence should remain — a leftover is
- * a resolver bug and throws. Every surviving value is already an engine fill
- * (TextFill / TableFill / ImageFill / TemplateFill), so no unwrapping is needed.
+ * A frontmatter parameter always fills one physical shape on the layout's own
+ * slide, so it projects to a single base `Block` (`sourceSlide === baseSlide`)
+ * and never transplants — its `frame` is never read. `NO_FRAME` is that unread
+ * placeholder; only body slots with a transplant block carry a real frame.
  */
-function narrowContent(content) {
-    const out = {};
-    for (const [key, value] of Object.entries(content)) {
-        if (isFence(value)) {
-            throw new Error(`resolveDeck: slot "${key}" still holds an unresolved ${value.type} block ` +
-                "after resolvers ran. This is a resolver bug.");
-        }
-        out[key] = value;
+const NO_FRAME = { x: 0, y: 0, cx: 0, cy: 0 };
+function paramToEngineSlot(param, baseSlide) {
+    const block = (type) => ({ type, sourceSlide: baseSlide, shapeName: param.shapeName });
+    switch (param.type) {
+        case ParameterType.Template:
+            // A text shape carries no top-level key — its template placeholders are the keys. The
+            // compiler emits its expanded content under shapeName, so the engine slot
+            // is keyed by shapeName too.
+            return { key: param.shapeName, frame: NO_FRAME, accepts: [block(SlotType.Template)] };
+        case ParameterType.Image:
+            return { key: param.key, frame: NO_FRAME, accepts: [block(SlotType.Image)] };
     }
-    return out;
 }
 /**
- * Run every compiler-owned resolver over `deck` (highlight code fences,
- * render mermaid PNGs) and return a `ResolvedCompilerDeck` whose content
- * values are narrowed to the engine's `TextFill | TableFill | ImageFill |
- * TemplateFill` union. Structurally equivalent to the engine's `Deck` — a
- * caller passes the returned value straight to `generate()` with no cast.
- *
- * Fails fast if `deck.output` is missing: downstream `generate()` requires it,
- * and the CLI populates it before calling `buildDeck`; a programmatic caller
- * that forgot to set it hits the error here instead of a confusing engine-side
- * failure.
+ * Project a body slot's real `accepts` to engine `Block[]` and pass its `frame`
+ * through. The compiler `accepts` already carry engine content types
+ * (text/table/image) — code folded to text and mermaid to image at authoring —
+ * so projection is 1:1. A slot with no declared `frame` (a base-only slot that
+ * never transplants) gets `NO_FRAME`, which the engine never reads.
  */
-export async function resolveDeck(deck, config) {
-    await resolveFences(deck, config);
-    if (deck.output === undefined) {
-        throw new Error('resolveDeck: deck.output is not set. Set it (e.g. "deck.pptx") before calling buildDeck.');
-    }
-    return {
-        theme: deck.theme,
-        output: deck.output,
-        steps: deck.steps.map((step) => {
-            const resolvedStep = { layout: step.layout };
-            if (step.content)
-                resolvedStep.content = narrowContent(step.content);
-            if (step.notes !== undefined)
-                resolvedStep.notes = step.notes;
-            return resolvedStep;
-        }),
-    };
+function slotToEngineSlot(slot) {
+    const accepts = slot.accepts.map((b) => {
+        const eb = { type: b.type, sourceSlide: b.sourceSlide, shapeName: b.shapeName };
+        if (b.startAt !== undefined)
+            eb.startAt = b.startAt;
+        return eb;
+    });
+    return { key: slot.key, frame: slot.frame ?? NO_FRAME, accepts };
 }
 /**
- * Project a CompilerParameter or CompilerSlot down to the engine's flat Slot.
- * Parameters (Template, Image) map straight to their engine equivalent; compiler-
- * only slot types (Code, Mermaid) map to Text / Image since their resolved
- * StyledParagraph[] / ImageFill content is filled by the corresponding engine
- * primitive once the compiler is done.
- *
- * The discriminated unions narrow per-variant fields, so the projection is a
- * straight switch over all six type values — no runtime "wrong field on wrong
- * type" checks; TypeScript enforces the invariants at authoring time.
+ * Compiler→engine boundary check: a slot with a transplant block (any block
+ * whose `sourceSlide` differs from the layout's base slide) must declare a
+ * `frame` — the real region the transplant is positioned into. A base-only slot
+ * (all blocks in place) needs none. Missing → fail fast, naming layout + slot.
+ * (The engine's `assertSlotsWellFormed` separately rejects duplicate accept
+ * types.)
  */
-function toEngineSlot(slot) {
-    switch (slot.type) {
-        case ParameterType.Template:
-            // A text shape carries no top-level key — its template placeholders are the keys. The
-            // compiler emits its expanded content under shapeName, so the engine slot
-            // is keyed by shapeName too.
-            return { key: slot.shapeName, shapeName: slot.shapeName, type: SlotType.Template };
-        case ParameterType.Image:
-            return { key: slot.key, shapeName: slot.shapeName, type: SlotType.Image };
-        case CompilerSlotType.Text: {
-            const result = { key: slot.key, shapeName: slot.shapeName, type: SlotType.Text };
-            if (slot.startAt !== undefined)
-                result.startAt = slot.startAt;
-            return result;
+function assertSlotFrames(layout) {
+    for (const slot of layout.slots) {
+        const transplants = slot.accepts.some((b) => b.sourceSlide !== layout.slideNumber);
+        if (transplants && slot.frame === undefined) {
+            throw new Error(`Layout "${layout.name}" slot "${slot.key}": a transplant block (sourceSlide ≠ ${layout.slideNumber}) ` +
+                'requires a "frame" (the region to position it into), but none is declared.');
         }
-        case CompilerSlotType.Table:
-            return { key: slot.key, shapeName: slot.shapeName, type: SlotType.Table };
-        case CompilerSlotType.Code:
-            // Highlighter resolves the code fence into StyledParagraph[]; engine
-            // fills it via fillText.
-            return { key: slot.key, shapeName: slot.shapeName, type: SlotType.Text };
-        case CompilerSlotType.Mermaid:
-            // Mermaid renderer produces a PNG (ImageFill); engine fills it via
-            // fillImage. The fit lives on the ImageFill, not the engine Slot.
-            return { key: slot.key, shapeName: slot.shapeName, type: SlotType.Image };
     }
 }
 function toEngineLayout(layout) {
+    assertSlotFrames(layout);
+    const base = layout.slideNumber;
     return {
         name: layout.name,
-        slideNumber: layout.slideNumber,
-        description: layout.description,
-        whenToUse: layout.whenToUse,
-        whenNotToUse: layout.whenNotToUse,
-        slots: [...layout.parameters.map(toEngineSlot), ...layout.slots.map(toEngineSlot)],
+        baseSlide: base,
+        slots: [...layout.parameters.map((p) => paramToEngineSlot(p, base)), ...layout.slots.map(slotToEngineSlot)],
     };
 }
 /**
@@ -124,21 +89,31 @@ export function toEngineConfig(config) {
     };
 }
 /**
- * End-to-end build: run compiler-owned resolvers (syntax highlighting, mermaid
- * PNG rendering) over the deck via `resolveDeck`, which returns a narrowed
- * `ResolvedCompilerDeck` — structurally equivalent to the engine's `Deck` —
- * then hand it to the engine's primitives-only `generate()`. No cast required:
- * the narrowing happens at the type level via `resolveDeck`.
+ * End-to-end build: `compileDeck` already produced engine-shaped content (code
+ * highlighted, mermaid rendered), so `buildDeck` only asserts an `output` is set
+ * and hands the deck to the engine's primitives-only `generate()`. The deck is
+ * structurally equivalent to the engine's `Deck` once `output` is present, so no
+ * cast is required. `buildDeck` does not itself validate `config` — a
+ * programmatic caller assembling a `CompilerConfig` by hand should load it
+ * through `loadThemeConfig` (or `parseThemeConfig`) first to get the same
+ * fail-fast structural checks the CLI gets.
+ *
+ * Fails fast if `deck.output` is missing: `generate()` requires it, and the CLI
+ * populates it before calling `buildDeck`; a programmatic caller that forgot to
+ * set it hits this error instead of a confusing engine-side failure.
  *
  * Mermaid PNGs are cached under `<outputDir>/.tycoslide-cache/mermaid/` so no
  * post-write cleanup is needed.
  */
 export async function buildDeck(deck, config, options = {}) {
-    const resolved = await resolveDeck(deck, config);
-    await generate(resolved, toEngineConfig(config), options);
+    if (deck.output === undefined) {
+        throw new Error('buildDeck: deck.output is not set. Set it (e.g. "deck.pptx") before calling buildDeck.');
+    }
+    const engineDeck = { theme: deck.theme, output: deck.output, steps: deck.steps };
+    await generate(engineDeck, toEngineConfig(config), options);
 }
 // Engine — primitives-only public surface.
 export { fillImage, fillTable, fillTemplate, fillText, generate, SlotType } from "./engine/index.js";
 export { generateManifest } from "./manifest.js";
 // Markdown / Compiler
-export { CompilerSlotType, compileMarkdownDeck, FenceType, ParameterType, resolveFences } from "./markdown/index.js";
+export { AcceptType, compileMarkdownDeck, loadThemeConfig, ParameterType, parseThemeConfig } from "./markdown/index.js";

package/dist/manifest.js

@@ -1,5 +1,5 @@
 import { templateKeys } from "./markdown/textTemplate.js";
-import { CompilerSlotType, ParameterType } from "./markdown/types.js";
+import { ParameterType } from "./markdown/types.js";
 /**
  * Flatten a compiler parameter to the manifest entries advertised to AI authors.
  * A template parameter has no top-level key — its template's keys are the keys, so it
@@ -24,42 +24,34 @@ function stripParameter(param) {
             const result = { key: param.key, type: param.type };
             if (param.required)
                 result.required = true;
-            if (param.limit)
-                result.limit = param.limit;
             return [result];
         }
     }
 }
 function stripSlot(slot) {
-    const result = { key: slot.key, type: slot.type };
+    const result = { key: slot.key, accepts: slot.accepts.map((b) => b.type) };
     if (slot.required)
         result.required = true;
     if (slot.limit)
         result.limit = slot.limit;
-    switch (slot.type) {
-        case CompilerSlotType.Text:
-        case CompilerSlotType.Table:
-            // No fields beyond the shared key/type/required/limit.
-            break;
-        case CompilerSlotType.Code:
-            result.codeTheme = slot.codeTheme;
-            break;
-        case CompilerSlotType.Mermaid:
-            result.mermaidVariant = slot.mermaidVariant;
-            break;
-    }
     return result;
 }
 export function generateManifest(config, options) {
-    const layouts = config.layouts.map((layout) => ({
-        name: layout.name,
-        slideNumber: layout.slideNumber,
-        description: layout.description,
-        whenToUse: layout.whenToUse,
-        whenNotToUse: layout.whenNotToUse,
-        parameters: layout.parameters.flatMap(stripParameter),
-        slots: layout.slots.map(stripSlot),
-    }));
+    const layouts = config.layouts.map((layout) => {
+        const ml = {
+            name: layout.name,
+            slideNumber: layout.slideNumber,
+            parameters: layout.parameters.flatMap(stripParameter),
+            slots: layout.slots.map(stripSlot),
+        };
+        if (layout.description !== undefined)
+            ml.description = layout.description;
+        if (layout.whenToUse !== undefined)
+            ml.whenToUse = layout.whenToUse;
+        if (layout.whenNotToUse !== undefined)
+            ml.whenNotToUse = layout.whenNotToUse;
+        return ml;
+    });
     const assets = {};
     for (const [category, entries] of Object.entries(config.assets)) {
         assets[category] = {};

package/dist/markdown/blocks/code.d.ts

@@ -0,0 +1,15 @@
+import type { StyledParagraph } from "../../engine/index.js";
+import { type BlockHandler } from "../types.js";
+/**
+ * Recognize a fenced code block (any language except mermaid) at a region's top
+ * level, folding it to a Text fill, and compile it by Shiki-highlighting its
+ * source into a TextFill. Theme resolution is strict: the theme MUST declare a
+ * `codeTheme` (one style per theme — the design-system framing); a deck with
+ * code fences but no theme-level `codeTheme` throws, naming the offending slot.
+ */
+export declare const CODE: BlockHandler;
+/**
+ * Run Shiki over a code block, producing StyledParagraph[] with per-token
+ * color runs. Blank lines become paragraphs with a single empty run.
+ */
+export declare function highlightCode(code: string, language: string, theme: string): Promise<StyledParagraph[]>;

package/dist/markdown/blocks/code.js

@@ -0,0 +1,50 @@
+import { MdastType } from "../mdast.js";
+import { AcceptType } from "../types.js";
+import { MERMAID_LANG } from "./mermaid.js";
+/**
+ * Recognize a fenced code block (any language except mermaid) at a region's top
+ * level, folding it to a Text fill, and compile it by Shiki-highlighting its
+ * source into a TextFill. Theme resolution is strict: the theme MUST declare a
+ * `codeTheme` (one style per theme — the design-system framing); a deck with
+ * code fences but no theme-level `codeTheme` throws, naming the offending slot.
+ */
+export const CODE = {
+    match: (node) => node.type === MdastType.Code && node.lang !== MERMAID_LANG,
+    acceptType: AcceptType.Text,
+    compile: async (node, ctx) => {
+        const code = node;
+        // A fence with no language can't be highlighted (no Shiki grammar to pick),
+        // so fail fast naming the slot rather than attempt a language-less highlight.
+        if (!code.lang) {
+            throw new Error(`Slide ${ctx.slideIdx}: layout "${ctx.layoutName}" slot content (from ${ctx.source}) has a code fence ` +
+                "with no language; add one after the opening ``` (e.g. ```sql).");
+        }
+        const theme = ctx.config.codeTheme;
+        if (!theme) {
+            throw new Error(`Layout "${ctx.layoutName}" slot content (from ${ctx.source}): deck contains a code fence but the theme ` +
+                'declares no "codeTheme". Add a theme-level "codeTheme" (a Shiki theme id) to theme.json.');
+        }
+        return { paragraphs: await highlightCode(code.value, code.lang, theme) };
+    },
+};
+/**
+ * Run Shiki over a code block, producing StyledParagraph[] with per-token
+ * color runs. Blank lines become paragraphs with a single empty run.
+ */
+export async function highlightCode(code, language, theme) {
+    const { createHighlighter } = await import("shiki");
+    const lang = language;
+    const thm = theme;
+    const highlighter = await createHighlighter({ themes: [thm], langs: [lang] });
+    const { tokens } = highlighter.codeToTokens(code, { lang, theme: thm });
+    return tokens.map((line) => ({
+        runs: line.length === 0
+            ? [{ text: "" }]
+            : line.map((token) => {
+                const run = { text: token.content };
+                if (token.color)
+                    run.color = token.color.replace(/^#/, "");
+                return run;
+            }),
+    }));
+}

package/dist/markdown/blocks/image.d.ts

@@ -0,0 +1,2 @@
+import { type BlockHandler } from "../types.js";
+export declare const IMAGE: BlockHandler;

package/dist/markdown/blocks/image.js

@@ -0,0 +1,9 @@
+import { MdastType } from "../mdast.js";
+import { AcceptType } from "../types.js";
+export const IMAGE = {
+    match: (node) => node.type === MdastType.Image,
+    acceptType: AcceptType.Image,
+    // `node.url` is the raw `$category.name` ref; `resolveAssetRef` validates and
+    // resolves it (fail-fast on a malformed or unknown reference). `alt` is ignored.
+    compile: async (node, ctx) => ctx.resolveAssetRef(node.url),
+};

package/dist/markdown/blocks/mermaid.d.ts

@@ -0,0 +1,15 @@
+import { type BlockHandler } from "../types.js";
+/** The markdown code-fence *language* that selects mermaid rendering. The CODE
+ * handler reuses this to exclude mermaid so the two fence kinds match disjointly
+ * on `lang`. */
+export declare const MERMAID_LANG = "mermaid";
+/**
+ * Recognize a ```mermaid fenced block at a region's top level, folding it to an
+ * Image fill, and compile it by rendering the definition to a PNG (cached under
+ * `<outputDir>/.tycoslide-cache/mermaid/<hash>.png`) and wrapping it as an
+ * ImageFill. Fit is always `contain` — mermaid diagrams are shown in their
+ * entirety. Resolution is strict: the theme MUST carry a `mermaid` block, MUST
+ * declare a `mermaidVariant`, and that variant MUST exist — each missing piece
+ * throws by name.
+ */
+export declare const MERMAID: BlockHandler;

package/dist/markdown/blocks/mermaid.js

@@ -0,0 +1,227 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { extname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { ImageFit, SlotType } from "../../engine/index.js";
+import { MdastType } from "../mdast.js";
+import { AcceptType } from "../types.js";
+import { buildMermaidRenderConfig, injectClassDefs, validateMermaidDefinition, } from "./mermaidTheme.js";
+/** The markdown code-fence *language* that selects mermaid rendering. The CODE
+ * handler reuses this to exclude mermaid so the two fence kinds match disjointly
+ * on `lang`. */
+export const MERMAID_LANG = "mermaid";
+/**
+ * Recognize a ```mermaid fenced block at a region's top level, folding it to an
+ * Image fill, and compile it by rendering the definition to a PNG (cached under
+ * `<outputDir>/.tycoslide-cache/mermaid/<hash>.png`) and wrapping it as an
+ * ImageFill. Fit is always `contain` — mermaid diagrams are shown in their
+ * entirety. Resolution is strict: the theme MUST carry a `mermaid` block, MUST
+ * declare a `mermaidVariant`, and that variant MUST exist — each missing piece
+ * throws by name.
+ */
+export const MERMAID = {
+    match: (node) => node.type === MdastType.Code && node.lang === MERMAID_LANG,
+    acceptType: AcceptType.Image,
+    compile: async (node, ctx) => {
+        const definition = node.value;
+        const { config } = ctx;
+        if (!config.mermaid) {
+            throw new Error('Deck contains mermaid diagrams, but theme has no "mermaid" block. ' +
+                "Add mermaid color configuration to theme.json.");
+        }
+        const variantName = config.mermaidVariant;
+        if (variantName === undefined) {
+            throw new Error(`Layout "${ctx.layoutName}" slot content (from ${ctx.source}): deck contains a mermaid diagram but the theme ` +
+                'declares no "mermaidVariant". Add a theme-level "mermaidVariant" naming a "mermaid" entry to theme.json.');
+        }
+        const variant = config.mermaid[variantName];
+        if (!variant) {
+            throw new Error(`Slide layout "${ctx.layoutName}": mermaid variant "${variantName}" not found in theme. ` +
+                `Available variants: ${Object.keys(config.mermaid).join(", ")}`);
+        }
+        const cacheDir = ensureCacheDir(config);
+        const pngPath = await renderOne(definition, variantName, variant, cacheDir, config);
+        return { type: SlotType.Image, path: pngPath, fit: ImageFit.Contain };
+    },
+};
+const FONT_FORMATS = {
+    ".woff2": "woff2",
+    ".woff": "woff",
+    ".ttf": "truetype",
+    ".otf": "opentype",
+};
+/** The `#output` div's DOM contract, shared by the in-page script and the
+ * Playwright poller — one const so a rename can't drift the two sides into a
+ * silent 30s timeout. */
+const RENDER_SIGNAL_ATTR = "data-render-signal";
+const RENDER_ERROR_ATTR = "data-render-error";
+const RenderSignal = { Pending: "pending", Done: "done" };
+function hashKey(definition, variantName, renderConfig, fonts) {
+    const hash = createHash("sha256")
+        .update(variantName)
+        .update("\n")
+        .update(definition)
+        .update("\n")
+        .update(JSON.stringify(renderConfig));
+    for (const f of fonts)
+        hash.update("\n").update(`${f.family}:${f.weight}:${f.url}`);
+    return hash.digest("hex").slice(0, 16);
+}
+function ensureCacheDir(config) {
+    const base = resolve(config.outputDir ?? process.cwd(), ".tycoslide-cache", "mermaid");
+    mkdirSync(base, { recursive: true });
+    return base;
+}
+/**
+ * Resolve each theme font's `path` to an absolute `file://` URL. A bare specifier
+ * (`@fontsource/inter/files/...`) resolves through the theme's node_modules; a
+ * `./`- or `/`-prefixed path resolves against `rootDir`. A missing file fails fast
+ * naming the family + path — never a silent skip.
+ */
+function resolveFonts(rootDir, fonts) {
+    const require = createRequire(join(rootDir, "package.json"));
+    return fonts.map((font) => {
+        const isFsPath = font.path.startsWith(".") || font.path.startsWith("/");
+        let absPath;
+        if (isFsPath) {
+            absPath = resolve(rootDir, font.path);
+        }
+        else {
+            try {
+                absPath = require.resolve(font.path);
+            }
+            catch {
+                throw new Error(`Theme font "${font.family}": could not resolve "${font.path}" from ${rootDir}. ` +
+                    "Install the package, or use a ./- or /-prefixed file path.");
+            }
+        }
+        if (!existsSync(absPath)) {
+            throw new Error(`Theme font "${font.family}": file not found at ${absPath} (from "${font.path}").`);
+        }
+        const format = FONT_FORMATS[extname(absPath).toLowerCase()];
+        if (!format) {
+            throw new Error(`Theme font "${font.family}": unsupported format "${extname(absPath)}". ` +
+                `Supported: ${Object.keys(FONT_FORMATS).join(", ")}.`);
+        }
+        return { family: font.family, url: pathToFileURL(absPath).href, weight: font.weight ?? 400, format };
+    });
+}
+async function renderOne(definition, variantName, variant, cacheDir, compilerConfig) {
+    const validated = validateMermaidDefinition(definition);
+    const processed = injectClassDefs(validated, variant.accents, variant.accentOpacity, variant.accentTextColor, variant.surface, variant.groupCornerRadius);
+    const fonts = resolveFonts(compilerConfig.rootDir, compilerConfig.fonts ?? []);
+    // The variant asks mermaid for `fontFamily` by name; if the theme declared
+    // fonts but none provide that family, Chromium substitutes silently — the exact
+    // failure this feature exists to prevent — so surface the likely typo. Not fatal:
+    // a theme may intentionally target an OS-installed font and declare no faces.
+    if (fonts.length > 0 && !fonts.some((f) => f.family === variant.fontFamily)) {
+        console.warn(`Mermaid variant "${variantName}": fontFamily "${variant.fontFamily}" matches none of the ` +
+            `declared theme fonts (${[...new Set(fonts.map((f) => f.family))].join(", ")}); ` +
+            "the diagram will fall back to a substitute font.");
+    }
+    const renderConfig = buildMermaidRenderConfig(variant);
+    const key = hashKey(processed, variantName, renderConfig, fonts);
+    const outputPath = join(cacheDir, `${key}.png`);
+    if (existsSync(outputPath))
+        return outputPath;
+    await renderMermaidToPng(processed, renderConfig, fonts, outputPath);
+    return outputPath;
+}
+let bundleCache = null;
+/** The mermaid browser bundle, read once and reused across renders. */
+function getMermaidBundle() {
+    if (bundleCache === null) {
+        const require = createRequire(import.meta.url);
+        bundleCache = readFileSync(require.resolve("mermaid/dist/mermaid.min.js"), "utf-8");
+    }
+    return bundleCache;
+}
+function fontFaceCss(fonts) {
+    return fonts
+        .map((f) => `@font-face { font-family: '${f.family}'; src: url('${f.url}') format('${f.format}'); font-weight: ${f.weight}; font-style: normal; }`)
+        .join("\n");
+}
+/**
+ * Render a mermaid definition to a transparent PNG via a headless Chromium
+ * (Playwright — the proven old driver, stronger headless font fidelity). The
+ * theme fonts are injected as `@font-face` and every registered face is awaited
+ * (`document.fonts.load()`) BEFORE `mermaid.render()` measures text — the only
+ * cross-platform, zero-install way to make Chromium lay out labels in the brand
+ * font instead of a substitute. mmdc's `--cssFile` injects too late (after layout)
+ * to affect metrics, which is why this replaces its programmatic API.
+ */
+async function renderMermaidToPng(processed, renderConfig, fonts, outputPath) {
+    const bundle = getMermaidBundle();
+    // JSON script blocks pass data without escaping issues; escape `</` so a value
+    // can't close the surrounding <script>.
+    const defJson = JSON.stringify(processed).replace(/<\//g, "<\\/");
+    const configJson = JSON.stringify(renderConfig).replace(/<\//g, "<\\/");
+    const html = `<!DOCTYPE html>
+<html><head>
+<style>
+body { margin: 0; background: transparent; }
+${fontFaceCss(fonts)}
+</style>
+</head>
+<body>
+  <div id="output" ${RENDER_SIGNAL_ATTR}="${RenderSignal.Pending}"></div>
+  <script id="mermaid-def" type="application/json">${defJson}</script>
+  <script id="mermaid-config" type="application/json">${configJson}</script>
+  <script>${bundle}</script>
+  <script>
+    (async () => {
+      const out = document.getElementById('output');
+      try {
+        const def = JSON.parse(document.getElementById('mermaid-def').textContent);
+        const config = JSON.parse(document.getElementById('mermaid-config').textContent);
+        const container = document.createElement('div');
+        container.style.position = 'absolute';
+        container.style.top = '-9999px';
+        document.body.appendChild(container);
+        // document.fonts.ready alone resolves early (nothing references the face
+        // yet); iterating and .load()-ing each forces the fetch before mermaid
+        // measures text.
+        await Promise.all([...document.fonts].map(f => f.load()));
+        await document.fonts.ready;
+        mermaid.initialize(config);
+        const { svg } = await mermaid.render('mermaid-0', def, container);
+        container.remove();
+        out.innerHTML = svg;
+        out.setAttribute('${RENDER_SIGNAL_ATTR}', '${RenderSignal.Done}');
+      } catch (e) {
+        out.setAttribute('${RENDER_ERROR_ATTR}', (e && e.message) || String(e));
+        out.setAttribute('${RENDER_SIGNAL_ATTR}', '${RenderSignal.Done}');
+      }
+    })();
+  </script>
+</body></html>`;
+    // Serve the page from a real file:// URL, not setContent — an about:blank
+    // origin can't fetch the file:// font resources (@font-face silently fails),
+    // whereas a file://-origin document loads them. Mirrors the old harness.
+    const htmlPath = `${outputPath}.html`;
+    const { chromium } = await import("playwright");
+    let browser;
+    try {
+        // Written inside the try so the finally always cleans it up, even if launch throws.
+        writeFileSync(htmlPath, html);
+        browser = await chromium.launch({ headless: true, args: ["--no-sandbox"] });
+        const page = await browser.newPage({ viewport: { width: 800, height: 600 }, deviceScaleFactor: 2 });
+        await page.goto(pathToFileURL(htmlPath).href, { waitUntil: "load" });
+        await page.waitForSelector(`#output[${RENDER_SIGNAL_ATTR}="${RenderSignal.Done}"]`, { timeout: 30000 });
+        const error = await page.getAttribute("#output", RENDER_ERROR_ATTR);
+        if (error)
+            throw new Error(error);
+        const svg = page.locator("#output svg");
+        if ((await svg.count()) === 0)
+            throw new Error("mermaid produced no SVG");
+        await svg.screenshot({ path: outputPath, omitBackground: true });
+    }
+    catch (e) {
+        throw new Error(`Mermaid render failed:\n${e instanceof Error ? e.message : String(e)}`);
+    }
+    finally {
+        await browser?.close();
+        rmSync(htmlPath, { force: true });
+    }
+}

package/dist/markdown/{resolvers → blocks}/mermaidTheme.d.ts

@@ -2,7 +2,7 @@
  * Mermaid theme types and definition-processing utilities.
  *
  * Owner of MermaidVariant / MermaidConfig — these types are compiler-facing
- * (the engine has no idea mermaid exists). `resolvers/mermaid.ts` consumes
+ * (the engine has no idea mermaid exists). `blocks/mermaid.ts` consumes
  * them to build --configFile input for `mmdc`.
  */
 export type MermaidVariant = {

package/dist/markdown/{resolvers → blocks}/mermaidTheme.js

@@ -2,7 +2,7 @@
  * Mermaid theme types and definition-processing utilities.
  *
  * Owner of MermaidVariant / MermaidConfig — these types are compiler-facing
- * (the engine has no idea mermaid exists). `resolvers/mermaid.ts` consumes
+ * (the engine has no idea mermaid exists). `blocks/mermaid.ts` consumes
  * them to build --configFile input for `mmdc`.
  */
 const FORBIDDEN_PATTERNS = [/^\s*style\s+\S+\s+/, /^\s*linkStyle\s+/, /^\s*classDef\s+/, /^\s*%%\{init/];

package/dist/markdown/blocks/registry.d.ts

@@ -0,0 +1,16 @@
+import { AcceptType, type BlockContext, type BlockFill, type BlockHandler } from "../types.js";
+export type { BlockContext, BlockHandler };
+/**
+ * Recognize a body/`::name::` region's content and return the engine
+ * `AcceptType` it folds to, plus a lazy `fill` that compiles it to the engine
+ * fill. The split is deliberate: `acceptType` is available synchronously so the
+ * caller can validate a region against its slot BEFORE running the (possibly
+ * expensive — Shiki, Playwright) `fill`. A region that is exactly one
+ * `mermaid`/`code`/`image`/`table` node folds to that kind; anything else
+ * aggregates to one TextFill (prose + lists + headings). The paragraph-unwrap
+ * mirrors remark wrapping a lone `![alt](src)` in a paragraph.
+ */
+export declare function parseSlotContent(text: string, ctx: BlockContext): {
+    acceptType: AcceptType;
+    fill: () => Promise<BlockFill>;
+};