@bendyline/squisq-formats 1.4.0 → 1.4.1

package/dist/ooxml/index.js

@@ -1,14 +1,3 @@
-import {
-  createPackage
-} from "../chunk-QSE7EWE7.js";
-import {
-  attrString,
-  escapeXml,
-  selfClosingElement,
-  textElement,
-  xmlDeclaration,
-  xmlElement
-} from "../chunk-U4MRIFKL.js";
 import {
   CONTENT_TYPE_CORE_PROPERTIES,
   CONTENT_TYPE_DOCX_DOCUMENT,
@@ -23,7 +12,9 @@ import {
   CONTENT_TYPE_PPTX_SLIDE_MASTER,
   CONTENT_TYPE_PPTX_THEME,
   CONTENT_TYPE_RELATIONSHIPS,
+  CONTENT_TYPE_XLSX_STYLES,
   CONTENT_TYPE_XLSX_WORKBOOK,
+  CONTENT_TYPE_XLSX_WORKSHEET,
   NS_CONTENT_TYPES,
   NS_CORE_PROPERTIES,
   NS_DC,
@@ -52,12 +43,22 @@ import {
   REL_SLIDE_MASTER,
   REL_STYLES,
   REL_THEME,
+  REL_WORKSHEET,
+  createPackage,
   getCoreProperties,
   getPartBinary,
   getPartRelationships,
   getPartXml,
   openPackage
-} from "../chunk-FMOIGA5T.js";
+} from "../chunk-SHLPSADL.js";
+import {
+  attrString,
+  escapeXml,
+  selfClosingElement,
+  textElement,
+  xmlDeclaration,
+  xmlElement
+} from "../chunk-U4MRIFKL.js";
 export {
   CONTENT_TYPE_CORE_PROPERTIES,
   CONTENT_TYPE_DOCX_DOCUMENT,
@@ -72,7 +73,9 @@ export {
   CONTENT_TYPE_PPTX_SLIDE_MASTER,
   CONTENT_TYPE_PPTX_THEME,
   CONTENT_TYPE_RELATIONSHIPS,
+  CONTENT_TYPE_XLSX_STYLES,
   CONTENT_TYPE_XLSX_WORKBOOK,
+  CONTENT_TYPE_XLSX_WORKSHEET,
   NS_CONTENT_TYPES,
   NS_CORE_PROPERTIES,
   NS_DC,
@@ -101,6 +104,7 @@ export {
   REL_SLIDE_MASTER,
   REL_STYLES,
   REL_THEME,
+  REL_WORKSHEET,
   attrString,
   createPackage,
   escapeXml,

package/dist/pdf/index.js

@@ -5,7 +5,8 @@ import {
   pdfToContainer,
   pdfToDoc,
   pdfToMarkdownDoc
-} from "../chunk-APSIAEXL.js";
+} from "../chunk-D7IFPWNZ.js";
+import "../chunk-SSUPBUF5.js";
 export {
   configurePdfWorker,
   docToPdf,

package/dist/pptx/index.d.ts

@@ -1,5 +1,6 @@
 import { Doc } from '@bendyline/squisq/schemas';
 import { MarkdownDocument } from '@bendyline/squisq/markdown';
+import { ContentContainer } from '@bendyline/squisq/storage';
 
 /**
  * PPTX Export
@@ -87,10 +88,24 @@ declare function docToPptx(doc: Doc, options?: PptxExportOptions): Promise<Array
  */
 
 interface PptxImportOptions {
-    /** Whether to extract embedded images as data URIs (not yet used). */
+    /**
+     * Whether to extract embedded slide images into the document as image nodes
+     * (referencing `images/imageN.ext`). When false, pictures are ignored so the
+     * markdown never carries dangling image references with no backing container.
+     * `pptxToContainer` forces this on. Default: false.
+     */
     extractImages?: boolean;
 }
-declare function pptxToMarkdownDoc(data: ArrayBuffer | Blob, _options?: PptxImportOptions): Promise<MarkdownDocument>;
+declare function pptxToMarkdownDoc(data: ArrayBuffer | Blob, options?: PptxImportOptions): Promise<MarkdownDocument>;
+/**
+ * Convert a .pptx file to a ContentContainer with markdown + extracted images.
+ *
+ * The container holds the primary markdown document plus every embedded slide
+ * image under `images/` (e.g. `images/image1.png`). Image extraction is always
+ * forced on here so the markdown's image references resolve inside the
+ * container. Mirrors `docxToContainer`.
+ */
+declare function pptxToContainer(data: ArrayBuffer | Blob, options?: PptxImportOptions): Promise<ContentContainer>;
 
 /**
  * @bendyline/squisq-formats PPTX Module
@@ -114,4 +129,4 @@ declare function pptxToMarkdownDoc(data: ArrayBuffer | Blob, _options?: PptxImpo
  */
 declare function pptxToDoc(data: ArrayBuffer | Blob, options?: PptxImportOptions): Promise<Doc>;
 
-export { type PptxExportOptions, type PptxImportOptions, docToPptx, markdownDocToPptx, pptxToDoc, pptxToMarkdownDoc };
+export { type PptxExportOptions, type PptxImportOptions, docToPptx, markdownDocToPptx, pptxToContainer, pptxToDoc, pptxToMarkdownDoc };

package/dist/pptx/index.js

@@ -1,18 +1,21 @@
 import {
   docToPptx,
   markdownDocToPptx,
+  pptxToContainer,
   pptxToDoc,
   pptxToMarkdownDoc
-} from "../chunk-I2GFTEOV.js";
+} from "../chunk-YESS7VY3.js";
 import "../chunk-6M7Z25LA.js";
 import "../chunk-PN52A5AA.js";
-import "../chunk-QSE7EWE7.js";
+import "../chunk-SHLPSADL.js";
 import "../chunk-U4MRIFKL.js";
-import "../chunk-FMOIGA5T.js";
-import "../chunk-A3FHLTY5.js";
+import "../chunk-SSUPBUF5.js";
+import "../chunk-MJGRI6XR.js";
+import "../chunk-DQAZR57U.js";
 export {
   docToPptx,
   markdownDocToPptx,
+  pptxToContainer,
   pptxToDoc,
   pptxToMarkdownDoc
 };

package/dist/registry/index.d.ts

@@ -0,0 +1,167 @@
+import { Doc } from '@bendyline/squisq/schemas';
+import { MarkdownDocument } from '@bendyline/squisq/markdown';
+import { ContentContainer } from '@bendyline/squisq/storage';
+
+/**
+ * Format registry — shared types.
+ *
+ * The registry is the programmatic heart of `convert()`: it maps a small set of
+ * format ids (`md`, `docx`, `pdf`, …) to `FormatDefinition`s, each of which
+ * knows how to import to / export from squisq's markdown + Doc model. Every
+ * converter module is loaded lazily via `import()` inside the definition
+ * methods, so pulling in the registry never eagerly bundles heavy converters.
+ */
+
+/** A format identifier (e.g. `'docx'`). Strings so hosts can register their own. */
+type FormatId = string;
+/** The built-in formats the default registry ships with. */
+declare const BUILTIN_FORMAT_IDS: readonly ["md", "docx", "pdf", "pptx", "xlsx", "csv", "html", "htmlzip", "epub", "dbk"];
+/** The bytes + metadata produced by a successful export. */
+interface ConversionResult {
+    /** Encoded output bytes. */
+    bytes: Uint8Array;
+    /** MIME type of the output. */
+    mimeType: string;
+    /** A sensible download filename (`<baseName>.<ext>`). */
+    suggestedFilename: string;
+    /** Non-fatal notes accumulated during conversion (may be empty). */
+    warnings: string[];
+}
+/**
+ * A source normalized into every shape an exporter might need. `doc` is always
+ * present; `markdownDoc` is present when the source was markdown-shaped (an
+ * exporter that wants markdown but finds none derives it from `doc`).
+ */
+interface NormalizedInput {
+    doc: Doc;
+    markdownDoc?: MarkdownDocument;
+    container: ContentContainer;
+    baseName: string;
+}
+/** Options threaded through `convert()` and into every format method. */
+interface ConvertOptions {
+    /** Registry to resolve formats against. Defaults to `defaultRegistry()`. */
+    registry?: FormatRegistry;
+    /** Explicit source format id (skips extension/byte sniffing). */
+    from?: FormatId;
+    /** Theme id to apply to the exported document. */
+    themeId?: string;
+    /** Transform style id to apply before export. */
+    transformStyle?: string;
+    /** Content-aware auto-templating when deriving a Doc from markdown. */
+    autoTemplates?: boolean;
+    /** Title hint for exporters that support one (epub, html). */
+    title?: string;
+    /** Lazily resolve the standalone player IIFE bundle (required for HTML export). */
+    resolvePlayerScript?: () => Promise<string>;
+    /** Per-format escape hatch for extra options. */
+    formatOptions?: Record<FormatId, Record<string, unknown>>;
+}
+/** Describes how a single format imports to / exports from the squisq model. */
+interface FormatDefinition {
+    id: FormatId;
+    label: string;
+    mimeType: string;
+    extensions: readonly string[];
+    /** Import raw bytes to a MarkdownDocument. */
+    importDoc?(data: ArrayBuffer, options: ConvertOptions): Promise<MarkdownDocument>;
+    /** Import raw bytes to a ContentContainer (markdown + extracted media). */
+    importContainer?(data: ArrayBuffer, options: ConvertOptions): Promise<ContentContainer>;
+    /** Export a normalized input to bytes. */
+    exportDoc?(input: NormalizedInput, options: ConvertOptions): Promise<ConversionResult>;
+}
+/** A mutable collection of format definitions keyed by id. */
+interface FormatRegistry {
+    register(def: FormatDefinition): void;
+    get(id: FormatId): FormatDefinition | undefined;
+    byExtension(ext: string): FormatDefinition | undefined;
+    list(): FormatDefinition[];
+}
+/** The three shapes `convert()` accepts as a source. */
+type ConvertSource = {
+    kind: 'bytes';
+    data: ArrayBuffer | Uint8Array;
+    filename?: string;
+} | {
+    kind: 'markdown';
+    markdown: string | MarkdownDocument;
+    container?: ContentContainer;
+    baseName?: string;
+} | {
+    kind: 'doc';
+    doc: Doc;
+    container?: ContentContainer;
+    baseName?: string;
+};
+
+/**
+ * Structured error for the format registry / `convert()` pipeline.
+ *
+ * Every failure path in the registry throws a `ConversionError` with a stable
+ * machine-readable `code`, so callers can branch on the failure kind rather
+ * than string-matching messages.
+ */
+
+/** Machine-readable failure kinds surfaced by the registry / `convert()`. */
+type ConversionErrorCode = 'unknown-format' | 'unsupported-input' | 'unsupported-output' | 'invalid-input' | 'missing-dependency' | 'conversion-failed';
+/** Options for constructing a {@link ConversionError}. */
+interface ConversionErrorOptions {
+    /** The format id the error relates to, if any. */
+    format?: FormatId;
+    /** A human-oriented remediation hint. */
+    hint?: string;
+    /** The underlying error, preserved on `error.cause`. */
+    cause?: unknown;
+}
+/** An error raised by the format registry or `convert()`. */
+declare class ConversionError extends Error {
+    readonly code: ConversionErrorCode;
+    readonly format?: FormatId;
+    readonly hint?: string;
+    constructor(code: ConversionErrorCode, message: string, opts?: ConversionErrorOptions);
+}
+
+/**
+ * Format registry implementation.
+ *
+ * `createRegistry()` returns an empty, mutable registry (last-write-wins by id);
+ * `defaultRegistry()` returns one preloaded with every built-in format.
+ */
+
+/** Create an empty registry. Registering an existing id overwrites it. */
+declare function createRegistry(): FormatRegistry;
+/** Create a registry preloaded with all built-in formats. */
+declare function defaultRegistry(): FormatRegistry;
+
+/**
+ * Built-in format definitions.
+ *
+ * Each definition loads its converter module lazily via `import()` inside the
+ * method body, so importing the registry never eagerly bundles a heavy
+ * converter (pdf-lib, jszip, the OOXML writers, …). The capability of each
+ * format — which of import/export it supports — is expressed purely by which
+ * methods are present.
+ */
+
+declare function defaultFormats(): FormatDefinition[];
+
+/**
+ * Programmatic `convert()` — the format-registry front door.
+ *
+ * Normalizes any {@link ConvertSource} into a {@link NormalizedInput} (always
+ * yielding a `Doc`, keeping the `MarkdownDocument` when the source was
+ * markdown-shaped, and always carrying a `ContentContainer` for media), applies
+ * an optional transform, then hands off to the target format's exporter.
+ */
+
+/**
+ * Convert a source document to a target format.
+ *
+ * @param source - A bytes / markdown / doc source.
+ * @param to - The target format id (must be registered and support export).
+ * @param options - Conversion options (registry, theme, transform, …).
+ * @throws {@link ConversionError} on any failure, with a stable `code`.
+ */
+declare function convert(source: ConvertSource, to: FormatId, options?: ConvertOptions): Promise<ConversionResult>;
+
+export { BUILTIN_FORMAT_IDS, ConversionError, type ConversionErrorCode, type ConversionErrorOptions, type ConversionResult, type ConvertOptions, type ConvertSource, type FormatDefinition, type FormatId, type FormatRegistry, type NormalizedInput, convert, createRegistry, defaultFormats, defaultRegistry };

package/dist/registry/index.js

@@ -0,0 +1,17 @@
+import {
+  BUILTIN_FORMAT_IDS,
+  ConversionError,
+  convert,
+  createRegistry,
+  defaultFormats,
+  defaultRegistry
+} from "../chunk-RTS5XBZ7.js";
+export {
+  BUILTIN_FORMAT_IDS,
+  ConversionError,
+  convert,
+  createRegistry,
+  defaultFormats,
+  defaultRegistry
+};
+//# sourceMappingURL=index.js.map

package/dist/registry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/xlsx/index.d.ts

@@ -1,5 +1,5 @@
-import { MarkdownDocument } from '@bendyline/squisq/markdown';
 import { Doc } from '@bendyline/squisq/schemas';
+import { MarkdownDocument } from '@bendyline/squisq/markdown';
 
 /**
  * XLSX import — SpreadsheetML (.xlsx) → MarkdownDocument.
@@ -18,39 +18,69 @@ interface XlsxImportOptions {
 declare function xlsxToMarkdownDoc(data: ArrayBuffer | Blob, options?: XlsxImportOptions): Promise<MarkdownDocument>;
 
 /**
- * @bendyline/squisq-formats XLSX Module (Stub)
+ * 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.
  *
- * Placeholder for Excel .xlsx import/export support.
- * Will use SpreadsheetML (`<spreadsheet>`, `<worksheet>`, `<sheetData>`)
- * via the shared ooxml/ infrastructure.
+ * 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 (placeholder).
+ * Options for XLSX export.
  */
 interface XlsxExportOptions {
-    /** Workbook title */
+    /** Workbook title (written to core properties). */
     title?: string;
-    /** Workbook author */
+    /** 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 Blob.
+ * Convert a MarkdownDocument to a .xlsx file (tables-only fidelity).
  *
- * @throws Error — XLSX export is not yet implemented
+ * 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 markdownDocToXlsx(_doc: MarkdownDocument, _options?: XlsxExportOptions): Promise<Blob>;
+declare function docToXlsx(doc: Doc, options?: XlsxExportOptions): Promise<ArrayBuffer>;
+
 /**
- * Convert a squisq Doc to a .xlsx Blob.
+ * @bendyline/squisq-formats XLSX Module
+ *
+ * Excel .xlsx support via SpreadsheetML and the shared ooxml/ infrastructure.
+ * Both directions are implemented: import (`xlsxToMarkdownDoc` / `xlsxToDoc`)
+ * turns each worksheet grid into a markdown table; export (`markdownDocToXlsx`
+ * / `docToXlsx`) turns each markdown table into a worksheet. Export is
+ * tables-only fidelity — non-table content is dropped (headings only survive
+ * as sheet names). See export.ts for details.
  *
- * @throws Error — XLSX export is not yet implemented
+ * @example
+ * ```ts
+ * import { xlsxToMarkdownDoc, markdownDocToXlsx } from '@bendyline/squisq-formats/xlsx';
+ * ```
  */
-declare function docToXlsx(_doc: Doc, _options?: XlsxExportOptions): Promise<Blob>;
+
 /**
  * Convert a .xlsx file to a squisq Doc (via the markdown table model).
  */

package/dist/xlsx/index.js

@@ -3,8 +3,10 @@ import {
   markdownDocToXlsx,
   xlsxToDoc,
   xlsxToMarkdownDoc
-} from "../chunk-L53YIGYS.js";
-import "../chunk-FMOIGA5T.js";
+} from "../chunk-EHLGMSTE.js";
+import "../chunk-PN52A5AA.js";
+import "../chunk-SHLPSADL.js";
+import "../chunk-U4MRIFKL.js";
 export {
   docToXlsx,
   markdownDocToXlsx,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/squisq-formats",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Document format converters — DOCX, PDF, OOXML import/export",
   "license": "MIT",
   "author": "Bendyline",
@@ -81,6 +81,11 @@
       "types": "./dist/container/index.d.ts",
       "import": "./dist/container/index.js",
       "default": "./dist/container/index.js"
+    },
+    "./registry": {
+      "types": "./dist/registry/index.d.ts",
+      "import": "./dist/registry/index.js",
+      "default": "./dist/registry/index.js"
     }
   },
   "scripts": {
@@ -89,7 +94,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@bendyline/squisq": "1.5.0",
+    "@bendyline/squisq": "1.5.1",
     "jszip": "3.10.1",
     "pdf-lib": "1.17.1",
     "pdfjs-dist": "4.10.38"

package/src/__tests__/convert.test.ts

@@ -0,0 +1,186 @@
+/**
+ * Tests for the programmatic convert() entry point: normalization across the
+ * three source shapes, byte sniffing, transform threading, round-trips, and
+ * suggested-filename correctness.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { parseMarkdown } from '@bendyline/squisq/markdown';
+import { markdownToDoc } from '@bendyline/squisq/doc';
+import { convert, ConversionError, defaultRegistry } from '../registry/index';
+
+const SAMPLE_MD = `# Round Trip
+
+This is a paragraph that should survive a docx round trip.
+`;
+
+// ── unknown-format / unsupported-output ─────────────────────────────
+
+describe('convert error paths', () => {
+  it('throws unknown-format for an unregistered target', async () => {
+    await expect(convert({ kind: 'markdown', markdown: '# hi' }, 'nope')).rejects.toMatchObject({
+      name: 'ConversionError',
+      code: 'unknown-format',
+    });
+  });
+
+  it('throws unsupported-output when exporting to an import-only format', async () => {
+    // Register a definition with only importDoc, then export to it.
+    const registry = defaultRegistry();
+    registry.register({
+      id: 'importonly',
+      label: 'Import Only',
+      mimeType: 'application/x-import',
+      extensions: ['.imp'],
+      async importDoc() {
+        return parseMarkdown('# x');
+      },
+    });
+    await expect(
+      convert({ kind: 'markdown', markdown: '# hi' }, 'importonly', { registry }),
+    ).rejects.toMatchObject({ name: 'ConversionError', code: 'unsupported-output' });
+  });
+});
+
+// ── round trip: md → docx → md ──────────────────────────────────────
+
+describe('md → docx → md round trip', () => {
+  it('preserves paragraph text through a docx round trip', async () => {
+    const toDocx = await convert(
+      { kind: 'markdown', markdown: SAMPLE_MD, baseName: 'doc' },
+      'docx',
+    );
+    expect(toDocx.mimeType).toContain('wordprocessingml');
+    expect(toDocx.bytes.byteLength).toBeGreaterThan(0);
+
+    // Feed the docx bytes back in with an explicit `from`.
+    const backToMd = await convert(
+      { kind: 'bytes', data: toDocx.bytes, filename: 'doc.docx' },
+      'md',
+      { from: 'docx' },
+    );
+    const text = new TextDecoder().decode(backToMd.bytes);
+    expect(text).toContain('survive a docx round trip');
+    expect(backToMd.suggestedFilename).toBe('doc.md');
+  });
+});
+
+// ── byte sniffing ───────────────────────────────────────────────────
+
+describe('byte sniffing', () => {
+  it('sniffs a PDF by its %PDF magic', async () => {
+    // Stub the pdf importer so the test exercises the sniff, not pdfjs (which
+    // can't run under jsdom). Any %PDF-prefixed bytes must route to 'pdf'.
+    const registry = defaultRegistry();
+    registry.register({
+      ...registry.get('pdf')!,
+      importContainer: undefined, // force the importDoc path (skip pdfjs)
+      async importDoc() {
+        return parseMarkdown('# sniffed as pdf');
+      },
+    });
+    const pdfBytes = new TextEncoder().encode('%PDF-1.4\n%mock pdf body\n');
+    const back = await convert({ kind: 'bytes', data: pdfBytes }, 'md', { registry });
+    expect(new TextDecoder().decode(back.bytes)).toContain('sniffed as pdf');
+  });
+
+  it('sniffs a squisq container (plain zip, no [Content_Types].xml) as dbk', async () => {
+    // A dbk is a ZIP with a markdown doc and no OOXML content-types part.
+    const dbk = await convert({ kind: 'markdown', markdown: '# In a container\n\nBody.' }, 'dbk');
+    expect(dbk.mimeType).toBe('application/zip');
+
+    const back = await convert({ kind: 'bytes', data: dbk.bytes }, 'md');
+    const text = new TextDecoder().decode(back.bytes);
+    expect(text).toContain('In a container');
+  });
+
+  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.
+    const back = await convert({ kind: 'bytes', data: docx.bytes }, 'md');
+    const text = new TextDecoder().decode(back.bytes);
+    expect(text).toContain('Word doc');
+  });
+});
+
+// ── transform threading ─────────────────────────────────────────────
+
+describe('transform threading', () => {
+  it('applies a transform style before handing off to the exporter', async () => {
+    // A capture format records the NormalizedInput it receives, letting us
+    // observe that the transform ran without depending on any converter.
+    let captured: import('../registry/index').NormalizedInput | undefined;
+    const registry = defaultRegistry();
+    registry.register({
+      id: 'capture',
+      label: 'Capture',
+      mimeType: 'application/x-capture',
+      extensions: ['.cap'],
+      async exportDoc(input) {
+        captured = input;
+        return {
+          bytes: new Uint8Array([1]),
+          mimeType: 'application/x-capture',
+          suggestedFilename: '',
+          warnings: [],
+        };
+      },
+    });
+
+    const plainDoc = markdownToDoc(parseMarkdown(SAMPLE_MD));
+    await convert({ kind: 'markdown', markdown: SAMPLE_MD }, 'capture', {
+      registry,
+      transformStyle: 'magazine',
+    });
+
+    expect(captured).toBeDefined();
+    // The transform promotes/reshapes blocks, so the exporter sees a different
+    // Doc than a plain markdownToDoc of the same source.
+    expect(captured!.doc.blocks.length).not.toBe(plainDoc.blocks.length);
+    // markdownDoc is re-derived from the transformed Doc.
+    expect(captured!.markdownDoc).toBeDefined();
+  });
+});
+
+// ── doc-kind source ─────────────────────────────────────────────────
+
+describe('doc-kind source', () => {
+  it('exports a Doc source', async () => {
+    const doc = markdownToDoc(parseMarkdown('# From a Doc\n\nContent.'));
+    const result = await convert({ kind: 'doc', doc, baseName: 'fromdoc' }, 'md');
+    const text = new TextDecoder().decode(result.bytes);
+    expect(text).toContain('From a Doc');
+    expect(result.suggestedFilename).toBe('fromdoc.md');
+  });
+});
+
+// ── suggested filename ──────────────────────────────────────────────
+
+describe('suggestedFilename', () => {
+  it('uses the primary extension per format', async () => {
+    const docx = await convert({ kind: 'markdown', markdown: '# t', baseName: 'report' }, 'docx');
+    expect(docx.suggestedFilename).toBe('report.docx');
+  });
+
+  it('htmlzip suggests <base>.html.zip', async () => {
+    const zip = await convert(
+      { kind: 'markdown', markdown: '# t', baseName: 'slides' },
+      'htmlzip',
+      {
+        resolvePlayerScript: async () => '/* stub */',
+      },
+    );
+    expect(zip.suggestedFilename).toBe('slides.html.zip');
+    expect(zip.mimeType).toBe('application/zip');
+  });
+
+  it('defaults baseName to "document" when none is given', async () => {
+    const out = await convert({ kind: 'markdown', markdown: '# t' }, 'md');
+    expect(out.suggestedFilename).toBe('document.md');
+  });
+});
+
+// sanity: ConversionError is exported and usable
+it('exports ConversionError', () => {
+  expect(new ConversionError('conversion-failed', 'x')).toBeInstanceOf(Error);
+});