@bendyline/squisq-formats 1.4.0 → 1.4.2

package/src/registry/convert.ts

@@ -0,0 +1,318 @@
+/**
+ * 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.
+ */
+
+import type { MarkdownDocument } from '@bendyline/squisq/markdown';
+import type { ContentContainer } from '@bendyline/squisq/storage';
+import { ConversionError } from './errors.js';
+import { defaultRegistry } from './registry.js';
+import type {
+  ConversionResult,
+  ConvertOptions,
+  ConvertSource,
+  FormatDefinition,
+  FormatId,
+  FormatRegistry,
+  NormalizedInput,
+} from './types.js';
+
+// ── Byte sniffing ───────────────────────────────────────────────────
+
+function hasPrefix(bytes: Uint8Array, prefix: number[]): boolean {
+  if (bytes.length < prefix.length) return false;
+  for (let i = 0; i < prefix.length; i++) {
+    if (bytes[i] !== prefix[i]) return false;
+  }
+  return true;
+}
+
+const ZIP_MAGIC = [0x50, 0x4b, 0x03, 0x04]; // "PK\x03\x04"
+const PDF_MAGIC = [0x25, 0x50, 0x44, 0x46]; // "%PDF"
+
+/**
+ * Disambiguate a ZIP-based file. OOXML formats (docx/pptx/xlsx) all carry a
+ * `[Content_Types].xml` whose content-type strings name the flavor; a squisq
+ * container (.dbk) is a plain ZIP with no such part, so absence of the OOXML
+ * 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 contentTypes = zip.file('[Content_Types].xml');
+  if (!contentTypes) return 'dbk';
+  const xml = await contentTypes.async('string');
+  if (xml.includes('wordprocessingml')) return 'docx';
+  if (xml.includes('presentationml')) return 'pptx';
+  if (xml.includes('spreadsheetml')) return 'xlsx';
+  return 'dbk';
+}
+
+/** Determine the source format for raw bytes. */
+async function detectByteFormat(
+  bytes: Uint8Array,
+  filename: string | undefined,
+  options: ConvertOptions,
+  registry: FormatRegistry,
+): Promise<FormatId> {
+  if (options.from) return options.from;
+
+  const ext = filename ? extractExt(filename) : undefined;
+  if (ext) {
+    const byExt = registry.byExtension(ext);
+    if (byExt) return byExt.id;
+  }
+
+  if (hasPrefix(bytes, PDF_MAGIC)) return 'pdf';
+  if (hasPrefix(bytes, ZIP_MAGIC)) return sniffZip(bytes);
+
+  // No magic and no recognized extension → assume UTF-8 markdown.
+  return 'md';
+}
+
+// ── Filename helpers ────────────────────────────────────────────────
+
+/** Lowercased extension without the leading dot (`report.DocX` → `docx`). */
+function extractExt(filename: string): string {
+  const base = filename.split('/').pop() ?? filename;
+  const dot = base.lastIndexOf('.');
+  if (dot <= 0) return '';
+  return base.slice(dot + 1).toLowerCase();
+}
+
+/** Basename without its final extension (`a/b/report.docx` → `report`). */
+function baseNameOf(filename: string): string {
+  const base = filename.split('/').pop() ?? filename;
+  const dot = base.lastIndexOf('.');
+  return dot > 0 ? base.slice(0, dot) : base;
+}
+
+// ── Normalization ───────────────────────────────────────────────────
+
+interface Normalized {
+  input: NormalizedInput;
+  warnings: string[];
+}
+
+async function normalizeBytes(
+  source: Extract<ConvertSource, { kind: 'bytes' }>,
+  options: ConvertOptions,
+  registry: FormatRegistry,
+): Promise<Normalized> {
+  const bytes = source.data instanceof Uint8Array ? source.data : new Uint8Array(source.data);
+  const buffer = bytes.buffer.slice(
+    bytes.byteOffset,
+    bytes.byteOffset + bytes.byteLength,
+  ) as ArrayBuffer;
+
+  const fromId = await detectByteFormat(bytes, source.filename, options, registry);
+  const fromDef = registry.get(fromId);
+  if (!fromDef) {
+    throw new ConversionError('unknown-format', `Unknown source format "${fromId}".`, {
+      format: fromId,
+    });
+  }
+  if (!fromDef.importContainer && !fromDef.importDoc) {
+    throw new ConversionError(
+      'unsupported-input',
+      `Format "${fromDef.label}" cannot be used as a conversion source.`,
+      {
+        format: fromId,
+        hint: 'This format is export-only.',
+      },
+    );
+  }
+
+  const { markdownToDoc } = await import('@bendyline/squisq/doc');
+  const { parseMarkdown, stringifyMarkdown } = await import('@bendyline/squisq/markdown');
+
+  const warnings: string[] = [];
+  let markdownDoc: MarkdownDocument;
+  let container: ContentContainer;
+
+  if (fromDef.importContainer) {
+    container = await fromDef.importContainer(buffer, options);
+    // PDF embedded-image extraction needs a browser canvas; under Node it's
+    // skipped inside pdfToContainer. importContainer has no warnings channel of
+    // its own, so surface that degraded path here where warnings are collected.
+    if (fromDef.id === 'pdf' && typeof document === 'undefined') {
+      warnings.push(
+        'PDF embedded images were skipped — image decoding requires a browser canvas (running under Node).',
+      );
+    }
+    const text = await container.readDocument();
+    markdownDoc = text ? parseMarkdown(text) : { type: 'document', children: [] };
+  } else {
+    // importDoc is guaranteed present by the guard above.
+    markdownDoc = await fromDef.importDoc!(buffer, options);
+    const { MemoryContentContainer } = await import('@bendyline/squisq/storage');
+    const mem = new MemoryContentContainer();
+    await mem.writeDocument(stringifyMarkdown(markdownDoc));
+    container = mem;
+  }
+
+  const doc = markdownToDoc(markdownDoc, { autoTemplates: options.autoTemplates });
+  const baseName = source.filename ? baseNameOf(source.filename) : 'document';
+
+  return {
+    input: { doc, markdownDoc, container, baseName },
+    warnings,
+  };
+}
+
+async function normalizeMarkdown(
+  source: Extract<ConvertSource, { kind: 'markdown' }>,
+  options: ConvertOptions,
+): Promise<Normalized> {
+  const { markdownToDoc } = await import('@bendyline/squisq/doc');
+  const { parseMarkdown } = await import('@bendyline/squisq/markdown');
+
+  const { stringifyMarkdown } = await import('@bendyline/squisq/markdown');
+
+  const markdownDoc =
+    typeof source.markdown === 'string' ? parseMarkdown(source.markdown) : source.markdown;
+
+  let container = source.container;
+  if (!container) {
+    // Seed a fresh container with the document so container-backed exports
+    // (dbk) and media resolution have the markdown to serialize.
+    const { MemoryContentContainer } = await import('@bendyline/squisq/storage');
+    const mem = new MemoryContentContainer();
+    await mem.writeDocument(stringifyMarkdown(markdownDoc));
+    container = mem;
+  }
+
+  const doc = markdownToDoc(markdownDoc, { autoTemplates: options.autoTemplates });
+  const baseName = source.baseName ?? 'document';
+
+  return { input: { doc, markdownDoc, container, baseName }, warnings: [] };
+}
+
+async function normalizeDoc(source: Extract<ConvertSource, { kind: 'doc' }>): Promise<Normalized> {
+  let container = source.container;
+  if (!container) {
+    const { MemoryContentContainer } = await import('@bendyline/squisq/storage');
+    const { docToMarkdown } = await import('@bendyline/squisq/doc');
+    const { stringifyMarkdown } = await import('@bendyline/squisq/markdown');
+    const mem = new MemoryContentContainer();
+    await mem.writeDocument(stringifyMarkdown(docToMarkdown(source.doc)));
+    container = mem;
+  }
+  const baseName = source.baseName ?? 'document';
+  // markdownDoc is intentionally omitted — exporters derive it lazily via docToMarkdown.
+  return { input: { doc: source.doc, container, baseName }, warnings: [] };
+}
+
+async function normalize(
+  source: ConvertSource,
+  options: ConvertOptions,
+  registry: FormatRegistry,
+): Promise<Normalized> {
+  switch (source.kind) {
+    case 'bytes':
+      return normalizeBytes(source, options, registry);
+    case 'markdown':
+      return normalizeMarkdown(source, options);
+    case 'doc':
+      return normalizeDoc(source);
+  }
+}
+
+// ── Transform ───────────────────────────────────────────────────────
+
+async function applyTransformStyle(
+  input: NormalizedInput,
+  transformStyle: string,
+  themeId?: string,
+): 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 });
+  input.doc = result.doc;
+  const markdownDoc = docToMarkdown(result.doc);
+  input.markdownDoc = markdownDoc;
+
+  // Lossy-path detection: transforms can emit template blocks whose data lives
+  // in template inputs rather than in round-trippable markdown `contents`, so
+  // `docToMarkdown` silently drops them. Re-parse with auto-templating off (so
+  // the comparison stays ~1:1 and isn't confused by content-aware promotion)
+  // and compare block counts. Best-effort — most blocks carry `contents` and
+  // round-trip fine, so this only fires on a genuine collapse.
+  const roundTripped = markdownToDoc(markdownDoc, { autoTemplates: false });
+  if (roundTripped.blocks.length < result.doc.blocks.length) {
+    return [
+      'Transform produced blocks that don’t round-trip to markdown; export may be incomplete.',
+    ];
+  }
+  return [];
+}
+
+// ── convert() ───────────────────────────────────────────────────────
+
+/**
+ * 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`.
+ */
+export async function convert(
+  source: ConvertSource,
+  to: FormatId,
+  options: ConvertOptions = {},
+): Promise<ConversionResult> {
+  const registry = options.registry ?? defaultRegistry();
+
+  const target: FormatDefinition | undefined = registry.get(to);
+  if (!target) {
+    throw new ConversionError('unknown-format', `Unknown target format "${to}".`, { format: to });
+  }
+  if (!target.exportDoc) {
+    throw new ConversionError(
+      'unsupported-output',
+      `Format "${target.label}" does not support export.`,
+      { format: to, hint: 'This format is import-only.' },
+    );
+  }
+
+  const { input, warnings } = await normalize(source, options, registry);
+
+  // 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,
+      )),
+    );
+  }
+
+  let result: ConversionResult;
+  try {
+    result = await target.exportDoc(input, options);
+  } catch (err: unknown) {
+    if (err instanceof ConversionError) throw err;
+    const message = err instanceof Error ? err.message : String(err);
+    throw new ConversionError('conversion-failed', message, { format: to, cause: err });
+  }
+
+  const ext = target.extensions[0]?.replace(/^\.+/, '') ?? to;
+  return {
+    ...result,
+    suggestedFilename: `${input.baseName}.${ext}`,
+    warnings: [...warnings, ...result.warnings],
+  };
+}

package/src/registry/defaultFormats.ts

@@ -0,0 +1,323 @@
+/**
+ * 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.
+ */
+
+import type { ContentContainer } from '@bendyline/squisq/storage';
+import type { MarkdownDocument } from '@bendyline/squisq/markdown';
+import { ConversionError } from './errors.js';
+import type {
+  ConversionResult,
+  ConvertOptions,
+  FormatDefinition,
+  NormalizedInput,
+} from './types.js';
+
+// ── MIME constants ──────────────────────────────────────────────────
+
+const MIME = {
+  md: 'text/markdown',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  pdf: 'application/pdf',
+  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  csv: 'text/csv',
+  html: 'text/html',
+  zip: 'application/zip',
+  epub: 'application/epub+zip',
+} as const;
+
+// ── Small shared helpers ────────────────────────────────────────────
+
+/** Normalize any binary export return shape to Uint8Array. */
+async function toBytes(data: ArrayBuffer | Uint8Array | Blob): Promise<Uint8Array> {
+  if (data instanceof Uint8Array) return data;
+  if (data instanceof ArrayBuffer) return new Uint8Array(data);
+  // Blob. Prefer the modern arrayBuffer() method; fall back to FileReader for
+  // environments (e.g. some jsdom builds) whose Blob lacks it.
+  if (typeof data.arrayBuffer === 'function') {
+    return new Uint8Array(await data.arrayBuffer());
+  }
+  const buffer = await new Promise<ArrayBuffer>((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(reader.result as ArrayBuffer);
+    reader.onerror = () => reject(reader.error);
+    reader.readAsArrayBuffer(data);
+  });
+  return new Uint8Array(buffer);
+}
+
+/** The theme to apply: explicit option wins, then the doc's own theme. */
+function resolveThemeId(input: NormalizedInput, options: ConvertOptions): string | undefined {
+  return options.themeId ?? input.doc.themeId;
+}
+
+/** 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;
+  const { docToMarkdown } = await import('@bendyline/squisq/doc');
+  return docToMarkdown(input.doc);
+}
+
+/**
+ * Collect image files from a container, keyed by both their container path and
+ * their bare filename. Exporters that resolve by url (PPTX) and the standalone
+ * player (HTML) both match against one of those two keys.
+ */
+async function collectContainerImages(
+  container: ContentContainer,
+): Promise<Map<string, ArrayBuffer>> {
+  const images = new Map<string, ArrayBuffer>();
+  const files = await container.listFiles();
+  for (const file of files) {
+    if (!/\.(jpg|jpeg|png|gif|webp|svg|bmp|avif)$/i.test(file.path)) continue;
+    const data = await container.readFile(file.path);
+    if (!data) continue;
+    images.set(file.path, data);
+    const slash = file.path.lastIndexOf('/');
+    if (slash !== -1) images.set(file.path.slice(slash + 1), data);
+  }
+  return images;
+}
+
+/** 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?.();
+  if (!script) {
+    throw new ConversionError('missing-dependency', 'HTML export needs a player script.', {
+      format,
+      hint: "pass resolvePlayerScript, e.g. () => import('@bendyline/squisq-react/standalone-source').then(m => m.PLAYER_BUNDLE)",
+    });
+  }
+  return script;
+}
+
+function ok(bytes: Uint8Array, mimeType: string, warnings: string[] = []): ConversionResult {
+  // suggestedFilename is filled in by convert() once the baseName is known.
+  return { bytes, mimeType, suggestedFilename: '', warnings };
+}
+
+// ── Definitions ─────────────────────────────────────────────────────
+
+export function defaultFormats(): FormatDefinition[] {
+  const md: FormatDefinition = {
+    id: 'md',
+    label: 'Markdown',
+    mimeType: MIME.md,
+    extensions: ['.md', '.markdown'],
+    async importDoc(data): Promise<MarkdownDocument> {
+      const { parseMarkdown } = await import('@bendyline/squisq/markdown');
+      return parseMarkdown(new TextDecoder().decode(data));
+    },
+    async exportDoc(input): Promise<ConversionResult> {
+      const { stringifyMarkdown } = await import('@bendyline/squisq/markdown');
+      const text = stringifyMarkdown(await markdownOf(input));
+      return ok(new TextEncoder().encode(text), MIME.md);
+    },
+  };
+
+  const docx: FormatDefinition = {
+    id: 'docx',
+    label: 'Word (DOCX)',
+    mimeType: MIME.docx,
+    extensions: ['.docx'],
+    async importContainer(data): Promise<ContentContainer> {
+      const { docxToContainer } = await import('../docx/index.js');
+      return docxToContainer(data);
+    },
+    async importDoc(data): Promise<MarkdownDocument> {
+      const { docxToMarkdownDoc } = await import('../docx/index.js');
+      return docxToMarkdownDoc(data);
+    },
+    async exportDoc(input, options): Promise<ConversionResult> {
+      const { markdownDocToDocx } = await import('../docx/index.js');
+      const buf = await markdownDocToDocx(await markdownOf(input), {
+        themeId: resolveThemeId(input, options),
+      });
+      return ok(await toBytes(buf), MIME.docx);
+    },
+  };
+
+  const pdf: FormatDefinition = {
+    id: 'pdf',
+    label: 'PDF',
+    mimeType: MIME.pdf,
+    extensions: ['.pdf'],
+    async importContainer(data): Promise<ContentContainer> {
+      const { pdfToContainer } = await import('../pdf/index.js');
+      return pdfToContainer(data);
+    },
+    async importDoc(data): Promise<MarkdownDocument> {
+      const { pdfToMarkdownDoc } = await import('../pdf/index.js');
+      return pdfToMarkdownDoc(data);
+    },
+    async exportDoc(input, options): Promise<ConversionResult> {
+      const { markdownDocToPdf } = await import('../pdf/index.js');
+      const buf = await markdownDocToPdf(await markdownOf(input), {
+        themeId: resolveThemeId(input, options),
+      });
+      return ok(await toBytes(buf), MIME.pdf);
+    },
+  };
+
+  const pptx: FormatDefinition = {
+    id: 'pptx',
+    label: 'PowerPoint (PPTX)',
+    mimeType: MIME.pptx,
+    extensions: ['.pptx'],
+    async importContainer(data): Promise<ContentContainer> {
+      const { pptxToContainer } = await import('../pptx/index.js');
+      return pptxToContainer(data);
+    },
+    async importDoc(data): Promise<MarkdownDocument> {
+      const { pptxToMarkdownDoc } = await import('../pptx/index.js');
+      return pptxToMarkdownDoc(data);
+    },
+    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), {
+        themeId: resolveThemeId(input, options),
+        images,
+      });
+      return ok(await toBytes(buf), MIME.pptx);
+    },
+  };
+
+  const xlsx: FormatDefinition = {
+    id: 'xlsx',
+    label: 'Excel (XLSX)',
+    mimeType: MIME.xlsx,
+    extensions: ['.xlsx'],
+    async importDoc(data): Promise<MarkdownDocument> {
+      const { xlsxToMarkdownDoc } = await import('../xlsx/index.js');
+      return xlsxToMarkdownDoc(data);
+    },
+    async exportDoc(input): Promise<ConversionResult> {
+      const { markdownDocToXlsx } = await import('../xlsx/index.js');
+      const markdownDoc = await markdownOf(input);
+      // XLSX fidelity is tables-only: `table` nodes become worksheets and
+      // headings name them, but every other top-level block (prose, lists,
+      // images, code, …) is dropped. Count those and warn honestly.
+      const omitted = markdownDoc.children.filter(
+        (n) => n.type !== 'table' && n.type !== 'heading',
+      ).length;
+      const warnings =
+        omitted > 0
+          ? [`XLSX export is tables-only; ${omitted} non-table block(s) were omitted.`]
+          : [];
+      const blob = await markdownDocToXlsx(markdownDoc);
+      return ok(await toBytes(blob), MIME.xlsx, warnings);
+    },
+  };
+
+  const csv: FormatDefinition = {
+    id: 'csv',
+    label: 'CSV',
+    mimeType: MIME.csv,
+    extensions: ['.csv'],
+    async importDoc(data): Promise<MarkdownDocument> {
+      const { csvToMarkdownDoc } = await import('../csv/index.js');
+      return csvToMarkdownDoc(data);
+    },
+    async exportDoc(input): Promise<ConversionResult> {
+      const { markdownDocToCsv } = await import('../csv/index.js');
+      const markdownDoc = await markdownOf(input);
+      const tableCount = markdownDoc.children.filter((n) => n.type === 'table').length;
+      const warnings: string[] = [];
+      if (tableCount > 1) {
+        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);
+      return ok(new TextEncoder().encode(text), MIME.csv, warnings);
+    },
+  };
+
+  const html: FormatDefinition = {
+    id: 'html',
+    label: 'HTML (single file)',
+    mimeType: MIME.html,
+    extensions: ['.html', '.htm'],
+    async importDoc(data): Promise<MarkdownDocument> {
+      const { htmlToMarkdownDoc } = await import('../html/index.js');
+      return htmlToMarkdownDoc(data);
+    },
+    // 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 htmlText = docToHtml(input.doc, {
+        playerScript,
+        images,
+        title: options.title ?? input.baseName,
+        mode: 'static',
+        themeId: resolveThemeId(input, options),
+      });
+      return ok(new TextEncoder().encode(htmlText), MIME.html);
+    },
+  };
+
+  const htmlzip: FormatDefinition = {
+    id: 'htmlzip',
+    label: 'HTML (ZIP archive)',
+    mimeType: MIME.zip,
+    extensions: ['.html.zip'],
+    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 blob = await docToHtmlZip(input.doc, {
+        playerScript,
+        images,
+        title: options.title ?? input.baseName,
+        mode: 'static',
+        themeId: resolveThemeId(input, options),
+      });
+      return ok(await toBytes(blob), MIME.zip);
+    },
+  };
+
+  const epub: FormatDefinition = {
+    id: 'epub',
+    label: 'EPUB',
+    mimeType: MIME.epub,
+    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), {
+        title: options.title ?? input.baseName,
+        themeId: resolveThemeId(input, options),
+        images,
+      });
+      return ok(await toBytes(buf), MIME.epub);
+    },
+  };
+
+  const dbk: FormatDefinition = {
+    id: 'dbk',
+    label: 'Squisq container (DBK)',
+    mimeType: MIME.zip,
+    extensions: ['.dbk', '.zip'],
+    async importContainer(data): Promise<ContentContainer> {
+      const { zipToContainer } = await import('../container/index.js');
+      return zipToContainer(data);
+    },
+    async exportDoc(input): Promise<ConversionResult> {
+      const { containerToZip } = await import('../container/index.js');
+      const blob = await containerToZip(input.container);
+      return ok(await toBytes(blob), MIME.zip);
+    },
+  };
+
+  return [md, docx, pdf, pptx, xlsx, csv, html, htmlzip, epub, dbk];
+}

package/src/registry/errors.ts

@@ -0,0 +1,46 @@
+/**
+ * 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.
+ */
+
+import type { FormatId } from './types.js';
+
+/** Machine-readable failure kinds surfaced by the registry / `convert()`. */
+export type ConversionErrorCode =
+  | 'unknown-format'
+  | 'unsupported-input'
+  | 'unsupported-output'
+  | 'invalid-input'
+  | 'missing-dependency'
+  | 'conversion-failed';
+
+/** Options for constructing a {@link ConversionError}. */
+export 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()`. */
+export class ConversionError extends Error {
+  readonly code: ConversionErrorCode;
+  readonly format?: FormatId;
+  readonly hint?: string;
+
+  constructor(code: ConversionErrorCode, message: string, opts: ConversionErrorOptions = {}) {
+    super(message);
+    this.name = 'ConversionError';
+    this.code = code;
+    this.format = opts.format;
+    this.hint = opts.hint;
+    if (opts.cause !== undefined) {
+      (this as Error & { cause?: unknown }).cause = opts.cause;
+    }
+  }
+}