@lutrin/core 1.0.0 → 1.1.1

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) {
@@ -910,7 +910,14 @@ body{margin:0;background:#${C.underground2};font-family:"${FONTS.body}",-apple-s
 .el{position:absolute;margin:0}
 a{color:#${C.primary};text-decoration:none}
 a:hover{text-decoration:underline}
-code{font-family:"${FONTS.mono}",monospace;color:#${C.primaryDarker}}
+/* inline code — every surface property EXPLICIT, not only the ones the theme
+   cares about. The fragment mode injects this CSS into hosts (VS Code
+   webview, Obsidian) whose own default stylesheets give "code" a padded,
+   theme-colored chip (VS Code: --vscode-textPreformat-background); any
+   property left undeclared here is repainted by the host — dark chips under
+   dark editor themes, unreadable on a light slide. (No backticks in these
+   comments: we are inside a JS template literal.) */
+code{font-family:"${FONTS.mono}",monospace;color:#${C.primaryDarker};background:transparent;padding:0;border-radius:0}
 
 /* chrome of content slides */
 .slide-title{position:absolute;left:${PAGE.margin}px;top:${SPACE.lg}px;width:${PAGE.width - 2 * PAGE.margin}px;height:${PAGE.titleHeight - SPACE.lg - 8}px;display:flex;align-items:center;font-size:${TYPE.slideTitle}pt;font-weight:700;line-height:1.15}
@@ -969,7 +976,10 @@ code{font-family:"${FONTS.mono}",monospace;color:#${C.primaryDarker}}
 .tl-axis-v.tl-no-arrow{background-size:2px 100%}
 .tl-arrow-v{position:absolute;bottom:0;left:50%;transform:translateX(-50%);width:0;height:0;border-top:14px solid #${C.neutralStroke};border-left:7px solid transparent;border-right:7px solid transparent}
 .tl-dot{display:flex;align-items:center;justify-content:center;background:#${C.primary};color:#${C.ground};border:2px solid #${C.ground};border-radius:50%;font-size:${TYPE.metricLabel}pt;font-weight:700;box-sizing:border-box}
-.quote blockquote{position:absolute;left:96px;right:32px;top:0;bottom:64px;display:flex;align-items:center;margin:0;font-size:${TYPE.quote}pt;font-style:italic;line-height:1.4}
+/* same host-default hazard as "code" above: the webview paints blockquote
+   with --vscode-textBlockQuote-background and a left border — neutralized
+   explicitly */
+.quote blockquote{position:absolute;left:96px;right:32px;top:0;bottom:64px;display:flex;align-items:center;margin:0;padding:0;background:transparent;border:0;font-size:${TYPE.quote}pt;font-style:italic;line-height:1.4}
 .quote-mark{position:absolute;left:0;top:-10px;font-size:72pt;font-weight:700;color:#${C.primary};line-height:1}
 .quote figcaption{position:absolute;right:32px;bottom:12px;font-size:${TYPE.body}pt;color:#${C.neutralSecondary}}
 .img-contain{object-fit:contain}

package/src/pptx/fonts.mjs

@@ -52,22 +52,29 @@ const FSTYPE_OFFSET = 8;
 const FSTYPE_RESTRICTED = 0x0002; // "Restricted License embedding": no
 
 /**
- * fsType of an sfnt font whose header (offset table) starts at `base`.
+ * Table record of an sfnt font whose header (offset table) starts at `base`.
  * The header: version on 4 bytes, numTables on 2, then three binary-search
  * fields we ignore; the table records follow at +12, 16 bytes each (tag,
- * checksum, offset, length).
- * @returns {number|null} null if the font has no OS/2 table
+ * checksum, offset, length). Offsets are counted from the START OF THE FILE —
+ * that is what lets two fonts of a .ttc collection share a table.
+ * @returns {{offset:number,length:number}|null}
  */
-function sfntFsType(buf, base) {
+function sfntTable(buf, base, tag) {
   const numTables = buf.readUInt16BE(base + 4);
   for (let k = 0; k < numTables; k++) {
     const rec = base + 12 + k * 16;
-    if (buf.toString('latin1', rec, rec + 4) !== 'OS/2') continue;
-    return buf.readUInt16BE(buf.readUInt32BE(rec + 8) + FSTYPE_OFFSET);
+    if (buf.toString('latin1', rec, rec + 4) === tag)
+      return { offset: buf.readUInt32BE(rec + 8), length: buf.readUInt32BE(rec + 12) };
   }
   return null;
 }
 
+/** fsType of an sfnt font. @returns {number|null} null without an OS/2 table */
+function sfntFsType(buf, base) {
+  const os2 = sfntTable(buf, base, 'OS/2');
+  return os2 ? buf.readUInt16BE(os2.offset + FSTYPE_OFFSET) : null;
+}
+
 /**
  * Reads the embedding permission declared by a font file.
  *
@@ -106,6 +113,99 @@ export function readFsType(file) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Embedded-font identity: the family name and style bits Windows matches by
+// ---------------------------------------------------------------------------
+
+/** fsSelection sits at +62 in the OS/2 table (after the vendor tag);
+ *  macStyle at +44 in head. Bit layouts differ: fsSelection carries italic in
+ *  bit 0 and bold in bit 5, macStyle bold in bit 0 and italic in bit 1. */
+const FSSELECTION_OFFSET = 62;
+const FSSELECTION_ITALIC = 0x01;
+const FSSELECTION_BOLD = 0x20;
+const MACSTYLE_OFFSET = 44;
+const MACSTYLE_BOLD = 0x01;
+const MACSTYLE_ITALIC = 0x02;
+
+/**
+ * The identity PowerPoint on Windows will match the embedded font by.
+ *
+ * GDI knows nothing of the `typeface` we write around the fntdata part: it
+ * registers the font under ITS OWN family name — name table, nameID 1, the
+ * Windows platform (3) records, UTF-16BE — and pairs the four styles of a
+ * family through the bold/italic bits (OS/2 fsSelection, head macStyle as a
+ * fallback). NameID 16, the "typographic family" that lets macOS group
+ * single-style webfont families under one name, is precisely what GDI does
+ * NOT read — which is how a deck can be flawless on the Mac that produced it
+ * and greet every Windows recipient with "unable to install embedded fonts".
+ *
+ * @param {string} file path to a .ttf, .otf or .ttc (first font read)
+ * @returns {{family:string|null,bold:boolean,italic:boolean}|null}
+ *          null if the file cannot be read at all; `family` null when the
+ *          font carries no Windows-platform family record (nothing to check).
+ */
+export function readFontIdentity(file) {
+  let buf;
+  try {
+    buf = fs.readFileSync(file);
+  } catch {
+    return null;
+  }
+  try {
+    const base = buf.toString('latin1', 0, 4) === 'ttcf' ? buf.readUInt32BE(12) : 0;
+
+    let family = null;
+    const name = sfntTable(buf, base, 'name');
+    if (name) {
+      const count = buf.readUInt16BE(name.offset + 2);
+      const storage = name.offset + buf.readUInt16BE(name.offset + 4);
+      let candidate = null; // any Windows record; an en-US one wins
+      for (let k = 0; k < count; k++) {
+        const rec = name.offset + 6 + k * 12;
+        const platform = buf.readUInt16BE(rec);
+        const language = buf.readUInt16BE(rec + 4);
+        const nameId = buf.readUInt16BE(rec + 6);
+        if (nameId !== 1 || (platform !== 3 && platform !== 0)) continue;
+        const at = storage + buf.readUInt16BE(rec + 10);
+        // copy before swap16(): it swaps IN PLACE and subarray() is a view
+        const value = Buffer.from(buf.subarray(at, at + buf.readUInt16BE(rec + 8)))
+          .swap16() // UTF-16BE in the file, utf16le for Buffer
+          .toString('utf16le');
+        if (platform === 3 && language === 0x409) {
+          candidate = value;
+          break;
+        }
+        candidate ??= value;
+      }
+      family = candidate;
+    }
+
+    let bold = false;
+    let italic = false;
+    const os2 = sfntTable(buf, base, 'OS/2');
+    if (os2 && os2.length >= FSSELECTION_OFFSET + 2) {
+      const fsSelection = buf.readUInt16BE(os2.offset + FSSELECTION_OFFSET);
+      bold = Boolean(fsSelection & FSSELECTION_BOLD);
+      italic = Boolean(fsSelection & FSSELECTION_ITALIC);
+    } else {
+      const head = sfntTable(buf, base, 'head');
+      if (head) {
+        const macStyle = buf.readUInt16BE(head.offset + MACSTYLE_OFFSET);
+        bold = Boolean(macStyle & MACSTYLE_BOLD);
+        italic = Boolean(macStyle & MACSTYLE_ITALIC);
+      }
+    }
+    return { family, bold, italic };
+  } catch {
+    // offset out of bounds, truncated table: malformed font file
+    return null;
+  }
+}
+
+/** Same string as far as Windows font matching cares: GDI compares family
+ *  names case-insensitively, and "é" may travel composed or decomposed. */
+const sameFamily = (a, b) => a.normalize('NFC').toLowerCase() === b.normalize('NFC').toLowerCase();
+
 /**
  * Embeds the brand font into a .pptx already written to disk.
  * Idempotent; touches nothing if the TTFs are absent.
@@ -123,7 +223,7 @@ export async function embedFonts(pptxPath) {
 
   // license filter: what is refused does not go into the deliverable, and the
   // author learns it here rather than by receiving a cease-and-desist
-  const variants = present.filter((v) => {
+  const licensed = present.filter((v) => {
     const fsType = readFsType(v.file);
     if (fsType == null) {
       warnings.push(
@@ -140,6 +240,44 @@ export async function embedFonts(pptxPath) {
     return true;
   });
 
+  // GDI coherence filter: Windows matches an embedded variant by the font's
+  // OWN identity (readFontIdentity), never by the typeface we declare around
+  // it. Webfonts commonly ship each weight as its own single-style family —
+  // the CSS @font-face re-groups them, macOS re-groups them through nameID 16,
+  // and GDI does neither: embedded as they are, every Windows recipient gets
+  // the "unable to install some embedded fonts / general failure" dialog at
+  // opening and reads the deck in the fallback font. Such a variant is NOT
+  // embedded — the deck keeps the documented installed-font fallback — and
+  // the author learns which table to rebuild, here rather than from a user's
+  // screenshot.
+  const STYLE_OF = {
+    regular: { bold: false, italic: false },
+    bold: { bold: true, italic: false },
+    italic: { bold: false, italic: true },
+  };
+  const variants = licensed.filter((v) => {
+    const id = readFontIdentity(v.file);
+    // unreadable or nameless: nothing to check against — the benefit of the
+    // doubt, same side as the unreadable fsType above
+    if (!id?.family) return true;
+    if (!sameFamily(id.family, FONTS.body)) {
+      warnings.push(
+        `Font "${path.basename(v.file)}" (${v.key}): its Windows family name is "${id.family}" while the theme declares "${FONTS.body}" — PowerPoint on Windows matches by that name and would fail to install the font at every recipient ("unable to install embedded fonts"). Not embedded; rebuild the font's name table (nameID 1) as "${FONTS.body}", or point fonts.files at a desktop cut of the family.`,
+      );
+      return false;
+    }
+    const want = STYLE_OF[v.key];
+    if (id.bold !== want.bold || id.italic !== want.italic) {
+      const said = (f) =>
+        [f.bold && 'bold', f.italic && 'italic'].filter(Boolean).join('+') || 'regular';
+      warnings.push(
+        `Font "${path.basename(v.file)}" (${v.key}): its style bits say "${said(id)}" where the ${v.key} slot requires "${said(want)}" — Windows pairs the styles of a family by those bits (OS/2 fsSelection, head macStyle) and would fail to install the font at every recipient. Not embedded; rebuild the font's style bits for the slot.`,
+      );
+      return false;
+    }
+    return true;
+  });
+
   if (!variants.length) return { count: 0, warnings };
 
   const zip = await JSZip.loadAsync(fs.readFileSync(pptxPath));