@bendyline/squisq-formats 1.4.2 → 2.0.0

package/src/registry/convert.ts

@@ -9,9 +9,12 @@
 
 import type { MarkdownDocument } from '@bendyline/squisq/markdown';
 import type { ContentContainer } from '@bendyline/squisq/storage';
+import type { TransformStyleInput, TransformStyleRegistry } from '@bendyline/squisq/transform';
 import { ConversionError } from './errors.js';
 import { defaultRegistry } from './registry.js';
+import { openBoundedZipArchive, ZipSafetyError } from '../shared/zipSafety.js';
 import type {
+  BuiltinFormatOptions,
   ConversionResult,
   ConvertOptions,
   ConvertSource,
@@ -21,6 +24,10 @@ import type {
   NormalizedInput,
 } from './types.js';
 
+function markdownFormatOptions(options: ConvertOptions): BuiltinFormatOptions['md'] {
+  return (options.formatOptions?.md ?? {}) as BuiltinFormatOptions['md'];
+}
+
 // ── Byte sniffing ───────────────────────────────────────────────────
 
 function hasPrefix(bytes: Uint8Array, prefix: number[]): boolean {
@@ -41,13 +48,19 @@ const PDF_MAGIC = [0x25, 0x50, 0x44, 0x46]; // "%PDF"
  * marker means `dbk`.
  */
 async function sniffZip(bytes: Uint8Array): Promise<FormatId> {
-  const JSZip = (await import('jszip')).default;
-  const zip = await JSZip.loadAsync(bytes).catch(() => {
-    throw new ConversionError('invalid-input', 'Input is not a readable ZIP archive.');
+  const archive = await openBoundedZipArchive(bytes).catch((cause: unknown) => {
+    if (cause instanceof ZipSafetyError && cause.code !== 'invalid-archive') throw cause;
+    throw new ConversionError('invalid-input', 'Input is not a readable ZIP archive.', { cause });
   });
-  const contentTypes = zip.file('[Content_Types].xml');
+  const contentTypes = archive.entries.find((entry) => entry.path === '[Content_Types].xml');
   if (!contentTypes) return 'dbk';
-  const xml = await contentTypes.async('string');
+  const maxContentTypesBytes = 1024 * 1024;
+  if ((contentTypes.declaredSize ?? 0) > maxContentTypesBytes) {
+    throw new ConversionError('invalid-input', 'OOXML content-types metadata is too large.');
+  }
+  const xmlBytes = await archive.read(contentTypes.path, maxContentTypesBytes);
+  if (!xmlBytes) return 'dbk';
+  const xml = new TextDecoder().decode(xmlBytes);
   if (xml.includes('wordprocessingml')) return 'docx';
   if (xml.includes('presentationml')) return 'pptx';
   if (xml.includes('spreadsheetml')) return 'xlsx';
@@ -80,7 +93,8 @@ async function detectByteFormat(
 
 /** Lowercased extension without the leading dot (`report.DocX` → `docx`). */
 function extractExt(filename: string): string {
-  const base = filename.split('/').pop() ?? filename;
+  const normalized = filename.replace(/\\/g, '/');
+  const base = normalized.split('/').pop() ?? normalized;
   const dot = base.lastIndexOf('.');
   if (dot <= 0) return '';
   return base.slice(dot + 1).toLowerCase();
@@ -88,7 +102,8 @@ function extractExt(filename: string): string {
 
 /** Basename without its final extension (`a/b/report.docx` → `report`). */
 function baseNameOf(filename: string): string {
-  const base = filename.split('/').pop() ?? filename;
+  const normalized = filename.replace(/\\/g, '/');
+  const base = normalized.split('/').pop() ?? normalized;
   const dot = base.lastIndexOf('.');
   return dot > 0 ? base.slice(0, dot) : base;
 }
@@ -147,7 +162,9 @@ async function normalizeBytes(
       );
     }
     const text = await container.readDocument();
-    markdownDoc = text ? parseMarkdown(text) : { type: 'document', children: [] };
+    markdownDoc = text
+      ? parseMarkdown(text, markdownFormatOptions(options).parse)
+      : { type: 'document', children: [] };
   } else {
     // importDoc is guaranteed present by the guard above.
     markdownDoc = await fromDef.importDoc!(buffer, options);
@@ -176,7 +193,9 @@ async function normalizeMarkdown(
   const { stringifyMarkdown } = await import('@bendyline/squisq/markdown');
 
   const markdownDoc =
-    typeof source.markdown === 'string' ? parseMarkdown(source.markdown) : source.markdown;
+    typeof source.markdown === 'string'
+      ? parseMarkdown(source.markdown, markdownFormatOptions(options).parse)
+      : source.markdown;
 
   let container = source.container;
   if (!container) {
@@ -228,13 +247,14 @@ async function normalize(
 
 async function applyTransformStyle(
   input: NormalizedInput,
-  transformStyle: string,
+  transformStyle: TransformStyleInput,
   themeId?: string,
+  registry?: TransformStyleRegistry,
 ): Promise<string[]> {
   const { applyTransform, extractDocImages } = await import('@bendyline/squisq/transform');
   const { docToMarkdown, markdownToDoc } = await import('@bendyline/squisq/doc');
   const images = extractDocImages(input.doc.blocks);
-  const result = applyTransform(input.doc, transformStyle, { themeId, images });
+  const result = applyTransform(input.doc, transformStyle, { themeId, images, registry });
   input.doc = result.doc;
   const markdownDoc = docToMarkdown(result.doc);
   input.markdownDoc = markdownDoc;
@@ -283,25 +303,36 @@ export async function convert(
     );
   }
 
-  const { input, warnings } = await normalize(source, options, registry);
+  let normalized: Normalized;
+  try {
+    normalized = await normalize(source, options, registry);
+  } catch (err: unknown) {
+    if (err instanceof ConversionError) throw err;
+    const message = err instanceof Error ? err.message : String(err);
+    throw new ConversionError('invalid-input', message, {
+      format: options.from,
+      cause: err,
+    });
+  }
+  const { input, warnings } = normalized;
 
   // Respect an existing doc theme; only fill it in from options when absent.
   if (options.themeId && !input.doc.themeId) {
-    input.doc.themeId = options.themeId;
-  }
-
-  if (options.transformStyle) {
-    warnings.push(
-      ...(await applyTransformStyle(
-        input,
-        options.transformStyle,
-        options.themeId ?? input.doc.themeId,
-      )),
-    );
+    input.doc = { ...input.doc, themeId: options.themeId };
   }
 
   let result: ConversionResult;
   try {
+    if (options.transformStyle) {
+      warnings.push(
+        ...(await applyTransformStyle(
+          input,
+          options.transformStyle,
+          options.themeId ?? input.doc.themeId,
+          options.transformRegistry,
+        )),
+      );
+    }
     result = await target.exportDoc(input, options);
   } catch (err: unknown) {
     if (err instanceof ConversionError) throw err;

package/src/registry/defaultFormats.ts

@@ -11,8 +11,10 @@
 import type { ContentContainer } from '@bendyline/squisq/storage';
 import type { MarkdownDocument } from '@bendyline/squisq/markdown';
 import { ConversionError } from './errors.js';
+import { markdownFidelityWarnings } from '../shared/fidelity.js';
 import type {
   ConversionResult,
+  BuiltinFormatOptions,
   ConvertOptions,
   FormatDefinition,
   NormalizedInput,
@@ -57,6 +59,13 @@ function resolveThemeId(input: NormalizedInput, options: ConvertOptions): string
   return options.themeId ?? input.doc.themeId;
 }
 
+function optionsFor<K extends keyof BuiltinFormatOptions>(
+  options: ConvertOptions,
+  id: K,
+): BuiltinFormatOptions[K] {
+  return (options.formatOptions?.[id] ?? {}) as BuiltinFormatOptions[K];
+}
+
 /** The markdown shape an exporter needs — reuse the source's, else derive it. */
 async function markdownOf(input: NormalizedInput): Promise<MarkdownDocument> {
   if (input.markdownDoc) return input.markdownDoc;
@@ -85,6 +94,34 @@ async function collectContainerImages(
   return images;
 }
 
+async function collectContainerDocxImages(
+  container: ContentContainer,
+): Promise<Map<string, { data: ArrayBuffer; contentType: string }>> {
+  const images = await collectContainerImages(container);
+  const { extToMime } = await import('../shared/images.js');
+  return new Map(
+    [...images].map(([path, data]) => [
+      path,
+      { data, contentType: extToMime(path.split('.').pop() ?? '') },
+    ]),
+  );
+}
+
+/** Copy a container and make its primary document match the normalized source. */
+async function snapshotContainerWithDocument(input: NormalizedInput): Promise<ContentContainer> {
+  const { MemoryContentContainer } = await import('@bendyline/squisq/storage');
+  const snapshot = new MemoryContentContainer();
+  const entries = await input.container.listFiles();
+  for (const entry of entries) {
+    const data = await input.container.readFile(entry.path);
+    if (data) await snapshot.writeFile(entry.path, new Uint8Array(data), entry.mimeType);
+  }
+  const { stringifyMarkdown } = await import('@bendyline/squisq/markdown');
+  const documentPath = (await input.container.getDocumentPath()) ?? 'index.md';
+  await snapshot.writeDocument(stringifyMarkdown(await markdownOf(input)), documentPath);
+  return snapshot;
+}
+
 /** Resolve the player IIFE bundle or throw a helpful missing-dependency error. */
 async function requirePlayerScript(options: ConvertOptions, format: string): Promise<string> {
   const script = await options.resolvePlayerScript?.();
@@ -102,6 +139,20 @@ function ok(bytes: Uint8Array, mimeType: string, warnings: string[] = []): Conve
   return { bytes, mimeType, suggestedFilename: '', warnings };
 }
 
+/**
+ * Narrow the untyped per-format escape hatch (`options.formatOptions.pptx`)
+ * into the PPTX importer's options. Theme + layout inference default ON;
+ * only an explicit `false` disables them.
+ */
+function pptxImportOptionsFrom(options: ConvertOptions): BuiltinFormatOptions['pptx'] {
+  const raw = optionsFor(options, 'pptx');
+  return {
+    ...raw,
+    inferTheme: raw?.inferTheme !== false,
+    inferLayouts: raw?.inferLayouts !== false,
+  };
+}
+
 // ── Definitions ─────────────────────────────────────────────────────
 
 export function defaultFormats(): FormatDefinition[] {
@@ -110,13 +161,13 @@ export function defaultFormats(): FormatDefinition[] {
     label: 'Markdown',
     mimeType: MIME.md,
     extensions: ['.md', '.markdown'],
-    async importDoc(data): Promise<MarkdownDocument> {
+    async importDoc(data, options): Promise<MarkdownDocument> {
       const { parseMarkdown } = await import('@bendyline/squisq/markdown');
-      return parseMarkdown(new TextDecoder().decode(data));
+      return parseMarkdown(new TextDecoder().decode(data), optionsFor(options, 'md').parse);
     },
-    async exportDoc(input): Promise<ConversionResult> {
+    async exportDoc(input, options): Promise<ConversionResult> {
       const { stringifyMarkdown } = await import('@bendyline/squisq/markdown');
-      const text = stringifyMarkdown(await markdownOf(input));
+      const text = stringifyMarkdown(await markdownOf(input), optionsFor(options, 'md').stringify);
       return ok(new TextEncoder().encode(text), MIME.md);
     },
   };
@@ -126,20 +177,28 @@ export function defaultFormats(): FormatDefinition[] {
     label: 'Word (DOCX)',
     mimeType: MIME.docx,
     extensions: ['.docx'],
-    async importContainer(data): Promise<ContentContainer> {
+    async importContainer(data, options): Promise<ContentContainer> {
       const { docxToContainer } = await import('../docx/index.js');
-      return docxToContainer(data);
+      return docxToContainer(data, optionsFor(options, 'docx'));
     },
-    async importDoc(data): Promise<MarkdownDocument> {
+    async importDoc(data, options): Promise<MarkdownDocument> {
       const { docxToMarkdownDoc } = await import('../docx/index.js');
-      return docxToMarkdownDoc(data);
+      return docxToMarkdownDoc(data, optionsFor(options, 'docx'));
     },
     async exportDoc(input, options): Promise<ConversionResult> {
       const { markdownDocToDocx } = await import('../docx/index.js');
-      const buf = await markdownDocToDocx(await markdownOf(input), {
+      const raw = optionsFor(options, 'docx');
+      const markdownDoc = await markdownOf(input);
+      const containerImages = await collectContainerDocxImages(input.container);
+      const images = new Map([...containerImages, ...(raw.images ?? new Map())]);
+      const buf = await markdownDocToDocx(markdownDoc, {
+        ...raw,
+        ...(options.title !== undefined ? { title: options.title } : {}),
         themeId: resolveThemeId(input, options),
+        themeRegistry: options.themeRegistry ?? raw.themeRegistry,
+        images,
       });
-      return ok(await toBytes(buf), MIME.docx);
+      return ok(await toBytes(buf), MIME.docx, markdownFidelityWarnings(markdownDoc, 'docx'));
     },
   };
 
@@ -148,20 +207,25 @@ export function defaultFormats(): FormatDefinition[] {
     label: 'PDF',
     mimeType: MIME.pdf,
     extensions: ['.pdf'],
-    async importContainer(data): Promise<ContentContainer> {
+    async importContainer(data, options): Promise<ContentContainer> {
       const { pdfToContainer } = await import('../pdf/index.js');
-      return pdfToContainer(data);
+      return pdfToContainer(data, optionsFor(options, 'pdf'));
     },
-    async importDoc(data): Promise<MarkdownDocument> {
+    async importDoc(data, options): Promise<MarkdownDocument> {
       const { pdfToMarkdownDoc } = await import('../pdf/index.js');
-      return pdfToMarkdownDoc(data);
+      return pdfToMarkdownDoc(data, optionsFor(options, 'pdf'));
     },
     async exportDoc(input, options): Promise<ConversionResult> {
       const { markdownDocToPdf } = await import('../pdf/index.js');
-      const buf = await markdownDocToPdf(await markdownOf(input), {
+      const raw = optionsFor(options, 'pdf');
+      const markdownDoc = await markdownOf(input);
+      const buf = await markdownDocToPdf(markdownDoc, {
+        ...raw,
+        ...(options.title !== undefined ? { title: options.title } : {}),
         themeId: resolveThemeId(input, options),
+        themeRegistry: options.themeRegistry ?? raw.themeRegistry,
       });
-      return ok(await toBytes(buf), MIME.pdf);
+      return ok(await toBytes(buf), MIME.pdf, markdownFidelityWarnings(markdownDoc, 'pdf'));
     },
   };
 
@@ -170,22 +234,28 @@ export function defaultFormats(): FormatDefinition[] {
     label: 'PowerPoint (PPTX)',
     mimeType: MIME.pptx,
     extensions: ['.pptx'],
-    async importContainer(data): Promise<ContentContainer> {
+    async importContainer(data, options): Promise<ContentContainer> {
       const { pptxToContainer } = await import('../pptx/index.js');
-      return pptxToContainer(data);
+      return pptxToContainer(data, pptxImportOptionsFrom(options));
     },
-    async importDoc(data): Promise<MarkdownDocument> {
+    async importDoc(data, options): Promise<MarkdownDocument> {
       const { pptxToMarkdownDoc } = await import('../pptx/index.js');
-      return pptxToMarkdownDoc(data);
+      return pptxToMarkdownDoc(data, pptxImportOptionsFrom(options));
     },
     async exportDoc(input, options): Promise<ConversionResult> {
       const { markdownDocToPptx } = await import('../pptx/index.js');
-      const images = await collectContainerImages(input.container);
-      const buf = await markdownDocToPptx(await markdownOf(input), {
+      const raw = optionsFor(options, 'pptx');
+      const markdownDoc = await markdownOf(input);
+      const containerImages = await collectContainerImages(input.container);
+      const images = new Map([...containerImages, ...(raw.images ?? new Map())]);
+      const buf = await markdownDocToPptx(markdownDoc, {
+        ...raw,
+        ...(options.title !== undefined ? { title: options.title } : {}),
         themeId: resolveThemeId(input, options),
+        themeRegistry: options.themeRegistry ?? raw.themeRegistry,
         images,
       });
-      return ok(await toBytes(buf), MIME.pptx);
+      return ok(await toBytes(buf), MIME.pptx, markdownFidelityWarnings(markdownDoc, 'pptx'));
     },
   };
 
@@ -194,11 +264,11 @@ export function defaultFormats(): FormatDefinition[] {
     label: 'Excel (XLSX)',
     mimeType: MIME.xlsx,
     extensions: ['.xlsx'],
-    async importDoc(data): Promise<MarkdownDocument> {
+    async importDoc(data, options): Promise<MarkdownDocument> {
       const { xlsxToMarkdownDoc } = await import('../xlsx/index.js');
-      return xlsxToMarkdownDoc(data);
+      return xlsxToMarkdownDoc(data, optionsFor(options, 'xlsx'));
     },
-    async exportDoc(input): Promise<ConversionResult> {
+    async exportDoc(input, options): Promise<ConversionResult> {
       const { markdownDocToXlsx } = await import('../xlsx/index.js');
       const markdownDoc = await markdownOf(input);
       // XLSX fidelity is tables-only: `table` nodes become worksheets and
@@ -211,7 +281,10 @@ export function defaultFormats(): FormatDefinition[] {
         omitted > 0
           ? [`XLSX export is tables-only; ${omitted} non-table block(s) were omitted.`]
           : [];
-      const blob = await markdownDocToXlsx(markdownDoc);
+      const blob = await markdownDocToXlsx(markdownDoc, {
+        ...optionsFor(options, 'xlsx'),
+        ...(options.title !== undefined ? { title: options.title } : {}),
+      });
       return ok(await toBytes(blob), MIME.xlsx, warnings);
     },
   };
@@ -221,21 +294,22 @@ export function defaultFormats(): FormatDefinition[] {
     label: 'CSV',
     mimeType: MIME.csv,
     extensions: ['.csv'],
-    async importDoc(data): Promise<MarkdownDocument> {
+    async importDoc(data, options): Promise<MarkdownDocument> {
       const { csvToMarkdownDoc } = await import('../csv/index.js');
-      return csvToMarkdownDoc(data);
+      return csvToMarkdownDoc(data, optionsFor(options, 'csv'));
     },
-    async exportDoc(input): Promise<ConversionResult> {
+    async exportDoc(input, options): Promise<ConversionResult> {
       const { markdownDocToCsv } = await import('../csv/index.js');
       const markdownDoc = await markdownOf(input);
+      const raw = optionsFor(options, 'csv');
       const tableCount = markdownDoc.children.filter((n) => n.type === 'table').length;
       const warnings: string[] = [];
-      if (tableCount > 1) {
+      if (tableCount > 1 && raw.tableIndex === undefined) {
         warnings.push(
           `Document has ${tableCount} tables; CSV export emitted only the first. Use the csv converter's tableIndex option to select another.`,
         );
       }
-      const text = markdownDocToCsv(markdownDoc);
+      const text = markdownDocToCsv(markdownDoc, raw);
       return ok(new TextEncoder().encode(text), MIME.csv, warnings);
     },
   };
@@ -245,22 +319,26 @@ export function defaultFormats(): FormatDefinition[] {
     label: 'HTML (single file)',
     mimeType: MIME.html,
     extensions: ['.html', '.htm'],
-    async importDoc(data): Promise<MarkdownDocument> {
+    async importDoc(data, options): Promise<MarkdownDocument> {
       const { htmlToMarkdownDoc } = await import('../html/index.js');
-      return htmlToMarkdownDoc(data);
+      return htmlToMarkdownDoc(data, optionsFor(options, 'html'));
     },
     // importContainer omitted: HTML import already inlines images as data URIs,
     // so there is nothing to extract into a container this wave.
     async exportDoc(input, options): Promise<ConversionResult> {
       const playerScript = await requirePlayerScript(options, 'html');
       const { docToHtml } = await import('../html/index.js');
-      const images = await collectContainerImages(input.container);
+      const raw = optionsFor(options, 'html');
+      const containerImages = await collectContainerImages(input.container);
+      const images = new Map([...containerImages, ...(raw.images ?? new Map())]);
       const htmlText = docToHtml(input.doc, {
+        ...raw,
         playerScript,
         images,
         title: options.title ?? input.baseName,
-        mode: 'static',
+        mode: raw.mode ?? 'static',
         themeId: resolveThemeId(input, options),
+        themeRegistry: options.themeRegistry ?? raw.themeRegistry,
       });
       return ok(new TextEncoder().encode(htmlText), MIME.html);
     },
@@ -274,13 +352,17 @@ export function defaultFormats(): FormatDefinition[] {
     async exportDoc(input, options): Promise<ConversionResult> {
       const playerScript = await requirePlayerScript(options, 'htmlzip');
       const { docToHtmlZip } = await import('../html/index.js');
-      const images = await collectContainerImages(input.container);
+      const raw = optionsFor(options, 'htmlzip');
+      const containerImages = await collectContainerImages(input.container);
+      const images = new Map([...containerImages, ...(raw.images ?? new Map())]);
       const blob = await docToHtmlZip(input.doc, {
+        ...raw,
         playerScript,
         images,
         title: options.title ?? input.baseName,
-        mode: 'static',
+        mode: raw.mode ?? 'static',
         themeId: resolveThemeId(input, options),
+        themeRegistry: options.themeRegistry ?? raw.themeRegistry,
       });
       return ok(await toBytes(blob), MIME.zip);
     },
@@ -293,13 +375,18 @@ export function defaultFormats(): FormatDefinition[] {
     extensions: ['.epub'],
     async exportDoc(input, options): Promise<ConversionResult> {
       const { markdownDocToEpub } = await import('../epub/index.js');
-      const images = await collectContainerImages(input.container);
-      const buf = await markdownDocToEpub(await markdownOf(input), {
+      const raw = optionsFor(options, 'epub');
+      const markdownDoc = await markdownOf(input);
+      const containerImages = await collectContainerImages(input.container);
+      const images = new Map([...containerImages, ...(raw.images ?? new Map())]);
+      const buf = await markdownDocToEpub(markdownDoc, {
+        ...raw,
         title: options.title ?? input.baseName,
         themeId: resolveThemeId(input, options),
+        themeRegistry: options.themeRegistry ?? raw.themeRegistry,
         images,
       });
-      return ok(await toBytes(buf), MIME.epub);
+      return ok(await toBytes(buf), MIME.epub, markdownFidelityWarnings(markdownDoc, 'epub'));
     },
   };
 
@@ -308,13 +395,13 @@ export function defaultFormats(): FormatDefinition[] {
     label: 'Squisq container (DBK)',
     mimeType: MIME.zip,
     extensions: ['.dbk', '.zip'],
-    async importContainer(data): Promise<ContentContainer> {
+    async importContainer(data, options): Promise<ContentContainer> {
       const { zipToContainer } = await import('../container/index.js');
-      return zipToContainer(data);
+      return zipToContainer(data, optionsFor(options, 'dbk'));
     },
     async exportDoc(input): Promise<ConversionResult> {
       const { containerToZip } = await import('../container/index.js');
-      const blob = await containerToZip(input.container);
+      const blob = await containerToZip(await snapshotContainerWithDocument(input));
       return ok(await toBytes(blob), MIME.zip);
     },
   };

package/src/registry/index.ts

@@ -27,6 +27,9 @@ export type {
   FormatDefinition,
   FormatRegistry,
   ConvertSource,
+  BuiltinFormatOptions,
+  MarkdownFormatOptions,
+  DbkFormatOptions,
 } from './types.js';
 export { BUILTIN_FORMAT_IDS } from './types.js';
 

package/src/registry/types.ts

@@ -8,9 +8,24 @@
  * methods, so pulling in the registry never eagerly bundles heavy converters.
  */
 
-import type { Doc } from '@bendyline/squisq/schemas';
+import type { Doc, ThemeRegistry } from '@bendyline/squisq/schemas';
+import type { TransformStyleInput, TransformStyleRegistry } from '@bendyline/squisq/transform';
 import type { MarkdownDocument } from '@bendyline/squisq/markdown';
 import type { ContentContainer } from '@bendyline/squisq/storage';
+import type { ParseOptions, StringifyOptions } from '@bendyline/squisq/markdown';
+import type { DocxExportOptions } from '../docx/export.js';
+import type { DocxImportOptions } from '../docx/import.js';
+import type { PptxExportOptions } from '../pptx/export.js';
+import type { PptxImportOptions } from '../pptx/import.js';
+import type { XlsxExportOptions } from '../xlsx/export.js';
+import type { XlsxImportOptions } from '../xlsx/import.js';
+import type { CsvExportOptions, CsvImportOptions } from '../csv/index.js';
+import type { PdfExportOptions } from '../pdf/export.js';
+import type { PdfImportOptions } from '../pdf/import.js';
+import type { HtmlExportOptions } from '../html/htmlTemplate.js';
+import type { HtmlImportOptions } from '../html/import.js';
+import type { EpubExportOptions } from '../epub/export.js';
+import type { ZipSafetyLimits } from '../shared/zipSafety.js';
 
 /** A format identifier (e.g. `'docx'`). Strings so hosts can register their own. */
 export type FormatId = string;
@@ -41,6 +56,33 @@ export interface ConversionResult {
   warnings: string[];
 }
 
+export interface MarkdownFormatOptions {
+  parse?: ParseOptions;
+  stringify?: StringifyOptions;
+}
+
+/** Resource limits applied when importing a DBK/ZIP container. */
+export type DbkFormatOptions = ZipSafetyLimits;
+
+/**
+ * Strongly typed option bags for built-in formats. Import and export options
+ * share a bag because a single conversion may use the format on either side.
+ * Custom registries may add arbitrary keys through the intersection used by
+ * {@link ConvertOptions.formatOptions}.
+ */
+export interface BuiltinFormatOptions {
+  md: MarkdownFormatOptions;
+  docx: DocxImportOptions & DocxExportOptions;
+  pptx: PptxImportOptions & PptxExportOptions;
+  xlsx: XlsxImportOptions & XlsxExportOptions;
+  csv: CsvImportOptions & CsvExportOptions;
+  pdf: PdfImportOptions & PdfExportOptions;
+  html: HtmlImportOptions & Partial<Omit<HtmlExportOptions, 'playerScript'>>;
+  htmlzip: Partial<Omit<HtmlExportOptions, 'playerScript'>>;
+  epub: EpubExportOptions;
+  dbk: DbkFormatOptions;
+}
+
 /**
  * A source normalized into every shape an exporter might need. `doc` is always
  * present; `markdownDoc` is present when the source was markdown-shaped (an
@@ -61,16 +103,20 @@ export interface ConvertOptions {
   from?: FormatId;
   /** Theme id to apply to the exported document. */
   themeId?: string;
-  /** Transform style id to apply before export. */
-  transformStyle?: string;
+  /** Explicit caller-owned registry for non-document custom themes. */
+  themeRegistry?: ThemeRegistry;
+  /** Built-in/registry id or call-scoped style to apply before export. */
+  transformStyle?: TransformStyleInput;
+  /** Explicit caller-owned registry used to resolve transform style ids. */
+  transformRegistry?: TransformStyleRegistry;
   /** Content-aware auto-templating when deriving a Doc from markdown. */
   autoTemplates?: boolean;
-  /** Title hint for exporters that support one (epub, html). */
+  /** Title hint for exporters that expose document metadata. */
   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>>;
+  /** Typed per-format options for built-ins; custom format ids remain extensible. */
+  formatOptions?: Partial<BuiltinFormatOptions> & Record<FormatId, unknown>;
 }
 
 /** Describes how a single format imports to / exports from the squisq model. */