@svgrid/enterprise 1.2.0 → 2.0.0

package/src/export.ts

@@ -1,549 +1,1452 @@
-/// <reference path="./pdfmake-shims.d.ts" />
-import type { RowData, TableFeatures } from '@svgrid/grid'
-import type { SvGridApi } from '@svgrid/grid'
-import { assertEnterpriseLicensed } from './license'
-import { installSmartShim, type SmartDataExporterInstance } from './smart-shim'
-
-export type ExportFormat = 'xlsx' | 'pdf' | 'csv' | 'tsv' | 'html'
-
-export type ExportColumn = {
-  /** Data field name on the row object. */
-  field: string
-  /** Header label to render in the exported file. Defaults to `field`. */
-  header?: string
-}
-
-/**
- * Per-cell style descriptor. Mirrors a subset of CSS; the keys the
- * underlying exporter honours are font / colour / background / border /
- * alignment. Anything else is ignored gracefully.
- */
-export type ExportCellStyle = {
-  color?: string
-  backgroundColor?: string
-  fontWeight?: 'normal' | 'bold' | number
-  fontStyle?: 'normal' | 'italic'
-  fontSize?: number | string
-  fontFamily?: string
-  border?: string
-  textAlign?: 'left' | 'right' | 'center'
-  verticalAlign?: 'top' | 'middle' | 'bottom'
-}
-
-/**
- * Document-level style. Apply blanket styles to the header row, the
- * value rows, or selectively per cell-reference (e.g. `'B2'`).
- */
-export type ExportStyles = {
-  /** Style applied to every header cell. */
-  headerRow?: ExportCellStyle
-  /** Style applied to every data row. Even / odd zebra are derived from this if `rowAlternate` is set. */
-  rows?: ExportCellStyle
-  /** Optional zebra background for odd-indexed rows. */
-  rowAlternate?: ExportCellStyle
-  /** Per-cell overrides keyed by Excel-style reference (`'A1'`, `'C3'`). */
-  cells?: Record<string, ExportCellStyle>
-}
-
-/**
- * Header / footer entries for xlsx + pdf. Each line is rendered top to
- * bottom on the page. Embed an image with `{ image: dataUrl }`; embed
- * text with `{ text: '...', style?: ExportCellStyle }`.
- */
-export type ExportHeaderFooterLine =
-  | { text: string; style?: ExportCellStyle }
-  | { image: string; width?: number; height?: number }
-  | { left?: string; center?: string; right?: string }
-
-export type ExportSheet<TData> = {
-  /** Sheet/tab label. Required. */
-  label: string
-  /** Rows for this sheet. */
-  rows: ReadonlyArray<TData>
-  /** Per-sheet columns. Falls back to the top-level `columns` if omitted. */
-  columns?: ReadonlyArray<ExportColumn>
-  /** Per-sheet styles. */
-  styles?: ExportStyles
-}
-
-export type ExportOptions<TData> = {
-  format: ExportFormat
-  /** Base filename (extension is appended if missing). Defaults to "grid". */
-  filename?: string
-  /**
-   * Columns to include. If omitted, every key of the first row is exported
-   * (in original object order) using the field name as the header label.
-   */
-  columns?: ReadonlyArray<ExportColumn>
-  /**
-   * Source rows. If omitted, the current displayed rows from the api are used.
-   * Provide explicitly when you want to override (e.g. export the whole
-   * dataset rather than the filtered view).
-   */
-  rows?: ReadonlyArray<TData>
-  /** PDF only. Page orientation. Defaults to "portrait". */
-  pageOrientation?: 'portrait' | 'landscape'
-  /**
-   * Cell + row styles. Apply once to match a light/dark theme, or per-cell
-   * for conditional formatting. xlsx and pdf honour these; csv/tsv ignore
-   * them; html bakes them into inline `style=` attributes.
-   */
-  styles?: ExportStyles
-  /** Page header lines (xlsx, pdf, html). Logos go here as `{ image: ... }`. */
-  header?: ReadonlyArray<ExportHeaderFooterLine>
-  /** Page footer lines. Common pattern: page number on the right. */
-  footer?: ReadonlyArray<ExportHeaderFooterLine>
-  /**
-   * Multi-sheet export (xlsx only). When set, each entry becomes one
-   * sheet/tab. The top-level `rows` / `columns` are ignored.
-   */
-  sheets?: ReadonlyArray<ExportSheet<TData>>
-  /**
-   * If a row has a column whose value matches one of these field names
-   * AND the value looks like a URL or data URL, the cell is exported as
-   * an embedded image (xlsx). Defaults to `[]` (no auto-detection).
-   */
-  imageFields?: ReadonlyArray<string>
-  /**
-   * Pixel dimensions used when embedding images. Smart's xlsx writer
-   * draws the image at this size relative to the cell origin. Defaults
-   * to `{ width: 32, height: 32 }`. Set larger for thumbnails, smaller
-   * for inline icons.
-   */
-  imageSize?: { width: number; height: number }
-  /**
-   * Group flat rows by one or more field names. The exporter wraps each
-   * group in an Excel outline row (with the +/- expand button), and
-   * emits a `<value> <field>` group header above every cluster. Maps
-   * straight to Smart DataExporter's constructor `groupBy` arg. xlsx
-   * only; csv/tsv/html flatten the groups back out.
-   */
-  groupBy?: ReadonlyArray<string>
-  /**
-   * Mark rows as a hierarchical (tree) data source. Each row should
-   * declare its own children either via the `subRows` convention or by
-   * matching the parent/child shape Smart expects on the input rows.
-   * Mutually exclusive with `groupBy`. xlsx only.
-   */
-  hierarchical?: boolean
-  /**
-   * Merged cells to write into the sheet (xlsx / pdf). Each entry spans
-   * `colSpan` columns and `rowSpan` rows starting at the given zero-based
-   * **body** row / column index (the header row is not counted). Mirrors the
-   * grid's own `MergeSpec` shape closely, so grid merges map straight through -
-   * convert a `MergeSpec` (`{ rowIndex, columnId, rowspan, colspan }`) by
-   * resolving `columnId` to its column index. Mutually exclusive with
-   * `groupBy` / `hierarchical`.
-   */
-  merges?: ReadonlyArray<ExportMerge>
-}
-
-/**
- * A merged cell region for {@link ExportOptions.merges}. `row` / `col` are
- * zero-based indices into the exported body (header excluded). A cell that
- * spans two columns to the right is `{ row, col, colSpan: 2 }`.
- */
-export type ExportMerge = {
-  row: number
-  col: number
-  /** Columns to span (default 1). */
-  colSpan?: number
-  /** Rows to span (default 1). */
-  rowSpan?: number
-}
-
-let exporterCtorPromise: Promise<
-  new (
-    options: Record<string, unknown>,
-    groupBy?: ReadonlyArray<string>,
-    filterBy?: Record<string, unknown>,
-    conditionalFormatting?: unknown,
-  ) => SmartDataExporterInstance
-> | null = null
-
-async function getDataExporter() {
-  if (typeof window === 'undefined') {
-    throw new Error('@svgrid/enterprise: export requires a browser environment')
-  }
-  if (!exporterCtorPromise) {
-    exporterCtorPromise = (async () => {
-      installSmartShim()
-      // Side-effect import: the IIFE registers Smart.Utilities.DataExporter
-      // on the global Smart namespace that installSmartShim() set up.
-      await import('./smart.export.js')
-      const Ctor = window.Smart?.Utilities?.DataExporter
-      if (!Ctor) {
-        throw new Error('@svgrid/enterprise: failed to load Smart.Utilities.DataExporter')
-      }
-      return Ctor
-    })()
-  }
-  return exporterCtorPromise
-}
-
-async function ensureGlobals(format: ExportFormat): Promise<void> {
-  const g = globalThis as unknown as { JSZip?: unknown; pdfMake?: unknown }
-  if (format === 'xlsx' && g.JSZip == null) {
-    let mod: unknown
-    try {
-      mod = await import('jszip')
-    } catch {
-      throw new Error(
-        '@svgrid/enterprise: xlsx export requires the "jszip" peer dependency. ' +
-          'Install it with: pnpm add jszip',
-      )
-    }
-    g.JSZip = (mod as { default?: unknown }).default ?? mod
-  }
-  if (format === 'pdf' && g.pdfMake == null) {
-    let pdfMakeMod: unknown
-    let vfsMod: unknown
-    try {
-      pdfMakeMod = await import('pdfmake/build/pdfmake')
-      vfsMod = await import('pdfmake/build/vfs_fonts')
-    } catch {
-      throw new Error(
-        '@svgrid/enterprise: pdf export requires the "pdfmake" peer dependency. ' +
-          'Install it with: pnpm add pdfmake',
-      )
-    }
-    const pdfMake = ((pdfMakeMod as { default?: unknown }).default ?? pdfMakeMod) as {
-      vfs?: Record<string, string>
-      createPdf: (def: unknown) => { download(name: string): void; getBlob(cb: (b: Blob) => void): void }
-    }
-    const vfsRoot = (vfsMod as { default?: unknown }).default ?? vfsMod
-    // pdfmake's vfs_fonts file historically exports either { pdfMake: { vfs } }
-    // or { default: { vfs } } or { vfs } depending on bundler. Try each shape.
-    const candidate =
-      (vfsRoot as { pdfMake?: { vfs?: Record<string, string> } }).pdfMake?.vfs ??
-      (vfsRoot as { vfs?: Record<string, string> }).vfs ??
-      (vfsRoot as { default?: { vfs?: Record<string, string> } }).default?.vfs
-    if (candidate) pdfMake.vfs = candidate
-    g.pdfMake = pdfMake
-  }
-}
-
-function buildExportPayload<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
->(
-  api: SvGridApi<TFeatures, TData>,
-  opts: ExportOptions<TData>,
-): {
-  rows: ReadonlyArray<Record<string, unknown>>
-  filename: string
-} {
-  const sourceRows: ReadonlyArray<TData> = opts.rows ?? api.getDisplayedRows()
-  let cols: ReadonlyArray<ExportColumn>
-  if (opts.columns && opts.columns.length > 0) {
-    cols = opts.columns
-  } else {
-    // Auto-derive columns from the grid's own columnDefs. This picks up the
-    // human-readable `header` labels so the exported file shows what the
-    // user sees on-screen (e.g. "Order ID" rather than "orderId"). Only
-    // visible, field-backed columns are exported.
-    const gridCols = api.getColumns().filter((c) => c.visible && c.field)
-    if (gridCols.length > 0) {
-      cols = gridCols.map((c) => ({ field: c.field!, header: c.header }))
-    } else if (sourceRows.length > 0) {
-      cols = Object.keys(sourceRows[0] as Record<string, unknown>)
-        .filter((k) => !k.startsWith('_'))
-        .map((field) => ({ field }))
-    } else {
-      cols = []
-    }
-  }
-  const headerRow: Record<string, unknown> = {}
-  for (const c of cols) headerRow[c.field] = c.header ?? c.field
-
-  const projected: Array<Record<string, unknown>> = [headerRow]
-  for (const r of sourceRows) {
-    const row: Record<string, unknown> = {}
-    const src = r as unknown as Record<string, unknown>
-    for (const c of cols) row[c.field] = src[c.field]
-    projected.push(row)
-  }
-  const filename = (opts.filename ?? 'grid').trim() || 'grid'
-  return { rows: projected, filename }
-}
-
-/**
- * Translate the public {@link ExportStyles} shape into the keys the Smart
- * exporter actually consumes:
- *   `style.header`    → all header cells
- *   `style.rows`      → all data rows. Cell-prop keys (color, backgroundColor,
- *                       fontWeight, fontStyle, fontSize, fontFamily,
- *                       textAlign, verticalAlign, textDecoration, numFmt)
- *                       are recognised by Smart's `storeCellStyle`.
- *   `style.rows.alternationCount` + `alternationStart` +
- *   `alternationIndex1BackgroundColor` (etc.) → zebra striping
- *   `style.cells.<ref>` → HTML-only per-cell ref overrides
- */
-function translateStyles(styles: ExportStyles | undefined): Record<string, unknown> | undefined {
-  if (!styles) return undefined
-  const out: Record<string, unknown> = {}
-  if (styles.headerRow) out.header = { ...styles.headerRow }
-  const rows: Record<string, unknown> = styles.rows ? { ...styles.rows } : {}
-  if (styles.rowAlternate) {
-    rows.alternationCount = 2
-    rows.alternationStart = 0
-    if (styles.rowAlternate.backgroundColor)
-      rows.alternationIndex1BackgroundColor = styles.rowAlternate.backgroundColor
-    if (styles.rowAlternate.color)
-      rows.alternationIndex1Color = styles.rowAlternate.color
-  }
-  if (Object.keys(rows).length > 0) out.rows = rows
-  if (styles.cells) out.cells = styles.cells
-  return out
-}
-
-let _imgIdCounter = 0
-const _imgIdCache = new Map<string, string>()
-function imageIdFor(dataUrl: string): string {
-  const cached = _imgIdCache.get(dataUrl)
-  if (cached) return cached
-  const id = `img${++_imgIdCounter}`
-  _imgIdCache.set(dataUrl, id)
-  return id
-}
-
-/**
- * Build the image object Smart's xlsx writer expects. The exporter pulls
- * `{ id, base64, imageType, width, height }` off the return of
- * `addImageToCell(...).image` and stores it under `this.images` →
- * eventually written to the workbook as `xl/media/imageN.<imageType>`.
- *
- * `base64` may be a full data URL - Smart strips the prefix when writing.
- */
-function makeSmartImage(dataUrl: string, width = 64, height = 64): {
-  id: string; base64: string; imageType: string; width: number; height: number
-} {
-  // Extract MIME → imageType. Defaults to png for safety.
-  const mime = /^data:image\/([a-zA-Z0-9+]+);/i.exec(dataUrl)?.[1]?.toLowerCase() ?? 'png'
-  const imageType = mime === 'jpg' ? 'jpeg'
-                  : mime === 'svg+xml' ? 'svg'
-                  : mime
-  return {
-    id: imageIdFor(dataUrl),
-    base64: dataUrl,
-    imageType,
-    width,
-    height,
-  }
-}
-
-/**
- * Build the header / footer arrays the Smart exporter understands.
- * Each input line becomes one full-width row in the spreadsheet with
- * `style.mergeAcross` so the line spans every column.
- *
- * Image lines are written as a data-URL string into the first column and
- * the wrapper's `addImageToCell` hook embeds them as real picture cells.
- */
-function buildContentRows(
-  lines: ReadonlyArray<ExportHeaderFooterLine> | undefined,
-  datafields: ReadonlyArray<string>,
-): Array<{ cells: Record<string, unknown>; style?: Record<string, unknown> }> | undefined {
-  if (!lines || lines.length === 0 || datafields.length === 0) return undefined
-  const first = datafields[0]!
-  const out: Array<{ cells: Record<string, unknown>; style?: Record<string, unknown> }> = []
-  for (const line of lines) {
-    const cells: Record<string, unknown> = {}
-    let style: Record<string, unknown> | undefined
-    if ('image' in line) {
-      cells[first] = line.image
-      style = { mergeAcross: true, textAlign: 'left' }
-    } else if ('text' in line) {
-      cells[first] = line.text
-      style = { mergeAcross: true, ...(line.style ?? {}) }
-    } else {
-      // 3-column { left, center, right }. Distribute across the first,
-      // middle, and last datafield.
-      const mid  = datafields[Math.floor(datafields.length / 2)]!
-      const last = datafields[datafields.length - 1]!
-      if (line.left   !== undefined) cells[first] = line.left
-      if (line.center !== undefined) cells[mid]   = line.center
-      if (line.right  !== undefined) cells[last]  = line.right
-      style = { textAlign: 'left' }
-    }
-    out.push({ cells, style })
-  }
-  return out
-}
-
-/**
- * Build an `addImageToCell` handler that embeds a value as a real image
- * cell whenever the value is a data URL. Smart calls this for every body
- * cell AND every header/footer cell, so the same handler covers both
- * code paths.
- *
- * `bodyImageSize` controls the embedded pixel size for body cells (the
- * thumbnails). Header/footer image lines use their own size hint
- * already encoded in the `cells[first]` value's metadata - here we just
- * embed with a slightly larger default so logos read well in the page
- * banner.
- */
-function buildImageHandler(
-  imageFields: ReadonlyArray<string> | undefined,
-  bodyImageSize: { width: number; height: number },
-): NonNullable<SmartDataExporterInstance['addImageToCell']> {
-  const allowed = imageFields && imageFields.length > 0 ? new Set(imageFields) : null
-  return (_rowIndex, dataField, value) => {
-    if (typeof value !== 'string') return null
-    if (!/^data:image\//i.test(value)) return null
-    if (allowed && !allowed.has(dataField)) {
-      // Header/footer image lines come through the first column too -
-      // those cells aren't in `imageFields`, but the wrapper wrote the
-      // data URL there itself. Embed bigger (logo banner).
-      return { image: makeSmartImage(value, 96, 96), value: '' }
-    }
-    return { image: makeSmartImage(value, bodyImageSize.width, bodyImageSize.height), value: '' }
-  }
-}
-
-/**
- * Build the constructor-options object passed to the Smart DataExporter.
- * Constructor only consumes a small set of keys; instance-level options
- * (`headerContent`, `footerContent`, `addImageToCell`) are applied
- * separately in {@link exportGrid} after `new DataExporter(...)`.
- */
-function buildExporterOptions<TData>(
-  opts: ExportOptions<TData>,
-): Record<string, unknown> {
-  const out: Record<string, unknown> = {
-    exportHeader: true,
-    pageOrientation: opts.pageOrientation ?? 'portrait',
-  }
-  const style = translateStyles(opts.styles)
-  if (style) out.style = style
-  // Smart's xlsx writer emits Excel-native row outlining when
-  // `hierarchical: true` is set on the constructor options OR when the
-  // second constructor arg is a non-empty groupBy array. We thread
-  // hierarchical through here and groupBy through the constructor call
-  // site in exportGrid.
-  if (opts.hierarchical) out.hierarchical = true
-  // Merged cells: translate the friendly {row, col, rowSpan, colSpan} shape to
-  // Smart's native {cell: [row, col], rowspan, colspan}. Skip 1x1 "merges"
-  // (nothing to span). Ignored when grouping/hierarchy owns the row layout.
-  if (opts.merges?.length && !opts.groupBy?.length && !opts.hierarchical) {
-    const mergedCells = opts.merges
-      .map((m) => ({
-        cell: [m.row, m.col],
-        rowspan: Math.max(1, Math.floor(m.rowSpan ?? 1)),
-        colspan: Math.max(1, Math.floor(m.colSpan ?? 1)),
-      }))
-      .filter((m) => m.rowspan > 1 || m.colspan > 1)
-    if (mergedCells.length) out.mergedCells = mergedCells
-  }
-  return out
-}
-
-/**
- * Apply instance-level options the constructor does not consume.
- * Mutates and returns the exporter for fluent use.
- */
-function applyInstanceOptions<TData>(
-  exporter: SmartDataExporterInstance,
-  opts: ExportOptions<TData>,
-  datafields: ReadonlyArray<string>,
-): SmartDataExporterInstance {
-  const headerRows = buildContentRows(opts.header, datafields)
-  const footerRows = buildContentRows(opts.footer, datafields)
-  if (headerRows) exporter.headerContent = headerRows
-  if (footerRows) exporter.footerContent = footerRows
-
-  // Wire image embedding when the caller opts in via imageFields OR the
-  // header/footer carries an image line. Both code paths funnel through
-  // the same handler.
-  const hasHeaderOrFooterImage =
-    (opts.header?.some((l) => 'image' in l) ?? false) ||
-    (opts.footer?.some((l) => 'image' in l) ?? false)
-  if (opts.imageFields?.length || hasHeaderOrFooterImage) {
-    const bodySize = opts.imageSize ?? { width: 32, height: 32 }
-    exporter.addImageToCell = buildImageHandler(opts.imageFields, bodySize)
-  }
-  return exporter
-}
-
-export async function exportGrid<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
->(api: SvGridApi<TFeatures, TData>, opts: ExportOptions<TData>): Promise<void> {
-  assertEnterpriseLicensed('Export')
-  await ensureGlobals(opts.format)
-  const Ctor = await getDataExporter()
-
-  // Multi-sheet path. Smart's `spreadsheets` option takes an array of
-  // `{ label, dataSource, columns, dataFields? }`. Each entry becomes one
-  // tab; the exporter prepends its own header row built from `columns`.
-  if (opts.sheets && opts.sheets.length > 0) {
-    if (opts.format !== 'xlsx') {
-      throw new Error(`@svgrid/enterprise: multi-sheet export requires format 'xlsx', got '${opts.format}'`)
-    }
-    // Same column-derivation fallback used by the single-sheet path: pull
-    // the human-readable headers from the grid when the caller didn't pass
-    // explicit columns.
-    const gridCols = api.getColumns().filter((c) => c.visible && c.field)
-    const fallbackCols: ReadonlyArray<ExportColumn> =
-      gridCols.length > 0
-        ? gridCols.map((c) => ({ field: c.field!, header: c.header }))
-        : []
-    const sheets = opts.sheets.map((sheet) => {
-      const cols = (sheet.columns ?? opts.columns ?? (
-        fallbackCols.length > 0
-          ? fallbackCols
-          : sheet.rows.length > 0
-            ? Object.keys(sheet.rows[0] as Record<string, unknown>)
-                .filter((k) => !k.startsWith('_'))
-                .map((field) => ({ field } as ExportColumn))
-            : []
-      ))
-      // Project each row to only the included fields (in column order).
-      const dataSource = sheet.rows.map((r) => {
-        const src = r as unknown as Record<string, unknown>
-        const out: Record<string, unknown> = {}
-        for (const c of cols) out[c.field] = src[c.field]
-        return out
-      })
-      return {
-        label: sheet.label,
-        dataSource,
-        columns: cols.map((c) => ({ dataField: c.field, label: c.header ?? c.field })),
-        dataFields: cols.map((c) => c.field),
-        style: translateStyles(sheet.styles ?? opts.styles),
-      }
-    })
-    const filename = (opts.filename ?? 'grid').trim() || 'grid'
-    const ctorOpts = buildExporterOptions(opts)
-    // Smart needs at least one main sheet to operate. Use the first sheet
-    // as the "main" exportData payload AND keep the full set on the
-    // `spreadsheets` property so the workbook ends up with one tab per
-    // entry.
-    const firstSheet = sheets[0]!
-    const exporter = new Ctor(ctorOpts)
-    exporter.spreadsheets = sheets
-    applyInstanceOptions(exporter, opts, firstSheet.dataFields)
-    // First sheet's data goes through the standard exportData path with
-    // its own header row.
-    const headerRow: Record<string, unknown> = {}
-    for (const c of firstSheet.columns) headerRow[c.dataField] = c.label
-    const firstSheetRows = [headerRow, ...firstSheet.dataSource]
-    exporter.exportData(firstSheetRows, opts.format, filename)
-    return
-  }
-
-  const { rows, filename } = buildExportPayload(api, opts)
-  if (rows.length <= 1) {
-    throw new Error('@svgrid/enterprise: nothing to export - the grid has no rows')
-  }
-  const datafields = Object.keys(rows[0]!)
-  // The constructor's SECOND arg is `groupBy`: when non-empty AND
-  // `hierarchical` is NOT set, Smart wraps each group of rows in an
-  // Excel outline row with an expand/collapse button at the group key.
-  const groupBy = !opts.hierarchical && opts.groupBy && opts.groupBy.length > 0
-    ? opts.groupBy
-    : undefined
-  const exporter = new Ctor(buildExporterOptions(opts), groupBy)
-  applyInstanceOptions(exporter, opts, datafields)
-  exporter.exportData(rows, opts.format, filename)
-}
+/// <reference path="./pdfmake-shims.d.ts" />
+import type { CellFormatConfig, RowData, TableFeatures } from '@svgrid/grid'
+import type { SvGridApi } from '@svgrid/grid'
+// Import the pure formatters from the grid's Svelte-free `/format` subpath so
+// this module (and the enterprise unit tests) don't drag in SvGrid.svelte.
+import { formatValueForExport, toExcelNumFmt, valueForExcel } from '@svgrid/grid/format'
+import { assertEnterpriseLicensed } from './license'
+import { installSmartShim, type SmartDataExporterInstance } from './smart-shim'
+import {
+  downloadBlobFile,
+  downloadTextFile,
+  serializeDelimited,
+  serializeHtml,
+  serializeJson,
+  serializeMarkdown,
+  serializeXml,
+  type CsvOptions,
+  type SerializeProgress,
+} from './export-serialize'
+import { serializeSpreadsheetML } from './export-xls'
+import { buildXlsxParts, packageXlsx, type XlsxCell, type XlsxCondFormat, type XlsxTableSpec } from './export-ooxml'
+import { buildPdfDocDefinition, type PdfBodyRow, type PdfExportOptions } from './export-pdf'
+import { buildConditionalResolver, type ExportCellVisualFn } from './export-conditional'
+import type { ConditionalFormat } from '@svgrid/grid/format'
+
+/**
+ * Export target formats.
+ *   - `xlsx` modern OOXML workbook (needs `jszip`),
+ *   - `xls`  legacy Excel 2003 XML Spreadsheet (no peer dependency),
+ *   - `pdf`  paginated document (needs `pdfmake`),
+ *   - `csv` / `tsv` / `html` / `json` / `xml` / `md` native, no peer deps.
+ */
+export type ExportFormat =
+  | 'xlsx'
+  | 'xls'
+  | 'pdf'
+  | 'csv'
+  | 'tsv'
+  | 'html'
+  | 'json'
+  | 'xml'
+  | 'md'
+
+/** Formats served by the native, dependency-free, streaming serializers. */
+const NATIVE_TEXT_FORMATS: ReadonlyArray<ExportFormat> = [
+  'csv',
+  'tsv',
+  'html',
+  'json',
+  'xml',
+  'md',
+]
+
+export type ExportColumn<TData = RowData> = {
+  /** Data field name on the row object. */
+  field: string
+  /** Header label to render in the exported file. Defaults to `field`. */
+  header?: string
+  /**
+   * Column format config. When set (and `rawValues` is off), the exporter
+   * renders the value the way the grid does on screen - currency symbol,
+   * date pattern, percent, etc. Auto-populated from the grid's own columns
+   * when you don't pass `columns` explicitly.
+   */
+  format?: CellFormatConfig
+  /** Cell alignment, carried into html / pdf output. */
+  align?: 'left' | 'center' | 'right'
+  /** Explicit column width in pixels (xlsx / xls). Overrides auto-fit. */
+  width?: number
+  /**
+   * Turn this column's cells into hyperlinks. Return the URL for a row (or
+   * null for no link). Rendered as clickable links in xls / html / pdf /
+   * print. (xlsx via the vendored writer doesn't support cell links.)
+   */
+  link?: (row: TData) => string | null | undefined
+  /**
+   * Escape hatch for columns whose on-screen value comes from a custom cell
+   * renderer (a snippet), a `fieldFn`, or a lookup the raw field can't
+   * express. Return the value to write for this row. Takes precedence over
+   * `format`. Return a number / Date to keep it typed in xlsx.
+   */
+  exportValue?: (row: TData) => string | number | Date | null | undefined
+}
+
+/** Progress reported during an export. `phase` is 'project' while building
+ *  rows, 'serialize' while writing text formats, 'write' around the xlsx/pdf
+ *  writer. `ratio` is 0..1. */
+export type ExportProgress =
+  | SerializeProgress
+  | { phase: 'project' | 'write'; ratio: number; row?: number; total?: number }
+
+/**
+ * The built export file. Returned by `exportData` for the dependency-free
+ * paths (csv/tsv/html/json/xml/md, xls, pdf, single-sheet xlsx) so callers can
+ * preview / upload / email / attach it instead of (or as well as) downloading.
+ * With `download: false`, nothing is downloaded and this is returned.
+ */
+export type ExportResult = {
+  blob: Blob
+  filename: string
+  mime: string
+  /** Number of data rows written (excludes the header). */
+  rowCount: number
+  byteSize: number
+}
+
+/**
+ * Per-cell style descriptor. Mirrors a subset of CSS; the keys the
+ * underlying exporter honours are font / colour / background / border /
+ * alignment. Anything else is ignored gracefully.
+ */
+export type ExportCellStyle = {
+  color?: string
+  backgroundColor?: string
+  fontWeight?: 'normal' | 'bold' | number
+  fontStyle?: 'normal' | 'italic'
+  fontSize?: number | string
+  fontFamily?: string
+  border?: string
+  textAlign?: 'left' | 'right' | 'center'
+  verticalAlign?: 'top' | 'middle' | 'bottom'
+}
+
+/**
+ * Document-level style. Apply blanket styles to the header row, the
+ * value rows, or selectively per cell-reference (e.g. `'B2'`).
+ */
+export type ExportStyles = {
+  /** Style applied to every header cell. */
+  headerRow?: ExportCellStyle
+  /** Style applied to every data row. Even / odd zebra are derived from this if `rowAlternate` is set. */
+  rows?: ExportCellStyle
+  /** Optional zebra background for odd-indexed rows. */
+  rowAlternate?: ExportCellStyle
+  /** Per-cell overrides keyed by Excel-style reference (`'A1'`, `'C3'`). */
+  cells?: Record<string, ExportCellStyle>
+}
+
+/**
+ * Header / footer entries for xlsx + pdf. Each line is rendered top to
+ * bottom on the page. Embed an image with `{ image: dataUrl }`; embed
+ * text with `{ text: '...', style?: ExportCellStyle }`.
+ */
+export type ExportHeaderFooterLine =
+  | { text: string; style?: ExportCellStyle }
+  | { image: string; width?: number; height?: number }
+  | { left?: string; center?: string; right?: string }
+
+export type ExportSheet<TData> = {
+  /** Sheet/tab label. Required. */
+  label: string
+  /** Rows for this sheet. */
+  rows: ReadonlyArray<TData>
+  /** Per-sheet columns. Falls back to the top-level `columns` if omitted. */
+  columns?: ReadonlyArray<ExportColumn<TData>>
+  /** Per-sheet styles. */
+  styles?: ExportStyles
+}
+
+/**
+ * Which rows to export:
+ *   'displayed' (default) - the current filtered / sorted / paginated view,
+ *   'selected'  - only checked rows,
+ *   'all'       - the full underlying dataset (pre-filter),
+ *   an explicit array - export exactly these.
+ */
+export type ExportRowSource<TData> = ReadonlyArray<TData> | 'displayed' | 'selected' | 'all'
+
+export type ExportOptions<TData> = {
+  format: ExportFormat
+  /** Base filename (extension is appended if missing). Defaults to "grid". */
+  filename?: string
+  /**
+   * Columns to include. If omitted, the grid's own visible columns are used
+   * (carrying their header labels + `format`), falling back to the keys of
+   * the first row.
+   */
+  columns?: ReadonlyArray<ExportColumn<TData>>
+  /**
+   * Source rows. Defaults to `'displayed'` (the current view). Pass
+   * `'selected'` / `'all'`, or an explicit array to override.
+   */
+  rows?: ExportRowSource<TData>
+  /**
+   * By default the exporter writes the FORMATTED display value (what the user
+   * sees) so the file matches the grid. Set `rawValues: true` to write the
+   * underlying raw values instead (numbers stay numeric in xlsx; useful for
+   * downstream data pipelines).
+   */
+  rawValues?: boolean
+  /**
+   * Auto-carry the grid's active row grouping into the export (xlsx outline
+   * rows). On by default; set false to ignore grouping, or pass `groupBy`
+   * explicitly to override. Ignored when you pass `groupBy` / `hierarchical`
+   * / `sheets` yourself.
+   */
+  autoGroup?: boolean
+  /** CSV / TSV tuning: delimiter, line ending, UTF-8 BOM. */
+  csv?: CsvOptions
+  /**
+   * Freeze the header row so it stays visible when scrolling (xlsx / xls).
+   * Default true.
+   */
+  freezeHeader?: boolean
+  /** Freeze this many leading columns (xlsx / xls). Default 0. */
+  freezeColumns?: number
+  /**
+   * Size columns to their content (xlsx / xls). Default true. A column's
+   * explicit `width` always wins.
+   */
+  autoFitColumns?: boolean
+  /**
+   * Export long integer IDs (> 15 significant digits) as TEXT so Excel's
+   * 15-digit float precision doesn't silently mangle them. Default false.
+   * (xlsx / xls.)
+   */
+  precisionSafe?: boolean
+  /**
+   * Wrap the xlsx data in a native Excel Table (filter dropdowns, banded rows,
+   * structured refs). `{ totalsRow: true }` adds a totals row with live
+   * SUM/AVG formulas for numeric columns. Single-sheet xlsx only.
+   */
+  excelTable?: boolean | { totalsRow?: boolean; style?: string }
+  /** Progress callback for large exports (row projection + serialization). */
+  onProgress?: (progress: ExportProgress) => void
+  /** Abort an in-flight export (checked between chunks). Throws `AbortError`. */
+  signal?: AbortSignal
+  /**
+   * When false, don't trigger a browser download - just build the file and
+   * return it as an {@link ExportResult} (`{ blob, filename, mime, rowCount,
+   * byteSize }`) so the app can preview / upload / email it. Default true.
+   * Not supported for the vendored-writer xlsx paths (grouped / multi-sheet /
+   * images / blanket styles), which download directly.
+   */
+  download?: boolean
+  /** PDF only. Page orientation. Defaults to "portrait" (auto-landscape for
+   *  wide grids). Shorthand for `pdf.pageOrientation`. */
+  pageOrientation?: 'portrait' | 'landscape'
+  /** PDF layout options: page size, margins, title / subtitle / logo, theme
+   *  colors, column widths, repeated header, page numbers. */
+  pdf?: PdfExportOptions
+  /**
+   * Conditional formatting rules - the same array you pass to
+   * `<SvGrid conditionalFormats>`. Carried into the styled formats (pdf, xlsx,
+   * html): cell background / text color / bold, plus icon-set glyphs. Ignored
+   * by the data formats (csv / tsv / json / xml / md).
+   */
+  conditionalFormats?: ReadonlyArray<ConditionalFormat<TData>>
+  /**
+   * Cell + row styles. Apply once to match a light/dark theme, or per-cell
+   * for conditional formatting. xlsx and pdf honour these; csv/tsv ignore
+   * them; html bakes them into inline `style=` attributes.
+   */
+  styles?: ExportStyles
+  /** Page header lines (xlsx, pdf, html). Logos go here as `{ image: ... }`. */
+  header?: ReadonlyArray<ExportHeaderFooterLine>
+  /** Page footer lines. Common pattern: page number on the right. */
+  footer?: ReadonlyArray<ExportHeaderFooterLine>
+  /**
+   * Multi-sheet export (xlsx only). When set, each entry becomes one
+   * sheet/tab. The top-level `rows` / `columns` are ignored.
+   */
+  sheets?: ReadonlyArray<ExportSheet<TData>>
+  /**
+   * If a row has a column whose value matches one of these field names
+   * AND the value looks like a URL or data URL, the cell is exported as
+   * an embedded image (xlsx). Defaults to `[]` (no auto-detection).
+   */
+  imageFields?: ReadonlyArray<string>
+  /**
+   * Pixel dimensions used when embedding images. Smart's xlsx writer
+   * draws the image at this size relative to the cell origin. Defaults
+   * to `{ width: 32, height: 32 }`. Set larger for thumbnails, smaller
+   * for inline icons.
+   */
+  imageSize?: { width: number; height: number }
+  /**
+   * Group flat rows by one or more field names. The exporter wraps each
+   * group in an Excel outline row (with the +/- expand button), and
+   * emits a `<value> <field>` group header above every cluster. Maps
+   * straight to Smart DataExporter's constructor `groupBy` arg. xlsx
+   * only; csv/tsv/html flatten the groups back out.
+   */
+  groupBy?: ReadonlyArray<string>
+  /**
+   * Mark rows as a hierarchical (tree) data source. Each row should
+   * declare its own children either via the `subRows` convention or by
+   * matching the parent/child shape Smart expects on the input rows.
+   * Mutually exclusive with `groupBy`. xlsx only.
+   */
+  hierarchical?: boolean
+  /**
+   * Merged cells to write into the sheet (xlsx / pdf). Each entry spans
+   * `colSpan` columns and `rowSpan` rows starting at the given zero-based
+   * **body** row / column index (the header row is not counted). Mirrors the
+   * grid's own `MergeSpec` shape closely, so grid merges map straight through -
+   * convert a `MergeSpec` (`{ rowIndex, columnId, rowspan, colspan }`) by
+   * resolving `columnId` to its column index. Mutually exclusive with
+   * `groupBy` / `hierarchical`.
+   */
+  merges?: ReadonlyArray<ExportMerge>
+}
+
+/**
+ * A merged cell region for {@link ExportOptions.merges}. `row` / `col` are
+ * zero-based indices into the exported body (header excluded). A cell that
+ * spans two columns to the right is `{ row, col, colSpan: 2 }`.
+ */
+export type ExportMerge = {
+  row: number
+  col: number
+  /** Columns to span (default 1). */
+  colSpan?: number
+  /** Rows to span (default 1). */
+  rowSpan?: number
+}
+
+let exporterCtorPromise: Promise<
+  new (
+    options: Record<string, unknown>,
+    groupBy?: ReadonlyArray<string>,
+    filterBy?: Record<string, unknown>,
+    conditionalFormatting?: unknown,
+  ) => SmartDataExporterInstance
+> | null = null
+
+async function getDataExporter() {
+  if (typeof window === 'undefined') {
+    throw new Error('@svgrid/enterprise: export requires a browser environment')
+  }
+  if (!exporterCtorPromise) {
+    exporterCtorPromise = (async () => {
+      installSmartShim()
+      // Side-effect import: the IIFE registers Smart.Utilities.DataExporter
+      // on the global Smart namespace that installSmartShim() set up.
+      await import('./smart.export.js')
+      const Ctor = window.Smart?.Utilities?.DataExporter
+      if (!Ctor) {
+        throw new Error('@svgrid/enterprise: failed to load Smart.Utilities.DataExporter')
+      }
+      return Ctor
+    })()
+  }
+  return exporterCtorPromise
+}
+
+async function ensureGlobals(format: ExportFormat): Promise<void> {
+  const g = globalThis as unknown as { JSZip?: unknown; pdfMake?: unknown }
+  if (format === 'xlsx' && g.JSZip == null) {
+    let mod: unknown
+    try {
+      mod = await import('jszip')
+    } catch {
+      throw new Error(
+        '@svgrid/enterprise: xlsx export requires the "jszip" peer dependency. ' +
+          'Install it with: pnpm add jszip',
+      )
+    }
+    g.JSZip = (mod as { default?: unknown }).default ?? mod
+  }
+  if (format === 'pdf' && g.pdfMake == null) {
+    let pdfMakeMod: unknown
+    let vfsMod: unknown
+    try {
+      pdfMakeMod = await import('pdfmake/build/pdfmake')
+      vfsMod = await import('pdfmake/build/vfs_fonts')
+    } catch {
+      throw new Error(
+        '@svgrid/enterprise: pdf export requires the "pdfmake" peer dependency. ' +
+          'Install it with: pnpm add pdfmake',
+      )
+    }
+    const pdfMake = ((pdfMakeMod as { default?: unknown }).default ?? pdfMakeMod) as {
+      vfs?: Record<string, string>
+      createPdf: (def: unknown) => { download(name: string): void; getBlob(cb: (b: Blob) => void): void }
+    }
+    const vfsRoot = (vfsMod as { default?: unknown }).default ?? vfsMod
+    // pdfmake's vfs_fonts file historically exports either { pdfMake: { vfs } }
+    // or { default: { vfs } } or { vfs } depending on bundler. Try each shape.
+    const candidate =
+      (vfsRoot as { pdfMake?: { vfs?: Record<string, string> } }).pdfMake?.vfs ??
+      (vfsRoot as { vfs?: Record<string, string> }).vfs ??
+      (vfsRoot as { default?: { vfs?: Record<string, string> } }).default?.vfs
+    if (candidate) pdfMake.vfs = candidate
+    g.pdfMake = pdfMake
+  }
+}
+
+/** Resolve the {@link ExportRowSource} shorthand against the grid api. */
+export function resolveRowSource<TFeatures extends TableFeatures, TData extends RowData>(
+  api: SvGridApi<TFeatures, TData>,
+  source: ExportRowSource<TData> | undefined,
+): ReadonlyArray<TData> {
+  if (Array.isArray(source)) return source
+  switch (source) {
+    case 'selected':
+      return api.getSelectedRows()
+    case 'all':
+      return api.getData()
+    case 'displayed':
+    case undefined:
+    default:
+      return api.getDisplayedRows()
+  }
+}
+
+/** Resolve the export columns, carrying grid header labels + `format`. */
+export function resolveColumns<TFeatures extends TableFeatures, TData extends RowData>(
+  api: SvGridApi<TFeatures, TData>,
+  opts: Pick<ExportOptions<TData>, 'columns'>,
+  sourceRows: ReadonlyArray<TData>,
+): ReadonlyArray<ExportColumn<TData>> {
+  if (opts.columns && opts.columns.length > 0) return opts.columns
+  const gridCols = api.getColumns().filter((c) => c.visible && c.field)
+  if (gridCols.length > 0) {
+    return gridCols.map((c) => ({
+      field: c.field!,
+      header: c.header,
+      format: c.format,
+      align: c.align,
+    }))
+  }
+  if (sourceRows.length > 0) {
+    return Object.keys(sourceRows[0] as Record<string, unknown>)
+      .filter((k) => !k.startsWith('_'))
+      .map((field) => ({ field }) as ExportColumn<TData>)
+  }
+  return []
+}
+
+/**
+ * The value written for one cell: an `exportValue` hook wins; otherwise the
+ * raw field value, formatted to the on-screen display string unless
+ * `rawValues` is set.
+ */
+function cellValueFor<TData extends RowData>(
+  col: ExportColumn<TData>,
+  rowData: TData,
+  rawValues: boolean,
+): unknown {
+  if (col.exportValue) {
+    const v = col.exportValue(rowData)
+    return v ?? ''
+  }
+  const raw = (rowData as unknown as Record<string, unknown>)[col.field]
+  if (rawValues) return raw
+  return formatValueForExport(raw, col.format)
+}
+
+
+/**
+ * Project source rows into the `[header, ...records]` shape the writers
+ * consume, applying per-column formatting / `exportValue`. Async so it can
+ * yield to the event loop (and honour an abort) on large datasets.
+ */
+export async function projectRows<TData extends RowData>(
+  sourceRows: ReadonlyArray<TData>,
+  cols: ReadonlyArray<ExportColumn<TData>>,
+  opts: Pick<ExportOptions<TData>, 'rawValues' | 'onProgress' | 'signal'>,
+): Promise<Array<Record<string, unknown>>> {
+  const rawValues = opts.rawValues === true
+  const headerRow: Record<string, unknown> = {}
+  for (const c of cols) headerRow[c.field] = c.header ?? c.field
+
+  const projected: Array<Record<string, unknown>> = [headerRow]
+  const total = sourceRows.length
+  const CHUNK = 5000
+  for (let i = 0; i < total; i++) {
+    if (opts.signal?.aborted) throw new DOMException('Export aborted', 'AbortError')
+    const r = sourceRows[i]!
+    const row: Record<string, unknown> = {}
+    for (const c of cols) row[c.field] = cellValueFor(c, r, rawValues)
+    projected.push(row)
+    if (i > 0 && i % CHUNK === 0) {
+      opts.onProgress?.({ phase: 'project', ratio: i / total, row: i, total })
+      await new Promise((resolve) => setTimeout(resolve, 0))
+    }
+  }
+  opts.onProgress?.({ phase: 'project', ratio: 1, row: total, total })
+  return projected
+}
+
+/**
+ * Translate the public {@link ExportStyles} shape into the keys the Smart
+ * exporter actually consumes:
+ *   `style.header`    → all header cells
+ *   `style.rows`      → all data rows. Cell-prop keys (color, backgroundColor,
+ *                       fontWeight, fontStyle, fontSize, fontFamily,
+ *                       textAlign, verticalAlign, textDecoration, numFmt)
+ *                       are recognised by Smart's `storeCellStyle`.
+ *   `style.rows.alternationCount` + `alternationStart` +
+ *   `alternationIndex1BackgroundColor` (etc.) → zebra striping
+ *   `style.cells.<ref>` → HTML-only per-cell ref overrides
+ */
+function translateStyles(styles: ExportStyles | undefined): Record<string, unknown> | undefined {
+  if (!styles) return undefined
+  const out: Record<string, unknown> = {}
+  if (styles.headerRow) out.header = { ...styles.headerRow }
+  const rows: Record<string, unknown> = styles.rows ? { ...styles.rows } : {}
+  if (styles.rowAlternate) {
+    rows.alternationCount = 2
+    rows.alternationStart = 0
+    if (styles.rowAlternate.backgroundColor)
+      rows.alternationIndex1BackgroundColor = styles.rowAlternate.backgroundColor
+    if (styles.rowAlternate.color)
+      rows.alternationIndex1Color = styles.rowAlternate.color
+  }
+  if (Object.keys(rows).length > 0) out.rows = rows
+  if (styles.cells) out.cells = styles.cells
+  return out
+}
+
+let _imgIdCounter = 0
+const _imgIdCache = new Map<string, string>()
+function imageIdFor(dataUrl: string): string {
+  const cached = _imgIdCache.get(dataUrl)
+  if (cached) return cached
+  const id = `img${++_imgIdCounter}`
+  _imgIdCache.set(dataUrl, id)
+  return id
+}
+
+/**
+ * Build the image object Smart's xlsx writer expects. The exporter pulls
+ * `{ id, base64, imageType, width, height }` off the return of
+ * `addImageToCell(...).image` and stores it under `this.images` →
+ * eventually written to the workbook as `xl/media/imageN.<imageType>`.
+ *
+ * `base64` may be a full data URL - Smart strips the prefix when writing.
+ */
+function makeSmartImage(dataUrl: string, width = 64, height = 64): {
+  id: string; base64: string; imageType: string; width: number; height: number
+} {
+  // Extract MIME → imageType. Defaults to png for safety.
+  const mime = /^data:image\/([a-zA-Z0-9+]+);/i.exec(dataUrl)?.[1]?.toLowerCase() ?? 'png'
+  const imageType = mime === 'jpg' ? 'jpeg'
+                  : mime === 'svg+xml' ? 'svg'
+                  : mime
+  return {
+    id: imageIdFor(dataUrl),
+    base64: dataUrl,
+    imageType,
+    width,
+    height,
+  }
+}
+
+/**
+ * Build the header / footer arrays the Smart exporter understands.
+ * Each input line becomes one full-width row in the spreadsheet with
+ * `style.mergeAcross` so the line spans every column.
+ *
+ * Image lines are written as a data-URL string into the first column and
+ * the wrapper's `addImageToCell` hook embeds them as real picture cells.
+ */
+function buildContentRows(
+  lines: ReadonlyArray<ExportHeaderFooterLine> | undefined,
+  datafields: ReadonlyArray<string>,
+): Array<{ cells: Record<string, unknown>; style?: Record<string, unknown> }> | undefined {
+  if (!lines || lines.length === 0 || datafields.length === 0) return undefined
+  const first = datafields[0]!
+  const out: Array<{ cells: Record<string, unknown>; style?: Record<string, unknown> }> = []
+  for (const line of lines) {
+    const cells: Record<string, unknown> = {}
+    let style: Record<string, unknown> | undefined
+    if ('image' in line) {
+      cells[first] = line.image
+      style = { mergeAcross: true, textAlign: 'left' }
+    } else if ('text' in line) {
+      cells[first] = line.text
+      style = { mergeAcross: true, ...(line.style ?? {}) }
+    } else {
+      // 3-column { left, center, right }. Distribute across the first,
+      // middle, and last datafield.
+      const mid  = datafields[Math.floor(datafields.length / 2)]!
+      const last = datafields[datafields.length - 1]!
+      if (line.left   !== undefined) cells[first] = line.left
+      if (line.center !== undefined) cells[mid]   = line.center
+      if (line.right  !== undefined) cells[last]  = line.right
+      style = { textAlign: 'left' }
+    }
+    out.push({ cells, style })
+  }
+  return out
+}
+
+/**
+ * Build an `addImageToCell` handler that embeds a value as a real image
+ * cell whenever the value is a data URL. Smart calls this for every body
+ * cell AND every header/footer cell, so the same handler covers both
+ * code paths.
+ *
+ * `bodyImageSize` controls the embedded pixel size for body cells (the
+ * thumbnails). Header/footer image lines use their own size hint
+ * already encoded in the `cells[first]` value's metadata - here we just
+ * embed with a slightly larger default so logos read well in the page
+ * banner.
+ */
+function buildImageHandler(
+  imageFields: ReadonlyArray<string> | undefined,
+  bodyImageSize: { width: number; height: number },
+): NonNullable<SmartDataExporterInstance['addImageToCell']> {
+  const allowed = imageFields && imageFields.length > 0 ? new Set(imageFields) : null
+  return (_rowIndex, dataField, value) => {
+    if (typeof value !== 'string') return null
+    if (!/^data:image\//i.test(value)) return null
+    if (allowed && !allowed.has(dataField)) {
+      // Header/footer image lines come through the first column too -
+      // those cells aren't in `imageFields`, but the wrapper wrote the
+      // data URL there itself. Embed bigger (logo banner).
+      return { image: makeSmartImage(value, 96, 96), value: '' }
+    }
+    return { image: makeSmartImage(value, bodyImageSize.width, bodyImageSize.height), value: '' }
+  }
+}
+
+/**
+ * Build the constructor-options object passed to the Smart DataExporter.
+ * Constructor only consumes a small set of keys; instance-level options
+ * (`headerContent`, `footerContent`, `addImageToCell`) are applied
+ * separately in {@link exportGrid} after `new DataExporter(...)`.
+ */
+function buildExporterOptions<TData>(
+  opts: ExportOptions<TData>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {
+    exportHeader: true,
+    pageOrientation: opts.pageOrientation ?? 'portrait',
+  }
+  // Freeze the header row (and optional leading columns) so they stay in view
+  // when scrolling the xlsx. On by default.
+  if (opts.freezeHeader !== false) out.freezeHeader = true
+  if (opts.freezeColumns && opts.freezeColumns > 0) {
+    out.freezeColumnsCount = Math.floor(opts.freezeColumns)
+  }
+  const style = translateStyles(opts.styles)
+  if (style) out.style = style
+  // Smart's xlsx writer emits Excel-native row outlining when
+  // `hierarchical: true` is set on the constructor options OR when the
+  // second constructor arg is a non-empty groupBy array. We thread
+  // hierarchical through here and groupBy through the constructor call
+  // site in exportGrid.
+  if (opts.hierarchical) out.hierarchical = true
+  // Merged cells: translate the friendly {row, col, rowSpan, colSpan} shape to
+  // Smart's native {cell: [row, col], rowspan, colspan}. Skip 1x1 "merges"
+  // (nothing to span). Ignored when grouping/hierarchy owns the row layout.
+  if (opts.merges?.length && !opts.groupBy?.length && !opts.hierarchical) {
+    const mergedCells = opts.merges
+      .map((m) => ({
+        cell: [m.row, m.col],
+        rowspan: Math.max(1, Math.floor(m.rowSpan ?? 1)),
+        colspan: Math.max(1, Math.floor(m.colSpan ?? 1)),
+      }))
+      .filter((m) => m.rowspan > 1 || m.colspan > 1)
+    if (mergedCells.length) out.mergedCells = mergedCells
+  }
+  return out
+}
+
+/**
+ * Apply instance-level options the constructor does not consume.
+ * Mutates and returns the exporter for fluent use.
+ */
+function applyInstanceOptions<TData>(
+  exporter: SmartDataExporterInstance,
+  opts: ExportOptions<TData>,
+  datafields: ReadonlyArray<string>,
+): SmartDataExporterInstance {
+  const headerRows = buildContentRows(opts.header, datafields)
+  const footerRows = buildContentRows(opts.footer, datafields)
+  if (headerRows) exporter.headerContent = headerRows
+  if (footerRows) exporter.footerContent = footerRows
+
+  // Wire image embedding when the caller opts in via imageFields OR the
+  // header/footer carries an image line. Both code paths funnel through
+  // the same handler.
+  const hasHeaderOrFooterImage =
+    (opts.header?.some((l) => 'image' in l) ?? false) ||
+    (opts.footer?.some((l) => 'image' in l) ?? false)
+  if (opts.imageFields?.length || hasHeaderOrFooterImage) {
+    const bodySize = opts.imageSize ?? { width: 32, height: 32 }
+    exporter.addImageToCell = buildImageHandler(opts.imageFields, bodySize)
+  }
+  return exporter
+}
+
+/** Append `.ext` to a filename that doesn't already carry it. */
+function ensureExt(name: string, ext: string): string {
+  return name.toLowerCase().endsWith('.' + ext) ? name : `${name}.${ext}`
+}
+
+/** Download the blob (unless `download === false`) and return the result. */
+function deliver(
+  blob: Blob,
+  filename: string,
+  mime: string,
+  rowCount: number,
+  download: boolean | undefined,
+): ExportResult {
+  if (download !== false) downloadBlobFile(blob, filename)
+  return { blob, filename, mime, rowCount, byteSize: blob.size }
+}
+
+/** Text-file variant: download via `downloadTextFile`, also return the blob. */
+function deliverText(
+  text: string,
+  filename: string,
+  mime: string,
+  rowCount: number,
+  download: boolean | undefined,
+): ExportResult {
+  if (download !== false) downloadTextFile(text, filename, mime)
+  const blob = new Blob([text], { type: mime })
+  return { blob, filename, mime, rowCount, byteSize: blob.size }
+}
+
+/**
+ * Estimate a per-column pixel width from the header + a sample of cell values,
+ * for xlsx / xls auto-fit. A column's explicit `width` always wins. ~7px per
+ * character, clamped to a sensible range.
+ */
+function autoFitWidths<TData extends RowData>(
+  cols: ReadonlyArray<ExportColumn<TData>>,
+  rows: ReadonlyArray<TData>,
+  rawValues: boolean,
+): number[] {
+  const SAMPLE = Math.min(rows.length, 200)
+  return cols.map((c) => {
+    if (typeof c.width === 'number') return c.width
+    let maxChars = String(c.header ?? c.field).length
+    for (let i = 0; i < SAMPLE; i++) {
+      const v = cellValueFor(c, rows[i]!, rawValues)
+      const len = v == null ? 0 : String(v).length
+      if (len > maxChars) maxChars = len
+    }
+    return Math.max(48, Math.min(400, maxChars * 7 + 14))
+  })
+}
+
+/**
+ * Freeze-column count: explicit `freezeColumns` wins; otherwise derive it from
+ * the grid's left-pinned columns that lead the export column order. Silent
+ * (returns undefined) when neither applies.
+ */
+function resolveFreezeColumns<TFeatures extends TableFeatures, TData extends RowData>(
+  api: SvGridApi<TFeatures, TData>,
+  opts: Pick<ExportOptions<TData>, 'freezeColumns'>,
+  cols: ReadonlyArray<ExportColumn<TData>>,
+): number | undefined {
+  if (typeof opts.freezeColumns === 'number') return opts.freezeColumns
+  const left = api.getColumnPinning().left
+  if (!left || left.length === 0) return undefined
+  const pinnedSet = new Set(left)
+  // Count leading export columns that are pinned-left (by field id).
+  let n = 0
+  for (const c of cols) {
+    if (pinnedSet.has(c.field)) n++
+    else break
+  }
+  return n > 0 ? n : undefined
+}
+
+/** Excel column letter for a 0-based column index (0 -> A, 26 -> AA). */
+function colLetter(index: number): string {
+  let n = index
+  let s = ''
+  do {
+    s = String.fromCharCode(65 + (n % 26)) + s
+    n = Math.floor(n / 26) - 1
+  } while (n >= 0)
+  return s
+}
+
+/** A `(rowIdx, colIdx) => url` resolver from column `link` hooks, or undefined
+ *  when no column defines links. */
+export function buildLinkResolver<TData extends RowData>(
+  cols: ReadonlyArray<ExportColumn<TData>>,
+  rows: ReadonlyArray<TData>,
+): ((rowIdx: number, colIdx: number) => string | undefined) | undefined {
+  if (!cols.some((c) => c.link)) return undefined
+  return (rowIdx, colIdx) => {
+    const col = cols[colIdx]
+    const row = rows[rowIdx]
+    if (!col?.link || !row) return undefined
+    return col.link(row) || undefined
+  }
+}
+
+/** Build a `field -> align` map from resolved columns (for html / md). */
+function alignMap<TData extends RowData>(
+  cols: ReadonlyArray<ExportColumn<TData>>,
+): Record<string, 'left' | 'center' | 'right'> {
+  const align: Record<string, 'left' | 'center' | 'right'> = {}
+  for (const c of cols) if (c.align) align[c.field] = c.align
+  return align
+}
+
+/**
+ * Serialize projected rows to the requested native format string. Shared by
+ * file export and clipboard export. Returns `{ text, mime, ext }`.
+ */
+async function serializeNative<TData extends RowData>(
+  format: ExportFormat,
+  projected: ReadonlyArray<Record<string, unknown>>,
+  cols: ReadonlyArray<ExportColumn<TData>>,
+  opts: Pick<ExportOptions<TData>, 'onProgress' | 'signal' | 'csv' | 'filename'>,
+  cellStyle?: ExportCellVisualFn,
+  cellLink?: (rowIdx: number, colIdx: number) => string | undefined,
+): Promise<{ text: string; mime: string; ext: string }> {
+  const fields = cols.map((c) => c.field)
+  const p = { onProgress: opts.onProgress, signal: opts.signal }
+  switch (format) {
+    case 'html': {
+      const text = await serializeHtml(projected, fields, {
+        ...p,
+        title: (opts.filename ?? 'grid').trim() || 'grid',
+        align: alignMap(cols),
+        cellStyle,
+        cellLink,
+      })
+      return { text, mime: 'text/html;charset=utf-8', ext: 'html' }
+    }
+    case 'json': {
+      const text = await serializeJson(projected, fields, p)
+      return { text, mime: 'application/json;charset=utf-8', ext: 'json' }
+    }
+    case 'xml': {
+      const text = await serializeXml(projected, fields, p)
+      return { text, mime: 'application/xml;charset=utf-8', ext: 'xml' }
+    }
+    case 'md': {
+      const text = await serializeMarkdown(projected, fields, { ...p, align: alignMap(cols) })
+      return { text, mime: 'text/markdown;charset=utf-8', ext: 'md' }
+    }
+    case 'tsv': {
+      const text = await serializeDelimited(projected, fields, { ...p, csv: { ...opts.csv, delimiter: '\t' } })
+      return { text, mime: 'text/tab-separated-values;charset=utf-8', ext: 'tsv' }
+    }
+    case 'csv':
+    default: {
+      const delimiter = opts.csv?.delimiter ?? ','
+      const text = await serializeDelimited(projected, fields, { ...p, csv: { ...opts.csv, delimiter } })
+      return { text, mime: 'text/csv;charset=utf-8', ext: 'csv' }
+    }
+  }
+}
+
+/**
+ * Native text export (csv / tsv / html / json / xml / md). No Smart exporter,
+ * no peer deps - pure streaming serialization with progress + abort. Values
+ * are formatted to match the on-screen display (json defaults to raw so it
+ * stays machine-readable).
+ */
+async function exportTextFormat<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(api: SvGridApi<TFeatures, TData>, opts: ExportOptions<TData>): Promise<ExportResult> {
+  if (opts.sheets && opts.sheets.length > 0) {
+    throw new Error(
+      `@svgrid/enterprise: multi-sheet export requires format 'xlsx', got '${opts.format}'`,
+    )
+  }
+  const sourceRows = resolveRowSource(api, opts.rows)
+  if (sourceRows.length === 0) {
+    throw new Error('@svgrid/enterprise: nothing to export - the grid has no rows')
+  }
+  const cols = resolveColumns(api, opts, sourceRows)
+  // JSON is a data format: default to raw values so consumers get real
+  // numbers/dates, not "$19.95" strings. The other formats default formatted.
+  const projectOpts =
+    opts.format === 'json' ? { ...opts, rawValues: opts.rawValues ?? true } : opts
+  const projected = await projectRows(sourceRows, cols, projectOpts)
+  const filename = (opts.filename ?? 'grid').trim() || 'grid'
+
+  // HTML carries conditional formatting (fill / color / bold / icon); the other
+  // native formats are unstyled data.
+  const cellStyle =
+    opts.format === 'html'
+      ? buildConditionalResolver(cols, sourceRows, opts.conditionalFormats)
+      : undefined
+  const cellLink = opts.format === 'html' ? buildLinkResolver(cols, sourceRows) : undefined
+  const { text, mime, ext } = await serializeNative(opts.format, projected, cols, opts, cellStyle, cellLink)
+  return deliverText(text, ensureExt(filename, ext), mime, sourceRows.length, opts.download)
+}
+
+/**
+ * Legacy `.xls` export (Excel 2003 XML Spreadsheet). Dependency-free and
+ * streaming, like the text path, but produces a real typed spreadsheet.
+ */
+async function exportXls<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(api: SvGridApi<TFeatures, TData>, opts: ExportOptions<TData>): Promise<ExportResult> {
+  if (opts.sheets && opts.sheets.length > 0) {
+    throw new Error(
+      "@svgrid/enterprise: multi-sheet export requires format 'xlsx'. Use 'xls' for a single legacy sheet.",
+    )
+  }
+  const sourceRows = resolveRowSource(api, opts.rows)
+  if (sourceRows.length === 0) {
+    throw new Error('@svgrid/enterprise: nothing to export - the grid has no rows')
+  }
+  const cols = resolveColumns(api, opts, sourceRows)
+  const filename = (opts.filename ?? 'grid').trim() || 'grid'
+  const visual = buildConditionalResolver(cols, sourceRows, opts.conditionalFormats)
+  const xml = await serializeSpreadsheetML(filename, cols, sourceRows, {
+    rawValues: opts.rawValues,
+    onProgress: opts.onProgress,
+    signal: opts.signal,
+    freezeHeader: opts.freezeHeader !== false,
+    freezeColumns: resolveFreezeColumns(api, opts, cols),
+    widths: opts.autoFitColumns !== false ? autoFitWidths(cols, sourceRows, opts.rawValues === true) : undefined,
+    cellVisual: opts.conditionalFormats?.length ? visual : undefined,
+    precisionSafe: opts.precisionSafe,
+  })
+  const mime = 'application/vnd.ms-excel;charset=utf-8'
+  return deliverText(xml, ensureExt(filename, 'xls'), mime, sourceRows.length, opts.download)
+}
+
+/** Columns whose values can be summed for a PDF subtotal row. */
+function isSummableColumn<TData extends RowData>(col: ExportColumn<TData>): boolean {
+  return col.format?.type === 'number' || col.format?.type === 'currency'
+}
+
+/**
+ * Build a grouped PDF body: a bold group header per cluster (nested for
+ * multi-level grouping), the cluster's data rows, then a subtotal row summing
+ * the numeric / currency columns. Values use the same formatting as the grid.
+ */
+export function buildGroupedPdfBody<TData extends RowData>(
+  cols: ReadonlyArray<ExportColumn<TData>>,
+  rows: ReadonlyArray<TData>,
+  groupBy: ReadonlyArray<string>,
+): PdfBodyRow[] {
+  const out: PdfBodyRow[] = []
+  const headerOf = (field: string) => cols.find((c) => c.field === field)?.header ?? field
+  // Put the "Subtotal" label in the first NON-numeric column; if every column
+  // is numeric, -1 means "don't overwrite a sum with the label".
+  const labelColIdx = cols.findIndex((c) => !isSummableColumn(c))
+
+  const recurse = (subset: ReadonlyArray<TData>, level: number) => {
+    if (level >= groupBy.length) {
+      for (const r of subset) {
+        out.push({ kind: 'data', cells: cols.map((c) => String(cellValueFor(c, r, false) ?? '')) })
+      }
+      return
+    }
+    const field = groupBy[level]!
+    // Preserve first-seen order of group keys.
+    const buckets = new Map<string, TData[]>()
+    for (const r of subset) {
+      const key = String((r as Record<string, unknown>)[field] ?? '')
+      const bucket = buckets.get(key)
+      if (bucket) bucket.push(r)
+      else buckets.set(key, [r])
+    }
+    for (const [key, groupRows] of buckets) {
+      out.push({ kind: 'group', label: `${headerOf(field)}: ${key} (${groupRows.length})`, level })
+      recurse(groupRows, level + 1)
+      // Subtotal row for the numeric columns of this cluster.
+      const hasSummable = cols.some(isSummableColumn)
+      if (hasSummable) {
+        const cells = cols.map((c) => {
+          if (!isSummableColumn(c)) return ''
+          const sum = groupRows.reduce(
+            (a, r) => a + (Number((r as Record<string, unknown>)[c.field]) || 0),
+            0,
+          )
+          return formatValueForExport(sum, c.format)
+        })
+        if (labelColIdx >= 0) cells[labelColIdx] = `Subtotal (${key})`
+        out.push({ kind: 'subtotal', cells })
+      }
+    }
+  }
+  recurse(rows, 0)
+  return out
+}
+
+/**
+ * PDF export via our own pdfmake docDefinition (page setup, repeated header,
+ * page numbers, per-column alignment/widths, title/logo, theme colors, and
+ * group + subtotal rows carried from the grid's grouping). Values are the
+ * formatted display strings, so the PDF matches the grid.
+ */
+async function exportPdf<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(api: SvGridApi<TFeatures, TData>, opts: ExportOptions<TData>): Promise<ExportResult> {
+  await ensureGlobals('pdf')
+  const pdfMake = (globalThis as unknown as {
+    pdfMake?: {
+      createPdf: (def: unknown) => {
+        download(name: string): void
+        getBlob(cb: (b: Blob) => void): void
+      }
+    }
+  }).pdfMake
+  if (!pdfMake) {
+    throw new Error('@svgrid/enterprise: pdf export requires the "pdfmake" peer dependency.')
+  }
+  const sourceRows = resolveRowSource(api, opts.rows)
+  if (sourceRows.length === 0) {
+    throw new Error('@svgrid/enterprise: nothing to export - the grid has no rows')
+  }
+  const cols = resolveColumns(api, opts, sourceRows)
+  const fields = cols.map((c) => c.field)
+  const columns = cols.map((c) => ({ header: c.header ?? c.field, align: c.align }))
+
+  // Carry the grid's active grouping into group + subtotal rows (unless the
+  // caller opted out or passed hierarchical), matching the xlsx outline path.
+  const autoGrouping =
+    opts.autoGroup !== false && !opts.groupBy?.length && !opts.hierarchical
+      ? (api.getState().grouping ?? []).filter((id) => !!id).map((id) => String(id))
+      : []
+  const effGroupBy = opts.groupBy?.length
+    ? opts.groupBy
+    : autoGrouping.length > 0
+      ? autoGrouping
+      : undefined
+
+  if (opts.signal?.aborted) throw new DOMException('Export aborted', 'AbortError')
+  opts.onProgress?.({ phase: 'write', ratio: 0, total: sourceRows.length })
+
+  const pdfOpts: PdfExportOptions = {
+    ...opts.pdf,
+    pageOrientation: opts.pdf?.pageOrientation ?? opts.pageOrientation,
+  }
+  const now = new Date()
+  let def
+  if (effGroupBy?.length) {
+    // Conditional formatting is skipped for grouped PDFs (group / subtotal
+    // rows own the layout); the grid colors still show on screen.
+    const body = buildGroupedPdfBody(cols, sourceRows, effGroupBy)
+    def = buildPdfDocDefinition({ columns, body, opts: pdfOpts, now })
+  } else {
+    const projected = await projectRows(sourceRows, cols, opts)
+    const dataRows = projected.slice(1).map((r) => fields.map((f) => String(r[f] ?? '')))
+    // Conditional formatting -> per-cell fill / color / bold + icon prefix.
+    const visual = buildConditionalResolver(cols, sourceRows, opts.conditionalFormats)
+    for (let r = 0; r < dataRows.length; r++) {
+      for (let c = 0; c < cols.length; c++) {
+        const icon = visual(r, c)?.icon
+        if (icon) dataRows[r]![c] = `${icon} ${dataRows[r]![c] ?? ''}`
+      }
+    }
+    const link = buildLinkResolver(cols, sourceRows)
+    def = buildPdfDocDefinition({
+      columns,
+      rows: dataRows,
+      dataCellStyle: (r, c) => {
+        const v = visual(r, c)
+        return v ? { fill: v.fill, color: v.color, bold: v.bold } : undefined
+      },
+      dataCellLink: link,
+      opts: pdfOpts,
+      now,
+    })
+  }
+  const filename = (opts.filename ?? 'grid').trim() || 'grid'
+  const blob = await new Promise<Blob>((resolve) => pdfMake.createPdf(def).getBlob(resolve))
+  opts.onProgress?.({ phase: 'write', ratio: 1, total: sourceRows.length })
+  return deliver(blob, ensureExt(filename, 'pdf'), 'application/pdf', sourceRows.length, opts.download)
+}
+
+/**
+ * Resolve one cell into the typed descriptor the native xlsx writer needs:
+ * real numbers / dates with a number format (Excel sums + sorts), or a
+ * formatted string, plus conditional-format fill / color / bold / icon and a
+ * hyperlink.
+ */
+async function buildXlsxCellMatrix<TData extends RowData>(
+  cols: ReadonlyArray<ExportColumn<TData>>,
+  rows: ReadonlyArray<TData>,
+  rawValues: boolean,
+  visual: ExportCellVisualFn,
+  link: ((rowIdx: number, colIdx: number) => string | undefined) | undefined,
+  opts?: { onProgress?: (p: ExportProgress) => void; signal?: AbortSignal; precisionSafe?: boolean },
+): Promise<{ header: string[]; cells: XlsxCell[][] }> {
+  const header = cols.map((c) => c.header ?? c.field)
+  const precisionSafe = opts?.precisionSafe === true
+  // Excel stores numbers as 64-bit floats (~15 significant digits); a longer
+  // integer (an ID) would be silently rounded. In precision-safe mode we write
+  // such values as text so they survive intact.
+  const num = (value: number, base: object, numFmt?: string): XlsxCell =>
+    precisionSafe && Math.abs(value) >= 1e15
+      ? { t: 's', value: String(value), ...base }
+      : { t: 'n', value, numFmt, ...base }
+
+  const cellFor = (row: TData, r: number, c: number): XlsxCell => {
+    const col = cols[c]!
+    const v = visual(r, c)
+    const base = { align: col.align, fill: v?.fill, color: v?.color, bold: v?.bold, link: link?.(r, c) }
+    if (col.exportValue) {
+      const ev = col.exportValue(row)
+      if (typeof ev === 'number' && Number.isFinite(ev)) return num(ev, base, toExcelNumFmt(col.format))
+      if (ev instanceof Date) return { t: 'd', value: ev, numFmt: toExcelNumFmt(col.format) ?? 'yyyy-mm-dd', ...base }
+      return { t: 's', value: ev == null ? '' : String(ev), ...base }
+    }
+    const raw = (row as Record<string, unknown>)[col.field]
+    // An icon-set glyph forces a string cell (icon + formatted value).
+    if (v?.icon) {
+      const disp = rawValues ? String(raw ?? '') : formatValueForExport(raw, col.format)
+      return { t: 's', value: `${v.icon} ${disp}`, ...base }
+    }
+    if (rawValues) {
+      if (typeof raw === 'number' && Number.isFinite(raw)) return num(raw, base)
+      return { t: 's', value: raw == null ? '' : String(raw), ...base }
+    }
+    const typed = valueForExcel(raw, col.format)
+    if (typed.ok) {
+      if (typed.value instanceof Date) return { t: 'd', value: typed.value, numFmt: toExcelNumFmt(col.format) ?? 'yyyy-mm-dd', ...base }
+      return num(typed.value, base, toExcelNumFmt(col.format))
+    }
+    return { t: 's', value: formatValueForExport(raw, col.format), ...base }
+  }
+
+  // Build in chunks, yielding to the event loop so a huge export doesn't freeze
+  // the tab (the per-cell Intl formatting is the expensive part).
+  const cells: XlsxCell[][] = []
+  const total = rows.length
+  const CHUNK = 2000
+  for (let r = 0; r < total; r++) {
+    if (opts?.signal?.aborted) throw new DOMException('Export aborted', 'AbortError')
+    const row = rows[r]!
+    cells.push(cols.map((_, c) => cellFor(row, r, c)))
+    if (r > 0 && r % CHUNK === 0) {
+      opts?.onProgress?.({ phase: 'project', ratio: r / total, row: r, total })
+      await new Promise((resolve) => setTimeout(resolve, 0))
+    }
+  }
+  return { header, cells }
+}
+
+/**
+ * Native single-sheet xlsx export (our own OOXML writer). Typed numbers +
+ * number formats, true per-cell conditional-format fills, freeze header,
+ * auto-fit widths, and real hyperlinks - none of which the vendored writer can
+ * do. Needs only `jszip`.
+ */
+async function exportXlsxNative<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(api: SvGridApi<TFeatures, TData>, opts: ExportOptions<TData>): Promise<ExportResult> {
+  await ensureGlobals('xlsx') // loads jszip onto globalThis
+  const JSZip = (globalThis as unknown as { JSZip?: new () => never }).JSZip as unknown as
+    | (new () => { file(p: string, d: string): void; generateAsync(o: { type: 'blob'; mimeType?: string }): Promise<Blob> })
+    | undefined
+  if (!JSZip) throw new Error('@svgrid/enterprise: xlsx export requires the "jszip" peer dependency.')
+
+  const src = resolveRowSource(api, opts.rows)
+  if (src.length === 0) {
+    throw new Error('@svgrid/enterprise: nothing to export - the grid has no rows')
+  }
+  const cols = resolveColumns(api, opts, src)
+  const rawValues = opts.rawValues === true
+
+  // Color scales + data bars become NATIVE Excel conditional formatting (Excel
+  // computes them, so they're interactive). Predicate rules + icon sets stay
+  // client-computed per cell. So the per-cell resolver only sees rule/iconSet.
+  const cf = opts.conditionalFormats ?? []
+  const cellCf = cf.filter((f) => f.type === 'rule' || f.type === 'iconSet')
+  const visual = buildConditionalResolver(cols, src, cellCf)
+  const link = buildLinkResolver(cols, src)
+
+  const condFormats: XlsxCondFormat[] = []
+  for (const f of cf) {
+    if (f.type !== 'colorScale' && f.type !== 'dataBar') continue
+    const targetIdxs =
+      f.columns && f.columns.length > 0
+        ? cols.map((c, i) => (f.columns!.includes(c.field) ? i : -1)).filter((i) => i >= 0)
+        : cols.map((_, i) => i)
+    for (const ci of targetIdxs) {
+      if (f.type === 'dataBar') condFormats.push({ kind: 'dataBar', colIdx: ci, color: f.color })
+      else condFormats.push({ kind: 'colorScale', colIdx: ci, colors: f.mid ? [f.min, f.mid, f.max] : [f.min, f.max] })
+    }
+  }
+
+  if (opts.signal?.aborted) throw new DOMException('Export aborted', 'AbortError')
+  opts.onProgress?.({ phase: 'write', ratio: 0, total: src.length })
+  const { header, cells } = await buildXlsxCellMatrix(cols, src, rawValues, visual, link, {
+    onProgress: opts.onProgress,
+    signal: opts.signal,
+    precisionSafe: opts.precisionSafe,
+  })
+  const widths = opts.autoFitColumns !== false ? autoFitWidths(cols, src, rawValues) : undefined
+  const filename = (opts.filename ?? 'grid').trim() || 'grid'
+
+  // Excel Table (ListObject): filter dropdowns + banded rows, and optionally a
+  // totals row with SUBTOTAL formulas over the summable columns.
+  let table: XlsxTableSpec | undefined
+  if (opts.excelTable) {
+    const totalsRow = typeof opts.excelTable === 'object' ? opts.excelTable.totalsRow === true : false
+    const style = typeof opts.excelTable === 'object' ? opts.excelTable.style : undefined
+    table = {
+      name: 'Table1',
+      totalsRow,
+      style,
+      totalsFns: cols.map((c) => (isSummableColumn(c) ? 'sum' : undefined)),
+    }
+  }
+
+  const parts = buildXlsxParts({
+    sheetName: filename,
+    header,
+    rows: cells,
+    widths,
+    freezeHeader: opts.freezeHeader !== false,
+    freezeColumns: resolveFreezeColumns(api, opts, cols),
+    condFormats,
+    table,
+  })
+  const blob = await packageXlsx(parts, JSZip)
+  opts.onProgress?.({ phase: 'write', ratio: 1, total: src.length })
+  return deliver(blob, ensureExt(filename, 'xlsx'), 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', src.length, opts.download)
+}
+
+export async function exportGrid<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(api: SvGridApi<TFeatures, TData>, opts: ExportOptions<TData>): Promise<ExportResult | undefined> {
+  assertEnterpriseLicensed('Export')
+
+  // Native text formats have their own dependency-free, streaming path.
+  if (NATIVE_TEXT_FORMATS.includes(opts.format)) {
+    return exportTextFormat(api, opts)
+  }
+  // Legacy xls (SpreadsheetML) is also dependency-free.
+  if (opts.format === 'xls') {
+    return exportXls(api, opts)
+  }
+  // PDF via our own pdfmake docDefinition.
+  if (opts.format === 'pdf') {
+    return exportPdf(api, opts)
+  }
+
+  // Native single-sheet xlsx (our OOXML writer): typed numbers + number
+  // formats, real per-cell conditional-format fills, freeze, widths, and
+  // hyperlinks. Grouping (Excel outline), multi-sheet, images, merges, and
+  // header/footer lines keep the vendored writer below.
+  if (opts.format === 'xlsx') {
+    const gridGrouping =
+      opts.autoGroup !== false ? (api.getState().grouping ?? []).filter((id) => !!id) : []
+    const grouped = (opts.groupBy?.length ?? 0) > 0 || gridGrouping.length > 0
+    // Blanket `styles` (header fill / zebra) are applied by the vendored
+    // writer, not our OOXML one - so a styled export (without conditional
+    // formatting, which the native writer does render) keeps the Smart path.
+    const wantsBlanketStyles = !!opts.styles && !opts.conditionalFormats?.length
+    if (
+      !opts.sheets?.length &&
+      !grouped &&
+      !opts.hierarchical &&
+      !opts.merges?.length &&
+      !opts.header?.length &&
+      !opts.footer?.length &&
+      !opts.imageFields?.length &&
+      !wantsBlanketStyles
+    ) {
+      return exportXlsxNative(api, opts)
+    }
+  }
+
+  await ensureGlobals(opts.format)
+  const Ctor = await getDataExporter()
+
+  // Multi-sheet path. Smart's `spreadsheets` option takes an array of
+  // `{ label, dataSource, columns, dataFields? }`. Each entry becomes one
+  // tab; the exporter prepends its own header row built from `columns`.
+  if (opts.sheets && opts.sheets.length > 0) {
+    if (opts.format !== 'xlsx') {
+      throw new Error(`@svgrid/enterprise: multi-sheet export requires format 'xlsx', got '${opts.format}'`)
+    }
+    const rawValues = opts.rawValues === true
+    const sheets = opts.sheets.map((sheet) => {
+      // Reuse the single-sheet column derivation (explicit → grid columns →
+      // row keys), so per-sheet columns pick up `format` for formatting too.
+      const cols = resolveColumns(
+        api,
+        { columns: sheet.columns ?? opts.columns },
+        sheet.rows,
+      )
+      // Project each row to only the included fields (in column order),
+      // applying per-column formatting / exportValue.
+      const dataSource = sheet.rows.map((r) => {
+        const out: Record<string, unknown> = {}
+        for (const c of cols) out[c.field] = cellValueFor(c, r, rawValues)
+        return out
+      })
+      const widths = opts.autoFitColumns !== false ? autoFitWidths(cols, sheet.rows, rawValues) : null
+      return {
+        label: sheet.label,
+        dataSource,
+        columns: cols.map((c, i) =>
+          widths
+            ? { dataField: c.field, label: c.header ?? c.field, width: widths[i] }
+            : { dataField: c.field, label: c.header ?? c.field },
+        ),
+        dataFields: cols.map((c) => c.field),
+        style: translateStyles(sheet.styles ?? opts.styles),
+      }
+    })
+    const filename = (opts.filename ?? 'grid').trim() || 'grid'
+    const ctorOpts = buildExporterOptions(opts)
+    // Smart needs at least one main sheet to operate. Use the first sheet
+    // as the "main" exportData payload AND keep the full set on the
+    // `spreadsheets` property so the workbook ends up with one tab per
+    // entry.
+    const firstSheet = sheets[0]!
+    const exporter = new Ctor(ctorOpts)
+    exporter.spreadsheets = sheets
+    applyInstanceOptions(exporter, opts, firstSheet.dataFields)
+    // First sheet's data goes through the standard exportData path with
+    // its own header row.
+    const headerRow: Record<string, unknown> = {}
+    for (const c of firstSheet.columns) headerRow[c.dataField] = c.label
+    const firstSheetRows = [headerRow, ...firstSheet.dataSource]
+    if (opts.download === false) {
+      throw new Error('@svgrid/enterprise: download:false is not supported for multi-sheet xlsx.')
+    }
+    exporter.exportData(firstSheetRows, opts.format, filename)
+    return undefined
+  }
+
+  // Single-sheet xlsx (grouped / merges / header / footer) path.
+  const sourceRows = resolveRowSource(api, opts.rows)
+  if (sourceRows.length === 0) {
+    throw new Error('@svgrid/enterprise: nothing to export - the grid has no rows')
+  }
+  const cols = resolveColumns(api, opts, sourceRows)
+  const rows = await projectRows(sourceRows, cols, opts)
+  const filename = (opts.filename ?? 'grid').trim() || 'grid'
+  const datafields = cols.map((c) => c.field)
+
+  // Auto-carry the grid's active row grouping (unless the caller opted out,
+  // passed their own groupBy, or is exporting a hierarchy). Grouping column
+  // ids line up with field names, which are the projected row keys.
+  const autoGrouping =
+    opts.autoGroup !== false && !opts.groupBy?.length && !opts.hierarchical
+      ? (api.getState().grouping ?? []).filter((id) => !!id).map((id) => String(id))
+      : []
+  const effectiveGroupBy = opts.groupBy?.length
+    ? opts.groupBy
+    : autoGrouping.length > 0
+      ? autoGrouping
+      : undefined
+  // The constructor's SECOND arg is `groupBy`: when non-empty AND
+  // `hierarchical` is NOT set, Smart wraps each group of rows in an
+  // Excel outline row with an expand/collapse button at the group key.
+  const groupBy = !opts.hierarchical && effectiveGroupBy?.length ? effectiveGroupBy : undefined
+
+  // Conditional formatting -> a per-cell style map (A1 refs) that Smart's xlsx
+  // writer applies, plus icon-set glyphs prepended to the cell text.
+  const ctorOpts = buildExporterOptions(opts)
+  if (opts.conditionalFormats?.length) {
+    const visual = buildConditionalResolver(cols, sourceRows, opts.conditionalFormats)
+    const cfCells: Record<string, ExportCellStyle> = {}
+    for (let r = 0; r < sourceRows.length; r++) {
+      for (let c = 0; c < cols.length; c++) {
+        const v = visual(r, c)
+        if (!v) continue
+        const st: ExportCellStyle = {}
+        if (v.fill) st.backgroundColor = v.fill
+        if (v.color) st.color = v.color
+        if (v.bold) st.fontWeight = 'bold'
+        if (Object.keys(st).length) cfCells[colLetter(c) + (r + 2)] = st // header is row 1
+        if (v.icon) {
+          const dataRow = rows[r + 1] // header at index 0
+          const field = cols[c]!.field
+          if (dataRow) dataRow[field] = `${v.icon} ${dataRow[field] ?? ''}`
+        }
+      }
+    }
+    if (Object.keys(cfCells).length) {
+      const style = (ctorOpts.style as Record<string, unknown> | undefined) ?? {}
+      ctorOpts.style = {
+        ...style,
+        cells: { ...((style.cells as Record<string, unknown> | undefined) ?? {}), ...cfCells },
+      }
+    }
+  }
+
+  if (opts.download === false) {
+    throw new Error(
+      '@svgrid/enterprise: download:false is not supported for this xlsx export (grouped / merges / header / footer / images). Use a plain xlsx, xls, pdf, or a text format.',
+    )
+  }
+  if (opts.signal?.aborted) throw new DOMException('Export aborted', 'AbortError')
+  opts.onProgress?.({ phase: 'write', ratio: 0, total: rows.length - 1 })
+  const exporter = new Ctor(ctorOpts, groupBy)
+  applyInstanceOptions(exporter, opts, datafields)
+  exporter.exportData(rows, opts.format, filename)
+  opts.onProgress?.({ phase: 'write', ratio: 1, total: rows.length - 1 })
+  return undefined
+}
+
+/** Native formats that can be placed on the clipboard. */
+export type ClipboardFormat = 'csv' | 'tsv' | 'html' | 'json' | 'xml' | 'md'
+
+export type ClipboardExportOptions<TData> = {
+  /** Clipboard payload format. Default 'tsv' (pastes cleanly into Excel / Sheets). */
+  format?: ClipboardFormat
+  columns?: ReadonlyArray<ExportColumn<TData>>
+  rows?: ExportRowSource<TData>
+  rawValues?: boolean
+  csv?: CsvOptions
+  onProgress?: (progress: ExportProgress) => void
+  signal?: AbortSignal
+}
+
+/** Write text (and, for html, rich text/html) to the clipboard. */
+async function writeClipboard(text: string, format: ClipboardFormat): Promise<void> {
+  const nav = typeof navigator !== 'undefined' ? navigator : undefined
+  if (!nav?.clipboard) {
+    throw new Error('@svgrid/enterprise: clipboard is unavailable (needs a secure context + user gesture)')
+  }
+  // For html, offer BOTH text/html (rich paste into Excel / Sheets / Docs) and
+  // a text/plain fallback. ClipboardItem may be missing in older browsers.
+  const CI = (globalThis as { ClipboardItem?: typeof ClipboardItem }).ClipboardItem
+  if (format === 'html' && CI && nav.clipboard.write) {
+    const item = new CI({
+      'text/html': new Blob([text], { type: 'text/html' }),
+      'text/plain': new Blob([text], { type: 'text/plain' }),
+    })
+    await nav.clipboard.write([item])
+    return
+  }
+  await nav.clipboard.writeText(text)
+}
+
+/**
+ * Copy the grid (current view / selection / all) to the clipboard in a native
+ * text format instead of downloading a file. Defaults to `tsv`, which pastes
+ * straight into Excel / Google Sheets as real columns. `html` writes rich
+ * `text/html` so pasted cells keep their table structure.
+ */
+export async function copyExportToClipboard<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(api: SvGridApi<TFeatures, TData>, opts: ClipboardExportOptions<TData> = {}): Promise<void> {
+  assertEnterpriseLicensed('Export')
+  const format: ClipboardFormat = opts.format ?? 'tsv'
+  const sourceRows = resolveRowSource(api, opts.rows)
+  if (sourceRows.length === 0) {
+    throw new Error('@svgrid/enterprise: nothing to copy - the grid has no rows')
+  }
+  const cols = resolveColumns(api, opts, sourceRows)
+  const projectOpts =
+    format === 'json' ? { ...opts, rawValues: opts.rawValues ?? true } : opts
+  const projected = await projectRows(sourceRows, cols, projectOpts)
+  const { text } = await serializeNative(format, projected, cols, opts)
+  await writeClipboard(text, format)
+}