@lutrin/core 1.0.0 → 1.1.0

package/src/deck/parse.mjs

@@ -44,6 +44,14 @@
 
 import MarkdownIt from 'markdown-it';
 import container from 'markdown-it-container';
+import {
+  classifyMarpDirective,
+  isMarpDeck,
+  marpBlocks,
+  marpMeta,
+  parseHeadingDivider,
+  parseMarpComment,
+} from './marp.mjs';
 
 export const CONTAINERS = ['info', 'success', 'warning', 'danger', 'metric'];
 
@@ -417,7 +425,26 @@ export function parseDeck(source) {
   // as a ghost slide. CI covers windows-latest; the BOM does not cost a line,
   // so source positions stay correct.
   const { meta, body, lineOffset } = splitFrontmatter(source.replace(/^\uFEFF/, ''));
+  /** Marp dialect (`marp: true` in the frontmatter): slides split on `---`
+   *  only, HTML comments are presenter notes, `![bg \u2026]` images become the
+   *  slide background \u2014 see marp.mjs. The lutrin DSL is unchanged without
+   *  the opt-in. */
+  const marp = isMarpDeck(meta);
+  const marpState = marp ? marpMeta(meta) : null;
   const tokens = buildMd().parse(body, {});
+  if (marp) {
+    // headingDivider is a GLOBAL Marp directive: wherever it is written, the
+    // LAST definition wins and applies to the whole deck — the slides before
+    // the comment split too. Hence this pre-scan, before any slide is cut.
+    for (const t of tokens) {
+      if (t.type !== 'html_block') continue;
+      for (const d of parseMarpComment(t.content)?.directives ?? []) {
+        if (classifyMarpDirective(d.key) === 'divider') {
+          marpState.divider = parseHeadingDivider(d.value);
+        }
+      }
+    }
+  }
   // 1-based, in the source file (frontmatter included)
   const lineOf = (t) => (t?.map ? t.map[0] + lineOffset + 1 : undefined);
 
@@ -469,6 +496,53 @@ export function parseDeck(source) {
     pending = [];
   };
 
+  /** Marp: has the slide's body opened yet? Images placed as backgrounds or
+   *  split sides do not count — `![bg …](…)` before the title is the
+   *  canonical Marp order, and the title that follows still titles the
+   *  slide. */
+  const marpSlideHasContent = (s) =>
+    s.sections.length > 1 ||
+    s.sections[0].heading !== null ||
+    s.sections[0].blocks.some(
+      (b) =>
+        !(
+          b.type === 'image' &&
+          (b.role === 'background' || b.role === 'left' || b.role === 'right')
+        ),
+    );
+
+  /** Routes a parsed Marp comment (directives + notes) into the deck. In the
+   *  Marp dialect a comment belongs to the slide it sits in — reading one
+   *  therefore OPENS the slide, like any content would: an empty Marp slide
+   *  carrying only a note exists and keeps its note. Directives with a lutrin
+   *  equivalent go through the normal machinery; the others land in
+   *  `marpState.ignored` so that validation reports them instead of losing
+   *  them in silence. */
+  function routeMarpComment(read, line) {
+    if (!read || (!read.directives.length && !read.notes.length)) return;
+    ensureSlide();
+    for (const note of read.notes) applyDirective(slide, { key: 'notes', value: note, line });
+    for (const d of read.directives) {
+      switch (classifyMarpDirective(d.key)) {
+        case 'lutrin':
+          applyDirective(slide, { key: d.key, value: d.value, line });
+          break;
+        case 'footer':
+          // lutrin's footer is deck-wide: the last definition wins, the way a
+          // Marp footer redefined mid-deck applies from there on
+          meta.footer = d.value;
+          break;
+        case 'divider':
+          // global directive: already applied deck-wide by the pre-scan
+          break;
+        case 'ignored':
+          marpState.ignored.push({ key: d.key, value: d.value, line });
+          break;
+        default: // silent: the engine already decides this on its own
+      }
+    }
+  }
+
   let i = 0;
   const n = tokens.length;
 
@@ -487,7 +561,14 @@ export function parseDeck(source) {
    *  Every block returned carries `line` (position in the source file). */
   function readBlock() {
     const line = lineOf(tokens[i]);
-    const b = readBlockAt();
+    let b = readBlockAt();
+    if (marp && b) {
+      // inline comments carry directives and notes too (Marpit reads them):
+      // collected during the strip, routed with the block's own line
+      const inline = [];
+      b = marpBlocks(b, (body) => inline.push(body));
+      for (const body of inline) routeMarpComment(parseMarpComment(`<!--${body}-->`), line);
+    }
     if (b && line != null) {
       for (const x of Array.isArray(b) ? b : [b]) x.line ??= line;
     }
@@ -518,10 +599,17 @@ export function parseDeck(source) {
       // nested block must not restart at "1." after the block. `startAt` is
       // the same convention as the split performed by pagination.
       let rank = 1;
+      /** Marp: `*` bullets and `1)` items are FRAGMENTED — they appear one by
+       *  one. The flag is read per chunk: a list cut in two by a nested block
+       *  keeps each half's own markers. */
+      let fragmented = false;
       /** Closes the current list chunk to let a block through. */
       const flushBullets = () => {
+        const frag = fragmented;
+        fragmented = false;
         if (!items.length) return;
         const b = { type: 'bullets', ordered, items };
+        if (marp && frag) b.fragmented = true;
         if (ordered && rank > 1) b.startAt = rank;
         if (itemsLine != null) b.line = itemsLine;
         rank += items.filter((it) => !it.level).length;
@@ -552,6 +640,11 @@ export function parseDeck(source) {
           i++;
           continue;
         }
+        if (u.type === 'list_item_open') {
+          if (marp && (u.markup === '*' || u.markup === ')')) fragmented = true;
+          i++;
+          continue;
+        }
         // A heading indented under a bullet does NOT open a section: its text
         // stays a bullet. It is therefore counted as an item paragraph, or
         // else the `para > 0` below would make it vanish without a trace.
@@ -663,6 +756,10 @@ export function parseDeck(source) {
       }
       case 'html_block': {
         i++;
+        if (marp) {
+          routeMarpComment(parseMarpComment(t.content), lineOf(t));
+          return null;
+        }
         const c = parseComment(t.content);
         if (c) {
           const directive = { ...c, line: lineOf(t) };
@@ -739,7 +836,48 @@ export function parseDeck(source) {
     // a paragraph mixing text and images returns several blocks: all of them
     // are placed, in source order
     for (const block of Array.isArray(read) ? read : [read]) {
-      if (block.type === 'heading' && block.depth === 1) {
+      if (marp && block.type === 'heading') {
+        // Marp never splits on a heading — `---` does, and headingDivider
+        // restores the heading splits the deck asked for
+        if (marpState.divider?.has(block.depth)) pushSlide();
+        // Structural depths are RELATIVE to the slide's title: `#`/`##` are
+        // always structural (title or section), and below the title it is the
+        // FIRST subheading level actually used that opens the sections — a
+        // `##` slide subdivided with `###`, or with `####` inside the
+        // `<div class="columns">` idiom of Marp decks (the divs themselves
+        // are ignored HTML). Deeper headings stay subheadings in the flow.
+        const tDepth = slide?.marpTitleDepth;
+        const structural =
+          block.depth <= 2 ||
+          (tDepth != null &&
+            block.depth > tDepth &&
+            block.depth === (slide.marpSectionDepth ?? block.depth));
+        if (structural) {
+          ensureSlide();
+          slide.line ??= block.line;
+          // the first heading of the slide titles it — unless the body
+          // already opened (a background image does not open it: `![bg]`
+          // before the title is the canonical Marp order); a heading met
+          // mid-flow opens a section, exactly like a `##` of the lutrin DSL
+          if (!slide.title && !marpSlideHasContent(slide) && block.depth <= 2) {
+            slide.titleRuns = block.runs;
+            slide.title = runsToText(block.runs).trim();
+            slide.marpTitleDepth = block.depth;
+          } else {
+            if (slide.marpTitleDepth != null && block.depth > slide.marpTitleDepth) {
+              slide.marpSectionDepth ??= block.depth;
+            }
+            if (curSection().heading !== null || curSection().blocks.length) {
+              slide.sections.push({ heading: block.runs, blocks: [] });
+            } else {
+              curSection().heading = block.runs;
+            }
+          }
+          continue;
+        }
+        // deep heading: flows as content below
+      }
+      if (!marp && block.type === 'heading' && block.depth === 1) {
         pushSlide();
         ensureSlide();
         slide.titleRuns = block.runs;
@@ -750,6 +888,12 @@ export function parseDeck(source) {
 
       ensureSlide();
       slide.line ??= block.line;
+      if (marp && block.fragmented) {
+        // a fragmented list reveals point by point: that is lutrin's animate,
+        // unless the slide opted out explicitly (<!-- animate: none -->)
+        delete block.fragmented;
+        if (slide.animate === null) slide.animate = true;
+      }
       if (block.type === 'heading' && block.depth === 2) {
         // new section (potential slot)
         if (curSection().heading !== null || curSection().blocks.length) {
@@ -766,11 +910,36 @@ export function parseDeck(source) {
   pushSlide();
   dropPending();
 
+  if (marp) {
+    // several `![bg]` on one slide (Marp composes them side by side): lutrin
+    // has ONE background — the first wins, the others return to the flow
+    for (const s of slides) {
+      // parse-time bookkeeping, not part of the IR
+      delete s.marpTitleDepth;
+      delete s.marpSectionDepth;
+      let bg = false;
+      for (const sec of s.sections) {
+        for (const b of sec.blocks) {
+          if (b.type === 'image' && (b.role === 'background' || b.role === 'cover')) {
+            if (bg) b.role = 'auto';
+            bg = true;
+          }
+        }
+      }
+    }
+  }
+
   return {
     meta,
-    slides: slides.filter((s) => s.title || s.sections.some((x) => x.blocks.length || x.heading)),
+    // Marp keeps a slide that only carries a note (its comment is content);
+    // a slide with nothing at all is dropped in both dialects
+    slides: slides.filter(
+      (s) =>
+        s.title || s.sections.some((x) => x.blocks.length || x.heading) || (marp && s.notes.length),
+    ),
     // key absent when there is nothing to report: the IR of a healthy deck
     // does not change shape for an anomaly it does not have
     ...(orphanDirectives.length ? { orphanDirectives } : {}),
+    ...(marp && marpState.ignored.length ? { marpIgnored: marpState.ignored } : {}),
   };
 }

package/src/deck/validate.mjs

@@ -37,6 +37,7 @@ import { chartDataDiagnostics } from './chart.mjs';
 import { LAYER_SHADES, PAGE, contentArea } from './tokens.mjs';
 import { prepareDeckContext } from './context.mjs';
 import { THEME_KEYS } from './theme.mjs';
+import { isMarpDeck } from './marp.mjs';
 import { closest } from './suggest.mjs';
 
 /** Candidates for animation preset suggestions (names + French aliases). */
@@ -110,6 +111,24 @@ export function validateDeck(
   // impossible parse into a diagnostic rather than a crash.
   const lines = source.split(/\r?\n/);
   if (typeof lines[0] === 'string') lines[0] = lines[0].replace(/^\uFEFF/, '');
+
+  // ------ IR -----------------------------------------------------------------
+  // Validation must never throw: a deck that cannot be parsed becomes a
+  // diagnostic, not a crash of the editor or of the CLI. Parsed BEFORE the
+  // text scan: the scan needs the deck's dialect, and only the parser knows
+  // it \u2014 frontmatter detection and quote stripping live there, a second
+  // ad hoc reading of `marp:` would inevitably diverge from it.
+  if (!deck) {
+    try {
+      deck = parseDeck(source);
+    } catch (e) {
+      push('error', 'PARSE_ERROR', `Could not parse the document: ${e?.message ?? e}`, 1);
+      return diags;
+    }
+  }
+  // Marp dialect: `:::` is not part of its syntax \u2014 a line starting with
+  // `:::` there is prose, not a mistyped directive. Whole scan off.
+  const marpDoc = isMarpDeck(deck.meta);
   let inFence = null;
   let inFrontmatter = lines[0]?.trim() === '---' ? 'open' : null;
   lines.forEach((raw, k) => {
@@ -126,6 +145,7 @@ export function validateDeck(
       return;
     }
     if (inFence) return;
+    if (marpDoc) return;
     const dir = line.match(/^:{3,}\s*([A-Za-z][\w-]*)/);
     // CASE-SENSITIVE comparison, like markdown-it-container when opening:
     // `:::Info` opens no callout and renders as a literal paragraph.
@@ -153,17 +173,14 @@ export function validateDeck(
     }
   });
 
-  // ------ IR -----------------------------------------------------------------
-  // Validation must never throw: a deck that cannot be parsed becomes a
-  // diagnostic, not a crash of the editor or of the CLI.
-  if (!deck) {
-    try {
-      deck = parseDeck(source);
-    } catch (e) {
-      push('error', 'PARSE_ERROR', `Could not parse the document: ${e?.message ?? e}`, 1);
-      return diags;
+  /** Line (1-based) of a frontmatter key, to position a diagnostic. */
+  const metaLine = (key) => {
+    if (lines[0]?.trim() !== '---') return 1;
+    for (let k = 1; k < lines.length && lines[k].trim() !== '---'; k++) {
+      if (new RegExp(`^${key}\\s*:`).test(lines[k])) return k + 1;
     }
-  }
+    return 1;
+  };
 
   // Directives the parser could not attach to any slide (end of file, or `---`
   // before any content). They have no effect: saying so here is the only trace
@@ -178,25 +195,46 @@ export function validateDeck(
     );
   }
 
-  if (!deck.slides.length && !deck.meta.title) {
+  // Marp directives with no lutrin equivalent: the parser collected them
+  // (deck.marpIgnored), each one is reported here — an author must never
+  // discover a lost directive by staring at the rendering. Info severity:
+  // the deck compiles, the engine simply decides these things itself.
+  // BEFORE the early return of EMPTY_DECK, for the same reason as the
+  // orphans: an empty deck loses its directives too.
+  for (const d of deck.marpIgnored ?? []) {
+    const at = d.line ?? metaLine(d.key);
+    if (d.key === 'theme') {
+      push(
+        'info',
+        'MARP_DIRECTIVE_IGNORED',
+        `Marp theme "${d.value}" ignored: lutrin themes come from kits — \`kit: <name>\` (frontmatter) or --kit. The generic theme applies.`,
+        at,
+        'kit:',
+      );
+    } else {
+      push(
+        'info',
+        'MARP_DIRECTIVE_IGNORED',
+        `Marp directive "${d.key}${d.value ? `: ${d.value}` : ''}" has no lutrin equivalent — ignored (layout, colors and chrome are decided by the engine and the theme).`,
+        at,
+      );
+    }
+  }
+
+  // In the Marp dialect, `title:` is HTML metadata — it creates no cover
+  // slide, so it cannot vouch for the deck the way a lutrin title does.
+  if (!deck.slides.length && (!deck.meta.title || marpDoc)) {
     push(
       'warning',
       'EMPTY_DECK',
-      'No slides: neither a frontmatter `title:`, nor a `# heading` in the body.',
+      marpDoc
+        ? 'No slides: in a Marp deck, `title:` is metadata and creates no slide — add body content (slides split on `---`).'
+        : 'No slides: neither a frontmatter `title:`, nor a `# heading` in the body.',
       1,
     );
     return diags;
   }
 
-  /** Line (1-based) of a frontmatter key, to position a diagnostic. */
-  const metaLine = (key) => {
-    if (lines[0]?.trim() !== '---') return 1;
-    for (let k = 1; k < lines.length && lines[k].trim() !== '---'; k++) {
-      if (new RegExp(`^${key}\\s*:`).test(lines[k])) return k + 1;
-    }
-    return 1;
-  };
-
   // `animate:` in the frontmatter (whole deck) — the same check as the slide
   // comment, positioned on the frontmatter line
   if (deck.meta.animate != null && !isKnownAnimateValue(deck.meta.animate)) {
@@ -658,8 +696,30 @@ export function capabilities() {
     codeFences: ['mermaid', 'math', 'latex', 'tex', 'chart'],
     comments: ['notes', 'layout', 'animate'],
     animatePresets: [...ANIM_PRESETS],
-    frontmatter: ['title', 'subtitle', 'author', 'date', 'footer', 'animate', 'kit', 'assets'],
+    frontmatter: [
+      'title',
+      'subtitle',
+      'author',
+      'date',
+      'footer',
+      'animate',
+      'kit',
+      'assets',
+      'marp',
+    ],
     outputs: ['pptx', 'html'],
+    marp:
+      '`marp: true` (frontmatter) reads the deck as Marp Markdown (Marpit + Marp Core): slides split on ' +
+      '`---` only (headingDivider honoured — global, last definition wins), the first #/## of a slide is ' +
+      'its title, and the first subheading level used below it opens sections (## under a # title, ### ' +
+      'or #### under a ## title — the <div class="columns"> idiom maps to real columns, the divs being ' +
+      'ignored HTML). HTML comments — inline ones included — are presenter notes unless they carry ' +
+      'directives, `![bg …]` images become the slide background (`bg left`/`bg right` = split side), Marp ' +
+      'sizing/filter keywords in alts are consumed, fragmented lists (`*`, `1)`) animate their slide, ' +
+      '<!-- fit --> is stripped. footer: maps onto the deck footer. Directives with no equivalent (style, ' +
+      'header, background*, color, size other than 16:9, Marp theme:) are reported by ' +
+      'MARP_DIRECTIVE_IGNORED — themes come from kits (kit:), which works in a Marp deck too, as do ' +
+      '<!-- layout: … -->, <!-- notes: … -->, <!-- animate --> and the ::: callouts.',
     remoteImages:
       '`![](https://…)` images are downloaded then embedded in the deliverable (the presentation has no ' +
       'network dependency). They land in the user cache ~/.cache/lutrin/remote/, shared between projects — ' +
@@ -732,6 +792,7 @@ export function capabilities() {
       'USER_CONFIG_INVALID',
       'LAYOUT_DEF_INVALID',
       'LAYOUT_DEF_ADJUSTED',
+      'MARP_DIRECTIVE_IGNORED',
     ],
   });
 }

package/src/html/render.mjs

@@ -735,7 +735,7 @@ function htmlMermaid(block, r, ctx) {
   const svg = ctx.mermaid.get(block);
   if (svg) return `<div class="figure mermaid el" style="${at(r, true)}">${svg}</div>`;
   // faithful fallback: source shown as a code block + a caption
-  return `${htmlCode({ lang: 'mermaid', source: block.source }, { ...r, h: r.h - 24 })}<div class="fallback-caption el" style="left:${Math.round(r.x)}px;top:${Math.round(r.y + r.h - 22)}px;width:${Math.round(r.w)}px;">Mermaid diagram — install @mermaid-js/mermaid-cli for graphical rendering</div>`;
+  return `${htmlCode({ lang: 'mermaid', source: block.source }, { ...r, h: r.h - 24 })}<div class="fallback-caption el" style="left:${Math.round(r.x)}px;top:${Math.round(r.y + r.h - 22)}px;width:${Math.round(r.w)}px;">Mermaid diagram — run \`lutrin setup-mermaid\` for graphical rendering</div>`;
 }
 
 function htmlIcon(block, r, ctx) {

package/src/pptx/render.mjs

@@ -151,7 +151,12 @@ function addPara(slide, block, r) {
     color: block.color ?? COLORS.neutralPrimary,
     align: 'left',
     valign: 'top',
-    lineSpacingMultiple: LINE_HEIGHT,
+    // exact points, never a multiple: OOXML's spcPct multiplies the FONT'S
+    // own line metrics, so a kit font with tall ascenders rendered ~20%
+    // taller than blockHeight() measured and crowded whatever followed.
+    // spcPts pins the pitch to what the layout engine and the HTML (.para
+    // line-height 1.4) both assume, whatever font the kit ships.
+    lineSpacing: TYPE.body * LINE_HEIGHT,
   });
 }
 
@@ -168,8 +173,9 @@ function addHeading(slide, block, r) {
     bold: true,
     valign: 'top',
     ...(block.align ? { align: block.align } : {}),
-    // multi-line message: same line height as the CSS .slot-heading (1.3)
-    ...(block.size ? { lineSpacingMultiple: 1.3 } : {}),
+    // multi-line message: same line height as the CSS .slot-heading (1.3),
+    // in exact points (spcPts) — see addPara on why never a multiple
+    ...(block.size ? { lineSpacing: block.size * 1.3 } : {}),
   });
 }
 
@@ -194,6 +200,13 @@ function addBullets(slide, block, r) {
         options: { fontFace: FONTS.body, color: block.color ?? COLORS.neutralPrimary },
       });
     }
+    if (it.level) {
+      // nested items: same size and pitch as the HTML (.bullets ul ul)
+      itemRuns.forEach((run) => {
+        run.options.fontSize = TYPE.bulletNested;
+      });
+      itemRuns[0].options.lineSpacing = TYPE.bulletNested * 1.3;
+    }
     itemRuns[0] = {
       ...itemRuns[0],
       options: {
@@ -222,8 +235,10 @@ function addBullets(slide, block, r) {
     fontFace: FONTS.body,
     color: block.color ?? COLORS.neutralPrimary,
     valign: 'top',
-    lineSpacingMultiple: 1.25,
-    paraSpaceAfter: 6,
+    // exact pitch and gap of the HTML (.bullets: line-height 1.3, li
+    // margin-bottom 6px) — spcPts + 4.5 pt (= 6 px); see addPara
+    lineSpacing: TYPE.bullet * 1.3,
+    paraSpaceAfter: 4.5,
   });
 }
 
@@ -259,7 +274,8 @@ function addCode(slide, block, r) {
     h: px(r.h - 2 * SPACE.xs),
     fontSize: TYPE.code,
     valign: 'top',
-    lineSpacingMultiple: 1.25,
+    // exact pitch of the HTML (.code line-height 1.3); see addPara
+    lineSpacing: TYPE.code * 1.3,
   });
 }
 
@@ -308,7 +324,13 @@ function addAlert(slide, block, r) {
   const runs = [
     {
       text: sem.label,
-      options: { bold: true, fontSize: TYPE.small, color: sem.text, breakLine: true },
+      options: {
+        bold: true,
+        fontSize: TYPE.small,
+        color: sem.text,
+        breakLine: true,
+        lineSpacing: TYPE.small * 1.3,
+      },
     },
   ];
   // outside ALERT_BLOCK_TYPES: ignored (height not reserved by blockHeight,
@@ -336,7 +358,9 @@ function addAlert(slide, block, r) {
     fontSize: TYPE.body,
     fontFace: FONTS.body,
     valign: 'top',
-    lineSpacingMultiple: 1.3,
+    // exact pitch of the HTML (.alert line-height 1.3); the label paragraph
+    // carries its own smaller pitch in its run options — see addPara
+    lineSpacing: TYPE.body * 1.3,
   });
 }
 
@@ -522,7 +546,8 @@ function addQuote(slide, block, r) {
     color: COLORS.neutralPrimary,
     fontFace: FONTS.body,
     valign: 'middle',
-    lineSpacingMultiple: LINE_HEIGHT,
+    // exact pitch of the HTML (.quote blockquote line-height 1.4); see addPara
+    lineSpacing: TYPE.quote * LINE_HEIGHT,
   });
   if (block.cite) {
     slide.addText(`— ${block.cite}`, {
@@ -598,7 +623,7 @@ function addMermaid(slide, block, r, ctx) {
   }
   // faithful fallback: source shown as a code block plus a caption
   addCode(slide, { type: 'code', lang: 'mermaid', source: block.source }, { ...r, h: r.h - 24 });
-  slide.addText('Mermaid diagram — install @mermaid-js/mermaid-cli for graphical rendering', {
+  slide.addText('Mermaid diagram — run `lutrin setup-mermaid` for graphical rendering', {
     x: px(r.x),
     y: px(r.y + r.h - 22),
     w: px(r.w),

package/vendor/mermaid/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 - 2022 Knut Sveidqvist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/vendor/mermaid/README.md

@@ -0,0 +1,44 @@
+# Vendored Mermaid
+
+`mermaid.min.js` — the standalone UMD bundle of [Mermaid](https://mermaid.js.org),
+copied verbatim from the npm package. MIT, see `LICENSE`.
+
+| | |
+|---|---|
+| Version | 11.16.0 |
+| Source | `mermaid@11.16.0/dist/mermaid.min.js` |
+| SHA-256 | `74d7c46dabca328c2294733910a8aa1ed0c37451776e8d5295da38a2b758fb9b` |
+
+## Why a copy in the repository rather than a dependency
+
+Mermaid needs a browser: it measures the text it lays out, so it cannot render
+without a layout engine. The two obvious ways to get one both cost far more
+than this file:
+
+- `@mermaid-js/mermaid-cli` pulls Puppeteer, which downloads a Chrome — 405 MB
+  of `node_modules` plus ~540 MB of browser, measured, on every install. That is
+  what made mermaid-cli an optional peer dependency nobody installs, and
+  therefore what made diagrams silently degrade to a text fallback on a fresh
+  machine.
+- Depending on `mermaid` itself installs 83 MB, of which 56 MB are source maps.
+  We load exactly one file out of it.
+
+So we take the one file. `browser.mjs` finds a browser already on the machine
+and `mermaid-render.mjs` loads this bundle into it; `@resvg/resvg-js`, already a
+dependency, turns the SVG into the PNG the .pptx needs.
+
+## Upgrading
+
+Version-bumping is a copy, and the two version markers must move together:
+
+```sh
+npm pack mermaid@<version>          # or npm i mermaid@<version> in a scratch dir
+cp .../mermaid/dist/mermaid.min.js packages/core/vendor/mermaid/
+shasum -a 256 packages/core/vendor/mermaid/mermaid.min.js
+```
+
+Then update the table above, the `@mermaid-js/mermaid-cli` peer range in
+`packages/core/package.json` (kept in step so both rendering paths speak the
+same Mermaid dialect), and `THIRD-PARTY-NOTICES.md`. `test/mermaid.test.mjs`
+asserts the bundle is present and that its recorded SHA-256 matches, so a
+half-finished upgrade fails the suite rather than shipping.