@bendyline/squisq-formats 1.2.2 → 1.3.0

package/src/__tests__/plainHtmlBundle.test.ts

@@ -0,0 +1,235 @@
+/**
+ * Tests for the recursive plain-HTML bundle export
+ * (`markdownDocsToPlainHtmlBundle`).
+ *
+ * Each test sets up an in-memory "container" — a `Map<path, string>`
+ * for markdown sources and a `Map<path, ArrayBuffer>` for binary
+ * assets — wires it up as the `readDocument` / `readBinary` callbacks,
+ * exports the bundle, and inspects the resulting JSZip.
+ */
+
+import { describe, it, expect } from 'vitest';
+import JSZip from 'jszip';
+import { markdownDocsToPlainHtmlBundle } from '../html/plainHtmlBundle';
+
+/** Helper to read a Blob as Uint8Array (works in jsdom). */
+async function blobToUint8Array(blob: Blob): Promise<Uint8Array> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(new Uint8Array(reader.result as ArrayBuffer));
+    reader.onerror = () => reject(reader.error);
+    reader.readAsArrayBuffer(blob);
+  });
+}
+
+function makeContainer(docs: Record<string, string>, binaries: Record<string, ArrayBuffer> = {}) {
+  return {
+    readDocument: async (p: string) => (p in docs ? docs[p] : null),
+    readBinary: async (p: string) => (p in binaries ? binaries[p] : null),
+  };
+}
+
+async function readZipPath(blob: Blob, path: string): Promise<string | null> {
+  const zip = await JSZip.loadAsync(await blobToUint8Array(blob));
+  const file = zip.file(path);
+  return file ? file.async('text') : null;
+}
+
+async function listZipPaths(blob: Blob): Promise<string[]> {
+  const zip = await JSZip.loadAsync(await blobToUint8Array(blob));
+  // JSZip emits implicit directory entries (paths ending in `/`) when
+  // any file lives in a subfolder. We're testing file content; the
+  // directory placeholders are noise.
+  return Object.keys(zip.files)
+    .filter((p) => !p.endsWith('/'))
+    .sort();
+}
+
+describe('markdownDocsToPlainHtmlBundle', () => {
+  it('exports a single doc with no links to a 1-file html', async () => {
+    const c = makeContainer({ 'home.md': '# Home\n\nJust a single page.' });
+    const blob = await markdownDocsToPlainHtmlBundle({
+      entryPath: 'home.md',
+      ...c,
+    });
+    const paths = await listZipPaths(blob);
+    expect(paths).toEqual(['home.html']);
+    const html = await readZipPath(blob, 'home.html');
+    expect(html).toContain('<h1>Home</h1>');
+  });
+
+  it('follows a linear chain home.md → resume.md and bundles both', async () => {
+    const c = makeContainer({
+      'home.md': '# Home\n\nMy [resume](resume.md) is here.',
+      'resume.md': '# Resume\n\nWork history.',
+    });
+    const blob = await markdownDocsToPlainHtmlBundle({
+      entryPath: 'home.md',
+      ...c,
+    });
+    const paths = await listZipPaths(blob);
+    expect(paths).toContain('home.html');
+    expect(paths).toContain('resume.html');
+    const home = await readZipPath(blob, 'home.html');
+    // The .md link is rewritten to .html
+    expect(home).toContain('href="resume.html"');
+    expect(home).not.toContain('href="resume.md"');
+    const resume = await readZipPath(blob, 'resume.html');
+    expect(resume).toContain('<h1>Resume</h1>');
+  });
+
+  it('cycle-detects so a.md ↔ b.md does not loop', async () => {
+    const c = makeContainer({
+      'a.md': '# A\n\n[b](b.md)',
+      'b.md': '# B\n\n[a](a.md)',
+    });
+    const blob = await markdownDocsToPlainHtmlBundle({
+      entryPath: 'a.md',
+      ...c,
+    });
+    const paths = await listZipPaths(blob);
+    expect(paths.sort()).toEqual(['a.html', 'b.html']);
+  });
+
+  it('does NOT follow ../parent.md (scope rule)', async () => {
+    const c = makeContainer({
+      'subdir/intro.md': '# Intro\n\nLink to [parent](../outside.md).',
+      'outside.md': '# Outside',
+    });
+    const blob = await markdownDocsToPlainHtmlBundle({
+      entryPath: 'subdir/intro.md',
+      ...c,
+    });
+    const paths = await listZipPaths(blob);
+    // `outside.md` lives ABOVE the entry doc's directory → out of scope.
+    expect(paths).toEqual(['subdir/intro.html']);
+    const intro = await readZipPath(blob, 'subdir/intro.html');
+    // The link is not rewritten to .html — it stays as authored.
+    expect(intro).toContain('href="../outside.md"');
+  });
+
+  it('follows links into subfolders (still in scope)', async () => {
+    const c = makeContainer({
+      'home.md': '# Home\n\n[chapter 1](chapters/one.md)',
+      'chapters/one.md': '# Chapter 1\n\nContent.',
+    });
+    const blob = await markdownDocsToPlainHtmlBundle({
+      entryPath: 'home.md',
+      ...c,
+    });
+    const paths = await listZipPaths(blob);
+    expect(paths).toContain('home.html');
+    expect(paths).toContain('chapters/one.html');
+    const home = await readZipPath(blob, 'home.html');
+    expect(home).toContain('href="chapters/one.html"');
+  });
+
+  it('preserves #anchor fragments when rewriting .md → .html', async () => {
+    const c = makeContainer({
+      'home.md': '# Home\n\nJump to [exp](resume.md#experience).',
+      'resume.md': '# Resume\n\n## Experience',
+    });
+    const blob = await markdownDocsToPlainHtmlBundle({
+      entryPath: 'home.md',
+      ...c,
+    });
+    const home = await readZipPath(blob, 'home.html');
+    expect(home).toContain('href="resume.html#experience"');
+  });
+
+  it('aborts with an error when a linked doc cannot be read', async () => {
+    const c = makeContainer({
+      'home.md': '# Home\n\n[missing](does-not-exist.md)',
+    });
+    await expect(markdownDocsToPlainHtmlBundle({ entryPath: 'home.md', ...c })).rejects.toThrow(
+      /failed to read.*does-not-exist\.md/i,
+    );
+  });
+
+  it('emits image assets at their authored relative paths inside the zip', async () => {
+    const png = new Uint8Array([0x89, 0x50, 0x4e, 0x47]).buffer;
+    const c = makeContainer(
+      { 'home.md': '# Home\n\n![hero](home_files/hero.png)' },
+      { 'home_files/hero.png': png },
+    );
+    const blob = await markdownDocsToPlainHtmlBundle({
+      entryPath: 'home.md',
+      ...c,
+    });
+    const paths = await listZipPaths(blob);
+    expect(paths).toContain('home_files/hero.png');
+    const home = await readZipPath(blob, 'home.html');
+    expect(home).toContain('src="home_files/hero.png"');
+  });
+
+  it('linked sub-folder docs reference parent assets via ../', async () => {
+    // The doc lives in subdir/, the image in home_files/, so the
+    // rewritten src should walk up one level.
+    const png = new Uint8Array([0x89]).buffer;
+    const c = makeContainer(
+      {
+        'home.md': '# Home\n\n[deep](chapters/one.md)',
+        'chapters/one.md': '# One\n\n![shared](../home_files/hero.png)',
+      },
+      { 'home_files/hero.png': png },
+    );
+    const blob = await markdownDocsToPlainHtmlBundle({
+      entryPath: 'home.md',
+      ...c,
+    });
+    const paths = await listZipPaths(blob);
+    expect(paths).toContain('home_files/hero.png');
+    const one = await readZipPath(blob, 'chapters/one.html');
+    expect(one).toContain('src="../home_files/hero.png"');
+  });
+
+  it('passes the entry title through; sibling docs derive title from the shallowest heading', async () => {
+    const c = makeContainer({
+      'home.md': '# Home\n\n[resume](resume.md)\n\n[notes](notes.md)',
+      'resume.md': '# Resume',
+      'notes.md': 'Just a paragraph.',
+    });
+    const blob = await markdownDocsToPlainHtmlBundle({
+      entryPath: 'home.md',
+      title: 'My Home Page',
+      ...c,
+    });
+    const home = await readZipPath(blob, 'home.html');
+    expect(home).toContain('<title>My Home Page</title>');
+    // Heading-bearing sibling uses its heading text, not the filename.
+    const resume = await readZipPath(blob, 'resume.html');
+    expect(resume).toContain('<title>Resume</title>');
+    // Heading-less sibling falls back to the filename.
+    const notes = await readZipPath(blob, 'notes.html');
+    expect(notes).toContain('<title>notes</title>');
+  });
+
+  it('respects maxDepth — depth 0 means entry only, no link following', async () => {
+    const c = makeContainer({
+      'home.md': '# Home\n\n[resume](resume.md)',
+      'resume.md': '# Resume',
+    });
+    const blob = await markdownDocsToPlainHtmlBundle({
+      entryPath: 'home.md',
+      maxDepth: 0,
+      ...c,
+    });
+    const paths = await listZipPaths(blob);
+    expect(paths).toEqual(['home.html']);
+  });
+
+  it('does not rewrite external links (http://) or fragment-only links', async () => {
+    const c = makeContainer({
+      'home.md':
+        '[google](https://google.com)\n\n[#section](#somewhere)\n\n[email](mailto:me@example.com)',
+    });
+    const blob = await markdownDocsToPlainHtmlBundle({
+      entryPath: 'home.md',
+      ...c,
+    });
+    const home = await readZipPath(blob, 'home.html');
+    expect(home).toContain('href="https://google.com"');
+    expect(home).toContain('href="#somewhere"');
+    expect(home).toContain('href="mailto:me@example.com"');
+  });
+});

package/src/docx/export.ts

@@ -18,7 +18,7 @@
  */
 
 import type { Doc, Theme } from '@bendyline/squisq/schemas';
-import { resolveTheme } from '@bendyline/squisq/schemas';
+import { resolveTheme, resolveFontFamily } from '@bendyline/squisq/schemas';
 import { docToMarkdown } from '@bendyline/squisq/doc';
 import type {
   MarkdownDocument,
@@ -40,6 +40,7 @@ import type {
   MarkdownImage,
   MarkdownFootnoteReference,
 } from '@bendyline/squisq/markdown';
+import { readFrontmatterThemeId } from '@bendyline/squisq/markdown';
 
 import { createPackage } from '../ooxml/writer.js';
 import { xmlDeclaration, escapeXml } from '../ooxml/xmlUtils.js';
@@ -117,9 +118,17 @@ export async function markdownDocToDocx(
   doc: MarkdownDocument,
   options: DocxExportOptions = {},
 ): Promise<ArrayBuffer> {
-  const ctx = new ExportContext(options);
+  // Mirror the PPTX export: fall back to the doc's frontmatter themeId
+  // when the caller didn't pass one explicitly. Lets the editor's
+  // `squisq-theme: …` frontmatter flow straight through without each
+  // host wiring its own resolution.
+  const resolvedOptions: DocxExportOptions =
+    options.themeId !== undefined
+      ? options
+      : { ...options, themeId: readFrontmatterThemeId(doc.frontmatter) };
+  const ctx = new ExportContext(resolvedOptions);
   const bodyXml = convertBlocks(doc.children, ctx);
-  return buildDocxPackage(bodyXml, ctx, options);
+  return buildDocxPackage(bodyXml, ctx, resolvedOptions);
 }
 
 /**
@@ -185,6 +194,12 @@ class ExportContext {
   readonly fontSize: number;
   /** Heading text color (hex without #), or undefined for default */
   readonly headingColor: string | undefined;
+  /** Body text color (hex without #), or undefined for default */
+  readonly bodyColor: string | undefined;
+  /** Muted text color (hex without #), used by Quote style. Undefined for default. */
+  readonly mutedColor: string | undefined;
+  /** Page background color (hex without #), or undefined for default white. */
+  readonly backgroundColor: string | undefined;
 
   /** Pre-resolved image data keyed by markdown image URL */
   readonly resolvedImages: Map<string, { data: ArrayBuffer | Uint8Array; contentType: string }>;
@@ -195,15 +210,26 @@ class ExportContext {
     let themeFont: string | undefined;
     let themeTitleFont: string | undefined;
     let themeHeadingColor: string | undefined;
+    let themeBodyColor: string | undefined;
+    let themeMutedColor: string | undefined;
+    let themeBackgroundColor: string | undefined;
 
     if (options.themeId) {
       const theme: Theme = resolveTheme(options.themeId);
-      themeFont = theme.typography?.bodyFontFamily;
-      themeTitleFont = theme.typography?.titleFontFamily;
-      if (theme.colors?.primary) {
-        const c = theme.colors.primary;
-        themeHeadingColor = c.startsWith('#') ? c.slice(1) : c;
-      }
+      // Theme fonts arrive as CSS stacks (e.g. `"Oswald", Impact,
+      // "Arial Black", sans-serif`). Word's `w:ascii` attribute is a
+      // single font name — passing the whole stack is treated as a
+      // bogus literal name and Word falls through to Calibri. Take the
+      // first concrete name from the stack so Word can resolve it (or
+      // gracefully fall back to its own default if the font isn't
+      // installed on the reader's machine).
+      themeFont = firstFontFromStack(resolveFontFamily(theme.typography?.bodyFont, ''));
+      themeTitleFont = firstFontFromStack(resolveFontFamily(theme.typography?.titleFont, ''));
+      const stripHash = (c: string) => (c.startsWith('#') ? c.slice(1) : c);
+      if (theme.colors?.primary) themeHeadingColor = stripHash(theme.colors.primary);
+      if (theme.colors?.text) themeBodyColor = stripHash(theme.colors.text);
+      if (theme.colors?.textMuted) themeMutedColor = stripHash(theme.colors.textMuted);
+      if (theme.colors?.background) themeBackgroundColor = stripHash(theme.colors.background);
     }
 
     this.font = options.defaultFont ?? themeFont ?? DEFAULT_FONT;
@@ -212,6 +238,9 @@ class ExportContext {
       ? options.defaultFontSize * 2
       : DEFAULT_FONT_SIZE_HALF_POINTS;
     this.headingColor = themeHeadingColor;
+    this.bodyColor = themeBodyColor;
+    this.mutedColor = themeMutedColor;
+    this.backgroundColor = themeBackgroundColor;
     this.resolvedImages = options.images ?? new Map();
   }
 
@@ -277,6 +306,42 @@ interface NumberingDef {
   ordered: boolean;
 }
 
+/**
+ * Pull the first concrete font name out of a CSS-style stack.
+ *
+ * `resolveFontFamily` returns CSS values like `"Oswald", Impact,
+ * "Arial Black", sans-serif`. Word's `w:ascii` / `w:hAnsi` attributes
+ * expect a single font name — feeding the whole stack causes Word to
+ * fall back to its default font instead of any of the named faces.
+ * We pick the first non-generic name (skipping `sans-serif`, `serif`,
+ * `monospace`, etc.) and strip the surrounding quotes that CSS lets
+ * you wrap multi-word family names in.
+ */
+function firstFontFromStack(stack: string): string {
+  if (!stack) return '';
+  const generics = new Set([
+    'sans-serif',
+    'serif',
+    'monospace',
+    'system-ui',
+    'cursive',
+    'fantasy',
+    'ui-serif',
+    'ui-sans-serif',
+    'ui-monospace',
+    'ui-rounded',
+    'inherit',
+    'initial',
+  ]);
+  for (const raw of stack.split(',')) {
+    const name = raw.trim().replace(/^["']|["']$/g, '');
+    if (!name) continue;
+    if (generics.has(name.toLowerCase())) continue;
+    return name;
+  }
+  return '';
+}
+
 // ============================================
 // Block Conversion
 // ============================================
@@ -324,16 +389,33 @@ function convertHeading(node: MarkdownHeading, ctx: ExportContext): string {
 }
 
 function convertParagraph(node: MarkdownParagraph, ctx: ExportContext): string {
-  const runs = convertInlines(node.children, ctx);
+  // Force body color on every run rather than relying on `Normal` /
+  // `rPrDefault` style inheritance — see InlineFormat.color comment.
+  // Headings render via `convertHeading` and skip this path so the
+  // heading style's own color wins.
+  const runs = convertInlines(node.children, ctx, bodyFormat(ctx));
   return `<w:p>${runs}</w:p>`;
 }
 
+/** Default inline format for body-text contexts (paragraphs, list items,
+ *  blockquote bodies, table cells). Carries the theme body color so runs
+ *  render in the right color regardless of style-resolution quirks. */
+function bodyFormat(ctx: ExportContext): InlineFormat {
+  return ctx.bodyColor ? { color: ctx.bodyColor } : {};
+}
+
 function convertBlockquote(node: MarkdownBlockquote, ctx: ExportContext): string {
   // Render each child block as a paragraph with Quote style
   const parts: string[] = [];
   for (const child of node.children) {
     if (child.type === 'paragraph') {
-      const runs = convertInlines(child.children, ctx);
+      // Use the theme's muted color when set (Quote style already
+      // declares it but explicit run-level color survives Word's
+      // style overrides — see InlineFormat.color comment).
+      const quoteFormat: InlineFormat = ctx.mutedColor
+        ? { color: ctx.mutedColor }
+        : bodyFormat(ctx);
+      const runs = convertInlines(child.children, ctx, quoteFormat);
       parts.push(
         `<w:p>` +
           `<w:pPr><w:pStyle w:val="Quote"/>` +
@@ -369,7 +451,7 @@ function convertListItem(
   const parts: string[] = [];
   for (const child of item.children) {
     if (child.type === 'paragraph') {
-      const runs = convertInlines(child.children, ctx);
+      const runs = convertInlines(child.children, ctx, bodyFormat(ctx));
       parts.push(
         `<w:p>` +
           `<w:pPr>` +
@@ -466,7 +548,7 @@ function convertTableCell(
   isHeader: boolean,
   align: 'left' | 'right' | 'center' | null,
 ): string {
-  const runs = convertInlines(cell.children, ctx);
+  const runs = convertInlines(cell.children, ctx, bodyFormat(ctx));
   const rPr = isHeader ? '<w:rPr><w:b/></w:rPr>' : '';
   const jcMap = { left: 'left', center: 'center', right: 'right' };
   const jc = align ? `<w:jc w:val="${jcMap[align]}"/>` : '';
@@ -511,7 +593,7 @@ function convertFootnoteDefinition(node: MarkdownFootnoteDefinition, ctx: Export
   const bodyParts: string[] = [];
   for (const child of node.children) {
     if (child.type === 'paragraph') {
-      const runs = convertInlines(child.children, ctx);
+      const runs = convertInlines(child.children, ctx, bodyFormat(ctx));
       bodyParts.push(`<w:p>${runs}</w:p>`);
     }
   }
@@ -539,6 +621,14 @@ interface InlineFormat {
   italic?: boolean;
   strike?: boolean;
   code?: boolean;
+  /**
+   * Explicit run color (hex without `#`). When set, every emitted run
+   * gets `<w:color>` directly in its `<w:rPr>` — bypassing Word's style
+   * inheritance, which some Word configurations silently override.
+   * Body paragraphs pass `ctx.bodyColor` here; headings leave it unset
+   * so the heading style's own color wins.
+   */
+  color?: string;
 }
 
 function convertInlines(
@@ -590,6 +680,7 @@ function makeRun(text: string, format: InlineFormat): string {
   if (format.bold) rPrParts.push('<w:b/>');
   if (format.italic) rPrParts.push('<w:i/>');
   if (format.strike) rPrParts.push('<w:strike/>');
+  if (format.color) rPrParts.push(`<w:color w:val="${format.color}"/>`);
   if (format.code) {
     rPrParts.push(
       `<w:rFonts w:ascii="${DEFAULT_CODE_FONT}" w:hAnsi="${DEFAULT_CODE_FONT}"/>`,
@@ -789,7 +880,7 @@ async function buildDocxPackage(
   const footnotesRelId = `rId${relCounter++}`;
 
   // --- word/document.xml ---
-  const documentXml = buildDocumentXml(bodyXml);
+  const documentXml = buildDocumentXml(bodyXml, ctx.backgroundColor);
   pkg.addPart('word/document.xml', documentXml, CONTENT_TYPE_DOCX_DOCUMENT);
 
   // --- word/styles.xml ---
@@ -797,7 +888,10 @@ async function buildDocxPackage(
   pkg.addPart('word/styles.xml', stylesXml, CONTENT_TYPE_DOCX_STYLES);
 
   // --- word/settings.xml ---
-  const settingsXml = buildSettingsXml();
+  // `displayBackgroundShape` is what makes Word actually paint the
+  // `<w:background>` element from document.xml on screen + print.
+  // Without it the bg color is in the file but invisible.
+  const settingsXml = buildSettingsXml(ctx.backgroundColor !== undefined);
   pkg.addPart('word/settings.xml', settingsXml, CONTENT_TYPE_DOCX_SETTINGS);
 
   // --- word/fontTable.xml ---
@@ -889,7 +983,11 @@ async function buildDocxPackage(
 // XML Part Generators
 // ============================================
 
-function buildDocumentXml(bodyXml: string): string {
+function buildDocumentXml(bodyXml: string, backgroundColor?: string): string {
+  // `<w:background>` must be the FIRST child of `<w:document>` per the
+  // WordprocessingML schema. Word also requires `<w:displayBackgroundShape/>`
+  // in settings.xml before the bg actually paints (see buildSettingsXml).
+  const backgroundEl = backgroundColor ? `<w:background w:color="${backgroundColor}"/>` : '';
   return (
     xmlDeclaration() +
     `<w:document` +
@@ -903,6 +1001,7 @@ function buildDocumentXml(bodyXml: string): string {
     ` xmlns:w10="urn:schemas-microsoft-com:office:word"` +
     ` xmlns:w="${NS_WML}"` +
     ` xmlns:wne="http://schemas.microsoft.com/office/word/2006/wordml">` +
+    backgroundEl +
     `<w:body>` +
     bodyXml +
     `<w:sectPr>` +
@@ -918,6 +1017,16 @@ function buildDocumentXml(bodyXml: string): string {
 function buildStylesXml(options: DocxExportOptions, ctx: ExportContext): string {
   const font = ctx.font;
   const headingFont = ctx.headingFont;
+  // Body color from the theme's `text`. We set it on BOTH the
+  // `<w:rPrDefault>` (for any rogue run that doesn't inherit Normal) and
+  // on the `Normal` style itself. Setting it only on rPrDefault was
+  // experimentally insufficient — Word's resolved formatting in Print
+  // Layout view ignored the docDefault color for direct-typed body
+  // paragraphs even though headings (with explicit rPr) honored their
+  // own color. Setting it on Normal puts the color one level higher in
+  // the precedence chain (paragraph-style > docDefaults) so it sticks.
+  const bodyColorXml = ctx.bodyColor ? `<w:color w:val="${ctx.bodyColor}"/>` : '';
+  const quoteColor = ctx.mutedColor ?? '404040';
 
   return (
     xmlDeclaration() +
@@ -926,24 +1035,29 @@ function buildStylesXml(options: DocxExportOptions, ctx: ExportContext): string
     `<w:docDefaults>` +
     `<w:rPrDefault><w:rPr>` +
     `<w:rFonts w:ascii="${escapeXml(font)}" w:hAnsi="${escapeXml(font)}" w:eastAsia="${escapeXml(font)}" w:cs="${escapeXml(font)}"/>` +
+    bodyColorXml +
     `<w:sz w:val="${DEFAULT_FONT_SIZE_HALF_POINTS}"/>` +
     `<w:szCs w:val="${DEFAULT_FONT_SIZE_HALF_POINTS}"/>` +
     `</w:rPr></w:rPrDefault>` +
     `<w:pPrDefault/>` +
     `</w:docDefaults>` +
-    // Normal style
+    // Normal style — carries the body color explicitly so direct-typed
+    // body paragraphs render in the theme's text color in every Word
+    // view (not just Web Layout).
     `<w:style w:type="paragraph" w:default="1" w:styleId="Normal">` +
     `<w:name w:val="Normal"/>` +
     `<w:qFormat/>` +
+    (bodyColorXml ? `<w:rPr>${bodyColorXml}</w:rPr>` : '') +
     `</w:style>` +
     // Heading styles
     buildHeadingStyles(headingFont, ctx.headingColor) +
-    // Quote style
+    // Quote style — muted text color from theme.textMuted (falls back
+    // to a neutral grey when no theme is supplied).
     `<w:style w:type="paragraph" w:styleId="Quote">` +
     `<w:name w:val="Quote"/>` +
     `<w:basedOn w:val="Normal"/>` +
     `<w:pPr><w:ind w:left="720"/></w:pPr>` +
-    `<w:rPr><w:i/><w:color w:val="404040"/></w:rPr>` +
+    `<w:rPr><w:i/><w:color w:val="${quoteColor}"/></w:rPr>` +
     `</w:style>` +
     // Code style
     `<w:style w:type="paragraph" w:styleId="Code">` +
@@ -1013,12 +1127,33 @@ function buildHeadingStyles(headingFont: string, headingColor?: string): string
   return result;
 }
 
-function buildSettingsXml(): string {
+function buildSettingsXml(displayBackground: boolean): string {
+  // `<w:compat>` with `compatibilityMode=15` is what tells Word "this
+  // is a Word 2016+ .docx, render with modern features." Without it,
+  // Word opens the file in Compatibility Mode and silently disables
+  // newer behaviors — including page-background rendering in Print
+  // Layout view and several default style precedence rules. The other
+  // compatSetting flags match what Word 2016+ writes by default.
+  const compatXml =
+    `<w:compat>` +
+    `<w:compatSetting w:name="compatibilityMode" w:uri="http://schemas.microsoft.com/office/word" w:val="15"/>` +
+    `<w:compatSetting w:name="overrideTableStyleFontSizeAndJustification" w:uri="http://schemas.microsoft.com/office/word" w:val="1"/>` +
+    `<w:compatSetting w:name="enableOpenTypeFeatures" w:uri="http://schemas.microsoft.com/office/word" w:val="1"/>` +
+    `<w:compatSetting w:name="doNotFlipMirrorIndents" w:uri="http://schemas.microsoft.com/office/word" w:val="1"/>` +
+    `<w:compatSetting w:name="differentiateMultirowTableHeaders" w:uri="http://schemas.microsoft.com/office/word" w:val="1"/>` +
+    `</w:compat>`;
+  // Element order inside `<w:settings>` matters — ECMA-376 defines a
+  // strict sequence (`displayBackgroundShape` → `defaultTabStop` →
+  // `characterSpacingControl` → … → `compat`). Word silently drops
+  // out-of-order children, which is why `<w:background>` looks correct
+  // in the file but doesn't paint when opened.
   return (
     xmlDeclaration() +
     `<w:settings xmlns:w="${NS_WML}">` +
+    (displayBackground ? `<w:displayBackgroundShape/>` : '') +
     `<w:defaultTabStop w:val="720"/>` +
     `<w:characterSpacingControl w:val="doNotCompress"/>` +
+    compatXml +
     `</w:settings>`
   );
 }
@@ -1078,7 +1213,13 @@ function buildNumberingXml(ctx: ExportContext): string {
             `<w:lvlText w:val="${bullet}"/>` +
             `<w:lvlJc w:val="left"/>` +
             `<w:pPr><w:ind w:left="${720 * (lvl + 1)}" w:hanging="360"/></w:pPr>` +
-            `<w:rPr><w:rFonts w:ascii="Symbol" w:hAnsi="Symbol"/></w:rPr>` +
+            // Bullet glyph renders in the document's body font, not
+            // Word's legacy `Symbol` font. `Symbol` only maps codes
+            // 0x20-0xFF to Greek/math glyphs, so the Unicode bullets
+            // we use (U+2022, U+25E6, U+25AA) come out as "tofu"
+            // empty boxes when forced into Symbol. Every modern OS
+            // font has these codepoints, so omitting the font
+            // override gets a real bullet.
             `</w:lvl>`,
         );
       }

package/src/epub/export.ts

@@ -23,7 +23,7 @@
 
 import JSZip from 'jszip';
 import type { Doc, AudioSegment } from '@bendyline/squisq/schemas';
-import { resolveTheme } from '@bendyline/squisq/schemas';
+import { resolveTheme, resolveFontFamily } from '@bendyline/squisq/schemas';
 import type {
   MarkdownDocument,
   MarkdownBlockNode,
@@ -803,8 +803,8 @@ function generateStylesheet(themeId?: string): string {
   --epub-bg: ${theme.colors.background};
   --epub-text: ${theme.colors.text};
   --epub-primary: ${theme.colors.primary};
-  --epub-heading-font: ${theme.typography.titleFontFamily};
-  --epub-body-font: ${theme.typography.bodyFontFamily};`;
+  --epub-heading-font: ${resolveFontFamily(theme.typography.titleFont, 'serif')};
+  --epub-body-font: ${resolveFontFamily(theme.typography.bodyFont, 'sans-serif')};`;
   }
 
   return `/* Squisq EPUB Stylesheet */