@bendyline/squisq-formats 1.3.1 → 1.4.1

package/src/__tests__/csvImport.test.ts

@@ -0,0 +1,84 @@
+/**
+ * Tests for CSV import/export: csvToMarkdownDoc, markdownDocToCsv, parseCsv.
+ */
+
+import { describe, expect, it } from 'vitest';
+import type { MarkdownDocument, MarkdownTable, MarkdownText } from '@bendyline/squisq/markdown';
+import { csvToMarkdownDoc, markdownDocToCsv, parseCsv } from '../csv/index';
+
+function cellValue(table: MarkdownTable, row: number, col: number): string {
+  const cell = table.children[row]?.children[col];
+  const first = cell?.children[0] as MarkdownText | undefined;
+  return first?.value ?? '';
+}
+
+describe('parseCsv', () => {
+  it('parses quoted fields, escaped quotes, and embedded delimiters', () => {
+    const rows = parseCsv('a,b,c\n"x,y","he said ""hi""",z\n');
+    expect(rows).toEqual([
+      ['a', 'b', 'c'],
+      ['x,y', 'he said "hi"', 'z'],
+    ]);
+  });
+
+  it('handles CRLF line endings', () => {
+    expect(parseCsv('a,b\r\n1,2\r\n')).toEqual([
+      ['a', 'b'],
+      ['1', '2'],
+    ]);
+  });
+});
+
+describe('csvToMarkdownDoc', () => {
+  it('builds a table with a header row by default', async () => {
+    const doc = await csvToMarkdownDoc('Name,Age\nAlice,30\n"Bob, Jr.",40\n');
+    expect(doc.type).toBe('document');
+    const table = doc.children[0] as MarkdownTable;
+    expect(table.type).toBe('table');
+    expect(table.children).toHaveLength(3);
+    expect(table.children[0]!.children[0]!.isHeader).toBe(true);
+    expect(cellValue(table, 0, 0)).toBe('Name');
+    expect(cellValue(table, 0, 1)).toBe('Age');
+    expect(cellValue(table, 2, 0)).toBe('Bob, Jr.');
+    expect(cellValue(table, 2, 1)).toBe('40');
+  });
+
+  it('round-trips through markdownDocToCsv', async () => {
+    const csv = 'Name,Age\r\nAlice,30\r\n"Bob, Jr.",40';
+    const doc = await csvToMarkdownDoc(csv);
+    expect(markdownDocToCsv(doc)).toBe(csv);
+  });
+});
+
+describe('markdownDocToCsv tableIndex', () => {
+  async function docWithTwoTables(): Promise<MarkdownDocument> {
+    const first = await csvToMarkdownDoc('a,b\r\n1,2');
+    const second = await csvToMarkdownDoc('c,d\r\n3,4');
+    return { type: 'document', children: [...first.children, ...second.children] };
+  }
+
+  it('exports the first table by default', async () => {
+    const doc = await docWithTwoTables();
+    expect(markdownDocToCsv(doc)).toBe('a,b\r\n1,2');
+  });
+
+  it('picks the Nth table via tableIndex', async () => {
+    const doc = await docWithTwoTables();
+    expect(markdownDocToCsv(doc, { tableIndex: 0 })).toBe('a,b\r\n1,2');
+    expect(markdownDocToCsv(doc, { tableIndex: 1 })).toBe('c,d\r\n3,4');
+  });
+
+  it('throws a clear error for an out-of-range tableIndex', async () => {
+    const doc = await docWithTwoTables();
+    expect(() => markdownDocToCsv(doc, { tableIndex: 2 })).toThrow(
+      'CSV export: tableIndex 2 is out of range — the document contains 2 table(s).',
+    );
+    expect(() => markdownDocToCsv(doc, { tableIndex: -1 })).toThrow('out of range');
+  });
+
+  it('returns an empty string for a table-less document with the implicit default', () => {
+    const doc: MarkdownDocument = { type: 'document', children: [] };
+    expect(markdownDocToCsv(doc)).toBe('');
+    expect(() => markdownDocToCsv(doc, { tableIndex: 0 })).toThrow('out of range');
+  });
+});

package/src/__tests__/exportThemeReconciliation.test.ts

@@ -0,0 +1,87 @@
+/**
+ * Export theme reconciliation.
+ *
+ * Every export format must honor the theme the document selects in its
+ * frontmatter (`squisq-theme`) — including an inline custom theme stored in
+ * `squisq-custom-themes` — without an explicit `themeId` option. This guards
+ * the fix that made PDF/EPUB read the frontmatter theme like PPTX/DOCX/HTML,
+ * and that custom themes resolve doc-scoped in exports (no global register).
+ */
+
+import { describe, it, expect } from 'vitest';
+import JSZip from 'jszip';
+import { compileTheme } from '@bendyline/squisq/schemas';
+import { writeCustomThemesToFrontmatter } from '@bendyline/squisq/doc';
+import { parseMarkdown } from '@bendyline/squisq/markdown';
+import { markdownDocToPptx } from '../pptx/export';
+import { markdownDocToDocx } from '../docx/export';
+import { markdownDocToPdf } from '../pdf/export';
+import { markdownDocToEpub } from '../epub/export';
+import { markdownDocToPlainHtml } from '../html/plainHtml';
+
+const brand = compileTheme({
+  id: 'custom-brand',
+  name: 'Brand',
+  seedColors: { primary: '#ff0088', background: '#123456', text: '#abcdef' },
+});
+
+const withTheme = parseMarkdown(`---
+title: Audit
+squisq-theme: custom-brand
+squisq-custom-themes: ${writeCustomThemesToFrontmatter([brand])}
+---
+
+# Heading One
+
+Body with a [link](https://example.com).
+`);
+
+const noTheme = parseMarkdown('# Heading One\n\nBody.\n');
+
+/** Concatenate the text of every XML/CSS/HTML entry in a ZIP export. */
+async function zipText(buf: ArrayBuffer): Promise<string> {
+  const zip = await JSZip.loadAsync(buf);
+  let text = '';
+  for (const name of Object.keys(zip.files)) {
+    if (/\.(xml|css|html|xhtml|rels)$/i.test(name)) {
+      text += await zip.files[name].async('string');
+    }
+  }
+  return text.toLowerCase();
+}
+
+describe('export theme reconciliation (frontmatter-only custom theme)', () => {
+  it('HTML applies the frontmatter custom theme colors', () => {
+    const html = markdownDocToPlainHtml(withTheme, {}).toLowerCase();
+    expect(html).toContain('123456'); // background
+    expect(html).toContain('abcdef'); // text
+  });
+
+  it('PPTX applies the frontmatter custom theme colors', async () => {
+    const text = await zipText(await markdownDocToPptx(withTheme, {}));
+    expect(text).toContain('123456');
+  });
+
+  it('DOCX applies the frontmatter custom theme colors', async () => {
+    const text = await zipText(await markdownDocToDocx(withTheme, {}));
+    expect(text).toContain('123456');
+  });
+
+  it('EPUB applies the frontmatter custom theme colors (frontmatter fallback)', async () => {
+    const text = await zipText(await markdownDocToEpub(withTheme, {}));
+    expect(text).toContain('123456');
+  });
+
+  it('PDF themes from frontmatter — themed output differs from un-themed', async () => {
+    const themed = new Uint8Array(await markdownDocToPdf(withTheme, {}));
+    const plain = new Uint8Array(await markdownDocToPdf(noTheme, {}));
+    const differs = themed.length !== plain.length || !themed.every((b, i) => b === plain[i]);
+    expect(differs).toBe(true);
+  });
+
+  it('an explicit themeId option still overrides the frontmatter theme', async () => {
+    const bare = await zipText(await markdownDocToPptx(withTheme, { themeId: 'standard' }));
+    // The custom background must NOT appear when the caller forces 'standard'.
+    expect(bare).not.toContain('123456');
+  });
+});

package/src/__tests__/formatRegistry.test.ts

@@ -0,0 +1,174 @@
+/**
+ * Tests for the format registry: createRegistry / defaultRegistry, capability
+ * consistency across every built-in, and the structured error codes.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { parseMarkdown } from '@bendyline/squisq/markdown';
+import { markdownToDoc } from '@bendyline/squisq/doc';
+import { MemoryContentContainer } from '@bendyline/squisq/storage';
+import {
+  createRegistry,
+  defaultRegistry,
+  defaultFormats,
+  ConversionError,
+  BUILTIN_FORMAT_IDS,
+} from '../registry/index';
+import type { FormatDefinition, NormalizedInput } from '../registry/index';
+
+const SAMPLE_MD = `# Title
+
+Some intro text.
+
+| Name | Value |
+| --- | --- |
+| A | 1 |
+| B | 2 |
+`;
+
+async function makeInput(baseName = 'sample'): Promise<NormalizedInput> {
+  const markdownDoc = parseMarkdown(SAMPLE_MD);
+  const doc = markdownToDoc(markdownDoc);
+  const container = new MemoryContentContainer();
+  await container.writeDocument(SAMPLE_MD);
+  return { doc, markdownDoc, container, baseName };
+}
+
+const stubDef = (id: string, extensions: string[]): FormatDefinition => ({
+  id,
+  label: id.toUpperCase(),
+  mimeType: 'application/octet-stream',
+  extensions,
+});
+
+// ── Registry mechanics ──────────────────────────────────────────────
+
+describe('createRegistry', () => {
+  it('registers and gets definitions by id', () => {
+    const reg = createRegistry();
+    reg.register(stubDef('foo', ['.foo']));
+    expect(reg.get('foo')?.id).toBe('foo');
+    expect(reg.get('missing')).toBeUndefined();
+  });
+
+  it('resolves byExtension, normalizing leading dot + case', () => {
+    const reg = createRegistry();
+    reg.register(stubDef('foo', ['.foo', '.f']));
+    expect(reg.byExtension('foo')?.id).toBe('foo');
+    expect(reg.byExtension('.FOO')?.id).toBe('foo');
+    expect(reg.byExtension('f')?.id).toBe('foo');
+    expect(reg.byExtension('nope')).toBeUndefined();
+  });
+
+  it('is last-write-wins by id', () => {
+    const reg = createRegistry();
+    reg.register(stubDef('foo', ['.foo']));
+    reg.register({ ...stubDef('foo', ['.foo']), label: 'SECOND' });
+    expect(reg.get('foo')?.label).toBe('SECOND');
+    expect(reg.list().filter((d) => d.id === 'foo')).toHaveLength(1);
+  });
+
+  it('lists all registered definitions', () => {
+    const reg = createRegistry();
+    reg.register(stubDef('a', ['.a']));
+    reg.register(stubDef('b', ['.b']));
+    expect(
+      reg
+        .list()
+        .map((d) => d.id)
+        .sort(),
+    ).toEqual(['a', 'b']);
+  });
+});
+
+describe('defaultRegistry', () => {
+  it('registers all built-in formats', () => {
+    const reg = defaultRegistry();
+    for (const id of BUILTIN_FORMAT_IDS) {
+      expect(reg.get(id), `built-in "${id}" should be registered`).toBeDefined();
+    }
+    expect(reg.list()).toHaveLength(BUILTIN_FORMAT_IDS.length);
+  });
+
+  it('defaultFormats matches BUILTIN_FORMAT_IDS exactly', () => {
+    const ids = defaultFormats()
+      .map((d) => d.id)
+      .sort();
+    expect(ids).toEqual([...BUILTIN_FORMAT_IDS].sort());
+  });
+});
+
+// ── Capability consistency ──────────────────────────────────────────
+
+describe('built-in capability consistency', () => {
+  const formats = defaultFormats();
+
+  for (const def of formats) {
+    if (!def.exportDoc) continue;
+    it(`${def.id}: exportDoc produces bytes (or a tolerated not-implemented error)`, async () => {
+      const input = await makeInput();
+      // HTML formats need a player script; provide a trivial stub.
+      const options = { resolvePlayerScript: async () => '/* stub */' };
+      try {
+        const result = await def.exportDoc!(input, options);
+        // Use ArrayBuffer.isView rather than `instanceof Uint8Array`: under the
+        // jsdom test env, bytes built from node's TextEncoder/Uint8Array live in
+        // a different realm than the test file's Uint8Array global.
+        expect(ArrayBuffer.isView(result.bytes)).toBe(true);
+        expect(result.bytes.byteLength).toBeGreaterThan(0);
+        expect(typeof result.mimeType).toBe('string');
+        expect(Array.isArray(result.warnings)).toBe(true);
+      } catch (err: unknown) {
+        // xlsx export is being implemented concurrently and may still throw
+        // 'not yet implemented'. Tolerate that specific case only.
+        const message = err instanceof Error ? err.message : String(err);
+        expect(def.id, `unexpected export failure for "${def.id}": ${message}`).toBe('xlsx');
+        expect(message).toMatch(/not yet implemented/i);
+      }
+    });
+  }
+
+  it('csv export warns when the document has multiple tables', async () => {
+    const multiTable = parseMarkdown(
+      `| A | B |\n| - | - |\n| 1 | 2 |\n\n| C | D |\n| - | - |\n| 3 | 4 |\n`,
+    );
+    const container = new MemoryContentContainer();
+    const input: NormalizedInput = {
+      doc: markdownToDoc(multiTable),
+      markdownDoc: multiTable,
+      container,
+      baseName: 'tables',
+    };
+    const csv = defaultFormats().find((d) => d.id === 'csv')!;
+    const result = await csv.exportDoc!(input, {});
+    expect(result.warnings.length).toBeGreaterThan(0);
+    expect(result.warnings[0]).toMatch(/table/i);
+  });
+});
+
+// ── Error codes ─────────────────────────────────────────────────────
+
+describe('error codes', () => {
+  it('ConversionError carries a stable code + optional fields', () => {
+    const err = new ConversionError('invalid-input', 'boom', {
+      format: 'docx',
+      hint: 'try again',
+      cause: new Error('root'),
+    });
+    expect(err).toBeInstanceOf(Error);
+    expect(err.name).toBe('ConversionError');
+    expect(err.code).toBe('invalid-input');
+    expect(err.format).toBe('docx');
+    expect(err.hint).toBe('try again');
+    expect((err as Error & { cause?: unknown }).cause).toBeInstanceOf(Error);
+  });
+
+  it('html export without a player script → missing-dependency', async () => {
+    const input = await makeInput();
+    const html = defaultFormats().find((d) => d.id === 'html')!;
+    await expect(html.exportDoc!(input, {})).rejects.toMatchObject({
+      name: 'ConversionError',
+      code: 'missing-dependency',
+    });
+  });
+});

package/src/__tests__/htmlImport.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+import { htmlToMarkdown, htmlToMarkdownDocSync } from '../html/import.js';
+
+describe('htmlToMarkdown', () => {
+  it('converts headings and paragraphs', () => {
+    const md = htmlToMarkdown('<h1>Title</h1><p>Hello <strong>world</strong>.</p>');
+    expect(md).toContain('# Title');
+    expect(md).toContain('Hello **world**.');
+  });
+
+  it('converts links and inline code', () => {
+    const md = htmlToMarkdown(
+      '<p>See <a href="https://x.test">site</a> and <code>npm i</code></p>',
+    );
+    expect(md).toContain('[site](https://x.test)');
+    expect(md).toContain('`npm i`');
+  });
+
+  it('converts unordered and ordered lists', () => {
+    const md = htmlToMarkdown('<ul><li>a</li><li>b</li></ul><ol><li>one</li><li>two</li></ol>');
+    expect(md).toMatch(/[-*]\s+a/);
+    expect(md).toMatch(/[-*]\s+b/);
+    expect(md).toMatch(/1\.\s+one/);
+  });
+
+  it('converts blockquotes and tables', () => {
+    const md = htmlToMarkdown(
+      '<blockquote><p>quoted</p></blockquote>' +
+        '<table><thead><tr><th>H</th></tr></thead><tbody><tr><td>cell</td></tr></tbody></table>',
+    );
+    expect(md).toContain('> quoted');
+    expect(md).toContain('cell');
+  });
+
+  it('drops scripts and styles (sanitized by default)', () => {
+    const md = htmlToMarkdown('<p>safe</p><script>alert(1)</script><style>.x{color:red}</style>');
+    expect(md).toContain('safe');
+    expect(md).not.toContain('alert(1)');
+    expect(md).not.toContain('color:red');
+  });
+
+  it('strips javascript: links via sanitizer', () => {
+    const md = htmlToMarkdown('<a href="javascript:alert(1)">click</a>');
+    expect(md).not.toContain('javascript:alert(1)');
+  });
+
+  it('builds a document node tree', () => {
+    const doc = htmlToMarkdownDocSync('<h2>Hi</h2>');
+    expect(doc.type).toBe('document');
+    expect(doc.children[0]?.type).toBe('heading');
+  });
+
+  it('handles unwrapped div/span containers', () => {
+    const md = htmlToMarkdown('<div><span>plain </span><em>text</em></div>');
+    expect(md).toContain('plain *text*');
+  });
+});

package/src/__tests__/lossyWarnings.test.ts

@@ -0,0 +1,105 @@
+/**
+ * Tests for the registry's consolidated lossy-path warnings, all surfaced
+ * through `ConversionResult.warnings`:
+ *  - xlsx export drops non-table content (tables-only fidelity)
+ *  - pdf import under Node skips embedded images (no DOM canvas)
+ *  - transform → markdown produces blocks that don't round-trip
+ */
+
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { MemoryContentContainer } from '@bendyline/squisq/storage';
+import { convert, defaultRegistry } from '../registry/index';
+
+// ── xlsx: tables-only fidelity ──────────────────────────────────────
+
+describe('xlsx export warns about omitted non-table content', () => {
+  it('warns when prose / lists accompany the table(s)', async () => {
+    const md =
+      '# Report\n\nIntro prose paragraph.\n\n- a\n- b\n\n| A | B |\n| - | - |\n| 1 | 2 |\n';
+    const result = await convert({ kind: 'markdown', markdown: md }, 'xlsx');
+    expect(result.warnings.some((w) => /tables-only/i.test(w))).toBe(true);
+    // Two omitted blocks: the paragraph and the list (heading names the sheet).
+    expect(result.warnings.find((w) => /tables-only/i.test(w))).toMatch(/2 non-table block/);
+  });
+
+  it('does not warn for a heading + table only document', async () => {
+    const md = '# Sales\n\n| A |\n| - |\n| x |\n';
+    const result = await convert({ kind: 'markdown', markdown: md }, 'xlsx');
+    expect(result.warnings.some((w) => /tables-only/i.test(w))).toBe(false);
+  });
+});
+
+// ── pdf: Node has no DOM canvas → images skipped ────────────────────
+
+describe('pdf import warns when running without a DOM (Node)', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  /** A pdf definition whose importContainer is stubbed (avoids pdfjs/canvas). */
+  function registryWithStubPdf() {
+    const registry = defaultRegistry();
+    registry.register({
+      ...registry.get('pdf')!,
+      async importContainer() {
+        const c = new MemoryContentContainer();
+        await c.writeDocument('# From PDF\n\nBody.');
+        return c;
+      },
+    });
+    return registry;
+  }
+
+  const pdfBytes = new TextEncoder().encode('%PDF-1.4\n%mock\n');
+
+  it('surfaces the skipped-images warning when document is undefined', async () => {
+    vi.stubGlobal('document', undefined);
+    const registry = registryWithStubPdf();
+    const result = await convert({ kind: 'bytes', data: pdfBytes, filename: 'x.pdf' }, 'md', {
+      from: 'pdf',
+      registry,
+    });
+    expect(result.warnings.some((w) => /embedded images were skipped/i.test(w))).toBe(true);
+  });
+
+  it('does not warn when a DOM is present (jsdom default)', async () => {
+    const registry = registryWithStubPdf();
+    const result = await convert({ kind: 'bytes', data: pdfBytes, filename: 'x.pdf' }, 'md', {
+      from: 'pdf',
+      registry,
+    });
+    expect(result.warnings.some((w) => /embedded images were skipped/i.test(w))).toBe(false);
+  });
+});
+
+// ── transform → markdown round-trip loss ────────────────────────────
+
+describe('transform-to-markdown export warns about non-round-tripping blocks', () => {
+  const CONTENT_MD = `# Big Title
+
+An intro paragraph with plenty of words so the transform has real content.
+
+## Numbers
+
+Revenue grew by 45% last quarter across every region and product line worldwide.
+
+- Point one with several words to analyze here
+- Point two with several words to analyze here
+
+| Metric | Value |
+| - | - |
+| Users | 1000 |
+`;
+
+  it('warns when a transform reshapes into template blocks that markdown can’t hold', async () => {
+    const result = await convert({ kind: 'markdown', markdown: CONTENT_MD }, 'md', {
+      transformStyle: 'magazine',
+    });
+    expect(result.warnings.some((w) => /round-trip to markdown/i.test(w))).toBe(true);
+  });
+
+  it('does not warn without a transform', async () => {
+    const result = await convert({ kind: 'markdown', markdown: CONTENT_MD }, 'md');
+    expect(result.warnings.some((w) => /round-trip to markdown/i.test(w))).toBe(false);
+  });
+});

package/src/__tests__/pdfImport.test.ts

@@ -11,11 +11,13 @@
 import { describe, it, expect } from 'vitest';
 import { PDFDocument, StandardFonts, rgb } from 'pdf-lib';
 
-import { pdfToMarkdownDoc, pdfToDoc } from '../pdf/import';
+import { pdfToMarkdownDoc, pdfToDoc, insertImageBlocks } from '../pdf/import';
+import type { ExtractedImage } from '../pdf/import';
 import type {
   MarkdownHeading,
   MarkdownBlockNode,
   MarkdownCodeBlock,
+  MarkdownParagraph,
 } from '@bendyline/squisq/markdown';
 
 /** Structural shape shared by all markdown node types, for recursive walkers. */
@@ -276,6 +278,98 @@ describe('pdfToMarkdownDoc', () => {
 // pdfToDoc convenience wrapper
 // ============================================
 
+// ============================================
+// insertImageBlocks — page-level image placement (pure)
+// ============================================
+
+describe('insertImageBlocks', () => {
+  /** Build a synthetic paragraph block carrying a marker text value. */
+  function para(label: string): MarkdownParagraph {
+    return { type: 'paragraph', children: [{ type: 'text', value: label }] };
+  }
+
+  /** Build a synthetic extracted image on a given page (data/y are irrelevant here). */
+  function img(index: number, page: number): ExtractedImage {
+    return { path: `images/image${index}.png`, data: new ArrayBuffer(0), page, y: 0 };
+  }
+
+  /** Extract a flat list of block descriptors: paragraph label or image url. */
+  function describeBlocks(blocks: MarkdownBlockNode[]): string[] {
+    return blocks.map((b) => {
+      if (b.type === 'paragraph') {
+        const child = (b as MarkdownParagraph).children[0];
+        if (child && child.type === 'image') return `img:${child.url}`;
+        if (child && child.type === 'text') return `p:${child.value}`;
+      }
+      return b.type;
+    });
+  }
+
+  it('is a no-op when there are no images', () => {
+    const blocks = [para('A'), para('B')];
+    const pages = [0, 0];
+    const result = insertImageBlocks(blocks, pages, []);
+    expect(result).toBe(blocks);
+  });
+
+  it('places an image after the last block of its page', () => {
+    // Page 0: A, B   Page 1: C
+    const blocks = [para('A'), para('B'), para('C')];
+    const pages = [0, 0, 1];
+    const result = insertImageBlocks(blocks, pages, [img(1, 0)]);
+    expect(describeBlocks(result)).toEqual(['p:A', 'p:B', 'img:images/image1.png', 'p:C']);
+  });
+
+  it('places images on the correct page in a multi-page document', () => {
+    // Page 0: A   Page 1: B   Page 2: C
+    const blocks = [para('A'), para('B'), para('C')];
+    const pages = [0, 1, 2];
+    const result = insertImageBlocks(blocks, pages, [img(1, 2), img(2, 0)]);
+    // image2 → after A (page 0), image1 → after C (page 2)
+    expect(describeBlocks(result)).toEqual([
+      'p:A',
+      'img:images/image2.png',
+      'p:B',
+      'p:C',
+      'img:images/image1.png',
+    ]);
+  });
+
+  it('preserves image order within the same page', () => {
+    const blocks = [para('A'), para('B')];
+    const pages = [0, 0];
+    const result = insertImageBlocks(blocks, pages, [img(1, 0), img(2, 0)]);
+    expect(describeBlocks(result)).toEqual([
+      'p:A',
+      'p:B',
+      'img:images/image1.png',
+      'img:images/image2.png',
+    ]);
+  });
+
+  it('falls back to the nearest preceding page for an image-only page', () => {
+    // Page 0: A   Page 1: (no blocks)   image on page 1 → after A
+    const blocks = [para('A'), para('B')];
+    const pages = [0, 2];
+    // Image on page 1 has no blocks; nearest preceding page with blocks is 0 → after A.
+    const result = insertImageBlocks(blocks, pages, [img(1, 1)]);
+    expect(describeBlocks(result)).toEqual(['p:A', 'img:images/image1.png', 'p:B']);
+  });
+
+  it('appends at the end when no preceding page has blocks', () => {
+    // Only page 5 has blocks; image on page 2 has no preceding page → append at end.
+    const blocks = [para('A'), para('B')];
+    const pages = [5, 5];
+    const result = insertImageBlocks(blocks, pages, [img(1, 2)]);
+    expect(describeBlocks(result)).toEqual(['p:A', 'p:B', 'img:images/image1.png']);
+  });
+
+  it('appends all images when there are no text blocks', () => {
+    const result = insertImageBlocks([], [], [img(1, 0), img(2, 3)]);
+    expect(describeBlocks(result)).toEqual(['img:images/image1.png', 'img:images/image2.png']);
+  });
+});
+
 describe('pdfToDoc', () => {
   it('converts PDF to a Doc object', async () => {
     const buffer = await buildSimplePdf([

package/src/__tests__/plainHtml.test.ts

@@ -43,6 +43,12 @@ describe('markdownDocToPlainHtml', () => {
     );
   });
 
+  it('renders unsafe markdown links as inert text by default', () => {
+    const html = render('[x](javascript:alert(1))');
+    expect(html).toContain('<p>x</p>');
+    expect(html).not.toContain('javascript:');
+  });
+
   it('renders ordered and unordered lists', () => {
     const html = render('- one\n- two\n\n1. first\n2. second');
     expect(html).toContain('<ul>');
@@ -112,6 +118,31 @@ describe('markdownDocToPlainHtml', () => {
     expect(html).not.toContain('src="resized.png"');
   });
 
+  it('sanitizes raw HTML by default', () => {
+    const html = render(
+      '<div><img src="x.jpg" onerror="alert(1)"><script>alert(1)</script><span onclick="alert(1)">ok</span></div>',
+    );
+    expect(html).toContain('<img src="x.jpg" />');
+    expect(html).toContain('<span>ok</span>');
+    expect(html).not.toContain('<script>');
+    expect(html).not.toContain('onerror');
+    expect(html).not.toContain('onclick');
+    expect(html).not.toContain('javascript:');
+  });
+
+  it('strips raw HTML when requested', () => {
+    const html = render('<div><span>hidden</span></div>', { htmlPolicy: 'strip' });
+    expect(html).not.toContain('<span>hidden</span>');
+    expect(html).not.toContain('hidden');
+  });
+
+  it('preserves raw HTML only with the trusted opt-in', () => {
+    const html = render('<div><span onclick="alert(1)">ok</span></div>', {
+      htmlPolicy: 'trusted',
+    });
+    expect(html).toContain('<div><span onclick="alert(1)">ok</span></div>');
+  });
+
   it('escapes quotes in href and src attributes', () => {
     const html = render('![a](a"b.jpg)\n\n[c](d"e)');
     expect(html).toContain('&quot;');