@bendyline/squisq-formats 1.4.2 → 2.0.0

package/dist/themeReader-DPw4J5Ss.d.ts

@@ -0,0 +1,56 @@
+import { a as OoxmlPackage } from './reader-Gof6OrJX.js';
+
+/**
+ * OOXML theme reader — parses a `theme1.xml` part (DrawingML `a:theme`)
+ * into normalized color and font schemes.
+ *
+ * Shared by DOCX/PPTX/XLSX theme inference: all three formats carry the same
+ * theme part shape, differing only in where the part hangs (document/master/
+ * workbook relationships). This module never fails hard — unreadable slots
+ * degrade to fallbacks or absence, with a warning per degradation.
+ */
+
+/**
+ * The clrScheme slots as normalized `#rrggbb` strings. The four surface/text
+ * slots always resolve (falling back to black/white when degraded); accent and
+ * hyperlink slots are omitted when unresolvable.
+ */
+interface OoxmlColorScheme {
+    dk1: string;
+    lt1: string;
+    dk2: string;
+    lt2: string;
+    accent1?: string;
+    accent2?: string;
+    accent3?: string;
+    accent4?: string;
+    accent5?: string;
+    accent6?: string;
+    hlink?: string;
+    folHlink?: string;
+}
+interface OoxmlFontScheme {
+    /** `a:fontScheme > a:majorFont > a:latin@typeface` (headings). */
+    majorLatin?: string;
+    /** `a:fontScheme > a:minorFont > a:latin@typeface` (body). */
+    minorLatin?: string;
+}
+interface OoxmlTheme {
+    /** `a:theme@name` (e.g. "Office Theme", "Ion"). */
+    name?: string;
+    /** Absent when the theme carries no parseable `a:clrScheme`. */
+    colors?: OoxmlColorScheme;
+    /** Absent when the theme carries no `a:fontScheme` latin typefaces. */
+    fonts?: OoxmlFontScheme;
+    warnings: string[];
+}
+/** Parse an already-loaded theme part Document. */
+declare function parseThemeXml(themeDoc: Document): OoxmlTheme;
+/**
+ * Resolve the theme part related from `fromPartPath` (via `REL_THEME`) and
+ * parse it. Returns null when the part has no theme relationship or the
+ * target part is missing — callers decide whether that's an error.
+ */
+declare function readThemePart(pkg: OoxmlPackage, fromPartPath: string): Promise<OoxmlTheme | null>;
+
+export { type OoxmlColorScheme as O, type OoxmlFontScheme as a, type OoxmlTheme as b, parseThemeXml as p, readThemePart as r };

package/dist/xlsx/index.d.ts

@@ -1,69 +1,9 @@
 import { Doc } from '@bendyline/squisq/schemas';
-import { MarkdownDocument } from '@bendyline/squisq/markdown';
-
-/**
- * XLSX import — SpreadsheetML (.xlsx) → MarkdownDocument.
- *
- * Reuses the shared ooxml/ reader (zip + DOMParser). Reads the workbook's
- * sheet list, resolves each sheet part via relationships, pulls shared strings,
- * and turns each worksheet's cell grid into a markdown table (first row treated
- * as the header). By default every sheet is imported, each preceded by an H1 of
- * the sheet name; pass `options.sheet` (index or name) to import just one.
- */
-
-interface XlsxImportOptions {
-    /** Which sheet to import (0-based index or sheet name). Default: all sheets. */
-    sheet?: number | string;
-}
-declare function xlsxToMarkdownDoc(data: ArrayBuffer | Blob, options?: XlsxImportOptions): Promise<MarkdownDocument>;
-
-/**
- * XLSX export — MarkdownDocument → SpreadsheetML (.xlsx).
- *
- * Tables-only fidelity (honestly documented): every `table` node in the
- * markdown AST becomes one worksheet; all other content (headings, prose,
- * lists, images, …) is dropped except that the nearest preceding heading is
- * used to name the sheet. This mirrors the import side (`xlsxToMarkdownDoc`),
- * which turns each worksheet grid back into a markdown table.
- *
- * Cells are emitted as inline strings (`t="inlineStr"`) so no sharedStrings
- * part is needed, except values matching a plain-number pattern, which are
- * emitted as numeric cells. The package is assembled with the shared ooxml/
- * writer (auto-generates `[Content_Types].xml` + `_rels`), so only the
- * SpreadsheetML-specific parts (workbook, worksheets, styles) are written here.
- *
- * @example
- * ```ts
- * import { parseMarkdown } from '@bendyline/squisq/markdown';
- * import { markdownDocToXlsx } from '@bendyline/squisq-formats/xlsx';
- *
- * const md = parseMarkdown('# Metrics\n\n| A | B |\n| - | - |\n| 1 | 2 |');
- * const buffer = await markdownDocToXlsx(md);
- * ```
- */
-
-/**
- * Options for XLSX export.
- */
-interface XlsxExportOptions {
-    /** Workbook title (written to core properties). */
-    title?: string;
-    /** Workbook author (written to core properties). */
-    author?: string;
-    /** Prefix used for auto-named sheets when no heading precedes a table. Default: "Sheet". */
-    sheetNamePrefix?: string;
-}
-/**
- * Convert a MarkdownDocument to a .xlsx file (tables-only fidelity).
- *
- * Each markdown `table` becomes one worksheet; a document with no tables
- * yields a single empty sheet (a valid, openable file — never throws).
- */
-declare function markdownDocToXlsx(doc: MarkdownDocument, options?: XlsxExportOptions): Promise<ArrayBuffer>;
-/**
- * Convert a squisq Doc to a .xlsx file (via the markdown table model).
- */
-declare function docToXlsx(doc: Doc, options?: XlsxExportOptions): Promise<ArrayBuffer>;
+import { a as XlsxImportOptions } from '../export-Djev9BLU.js';
+export { X as XlsxExportOptions, d as docToXlsx, m as markdownDocToXlsx, x as xlsxToMarkdownDoc } from '../export-Djev9BLU.js';
+import '@bendyline/squisq/markdown';
+import '../reader-Gof6OrJX.js';
+import '../zipLimits-bGYMS9cI.js';
 
 /**
  * @bendyline/squisq-formats XLSX Module
@@ -86,4 +26,4 @@ declare function docToXlsx(doc: Doc, options?: XlsxExportOptions): Promise<Array
  */
 declare function xlsxToDoc(data: ArrayBuffer | Blob, options?: XlsxImportOptions): Promise<Doc>;
 
-export { type XlsxExportOptions, type XlsxImportOptions, docToXlsx, markdownDocToXlsx, xlsxToDoc, xlsxToMarkdownDoc };
+export { XlsxImportOptions, xlsxToDoc };

package/dist/xlsx/index.js

@@ -3,10 +3,12 @@ import {
   markdownDocToXlsx,
   xlsxToDoc,
   xlsxToMarkdownDoc
-} from "../chunk-EHLGMSTE.js";
+} from "../chunk-HBSCRS5P.js";
 import "../chunk-PN52A5AA.js";
-import "../chunk-SHLPSADL.js";
+import "../chunk-XTLQXR4U.js";
 import "../chunk-U4MRIFKL.js";
+import "../chunk-4HJ6AK2Q.js";
+import "../chunk-H7T5DXUU.js";
 export {
   docToXlsx,
   markdownDocToXlsx,

package/dist/zipLimits-bGYMS9cI.d.ts

@@ -0,0 +1,29 @@
+/** ZIP safety policy, structured errors, path checks, and metadata validation. */
+
+interface ZipSafetyLimits {
+    /** Maximum number of archive records, including directories. Default: 10,000. */
+    maxEntries?: number;
+    /** Maximum uncompressed bytes for one member. Defaults to maxUncompressedBytes. */
+    maxEntryUncompressedBytes?: number;
+    /** Maximum total uncompressed bytes across the archive. Default: 512 MiB. */
+    maxUncompressedBytes?: number;
+    /** Maximum uncompressed/compressed ratio for a member. Default: 1,000. */
+    maxCompressionRatio?: number;
+}
+type ZipSafetyErrorCode = 'invalid-limit' | 'invalid-archive' | 'unsafe-path' | 'invalid-entry-metadata' | 'too-many-entries' | 'entry-too-large' | 'archive-too-large' | 'compression-ratio-exceeded' | 'size-mismatch' | 'crc-mismatch' | 'decompression-failed';
+interface ZipSafetyErrorOptions {
+    path?: string;
+    limit?: number;
+    actual?: number;
+    cause?: unknown;
+}
+/** A stable, machine-readable error raised while validating or reading a ZIP. */
+declare class ZipSafetyError extends Error {
+    readonly code: ZipSafetyErrorCode;
+    readonly path?: string;
+    readonly limit?: number;
+    readonly actual?: number;
+    constructor(code: ZipSafetyErrorCode, message: string, options?: ZipSafetyErrorOptions);
+}
+
+export { ZipSafetyError as Z, type ZipSafetyErrorCode as a, type ZipSafetyErrorOptions as b, type ZipSafetyLimits as c };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/squisq-formats",
-  "version": "1.4.2",
+  "version": "2.0.0",
   "description": "Document format converters — DOCX, PDF, OOXML import/export",
   "license": "MIT",
   "author": "Bendyline",
@@ -86,6 +86,11 @@
       "types": "./dist/registry/index.d.ts",
       "import": "./dist/registry/index.js",
       "default": "./dist/registry/index.js"
+    },
+    "./infer": {
+      "types": "./dist/infer/index.d.ts",
+      "import": "./dist/infer/index.js",
+      "default": "./dist/infer/index.js"
     }
   },
   "scripts": {
@@ -94,7 +99,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@bendyline/squisq": "1.5.2",
+    "@xmldom/xmldom": "0.9.10",
+    "@bendyline/squisq": "2.0.0",
     "jszip": "3.10.1",
     "pdf-lib": "1.17.1",
     "pdfjs-dist": "4.10.38"

package/src/__tests__/container.test.ts

@@ -78,6 +78,13 @@ describe('containerToZip', () => {
     const data = await zip.file('image.png')!.async('uint8array');
     expect(data).toEqual(binaryData);
   });
+
+  it('refuses to create a ZIP with an unsafe container path', async () => {
+    const container = new MemoryContentContainer();
+    await container.writeFile('../outside.txt', new TextEncoder().encode('nope'));
+
+    await expect(containerToZip(container)).rejects.toThrow(/path is unsafe/i);
+  });
 });
 
 // ============================================
@@ -137,6 +144,40 @@ describe('zipToContainer', () => {
     const container = await zipToContainer(ab);
     expect(await container.readDocument()).toBe('# Read me');
   });
+
+  it('rejects archives that exceed the configured entry limit', async () => {
+    const zip = new JSZip();
+    zip.file('one.txt', '1');
+    zip.file('two.txt', '2');
+    const data = await zip.generateAsync({ type: 'arraybuffer' });
+    await expect(zipToContainer(data, { maxEntries: 1 })).rejects.toThrow(/archive has 2 files/);
+  });
+
+  it('rejects archives that exceed the configured uncompressed byte limit', async () => {
+    const zip = new JSZip();
+    zip.file('large.txt', '12345');
+    const data = await zip.generateAsync({ type: 'arraybuffer' });
+    await expect(zipToContainer(data, { maxUncompressedBytes: 4 })).rejects.toThrow(
+      /uncompressed content exceeds 4 byte limit/,
+    );
+  });
+
+  it('rejects traversal paths even when JSZip sanitizes their loaded key', async () => {
+    const zip = new JSZip();
+    zip.file('../outside.txt', 'nope');
+    const data = await zip.generateAsync({ type: 'arraybuffer' });
+
+    await expect(zipToContainer(data)).rejects.toThrow(/unsafe path.*\.\.\/outside\.txt/i);
+  });
+
+  it('rejects absolute and Windows-style archive paths', async () => {
+    for (const path of ['/absolute.txt', 'C:\\outside.txt']) {
+      const zip = new JSZip();
+      zip.file(path, 'nope');
+      const data = await zip.generateAsync({ type: 'arraybuffer' });
+      await expect(zipToContainer(data)).rejects.toThrow(/unsafe path/i);
+    }
+  });
 });
 
 // ============================================

package/src/__tests__/convert.test.ts

@@ -5,9 +5,15 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import JSZip from 'jszip';
 import { parseMarkdown } from '@bendyline/squisq/markdown';
 import { markdownToDoc } from '@bendyline/squisq/doc';
+import { MemoryContentContainer } from '@bendyline/squisq/storage';
+import { createTransformStyleRegistry, resolveTransformStyle } from '@bendyline/squisq/transform';
 import { convert, ConversionError, defaultRegistry } from '../registry/index';
+import { zipToContainer } from '../container/index';
+import { markdownDocToPptx } from '../pptx/export';
+import { buildThemedPptx } from './pptxInferFixtures';
 
 const SAMPLE_MD = `# Round Trip
 
@@ -40,6 +46,70 @@ describe('convert error paths', () => {
       convert({ kind: 'markdown', markdown: '# hi' }, 'importonly', { registry }),
     ).rejects.toMatchObject({ name: 'ConversionError', code: 'unsupported-output' });
   });
+
+  it('normalizes importer failures to ConversionError', async () => {
+    const promise = convert({ kind: 'bytes', data: new TextEncoder().encode('not a zip') }, 'md', {
+      from: 'docx',
+    });
+    await expect(promise).rejects.toMatchObject({
+      name: 'ConversionError',
+      code: 'invalid-input',
+      format: 'docx',
+    });
+  });
+});
+
+describe('format option threading', () => {
+  it('threads CSV tableIndex and delimiter through the conversion facade', async () => {
+    const markdown =
+      '| A | B |\n|---|---|\n| first | row |\n\n| C | D |\n|---|---|\n| second | row |\n';
+    const result = await convert({ kind: 'markdown', markdown }, 'csv', {
+      formatOptions: { csv: { tableIndex: 1, delimiter: ';' } },
+    });
+    expect(new TextDecoder().decode(result.bytes)).toBe('C;D\r\nsecond;row');
+    expect(result.warnings).toEqual([]);
+  });
+
+  it('honors Markdown parse options for direct Markdown sources', async () => {
+    let captured: import('../registry/index').NormalizedInput | undefined;
+    const registry = defaultRegistry();
+    registry.register({
+      id: 'capture-md-options',
+      label: 'Capture Markdown Options',
+      mimeType: 'application/x-capture',
+      extensions: ['.capture'],
+      async exportDoc(input) {
+        captured = input;
+        return {
+          bytes: new Uint8Array(),
+          mimeType: 'application/x-capture',
+          suggestedFilename: '',
+          warnings: [],
+        };
+      },
+    });
+
+    await convert(
+      { kind: 'markdown', markdown: '---\ntitle: Hidden metadata\n---\n\n# Body' },
+      'capture-md-options',
+      {
+        registry,
+        formatOptions: { md: { parse: { frontmatter: false } } },
+      },
+    );
+
+    expect(captured?.markdownDoc?.frontmatter).toBeUndefined();
+  });
+
+  it('threads archive safety limits into OOXML importers', async () => {
+    const docx = await convert({ kind: 'markdown', markdown: '# Limited' }, 'docx');
+    await expect(
+      convert({ kind: 'bytes', data: docx.bytes }, 'md', {
+        from: 'docx',
+        formatOptions: { docx: { maxEntries: 1 } },
+      }),
+    ).rejects.toMatchObject({ code: 'invalid-input', format: 'docx' });
+  });
 });
 
 // ── round trip: md → docx → md ──────────────────────────────────────
@@ -94,6 +164,21 @@ describe('byte sniffing', () => {
     expect(text).toContain('In a container');
   });
 
+  it('DBK export snapshots the supplied source instead of stale container markdown', async () => {
+    const container = new MemoryContentContainer();
+    await container.writeDocument('# Old');
+    await container.writeFile('asset.bin', new Uint8Array([1, 2, 3]));
+
+    const result = await convert({ kind: 'markdown', markdown: '# New', container }, 'dbk');
+    const restored = await zipToContainer(result.bytes);
+    expect(await restored.readDocument()).toContain('# New');
+    expect(new Uint8Array((await restored.readFile('asset.bin'))!)).toEqual(
+      new Uint8Array([1, 2, 3]),
+    );
+    // Snapshotting must not mutate the caller's container.
+    expect(await container.readDocument()).toBe('# Old');
+  });
+
   it('disambiguates a docx zip via its content-types part', async () => {
     const docx = await convert({ kind: 'markdown', markdown: '# Word doc' }, 'docx');
     // No filename, no `from` — must read [Content_Types].xml to pick docx.
@@ -140,6 +225,40 @@ describe('transform threading', () => {
     // markdownDoc is re-derived from the transformed Doc.
     expect(captured!.markdownDoc).toBeDefined();
   });
+
+  it('resolves transform ids only from the explicitly supplied registry', async () => {
+    let captured: import('../registry/index').NormalizedInput | undefined;
+    const formats = defaultRegistry();
+    formats.register({
+      id: 'capture-custom-transform',
+      label: 'Capture Custom Transform',
+      mimeType: 'application/x-capture',
+      extensions: ['.cap'],
+      async exportDoc(input) {
+        captured = input;
+        return {
+          bytes: new Uint8Array([1]),
+          mimeType: 'application/x-capture',
+          suggestedFilename: '',
+          warnings: [],
+        };
+      },
+    });
+    const custom = {
+      ...resolveTransformStyle('minimal'),
+      id: 'tenant-transform',
+      suggestedThemeId: 'cinematic',
+    };
+    const transformRegistry = createTransformStyleRegistry([custom]);
+
+    await convert({ kind: 'markdown', markdown: SAMPLE_MD }, 'capture-custom-transform', {
+      registry: formats,
+      transformStyle: 'tenant-transform',
+      transformRegistry,
+    });
+
+    expect(captured?.doc.themeId).toBe('cinematic');
+  });
 });
 
 // ── doc-kind source ─────────────────────────────────────────────────
@@ -178,9 +297,57 @@ describe('suggestedFilename', () => {
     const out = await convert({ kind: 'markdown', markdown: '# t' }, 'md');
     expect(out.suggestedFilename).toBe('document.md');
   });
+
+  it('uses only the basename for Windows-style input paths', async () => {
+    const out = await convert(
+      {
+        kind: 'bytes',
+        data: new TextEncoder().encode('# Windows'),
+        filename: 'C:\\docs\\report.md',
+      },
+      'md',
+    );
+    expect(out.suggestedFilename).toBe('report.md');
+  });
 });
 
 // sanity: ConversionError is exported and usable
+// ── pptx theme/layout inference threading ───────────────────────────
+
+describe('pptx import inference threading (default ON)', () => {
+  it('carries an inferred theme through convert() by default', async () => {
+    const deck = await markdownDocToPptx(parseMarkdown('# Hi\n\nBody.\n'), {});
+    const result = await convert({ kind: 'bytes', data: deck, filename: 'deck.pptx' }, 'md');
+    const md = new TextDecoder().decode(result.bytes);
+    expect(md).toContain('squisq-theme: custom-office-theme');
+    expect(md).toContain('squisq-custom-themes');
+  });
+
+  it('omits inference with formatOptions.pptx.inferTheme=false', async () => {
+    const deck = await markdownDocToPptx(parseMarkdown('# Hi\n\nBody.\n'), {});
+    const result = await convert({ kind: 'bytes', data: deck, filename: 'deck.pptx' }, 'md', {
+      formatOptions: { pptx: { inferTheme: false, inferLayouts: false } },
+    });
+    const md = new TextDecoder().decode(result.bytes);
+    expect(md).not.toContain('squisq-theme');
+    expect(md).not.toContain('squisq-custom-themes');
+  });
+
+  it('end-to-end: inferred theme colors reach a downstream docx export', async () => {
+    // Distinctive fixture theme (bg #fdfdf8, text #1a1a2e) → pptx → docx.
+    const result = await convert(
+      { kind: 'bytes', data: await buildThemedPptx(), filename: 'deck.pptx' },
+      'docx',
+    );
+    const zip = await JSZip.loadAsync(result.bytes);
+    let text = '';
+    for (const name of Object.keys(zip.files)) {
+      if (/\.(xml|rels)$/i.test(name)) text += await zip.files[name]!.async('string');
+    }
+    expect(text.toLowerCase()).toContain('1a1a2e');
+  });
+});
+
 it('exports ConversionError', () => {
   expect(new ConversionError('conversion-failed', 'x')).toBeInstanceOf(Error);
 });

package/src/__tests__/epub.test.ts

@@ -5,7 +5,7 @@
  * image embedding, metadata, and stylesheet generation.
  */
 
-import { describe, it, expect } from 'vitest';
+import { afterEach, describe, it, expect, vi } from 'vitest';
 import JSZip from 'jszip';
 import type { MarkdownDocument, MarkdownBlockNode } from '@bendyline/squisq/markdown';
 import { markdownDocToEpub } from '../epub/export';
@@ -65,6 +65,10 @@ async function exportAndUnzip(doc: MarkdownDocument, options?: EpubExportOptions
 // ============================================
 
 describe('markdownDocToEpub', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
   describe('EPUB structure', () => {
     it('produces a valid ZIP with required EPUB files', async () => {
       const doc = makeDoc([heading(1, 'Title'), paragraph('Content')]);
@@ -175,6 +179,15 @@ describe('markdownDocToEpub', () => {
       expect(ch).toContain('<a href="https://example.com">click</a>');
     });
 
+    it('strips executable link schemes while preserving link text', async () => {
+      const doc = makeDoc([heading(1, 'Test'), linkParagraph('click', 'javascript:alert(1)')]);
+      const zip = await exportAndUnzip(doc);
+      const ch = await zip.file('OEBPS/chapters/chapter-001.xhtml')!.async('string');
+      expect(ch).not.toContain('javascript:');
+      expect(ch).not.toContain('<a ');
+      expect(ch).toContain('click');
+    });
+
     it('renders code blocks with language class', async () => {
       const doc = makeDoc([heading(1, 'Test'), codeBlock('const x = 1;', 'javascript')]);
       const zip = await exportAndUnzip(doc);
@@ -298,6 +311,17 @@ describe('markdownDocToEpub', () => {
       expect(opf).toContain('image/png');
     });
 
+    it('flattens backslash-separated image paths to safe archive basenames', async () => {
+      const source = '..\\private\\logo.png';
+      const doc = makeDoc([heading(1, 'Test'), imageParagraph('Logo', source)]);
+      const zip = await exportAndUnzip(doc, {
+        images: new Map([[source, new Uint8Array([0x89]).buffer]]),
+      });
+
+      expect(zip.file('OEBPS/images/logo.png')).toBeTruthy();
+      expect(Object.keys(zip.files).some((path) => path.includes('\\'))).toBe(false);
+    });
+
     it('embeds cover image with cover-image property', async () => {
       const coverData = new Uint8Array([0xff, 0xd8]).buffer;
       const doc = makeDoc([heading(1, 'Test')]);
@@ -307,6 +331,23 @@ describe('markdownDocToEpub', () => {
       const opf = await zip.file('OEBPS/content.opf')!.async('string');
       expect(opf).toContain('cover-image');
     });
+
+    it('does not overwrite a document image whose basename collides with the cover', async () => {
+      const documentImage = new Uint8Array([1, 2, 3]).buffer;
+      const coverImage = new Uint8Array([0x89, 0x50, 0x4e, 0x47]).buffer;
+      const doc = makeDoc([heading(1, 'Test'), imageParagraph('Inline cover', 'cover.png')]);
+      const zip = await exportAndUnzip(doc, {
+        images: new Map([['cover.png', documentImage]]),
+        coverImage,
+      });
+
+      expect(await zip.file('OEBPS/images/cover.png')!.async('uint8array')).toEqual(
+        new Uint8Array(documentImage),
+      );
+      expect(zip.file('OEBPS/images/cover-2.png')).toBeTruthy();
+      const opf = await zip.file('OEBPS/content.opf')!.async('string');
+      expect(opf).toContain('href="images/cover-2.png"');
+    });
   });
 
   describe('metadata', () => {
@@ -356,6 +397,18 @@ describe('markdownDocToEpub', () => {
       expect(opf).toContain('urn:uuid:');
     });
 
+    it('falls back to getRandomValues when randomUUID is unavailable', async () => {
+      vi.stubGlobal('crypto', {
+        getRandomValues<T extends ArrayBufferView>(array: T): T {
+          new Uint8Array(array.buffer, array.byteOffset, array.byteLength).fill(0xab);
+          return array;
+        },
+      });
+      const zip = await exportAndUnzip(makeDoc([heading(1, 'Test')]));
+      const opf = await zip.file('OEBPS/content.opf')!.async('string');
+      expect(opf).toMatch(/urn:uuid:abababab-abab-4bab-abab-abababababab/);
+    });
+
     it('uses frontmatter title as fallback', async () => {
       const doc = makeDoc([heading(1, 'Intro')], { title: 'Frontmatter Title' });
       const zip = await exportAndUnzip(doc);
@@ -446,6 +499,54 @@ describe('markdownDocToEpub', () => {
       expect(zip.file('OEBPS/audio/body.mp3')).toBeTruthy();
     });
 
+    it('deduplicates colliding audio basenames without overwriting either segment', async () => {
+      const doc = makeDoc([
+        heading(1, 'One'),
+        paragraph('First'),
+        heading(1, 'Two'),
+        paragraph('Second'),
+      ]);
+      const segments = [
+        { src: 'a/narration.mp3', name: 'one', duration: 10, startTime: 0 },
+        { src: 'b/narration.mp3', name: 'two', duration: 10, startTime: 10 },
+      ];
+      const zip = await exportAndUnzip(doc, {
+        audio: new Map([
+          ['a/narration.mp3', new Uint8Array([1]).buffer],
+          ['b/narration.mp3', new Uint8Array([2]).buffer],
+        ]),
+        audioSegments: segments,
+        totalDuration: 20,
+      });
+
+      expect(zip.file('OEBPS/audio/narration.mp3')).toBeTruthy();
+      expect(zip.file('OEBPS/audio/narration-2.mp3')).toBeTruthy();
+      const firstSmil = await zip.file('OEBPS/chapters/chapter-001.smil')!.async('string');
+      const secondSmil = await zip.file('OEBPS/chapters/chapter-002.smil')!.async('string');
+      expect(firstSmil).toContain('narration.mp3');
+      expect(secondSmil).toContain('narration-2.mp3');
+    });
+
+    it('writes one manifest item when multiple segments reuse one audio source', async () => {
+      const doc = makeDoc([
+        heading(1, 'One'),
+        paragraph('First'),
+        heading(1, 'Two'),
+        paragraph('Second'),
+      ]);
+      const zip = await exportAndUnzip(doc, {
+        audio: new Map([['narration.mp3', new Uint8Array([1, 2, 3]).buffer]]),
+        audioSegments: [
+          { src: 'narration.mp3', name: 'one', duration: 10, startTime: 0 },
+          { src: 'narration.mp3', name: 'two', duration: 10, startTime: 10 },
+        ],
+        totalDuration: 20,
+      });
+      const opf = await zip.file('OEBPS/content.opf')!.async('string');
+
+      expect(opf.match(/href="audio\/narration\.mp3"/g)).toHaveLength(1);
+    });
+
     it('generates SMIL overlay files for each chapter', async () => {
       const doc = makeDoc([
         heading(1, 'Intro'),