@xeplr/actions 1.1.18 → 1.1.19

package/README.md

@@ -107,6 +107,8 @@ Register the ones you want (`register(actions.builtins.dbFetch)`) or pass a modu
 | key | action name | does |
 |---|---|---|
 | `dataOperation` | `data-operation` | From a list of rows, make the list the next step needs — keep some rows, pick and rename columns, compute new ones, sort, optionally render. See [Data operation](#data-operation). |
+| `exportTable` | `export-table` | Rows to a **CSV, Excel (.xlsx) or PDF** file. See [Export](#export). |
+| `exportPages` | `export-pages` | Pages of placed blocks (text, tables, images, shapes) to a PDF — a dashboard as it looked. See [Export](#export). |
 | `dbFetch` | `db-fetch` | Stream rows from a table (`mode: 'table'`) or SQL (`mode: 'query'`, `params`). Default `streaming_mode: true` → NDJSON file `{ filePath, format: 'jsonl', bytes, rows }`; `false` → `{ rows, rowCount }`. |
 | `dbPush` | `db-push` | Write `rows` or an NDJSON `filePath` into `targetTable` through the uploader. `primaryKeys` → upsert. |
 | `dbMove` | `db-move` | One window of rows from a source table, query or procedure into a target table in one streamed pass. See [db-move](#db-move). |
@@ -220,6 +222,48 @@ should not take the other eight hundred and ninety-nine with it.
 **No aggregation.** `group by status, count` changes what a row *is*; that is
 a different shape and, when it is wanted, a different step.
 
+## Export
+
+`export-table` writes rows that arrive **already presented**: which columns, in what order, under what heading, and for each cell its raw value and the text a reader saw. The action knows nothing of reports or pivots; the caller decides all that (in xeplr-bi, `report-engine`'s `presentTable` does). Each format takes what it needs:
+
+| format | writes | from |
+|---|---|---|
+| `csv` | RFC 4180; a UTF-8 byte-order mark so Excel reads `₹` and accents; a text cell starting with `= + - @` gets a leading `'` (no formula injection; numbers untouched) | `values` |
+| `xlsx` | numbers and dates as **real typed cells carrying the column's Excel number format** (`"₹"#,##0.00`, `0.0%`, `mmm yyyy`, `#,##0.0,,"M"`), so the sheet looks like the screen and still sums; an optional title and subtitle; a bold, frozen header with an autofilter; bold subtotals and a tinted total row; column widths from the first 200 rows. Excel's 1,048,576-row limit is respected (`truncated`) | `values` |
+| `pdf` | each cell exactly as displayed, numbers right-aligned by `align`, header repeated on every page, landscape past 6 columns, "Page x of y", bold or tinted total rows. Capped at 5,000 rows (`maxRows`) with a closing note | `display` |
+
+```js
+await runAction(builtins.exportTable, {
+  format: 'xlsx',
+  document: {
+    title: 'Sales by region', subtitle: 'Date: Current financial year',
+    columns: [
+      { header: 'Region' },
+      { header: 'Month', kind: 'date', numFmt: 'mmm yyyy' },
+      { header: 'Revenue', kind: 'number', numFmt: '"₹"#,##0.00', align: 'right' }
+    ]
+  },
+  rows: [{ values: ['North', '2024-01-01', 1234.5], display: ['North', 'Jan 2024', '₹1,234.50'], kind: 'detail' }]
+  // or rowsFile: an NDJSON file, one row per line — streamed, never held
+})
+// → { filePath, fileName, contentType, bytes, rows, truncated }
+```
+
+- **Streaming.** CSV and Excel stream rows to disk, from `rows` or from `rowsFile` (NDJSON, one row per line, as `streaming.spool` writes it); 200,000 rows to xlsx take about 2 s in flat memory. Our own xlsx writer runs on `fflate`. `exceljs` was rejected: it pulls a `uuid` with a published advisory and has had no release since December 2024.
+- **Fonts.** pdfkit's built-in fonts cannot draw `₹` or non-Latin text; a missing glyph draws as nothing. The PDF embeds **DejaVu Sans Condensed** (the `dejavu-fonts-ttf` peer). Pass `document.font` / `boldFont` (TTF/OTF paths) for scripts it lacks. Only the glyphs used are embedded.
+- **Output** goes to `outputPath`, or to a new directory under `XEPLR_ACTIONS_TMP_DIR` with a file named after the title. A failed export leaves no half-written file.
+
+`export-pages` lays out `pages: [{ blocks }]`, each block positioned by **fractions** of the page's content box (A4 landscape by default):
+- `text` (`text`, `size`, `bold`, `color`, `align`)
+- `table` (`title`, `columns`, `rows`; drawn inside its box, and rows that don't fit are counted as "+N more rows")
+- `image` (`src` must be a **PNG or JPEG data URL**: no fetching, no SVG, no markup)
+- `rect` (`fill`, `stroke`, `radius`)
+- `line`
+
+What it is given is assumed to come from a browser, so it is bounded: 50 pages, 200 blocks a page, 8 MB per image, 500 table rows, and 5,000 characters of text. An image that will not decode draws a note in its box instead of failing the whole file.
+
+Peers (optional, needed only by the format used): `fflate` for xlsx; `pdfkit` and `dejavu-fonts-ttf` for pdf. `writers` (`getWriter`, `INFO`, `SUPPORTED`) is exported for code that wants a writer without the action.
+
 ## Uploader
 
 `uploader.upload(opts)` is what `db-push`, `db-move` and `file-upload` use:

package/index.js

@@ -41,6 +41,8 @@ module.exports = {
   streaming:     streaming,
   drivers:       { db: dbDrivers, file: fileDrivers },
   formats:       formats,
+  // { getWriter(type), INFO, SUPPORTED } — csv / xlsx / pdf writers behind export-table.
+  writers:       require('./lib/formats/writers'),
 
   // xeplr_configs — shared control-plane DB (import/movement metadata).
   // One call per app: attachConfig({ service }); await xcfg.ready(). See

package/lib/builtins/export/pages.js

@@ -0,0 +1,92 @@
+// export-pages — placed blocks to a PDF: a dashboard as it looked.
+//
+// Each page is a list of blocks positioned by FRACTIONS of the page's content
+// box (x, w across; y, h down), so a layout drawn on any screen keeps its
+// proportions on paper. A block is text, a small table, an image (a PNG or
+// JPEG data URL — a chart is captured as one), a rectangle or a line. See
+// lib/formats/writers/pdf.js renderPages for each block's fields.
+//
+// Bounded on purpose: what arrives here was posted by a browser, so the page,
+// block and image counts and sizes are capped and an image must be a data URL
+// of a raster type — no fetching, no markup.
+
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+var pdf = require('../../formats/writers/pdf');
+var { checkFormatRequires } = require('../../formats');
+
+var LIMITS = { pages: 50, blocksPerPage: 200, imageBytes: 8 * 1024 * 1024, tableRows: 500, text: 5000 };
+var TYPES = ['text', 'table', 'image', 'rect', 'line'];
+
+function fail(message) {
+  var err = new Error(message);
+  err.status = 400;
+  return err;
+}
+
+function fraction(n) { return typeof n === 'number' && isFinite(n) && n >= -0.01 && n <= 50; }
+
+/** Throws (400) naming the first block that is not one this action draws. */
+function validate(spec) {
+  var pages = spec.pages;
+  if (!Array.isArray(pages) || !pages.length) throw fail('pages must list at least one page');
+  if (pages.length > LIMITS.pages) throw fail('At most ' + LIMITS.pages + ' pages');
+  pages.forEach(function(page, p) {
+    var blocks = (page && page.blocks) || [];
+    if (!Array.isArray(blocks)) throw fail('pages[' + p + '].blocks must be a list');
+    if (blocks.length > LIMITS.blocksPerPage) throw fail('At most ' + LIMITS.blocksPerPage + ' blocks on a page');
+    blocks.forEach(function(b, i) {
+      var where = 'pages[' + p + '].blocks[' + i + ']';
+      if (!b || TYPES.indexOf(b.type) === -1) throw fail(where + ': type must be one of ' + TYPES.join(', '));
+      if (![b.x, b.y, b.w, b.h].every(fraction)) throw fail(where + ': x, y, w and h are fractions of the page');
+      if (b.type === 'image') {
+        var src = String(b.src || '');
+        if (!/^data:image\/(png|jpe?g);base64,[A-Za-z0-9+/=]+$/.test(src)) throw fail(where + ': src must be a PNG or JPEG data URL');
+        if (src.length * 0.75 > LIMITS.imageBytes) throw fail(where + ': image is larger than ' + (LIMITS.imageBytes >> 20) + ' MB');
+      }
+      if (b.type === 'table') {
+        if (!Array.isArray(b.columns) || !Array.isArray(b.rows)) throw fail(where + ': a table needs columns and rows');
+        if (b.rows.length > LIMITS.tableRows) b.rows = b.rows.slice(0, LIMITS.tableRows);
+      }
+      if (b.type === 'text' && String(b.text == null ? '' : b.text).length > LIMITS.text) b.text = String(b.text).slice(0, LIMITS.text);
+    });
+  });
+}
+
+module.exports = {
+  name: 'export-pages',
+  description: 'Lay out pages of placed blocks (text, tables, images, shapes) as a PDF — a dashboard as it looked.',
+  requires: [],
+  LIMITS: LIMITS,
+
+  inputSchema: [
+    { name: 'pages', type: 'array', required: true, order: 1,
+      description: '[{ blocks: [{ type: text|table|image|rect|line, x, y, w, h, … }] }], positions as fractions of the page.' },
+    { name: 'title', type: 'string', order: 2 },
+    { name: 'footer', type: 'string', order: 3 },
+    { name: 'landscape', type: 'boolean', order: 4, description: 'Default true.' },
+    { name: 'outputPath', type: 'string', order: 5 }
+  ],
+  outputSchema: [
+    { name: 'filePath', type: 'string' }, { name: 'fileName', type: 'string' },
+    { name: 'contentType', type: 'string' }, { name: 'bytes', type: 'number' }, { name: 'pages', type: 'number' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    checkFormatRequires('export-pages', 'pdf', pdf);
+    validate(input);
+    var name = (String(input.title || 'dashboard').replace(/[\\/:*?"<>|\u0000-\u001F]+/g, ' ').trim().slice(0, 80) || 'dashboard') + '.pdf';
+    var dir = process.env.XEPLR_ACTIONS_TMP_DIR || path.join(os.tmpdir(), 'xeplr-actions');
+    fs.mkdirSync(dir, { recursive: true });
+    var filePath = input.outputPath || path.join(fs.mkdtempSync(path.join(dir, 'export-')), name);
+    var done = await pdf.renderPages(filePath, {
+      pages: input.pages, title: input.title, footer: input.footer, landscape: input.landscape !== false
+    });
+    return {
+      filePath: filePath, fileName: path.basename(filePath), contentType: 'application/pdf',
+      bytes: fs.statSync(filePath).size, pages: done.pages
+    };
+  }
+};

package/lib/builtins/export/table.js

@@ -0,0 +1,116 @@
+// export-table — rows to a CSV, Excel or PDF file.
+//
+// The rows arrive already DECIDED: which columns, in what order, under what
+// heading, and for each cell both its raw value and the text a reader saw.
+// This action does not know what a report or a pivot is; whoever calls it
+// worked that out (in BI, report-engine's presentTable). Each format takes
+// what it needs from a row:
+//
+//   csv   the raw values, unformatted — a file for another program
+//   xlsx  the raw values as TYPED cells carrying each column's number format,
+//         so the sheet looks like the screen and still sums
+//   pdf   the display text, exactly as shown
+//
+// Rows come inline (`rows`) or from an NDJSON file (`rowsFile`, one row per
+// line — what streaming/spool writes), so a large result never has to be one
+// array in memory. CSV and Excel stream; a PDF holds its rows (capped, 5,000 by
+// default) because a page is laid out from them.
+
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+var readline = require('readline');
+var writers = require('../../formats/writers');
+var { checkFormatRequires } = require('../../formats');
+
+function tmpDir() {
+  var dir = process.env.XEPLR_ACTIONS_TMP_DIR || path.join(os.tmpdir(), 'xeplr-actions');
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/** A file name from a title: what a person would recognise in their downloads. */
+function fileNameFor(title, extension) {
+  var base = String(title || 'export').replace(/[\\/:*?"<>|\u0000-\u001F]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 80) || 'export';
+  return base + '.' + extension;
+}
+
+async function* rowsFrom(input) {
+  if (Array.isArray(input.rows)) { for (var i = 0; i < input.rows.length; i++) yield input.rows[i]; return; }
+  var lines = readline.createInterface({ input: fs.createReadStream(input.rowsFile), crlfDelay: Infinity });
+  for await (var line of lines) if (line.trim()) yield JSON.parse(line);
+}
+
+module.exports = {
+  name: 'export-table',
+  description: 'Write rows to a CSV, Excel (.xlsx) or PDF file. Excel cells stay numbers with their number format; ' +
+               'a PDF shows each cell as it was displayed.',
+  requires: [],
+
+  inputSchema: [
+    { name: 'format', type: 'string', required: true, order: 1, enum: writers.SUPPORTED,
+      description: 'csv, xlsx or pdf.' },
+    { name: 'document', type: 'object', required: true, order: 2,
+      description: '{ title?, subtitle?, footer?, columns: [{ header, kind?: number|date|text, numFmt?, align?, width? }] }. ' +
+                   'numFmt is an Excel number format ("#,##0.00", "0.0%", "mmm yyyy").' },
+    { name: 'rows', type: 'array', order: 3,
+      description: 'Rows: { values: [], display?: [], kind?: detail|subtotal|total }. Or give rowsFile.' },
+    { name: 'rowsFile', type: 'string', order: 4,
+      description: 'An NDJSON file with one row per line, instead of rows.' },
+    { name: 'outputPath', type: 'string', order: 5,
+      description: 'Where to write. Default: a new file in XEPLR_ACTIONS_TMP_DIR named after the title.' },
+    { name: 'maxRows', type: 'number', order: 6,
+      description: 'PDF only: rows to draw before stopping with a note (default 5,000).' }
+  ],
+  outputSchema: [
+    { name: 'filePath', type: 'string' }, { name: 'fileName', type: 'string' },
+    { name: 'contentType', type: 'string' }, { name: 'bytes', type: 'number' },
+    { name: 'rows', type: 'number' }, { name: 'truncated', type: 'boolean' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var format = String(input.format || '').toLowerCase();
+    var writer = writers.getWriter(format);
+    checkFormatRequires('export-table', format, writer);
+    var doc = Object.assign({}, input.document || {});
+    if (!Array.isArray(doc.columns) || !doc.columns.length) {
+      var bad = new Error('document.columns must list at least one column');
+      bad.status = 400;
+      throw bad;
+    }
+    if (!Array.isArray(input.rows) && !input.rowsFile) {
+      var none = new Error('Give rows, or a rowsFile');
+      none.status = 400;
+      throw none;
+    }
+    if (format === 'pdf' && input.maxRows) doc.maxRows = input.maxRows;
+
+    var info = writers.INFO[format];
+    var fileName = fileNameFor(doc.title, info.extension);
+    var filePath = input.outputPath || path.join(fs.mkdtempSync(path.join(tmpDir(), 'export-')), fileName);
+    var open = writer.open(filePath, doc);
+    var signal = ctx.signal;
+    try {
+      for await (var row of rowsFrom(input)) {
+        if (signal && signal.aborted) throw new Error('Stopped by request');
+        var more = await open.writeRow(row);
+        // Excel's own limit: the rest are only counted. A PDF keeps counting
+        // too, so its closing note can say how many were left out.
+        if (more === false && format === 'xlsx') { /* keep reading to count */ }
+      }
+      var done = await open.close();
+      return {
+        filePath: filePath,
+        fileName: path.basename(filePath),
+        contentType: info.contentType,
+        bytes: fs.statSync(filePath).size,
+        rows: done.rows,
+        truncated: done.truncated
+      };
+    } catch (err) {
+      try { fs.rmSync(filePath, { force: true }); } catch (e) { /* nothing to clean */ }
+      throw err;
+    }
+  }
+};

package/lib/builtins/index.js

@@ -61,5 +61,12 @@ module.exports = {
   emailMove:                require('./email/move'),
   emailDelete:              require('./email/delete'),
   emailDownloadEmail:       require('./email/download-email'),
-  emailDownloadAttachments: require('./email/download-attachments')
+  emailDownloadAttachments: require('./email/download-attachments'),
+
+  // Export — rows to CSV / Excel / PDF, and placed blocks to a PDF. The rows
+  // arrive already presented (columns, headings, raw values and display
+  // text); see export/table.js. Peers: fflate (xlsx), pdfkit and
+  // dejavu-fonts-ttf (pdf) — optional, required only by the format used.
+  exportTable:              require('./export/table'),
+  exportPages:              require('./export/pages')
 };

package/lib/formats/index.js

@@ -21,8 +21,10 @@ function getFormat(type) {
 function checkFormatRequires(actionName, format, mod) {
   var requires = (mod && mod.requires) || [];
   for (var i = 0; i < requires.length; i++) {
+    // A package of data files (a font) has no main to resolve; its
+    // package.json says it is installed just as well.
     try { require.resolve(requires[i]); }
-    catch (_) {
+    catch (_) { try { require.resolve(requires[i] + '/package.json'); continue; } catch (__) { /* missing — fall through */ }
       throw new Error(
         actionName + ' requires "' + requires[i] + '" for format="' + format + '". ' +
         'Install with: npm install ' + requires[i]

package/lib/formats/writers/csv.js

@@ -0,0 +1,78 @@
+// CSV writer — the raw values, nothing formatted.
+//
+// RFC 4180: a field is quoted when it holds the delimiter, a quote, or a line
+// break, and a quote inside is doubled. A UTF-8 byte order mark leads the
+// file: without it Excel on Windows reads the file as the system code page
+// and "₹" or "São Paulo" arrive as mojibake. Every other reader ignores it.
+//
+// A Date is written as ISO 8601 (YYYY-MM-DD when it is a whole UTC day), a
+// boolean as true/false, null as an empty field.
+//
+// A field that would start with = + - @ (or a tab / carriage return) is
+// prefixed with an apostrophe when `safe` is on (default): opened in a
+// spreadsheet, such a cell is a FORMULA, and a value somebody typed into a
+// source system would run on the reader's machine (CSV injection). Off for a
+// file meant for another program rather than a person.
+
+var fs = require('fs');
+
+function isoOf(d) {
+  if (isNaN(d.getTime())) return '';
+  var iso = d.toISOString();
+  return iso.slice(10) === 'T00:00:00.000Z' ? iso.slice(0, 10) : iso;
+}
+
+module.exports = {
+  requires: [],
+
+  /**
+   * @param {string} filePath
+   * @param {object} doc - { columns: [{ header }], delimiter?: ',', safe?: true }
+   * @returns {{ writeRow(row): Promise<boolean>, close(): Promise<{ rows, truncated }> }}
+   */
+  open: function(filePath, doc) {
+    var delimiter = doc.delimiter || ',';
+    var safe = doc.safe !== false;
+    var out = fs.createWriteStream(filePath);
+    var failed = null;
+    out.on('error', function(err) { failed = err; });
+    var rows = 0;
+    var buffered = '';
+
+    function field(value) {
+      if (value === null || value === undefined) return '';
+      var text = value instanceof Date ? isoOf(value) : String(value);
+      if (safe && typeof value === 'string' && /^[=+\-@\t\r]/.test(text)) text = "'" + text;
+      if (text.indexOf(delimiter) !== -1 || /["\r\n]/.test(text)) text = '"' + text.replace(/"/g, '""') + '"';
+      return text;
+    }
+    function line(values) { return values.map(field).join(delimiter) + '\r\n'; }
+
+    async function push(text, final) {
+      buffered += text;
+      if (buffered.length < 1 << 20 && !final) return;
+      var chunk = buffered;
+      buffered = '';
+      if (failed) throw failed;
+      if (!out.write(chunk)) await new Promise(function(r) { out.once('drain', r); });
+    }
+
+    var started = push('' + line((doc.columns || []).map(function(c) { return c.header == null ? '' : c.header; })));
+
+    return {
+      writeRow: async function(row) {
+        await started;
+        rows += 1;
+        await push(line(row.values || []));
+        return true;
+      },
+      close: async function() {
+        await started;
+        await push('', true);
+        await new Promise(function(resolve, reject) { out.end(function(err) { return err ? reject(err) : resolve(); }); });
+        if (failed) throw failed;
+        return { rows: rows, truncated: false };
+      }
+    };
+  }
+};

package/lib/formats/writers/index.js

@@ -0,0 +1,23 @@
+// File WRITERS — the other direction from the parsers beside this folder.
+// Each is { requires, open(filePath, doc) → { writeRow(row), close() } }.
+// The PDF writer also lays out placed blocks (renderPages).
+
+var WRITERS = {
+  csv:  function() { return require('./csv'); },
+  xlsx: function() { return require('./xlsx'); },
+  pdf:  function() { return require('./pdf'); }
+};
+
+var INFO = {
+  csv:  { extension: 'csv',  contentType: 'text/csv; charset=utf-8' },
+  xlsx: { extension: 'xlsx', contentType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' },
+  pdf:  { extension: 'pdf',  contentType: 'application/pdf' }
+};
+
+function getWriter(type) {
+  var loader = WRITERS[type];
+  if (!loader) throw new Error('Unknown export format: "' + type + '". Supported: ' + Object.keys(WRITERS).join(', '));
+  return loader();
+}
+
+module.exports = { getWriter: getWriter, INFO: INFO, SUPPORTED: Object.keys(WRITERS) };

package/lib/formats/writers/pdf.js

@@ -0,0 +1,293 @@
+// PDF writer, on pdfkit — a table as the reader saw it, or a page of placed
+// blocks (a dashboard as it looked).
+//
+// Text is drawn from each cell's DISPLAY string: a PDF is for reading, so it
+// shows exactly what the screen did ("₹1,234.50", "Jan 2024"), not the raw
+// value. Numbers are right-aligned by the column's own `align`.
+//
+// FONT: pdfkit's built-in fonts are WinAnsi only — no "₹", no Devanagari, no
+// CJK — and a missing glyph draws as nothing at all. DejaVu Sans Condensed
+// (the `dejavu-fonts-ttf` peer) covers Latin, Greek, Cyrillic, the currency
+// signs and box drawing, and is narrow enough for a table. Pass `font` /
+// `boldFont` (paths to TTF/OTF) for scripts it lacks. Only the glyphs used
+// are embedded, so the file stays small.
+
+var fs = require('fs');
+var path = require('path');
+
+var MAX_TABLE_ROWS = 5000;
+var COLORS = { text: '#1c2029', muted: '#6b7280', headerFill: '#f1f3f7', totalFill: '#e8ebf2', rule: '#9aa1ae', grid: '#e2e5eb' };
+
+function fontPaths(opts) {
+  if (opts.font) return { body: opts.font, bold: opts.boldFont || opts.font };
+  var dir = path.join(path.dirname(require.resolve('dejavu-fonts-ttf/package.json')), 'ttf');
+  return { body: path.join(dir, 'DejaVuSansCondensed.ttf'), bold: path.join(dir, 'DejaVuSansCondensed-Bold.ttf') };
+}
+
+function newDocument(filePath, opts) {
+  var PDFDocument = require('pdfkit');
+  var doc = new PDFDocument({
+    size: opts.size || 'A4',
+    layout: opts.landscape ? 'landscape' : 'portrait',
+    margins: { top: 36, bottom: 36, left: 32, right: 32 },
+    bufferPages: true,
+    info: { Title: opts.title || 'Export', Producer: '@xeplr/actions' }
+  });
+  var fonts = fontPaths(opts);
+  doc.registerFont('body', fonts.body);
+  doc.registerFont('bold', fonts.bold);
+  doc.font('body');
+  var out = fs.createWriteStream(filePath);
+  var finished = new Promise(function(resolve, reject) { out.on('finish', resolve); out.on('error', reject); doc.on('error', reject); });
+  // Observed now, awaited later: a render that throws part-way never awaits
+  // it, and its rejection must not surface as an unhandled one.
+  finished.catch(function() {});
+  doc.pipe(out);
+  return {
+    doc: doc,
+    finished: finished,
+    /** A render that failed: close the stream and leave no half a file. */
+    abandon: function() {
+      try { doc.unpipe(out); } catch (e) { /* not piped */ }
+      out.destroy();
+      try { fs.rmSync(filePath, { force: true }); } catch (e) { /* already gone */ }
+    }
+  };
+}
+
+/** "Page 3 of 12" on every page, written once the page count is known. */
+function stampPages(doc, footer) {
+  var range = doc.bufferedPageRange();
+  for (var i = range.start; i < range.start + range.count; i++) {
+    doc.switchToPage(i);
+    var bottom = doc.page.height - 24;
+    // A footer drawn below the bottom margin would otherwise open a new page.
+    var saved = doc.page.margins.bottom;
+    doc.page.margins.bottom = 0;
+    doc.font('body').fontSize(7.5).fillColor(COLORS.muted);
+    if (footer) doc.text(footer, doc.page.margins.left, bottom, { lineBreak: false });
+    doc.text('Page ' + (i - range.start + 1) + ' of ' + range.count, doc.page.margins.left, bottom,
+      { width: doc.page.width - doc.page.margins.left - doc.page.margins.right, align: 'right', lineBreak: false });
+    doc.page.margins.bottom = saved;
+  }
+}
+
+/**
+ * Column widths for a table drawn `width` points wide: each column as wide as
+ * its header and its widest sampled value, then scaled to fill the width —
+ * shrinking the font first when the natural widths do not fit, so a wide
+ * table still reads rather than truncating every cell.
+ */
+function layoutColumns(doc, columns, sampleRows, width, baseSize) {
+  var size = baseSize;
+  var natural;
+  for (;;) {
+    natural = columns.map(function(c, i) {
+      doc.font('bold').fontSize(size);
+      var w = doc.widthOfString(String(c.header == null ? '' : c.header));
+      doc.font('body').fontSize(size);
+      sampleRows.forEach(function(r) {
+        var t = cellText(r, i);
+        if (t) w = Math.max(w, doc.widthOfString(t));
+      });
+      return Math.min(w, width * 0.45) + size * 1.2;
+    });
+    var total = natural.reduce(function(a, b) { return a + b; }, 0);
+    if (total <= width || size <= 6) break;
+    size = Math.max(6, size - 0.5);
+  }
+  var sum = natural.reduce(function(a, b) { return a + b; }, 0) || 1;
+  return { size: size, widths: natural.map(function(w) { return w * width / sum; }) };
+}
+
+function cellText(row, i) {
+  var v = row.display ? row.display[i] : (row.values || [])[i];
+  return v === null || v === undefined ? '' : String(v);
+}
+
+/**
+ * Draws a header and rows into a box. Paged: when `paged`, a row that would
+ * cross the bottom opens a new page and repeats the header; otherwise rows
+ * stop at the box and the rest are counted.
+ * @returns {{ drawn, hidden }}
+ */
+function drawTable(doc, box, columns, rows, opts) {
+  var layout = layoutColumns(doc, columns, rows.slice(0, 300), box.w, opts.fontSize || 8.5);
+  var size = layout.size;
+  var rowH = size * 1.95;
+  var pad = size * 0.6;
+  var y = box.y;
+  var bottom = box.y + box.h;
+
+  function drawRow(cells, look) {
+    var x = box.x;
+    if (look.fill) doc.rect(box.x, y, box.w, rowH).fill(look.fill);
+    if (look.rule) doc.moveTo(box.x, y).lineTo(box.x + box.w, y).lineWidth(0.8).strokeColor(COLORS.rule).stroke();
+    doc.font(look.bold ? 'bold' : 'body').fontSize(size).fillColor(COLORS.text);
+    for (var i = 0; i < columns.length; i++) {
+      var w = layout.widths[i];
+      var align = columns[i].align === 'right' || columns[i].align === 'center' ? columns[i].align : 'left';
+      doc.text(cells[i], x + pad / 2, y + (rowH - size) / 2 - 1, { width: Math.max(1, w - pad), align: align, lineBreak: false, ellipsis: true, height: rowH });
+      x += w;
+    }
+    if (!look.fill && !look.rule) doc.moveTo(box.x, y + rowH).lineTo(box.x + box.w, y + rowH).lineWidth(0.4).strokeColor(COLORS.grid).stroke();
+    y += rowH;
+  }
+  function header() {
+    drawRow(columns.map(function(c) { return c.header == null ? '' : String(c.header); }), { bold: true, fill: COLORS.headerFill });
+  }
+
+  header();
+  var drawn = 0;
+  for (var r = 0; r < rows.length; r++) {
+    if (y + rowH > bottom) {
+      if (!opts.paged) break;
+      doc.addPage();
+      y = doc.page.margins.top;
+      bottom = doc.page.height - doc.page.margins.bottom - 14;
+      header();
+    }
+    var kind = rows[r].kind;
+    drawRow(columns.map(function(c, i) { return cellText(rows[r], i); }),
+      kind === 'total' ? { bold: true, fill: COLORS.totalFill, rule: true } : kind === 'subtotal' ? { bold: true } : {});
+    drawn += 1;
+  }
+  return { drawn: drawn, hidden: rows.length - drawn, endY: y };
+}
+
+module.exports = {
+  requires: ['pdfkit', 'dejavu-fonts-ttf'],
+  MAX_TABLE_ROWS: MAX_TABLE_ROWS,
+
+  /**
+   * A table, paged. Rows are held until close (pdfkit lays out page by page,
+   * and the column widths need a look at the rows), so the row cap matters:
+   * a PDF is for reading, and 5,000 rows is already a hundred pages.
+   *
+   * @param {object} doc - { title?, subtitle?, footer?, columns: [{ header, align? }], maxRows?, font?, boldFont? }
+   */
+  open: function(filePath, doc) {
+    var columns = doc.columns || [];
+    var cap = doc.maxRows || MAX_TABLE_ROWS;
+    var rows = [];
+    var offered = 0;
+    return {
+      writeRow: async function(row) {
+        offered += 1;
+        if (rows.length >= cap) return false;
+        rows.push(row);
+        return true;
+      },
+      close: async function() {
+        var made = newDocument(filePath, { title: doc.title, landscape: columns.length > 6, font: doc.font, boldFont: doc.boldFont });
+        var pdf = made.doc;
+        try {
+        var left = pdf.page.margins.left;
+        var width = pdf.page.width - left - pdf.page.margins.right;
+        var y = pdf.page.margins.top;
+        if (doc.title) { pdf.font('bold').fontSize(14).fillColor(COLORS.text).text(doc.title, left, y, { width: width }); y = pdf.y + 2; }
+        if (doc.subtitle) { pdf.font('body').fontSize(8.5).fillColor(COLORS.muted).text(doc.subtitle, left, y, { width: width }); y = pdf.y; }
+        if (doc.title || doc.subtitle) y += 8;
+        var result = drawTable(pdf, { x: left, y: y, w: width, h: pdf.page.height - pdf.page.margins.bottom - 14 - y }, columns, rows, { paged: true });
+        if (offered > rows.length) {
+          var noteY = result.endY + 6;
+          if (noteY + 12 > pdf.page.height - pdf.page.margins.bottom - 14) { pdf.addPage(); noteY = pdf.page.margins.top; }
+          pdf.font('body').fontSize(8).fillColor(COLORS.muted).text('Showing the first ' + rows.length.toLocaleString('en-US') + ' of ' +
+            offered.toLocaleString('en-US') + ' rows. Export to Excel or CSV for all of them.', left, noteY, { width: width });
+        }
+        stampPages(pdf, doc.footer);
+        } catch (err) {
+          made.abandon();
+          throw err;
+        }
+        pdf.end();
+        await made.finished;
+        return { rows: rows.length, truncated: offered > rows.length };
+      }
+    };
+  },
+
+  /**
+   * Pages of placed blocks — a dashboard as it looked. Every position is a
+   * FRACTION of the page's content box, so the layout keeps its proportions
+   * on any paper size.
+   *
+   * blocks:
+   *   { type: 'text', x, y, w, h, text, size? | sizeRel?, bold?, color?, align? }  — sizeRel: a fraction of the page width
+   *   { type: 'table', x, y, w, h, title?, columns, rows }  — no paging; rows past the box are counted
+   *   { type: 'image', x, y, w, h, src }                     — a data: URL, PNG or JPEG only
+   *   { type: 'rect', x, y, w, h, fill?, stroke?, strokeWidth?, radius? }
+   *   { type: 'line', x, y, w, h, stroke?, strokeWidth? }    — from (x,y) to (x+w,y+h)
+   *
+   * @param {object} spec - { pages: [{ blocks }], title?, footer?, landscape?: true, font?, boldFont? }
+   */
+  renderPages: async function(filePath, spec) {
+    var made = newDocument(filePath, { title: spec.title, landscape: spec.landscape !== false, font: spec.font, boldFont: spec.boldFont });
+    var pdf = made.doc;
+    var pages = spec.pages && spec.pages.length ? spec.pages : [{ blocks: [] }];
+    try {
+    var counts = { blocks: 0, hiddenRows: 0, badImages: 0 };
+    pages.forEach(function(page, p) {
+      if (p > 0) pdf.addPage();
+      var m = pdf.page.margins;
+      var box = { x: m.left, y: m.top, w: pdf.page.width - m.left - m.right, h: pdf.page.height - m.top - m.bottom - 14 };
+      if (p === 0 && spec.title) {
+        pdf.font('bold').fontSize(13).fillColor(COLORS.text).text(spec.title, box.x, box.y, { width: box.w, lineBreak: false });
+        var used = pdf.y - box.y + 6;
+        box = { x: box.x, y: box.y + used, w: box.w, h: box.h - used };
+      }
+      (page.blocks || []).forEach(function(b) {
+        counts.blocks += 1;
+        var at = { x: box.x + b.x * box.w, y: box.y + b.y * box.h, w: b.w * box.w, h: b.h * box.h };
+        pdf.save();
+        pdf.rect(at.x, at.y, at.w, at.h).clip();
+        if (b.type === 'rect') {
+          var shape = b.radius ? pdf.roundedRect(at.x, at.y, at.w, at.h, b.radius) : pdf.rect(at.x, at.y, at.w, at.h);
+          if (b.fill && b.stroke) shape.lineWidth(b.strokeWidth || 1).fillAndStroke(b.fill, b.stroke);
+          else if (b.fill) shape.fill(b.fill);
+          else if (b.stroke) shape.lineWidth(b.strokeWidth || 1).stroke(b.stroke);
+        } else if (b.type === 'line') {
+          pdf.restore(); pdf.save();   // a line is not clipped to its own (often zero-height) box
+          pdf.moveTo(at.x, at.y).lineTo(at.x + at.w, at.y + at.h).lineWidth(b.strokeWidth || 1).strokeColor(b.stroke || COLORS.rule).stroke();
+        } else if (b.type === 'image') {
+          var match = /^data:image\/(png|jpe?g);base64,([A-Za-z0-9+/=]+)$/.exec(String(b.src || ''));
+          // One chart that would not capture must not sink the whole board:
+          // its box says so and the rest is drawn.
+          try {
+            if (match) pdf.image(Buffer.from(match[2], 'base64'), at.x, at.y, { fit: [at.w, at.h], align: 'center', valign: 'center' });
+          } catch (err) {
+            counts.badImages += 1;
+            pdf.font('body').fontSize(8).fillColor(COLORS.muted).text('This chart could not be drawn', at.x, at.y + at.h / 2 - 4, { width: at.w, align: 'center', lineBreak: false });
+          }
+        } else if (b.type === 'table') {
+          var top = at.y;
+          if (b.title) {
+            pdf.font('bold').fontSize(9).fillColor(COLORS.text).text(b.title, at.x, at.y, { width: at.w, lineBreak: false, ellipsis: true });
+            top = at.y + 14;
+          }
+          var drawn = drawTable(pdf, { x: at.x, y: top, w: at.w, h: at.y + at.h - top }, b.columns || [], b.rows || [], { paged: false, fontSize: 7.5 });
+          counts.hiddenRows += drawn.hidden;
+          if (drawn.hidden > 0) {
+            pdf.font('body').fontSize(7).fillColor(COLORS.muted)
+              .text('+' + drawn.hidden.toLocaleString('en-US') + ' more rows', at.x, at.y + at.h - 9, { width: at.w, align: 'right', lineBreak: false });
+          }
+        } else if (b.type === 'text') {
+          // sizeRel: a fraction of the page width — how a screen's text keeps
+          // its proportion on paper of another width.
+          var size = b.sizeRel ? Math.max(5, Math.min(72, b.sizeRel * box.w)) : (b.size || 10);
+          pdf.font(b.bold ? 'bold' : 'body').fontSize(size).fillColor(b.color || COLORS.text)
+            .text(String(b.text == null ? '' : b.text), at.x, at.y, { width: at.w, height: at.h, align: b.align || 'left', ellipsis: true });
+        }
+        pdf.restore();
+      });
+    });
+    stampPages(pdf, spec.footer);
+    } catch (err) {
+      made.abandon();
+      throw err;
+    }
+    pdf.end();
+    await made.finished;
+    return { pages: pages.length, blocks: counts.blocks, hiddenRows: counts.hiddenRows, badImages: counts.badImages };
+  }
+};

package/lib/formats/writers/xlsx.js

@@ -0,0 +1,278 @@
+// .xlsx writer — our own, on fflate's streaming zip.
+//
+// Why not exceljs: it pulls a uuid with a published advisory, has not had a
+// release since December 2024, and the override that silences it has to be
+// repeated in every app that installs this package. Writing SpreadsheetML is
+// the other half of what lib/formats/_xlsx-stream.js already reads, and a
+// workbook of one styled sheet is a small, well-specified thing.
+//
+// WHAT IT WRITES: one sheet; an optional title and subtitle above the header;
+// the header bold on a tint, frozen, with an autofilter; numbers and dates as
+// REAL cells carrying their number format, so the reader can still sum and
+// filter; subtotal rows bold, total rows bold on a tint; column widths from
+// the header and the first rows.
+//
+// Streaming: rows go straight into the zip, which goes straight to disk,
+// waiting on the file stream when it is full — a million rows costs the
+// same memory as a hundred. Only the first SAMPLE_ROWS are held, to size the
+// columns, because <cols> must come before the rows in the sheet.
+
+var fs = require('fs');
+
+var MAX_ROWS = 1048576;          // Excel's own limit, header and title rows included
+var SAMPLE_ROWS = 200;
+var CHUNK = 1 << 20;             // push to the zip in ~1 MB pieces
+
+// XML 1.0 cannot carry most control characters even escaped; Excel refuses
+// the file ("We found a problem with some content"). Dropped.
+var INVALID_XML = /[\u0000-\u0008\u000B\u000C\u000E-\u001F￾￿]/g;
+function esc(value) {
+  return String(value).replace(INVALID_XML, '')
+    .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+/** 0 → A, 25 → Z, 26 → AA. */
+function colName(i) {
+  var s = '';
+  for (var n = i + 1; n > 0; n = Math.floor((n - 1) / 26)) s = String.fromCharCode(65 + ((n - 1) % 26)) + s;
+  return s;
+}
+
+/** A Date, or an ISO date string, as an Excel serial — or null. */
+function dateSerial(value) {
+  var d = value instanceof Date ? value : (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}/.test(value) ? new Date(value) : null);
+  if (!d || isNaN(d.getTime())) return null;
+  return d.getTime() / 86400000 + 25569;
+}
+
+// Fonts: 0 normal, 1 bold, 2 title. Fills: 0 none, 1 gray125 (both required
+// by Excel at those positions), 2 header tint, 3 total tint.
+var FONT = { normal: 0, bold: 1, title: 2 };
+var FILL = { none: 0, header: 2, total: 3 };
+
+function stylesXml(numFmts, xfs) {
+  var fmts = numFmts.map(function(code, i) { return '<numFmt numFmtId="' + (164 + i) + '" formatCode="' + esc(code) + '"/>'; });
+  return '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n' +
+    '<styleSheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">' +
+    (fmts.length ? '<numFmts count="' + fmts.length + '">' + fmts.join('') + '</numFmts>' : '') +
+    '<fonts count="3"><font><sz val="11"/><name val="Calibri"/></font><font><b/><sz val="11"/><name val="Calibri"/></font>' +
+    '<font><b/><sz val="14"/><name val="Calibri"/></font></fonts>' +
+    '<fills count="4"><fill><patternFill patternType="none"/></fill><fill><patternFill patternType="gray125"/></fill>' +
+    '<fill><patternFill patternType="solid"><fgColor rgb="FFF1F3F7"/><bgColor indexed="64"/></patternFill></fill>' +
+    '<fill><patternFill patternType="solid"><fgColor rgb="FFE8EBF2"/><bgColor indexed="64"/></patternFill></fill></fills>' +
+    '<borders count="2"><border><left/><right/><top/><bottom/><diagonal/></border>' +
+    '<border><left/><right/><top style="thin"><color rgb="FF9AA1AE"/></top><bottom/><diagonal/></border></borders>' +
+    '<cellStyleXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0"/></cellStyleXfs>' +
+    '<cellXfs count="' + xfs.length + '">' + xfs.map(function(x) {
+      return '<xf numFmtId="' + x.numFmtId + '" fontId="' + x.fontId + '" fillId="' + x.fillId + '" borderId="' + x.borderId + '" xfId="0"' +
+        (x.numFmtId ? ' applyNumberFormat="1"' : '') + (x.fontId ? ' applyFont="1"' : '') + (x.fillId ? ' applyFill="1"' : '') +
+        (x.borderId ? ' applyBorder="1"' : '') + (x.align ? ' applyAlignment="1"><alignment horizontal="' + x.align + '"/></xf>' : '/>');
+    }).join('') + '</cellXfs>' +
+    '<cellStyles count="1"><cellStyle name="Normal" xfId="0" builtinId="0"/></cellStyles></styleSheet>';
+}
+
+var STATIC = {
+  '[Content_Types].xml': '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n' +
+    '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">' +
+    '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>' +
+    '<Default Extension="xml" ContentType="application/xml"/>' +
+    '<Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>' +
+    '<Override PartName="/xl/worksheets/sheet1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>' +
+    '<Override PartName="/xl/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml"/>' +
+    '</Types>',
+  '_rels/.rels': '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n' +
+    '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">' +
+    '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/>' +
+    '</Relationships>',
+  'xl/_rels/workbook.xml.rels': '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n' +
+    '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">' +
+    '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet1.xml"/>' +
+    '<Relationship Id="rId2" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/>' +
+    '</Relationships>'
+};
+
+function workbookXml(sheetName, filterRef) {
+  return '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n' +
+    '<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">' +
+    '<sheets><sheet name="' + esc(sheetName) + '" sheetId="1" r:id="rId1"/></sheets>' +
+    (filterRef ? '<definedNames><definedName name="_xlnm._FilterDatabase" localSheetId="0" hidden="1">' + esc("'" + sheetName.replace(/'/g, "''") + "'!" + filterRef) + '</definedName></definedNames>' : '') +
+    '</workbook>';
+}
+
+/** Excel refuses a sheet name over 31 characters or with any of : \ / ? * [ ] */
+function sheetNameOf(title) {
+  var name = String(title || 'Sheet1').replace(/[:\\/?*[\]]/g, ' ').trim().slice(0, 31);
+  return name || 'Sheet1';
+}
+
+module.exports = {
+  requires: ['fflate'],
+  MAX_ROWS: MAX_ROWS,
+
+  /**
+   * @param {string} filePath
+   * @param {object} doc - { title?, subtitle?, columns: [{ header, kind?: 'number'|'date'|'text'|'raw', numFmt?, width?, align? }] }
+   *   kind 'number': the value is written as a number (numFmt applies);
+   *   kind 'date': a Date or ISO string, written as a date serial (numFmt applies);
+   *   anything else: a number stays a number, everything else is text.
+   * @returns {{ writeRow(row): Promise<boolean>, close(): Promise<{ rows, truncated }> }}
+   *   row: { values: [], kind?: 'detail'|'subtotal'|'total' }. writeRow answers
+   *   false once Excel's row limit is reached (the rest are counted, not written).
+   */
+  open: function(filePath, doc) {
+    var fflate = require('fflate');
+    var columns = doc.columns || [];
+    var out = fs.createWriteStream(filePath);
+    var failed = null;
+    out.on('error', function(err) { failed = err; });
+    var zipDone;
+    var zipFinished = new Promise(function(resolve) { zipDone = resolve; });
+    var zip = new fflate.Zip(function(err, chunk, final) {
+      if (err) { failed = err; return; }
+      out.write(Buffer.from(chunk));
+      if (final) zipDone();
+    });
+    function addFile(name, text) {
+      var f = new fflate.ZipDeflate(name, { level: 6 });
+      zip.add(f);
+      f.push(fflate.strToU8(text), true);
+    }
+
+    // Styles are collected as the rows use them and written at the end.
+    var numFmts = [];
+    var xfs = [{ numFmtId: 0, fontId: 0, fillId: 0, borderId: 0 }];
+    var xfIndex = { '0|0|0|0|': 0 };
+    function styleId(numFmt, fontId, fillId, borderId, align) {
+      var numFmtId = 0;
+      if (numFmt) {
+        var at = numFmts.indexOf(numFmt);
+        if (at < 0) { numFmts.push(numFmt); at = numFmts.length - 1; }
+        numFmtId = 164 + at;
+      }
+      var key = numFmtId + '|' + fontId + '|' + fillId + '|' + borderId + '|' + (align || '');
+      if (xfIndex[key] === undefined) {
+        xfs.push({ numFmtId: numFmtId, fontId: fontId, fillId: fillId, borderId: borderId, align: align || null });
+        xfIndex[key] = xfs.length - 1;
+      }
+      return xfIndex[key];
+    }
+    var LOOK = {
+      detail: { font: FONT.normal, fill: FILL.none, border: 0 },
+      subtotal: { font: FONT.bold, fill: FILL.none, border: 0 },
+      total: { font: FONT.bold, fill: FILL.total, border: 1 }
+    };
+
+    var sheet = new fflate.ZipDeflate('xl/worksheets/sheet1.xml', { level: 6 });
+    var buffered = '';
+    var rowNo = 0;
+    var written = 0;     // data rows written
+    var offered = 0;     // data rows asked for
+    var headerRow = 0;
+    var sample = [];
+    var started = false;
+
+    function cellXml(ref, value, column, look) {
+      if (value === null || value === undefined || value === '') return '';
+      var kind = column.kind;
+      var align = column.align === 'right' || column.align === 'center' ? column.align : null;
+      if (kind === 'date') {
+        var serial = dateSerial(value);
+        if (serial !== null) return '<c r="' + ref + '" s="' + styleId(column.numFmt || 'yyyy-mm-dd', look.font, look.fill, look.border, align) + '"><v>' + serial + '</v></c>';
+      }
+      var num = typeof value === 'number' ? value : (kind === 'number' && value !== '' && !isNaN(Number(value)) ? Number(value) : null);
+      if (num !== null && isFinite(num)) {
+        return '<c r="' + ref + '" s="' + styleId(kind === 'number' ? column.numFmt : null, look.font, look.fill, look.border, align) + '"><v>' + num + '</v></c>';
+      }
+      if (typeof value === 'boolean') return '<c r="' + ref + '" t="b" s="' + styleId(null, look.font, look.fill, look.border, align) + '"><v>' + (value ? 1 : 0) + '</v></c>';
+      return '<c r="' + ref + '" t="inlineStr" s="' + styleId(null, look.font, look.fill, look.border, align) + '"><is><t xml:space="preserve">' + esc(value) + '</t></is></c>';
+    }
+
+    function textRow(cells) { rowNo += 1; return '<row r="' + rowNo + '">' + cells + '</row>'; }
+
+    async function push(text, final) {
+      buffered += text;
+      if (buffered.length < CHUNK && !final) return;
+      sheet.push(fflate.strToU8(buffered), Boolean(final));
+      buffered = '';
+      if (failed) throw failed;
+      if (out.writableNeedDrain) await new Promise(function(r) { out.once('drain', r); });
+    }
+
+    // <cols> needs the widths, which need a look at the rows: written once
+    // the sample is full, or at close for a short table.
+    async function start() {
+      started = true;
+      var widths = columns.map(function(c, i) {
+        if (c.width) return c.width;
+        var longest = String(c.header || '').length;
+        // A date is as wide as its pattern, not as its JS string form.
+        if (c.kind === 'date') return Math.min(60, Math.max(10, longest, String(c.numFmt || 'yyyy-mm-dd').length) + 2);
+        sample.forEach(function(r) {
+          var shown = r.display ? r.display[i] : r.values[i];
+          if (shown !== null && shown !== undefined) longest = Math.max(longest, String(shown).length);
+        });
+        return Math.min(60, Math.max(8, longest + 2));
+      });
+      zip.add(sheet);
+      var head = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n' +
+        '<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">';
+      var titleRows = (doc.title ? 1 : 0) + (doc.subtitle ? 1 : 0);
+      headerRow = titleRows + (titleRows ? 2 : 1);
+      head += '<sheetViews><sheetView workbookViewId="0"><pane ySplit="' + headerRow + '" topLeftCell="A' + (headerRow + 1) +
+        '" activePane="bottomLeft" state="frozen"/></sheetView></sheetViews>';
+      head += '<cols>' + widths.map(function(w, i) { return '<col min="' + (i + 1) + '" max="' + (i + 1) + '" width="' + w + '" customWidth="1"/>'; }).join('') + '</cols>';
+      head += '<sheetData>';
+      if (doc.title) head += textRow('<c r="A' + (rowNo + 1) + '" t="inlineStr" s="' + styleId(null, FONT.title, 0, 0) + '"><is><t xml:space="preserve">' + esc(doc.title) + '</t></is></c>');
+      if (doc.subtitle) head += textRow('<c r="A' + (rowNo + 1) + '" t="inlineStr"><is><t xml:space="preserve">' + esc(doc.subtitle) + '</t></is></c>');
+      if (titleRows) rowNo += 1; // a blank row between the title block and the table
+      head += textRow(columns.map(function(c, i) {
+        var align = c.align === 'right' || c.align === 'center' ? c.align : null;
+        return '<c r="' + colName(i) + (rowNo + 1) + '" t="inlineStr" s="' + styleId(null, FONT.bold, FILL.header, 0, align) + '"><is><t xml:space="preserve">' + esc(c.header == null ? '' : c.header) + '</t></is></c>';
+      }).join(''));
+      await push(head);
+      var held = sample;
+      sample = null;
+      for (var k = 0; k < held.length; k++) await emit(held[k]);
+    }
+
+    async function emit(row) {
+      if (rowNo >= MAX_ROWS) return false;
+      var look = LOOK[row.kind] || LOOK.detail;
+      var r = rowNo + 1;
+      var cells = '';
+      var values = row.values || [];
+      for (var i = 0; i < columns.length; i++) cells += cellXml(colName(i) + r, values[i], columns[i], look);
+      written += 1;
+      await push(textRow(cells));
+      return true;
+    }
+
+    return {
+      writeRow: async function(row) {
+        offered += 1;
+        if (!started) {
+          sample.push(row);
+          if (sample.length >= SAMPLE_ROWS) await start();
+          return true;
+        }
+        return emit(row);
+      },
+      close: async function() {
+        if (!started) await start();
+        var lastRow = Math.max(rowNo, headerRow);
+        var filterRef = columns.length ? 'A' + headerRow + ':' + colName(columns.length - 1) + lastRow : null;
+        await push('</sheetData>' + (filterRef ? '<autoFilter ref="' + filterRef + '"/>' : '') +
+          '<pageSetup orientation="' + (columns.length > 6 ? 'landscape' : 'portrait') + '"/></worksheet>', true);
+        var sheetName = sheetNameOf(doc.title);
+        Object.keys(STATIC).forEach(function(name) { addFile(name, STATIC[name]); });
+        addFile('xl/workbook.xml', workbookXml(sheetName, filterRef ? '$A$' + headerRow + ':$' + colName(columns.length - 1) + '$' + lastRow : null));
+        addFile('xl/styles.xml', stylesXml(numFmts, xfs));
+        zip.end();
+        await zipFinished;
+        await new Promise(function(resolve, reject) { out.end(function(err) { return err ? reject(err) : resolve(); }); });
+        if (failed) throw failed;
+        return { rows: written, truncated: offered > written };
+      }
+    };
+  }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/actions",
-  "version": "1.1.18",
+  "version": "1.1.19",
   "description": "Named-action registry with typed inputs and safe invocation — plus built-in actions for HTTP, DB, files, email, spawn",
   "main": "index.js",
   "files": [
@@ -16,7 +16,11 @@
     "http",
     "db",
     "file",
-    "email"
+    "email",
+    "export",
+    "csv",
+    "xlsx",
+    "pdf"
   ],
   "author": "xeplr",
   "license": "MIT",
@@ -28,15 +32,17 @@
     "access": "public"
   },
   "dependencies": {
-    "@xeplr/schema-handler": "^1.0.0",
-    "@xeplr/expression-handler": "^2.0.0"
+    "@xeplr/expression-handler": "^2.0.0",
+    "@xeplr/schema-handler": "^1.0.0"
   },
   "peerDependencies": {
     "@duckdb/node-api": "1.5.5-r.3",
     "@xeplr/email": "^1.0.0",
     "@xeplr/utils": "^1.0.0",
     "csv-parse": "^7.0.2",
+    "dejavu-fonts-ttf": "^2.37.3",
     "exceljs": "^4.0.0",
+    "fflate": "^0.8.2",
     "imapflow": "^1.0.0",
     "knex": "^3.0.0",
     "mailparser": "^3.0.0",
@@ -44,6 +50,7 @@
     "mssql": "^11.0.0",
     "mysql2": "^3.0.0",
     "nodemailer": "^10.0.13",
+    "pdfkit": "^0.20.2",
     "pg": "^8.0.0",
     "saxes": "^6.0.0",
     "ssh2-sftp-client": "^11.0.0",
@@ -97,15 +104,27 @@
     },
     "@xeplr/email": {
       "optional": true
+    },
+    "fflate": {
+      "optional": true
+    },
+    "pdfkit": {
+      "optional": true
+    },
+    "dejavu-fonts-ttf": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@duckdb/node-api": "^1.5.5-r.3",
     "@xeplr/utils": "^1.0.0",
     "csv-parse": "^7.0.2",
+    "dejavu-fonts-ttf": "^2.37.3",
     "express": "^4.0.0",
+    "fflate": "^0.8.3",
     "mssql": "^12.7.0",
     "mysql2": "^3.23.1",
+    "pdfkit": "^0.20.2",
     "pg": "^8.0.0",
     "saxes": "^6.0.0",
     "unzipper": "^0.12.0"