@bendyline/squisq-formats 1.4.0 → 1.4.2

package/src/__tests__/csvImport.test.ts

@@ -3,7 +3,7 @@
  */
 
 import { describe, expect, it } from 'vitest';
-import type { MarkdownTable, MarkdownText } from '@bendyline/squisq/markdown';
+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 {
@@ -49,3 +49,36 @@ describe('csvToMarkdownDoc', () => {
     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__/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__/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__/pptxImport.test.ts

@@ -5,6 +5,7 @@
 
 import { describe, expect, it } from 'vitest';
 import type {
+  MarkdownDocument,
   MarkdownHeading,
   MarkdownList,
   MarkdownParagraph,
@@ -13,7 +14,11 @@ import type {
 import { NS_DRAWINGML, NS_PML, NS_R, REL_OFFICE_DOCUMENT, REL_SLIDE } from '../ooxml/namespaces';
 import { createPackage } from '../ooxml/writer';
 import { xmlDeclaration } from '../ooxml/xmlUtils';
-import { pptxToMarkdownDoc } from '../pptx/import';
+import { markdownDocToPptx } from '../pptx/export';
+import { pptxToContainer, pptxToMarkdownDoc } from '../pptx/import';
+
+/** Distinctive PNG-signature-prefixed payload so round-trip fidelity is checkable. */
+const IMAGE_BYTES = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 1, 2, 3, 4, 5]);
 
 async function buildTestPptx(): Promise<ArrayBuffer> {
   const pkg = createPackage();
@@ -68,3 +73,43 @@ describe('pptxToMarkdownDoc', () => {
     expect((firstItemPara.children[0] as MarkdownText).value).toBe('First bullet');
   });
 });
+
+describe('pptxToContainer (embedded image import)', () => {
+  const deckWithImage: MarkdownDocument = {
+    type: 'document',
+    children: [
+      { type: 'heading', depth: 2, children: [{ type: 'text', value: 'Picture Slide' }] },
+      { type: 'paragraph', children: [{ type: 'image', url: 'photo.png', alt: 'A photo' }] },
+    ],
+  };
+
+  async function buildDeck(): Promise<ArrayBuffer> {
+    return markdownDocToPptx(deckWithImage, {
+      images: new Map([['photo.png', IMAGE_BYTES.buffer]]),
+    });
+  }
+
+  it('extracts embedded images into the container and references them', async () => {
+    const container = await pptxToContainer(await buildDeck());
+
+    // The extracted image exists at the docx-style images/imageN.ext path.
+    expect(await container.exists('images/image1.png')).toBe(true);
+
+    // The bytes survived the round-trip verbatim.
+    const bytes = await container.readFile('images/image1.png');
+    expect(bytes).not.toBeNull();
+    expect(new Uint8Array(bytes!)).toEqual(IMAGE_BYTES);
+
+    // The markdown references the extracted image (no dangling ref).
+    const markdown = await container.readDocument();
+    expect(markdown).toContain('images/image1.png');
+  });
+
+  it('does not emit dangling image refs without extractImages', async () => {
+    const doc = await pptxToMarkdownDoc(await buildDeck());
+    const hasImage = doc.children.some(
+      (b) => b.type === 'paragraph' && b.children.some((c) => c.type === 'image'),
+    );
+    expect(hasImage).toBe(false);
+  });
+});

package/src/__tests__/roundTripAssets.test.ts

@@ -0,0 +1,50 @@
+/**
+ * Asset-fidelity guard: an embedded image must survive a full export → import
+ * round-trip for every container-producing format. We author a markdown doc
+ * with an image, export it (supplying the image bytes), re-import via the
+ * format's `*ToContainer`, and assert the bytes + reference come back intact.
+ */
+
+import { describe, expect, it } from 'vitest';
+import type { MarkdownDocument } from '@bendyline/squisq/markdown';
+import { markdownDocToPptx } from '../pptx/export';
+import { pptxToContainer } from '../pptx/import';
+import { markdownDocToDocx } from '../docx/export';
+import { docxToContainer } from '../docx/import';
+
+/** PNG-signature-prefixed payload with a distinctive tail for byte comparison. */
+const IMAGE_BYTES = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 9, 8, 7, 6]);
+
+const doc: MarkdownDocument = {
+  type: 'document',
+  children: [
+    { type: 'heading', depth: 1, children: [{ type: 'text', value: 'Assets' }] },
+    { type: 'paragraph', children: [{ type: 'image', url: 'hero.png', alt: 'Hero' }] },
+  ],
+};
+
+describe('embedded image round-trips through container formats', () => {
+  it('survives markdown → pptx → pptxToContainer', async () => {
+    const pptx = await markdownDocToPptx(doc, {
+      images: new Map([['hero.png', IMAGE_BYTES.buffer]]),
+    });
+    const container = await pptxToContainer(pptx);
+
+    expect(await container.exists('images/image1.png')).toBe(true);
+    const bytes = await container.readFile('images/image1.png');
+    expect(new Uint8Array(bytes!)).toEqual(IMAGE_BYTES);
+    expect(await container.readDocument()).toContain('images/image1.png');
+  });
+
+  it('survives markdown → docx → docxToContainer', async () => {
+    const docx = await markdownDocToDocx(doc, {
+      images: new Map([['hero.png', { data: IMAGE_BYTES.buffer, contentType: 'image/png' }]]),
+    });
+    const container = await docxToContainer(docx);
+
+    expect(await container.exists('images/image1.png')).toBe(true);
+    const bytes = await container.readFile('images/image1.png');
+    expect(new Uint8Array(bytes!)).toEqual(IMAGE_BYTES);
+    expect(await container.readDocument()).toContain('images/image1.png');
+  });
+});

package/src/__tests__/roundTripMatrix.test.ts

@@ -12,6 +12,7 @@ import { markdownDocToCsv, csvToMarkdownDoc } from '../csv/index';
 import { markdownDocToEpub } from '../epub/export';
 import { docToHtml } from '../html/index';
 import { markdownDocToXlsx } from '../xlsx/index';
+import { xlsxToMarkdownDoc } from '../xlsx/import';
 import { assertHybridRoundTrip, extractNormalizedText } from './roundTripMatrix.helpers';
 import { ROUNDTRIP_FIXTURES } from './roundTripMatrix.fixtures';
 
@@ -128,9 +129,14 @@ describe('format content-flow matrix', () => {
     expect(csvText).toContain('throughput');
   });
 
-  it('asserts current XLSX export stub behavior', async () => {
-    await expect(markdownDocToXlsx(ROUNDTRIP_FIXTURES.table.doc)).rejects.toThrow(
-      'XLSX export is not yet implemented',
-    );
+  it('round-trips markdown through XLSX with table cell survival', async () => {
+    const source = ROUNDTRIP_FIXTURES.table;
+    const xlsx = await markdownDocToXlsx(source.doc);
+    const roundTrip = await xlsxToMarkdownDoc(xlsx);
+
+    const text = extractNormalizedText(roundTrip);
+    for (const phrase of source.keyPhrases) {
+      expect(text).toContain(phrase);
+    }
   });
 });

package/src/__tests__/sharedContainer.test.ts

@@ -0,0 +1,41 @@
+/**
+ * Tests for the shared container-assembly tail (`shared/container.ts`) that the
+ * docx / pptx / pdf `*ToContainer` importers now delegate to.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { buildContainer } from '../shared/container';
+
+const BYTES_A = new Uint8Array([1, 2, 3, 4]);
+const BYTES_B = new Uint8Array([9, 8, 7]);
+
+describe('buildContainer', () => {
+  it('writes the markdown document and every image with its mime type', async () => {
+    const container = await buildContainer(
+      '# Hello\n\n![](images/a.png)',
+      new Map([
+        ['images/a.png', { data: BYTES_A.buffer, mimeType: 'image/png' }],
+        ['images/b.jpg', { data: BYTES_B.buffer, mimeType: 'image/jpeg' }],
+      ]),
+    );
+
+    expect(await container.readDocument()).toContain('Hello');
+    expect(await container.exists('images/a.png')).toBe(true);
+    expect(await container.exists('images/b.jpg')).toBe(true);
+    expect(new Uint8Array((await container.readFile('images/a.png'))!)).toEqual(BYTES_A);
+    expect(new Uint8Array((await container.readFile('images/b.jpg'))!)).toEqual(BYTES_B);
+  });
+
+  it('accepts any iterable of [path, {data, mimeType}] (e.g. mapped array)', async () => {
+    const images = [{ path: 'images/x.png', data: BYTES_A.buffer }].map(
+      (i) => [i.path, { data: i.data, mimeType: 'image/png' }] as const,
+    );
+    const container = await buildContainer('# Doc', images);
+    expect(await container.exists('images/x.png')).toBe(true);
+  });
+
+  it('produces a valid empty container with no images', async () => {
+    const container = await buildContainer('', []);
+    expect(await container.readDocument()).toBe('');
+  });
+});