@xeplr/actions 1.1.18 → 1.1.20

package/lib/drivers/db/mysql.js

@@ -19,8 +19,9 @@
 //   number  → DECIMAL(38,10)   (exact; > 10 fractional digits are rounded —
 //                               pre-create a wider column if you need more)
 //   boolean → TINYINT(1)
-//   date    → DATETIME(6)      (user rule: always datetime, stored UTC)
-//   datetime→ DATETIME(6)
+//   date          → DATE         (the same day — dateValues.js)
+//   datetime      → DATETIME(6)  (an instant, written in UTC)
+//   localdatetime → DATETIME(6)  (no zone; its digits as they were)
 //   object  → JSON
 //   array   → JSON
 
@@ -29,7 +30,8 @@ var TYPE_MAP = {
   number:   'DECIMAL(38,10)',
   boolean:  'TINYINT(1)',
   date:     'DATE',
-  datetime: 'DATETIME(6)',
+  datetime: 'DATETIME(6)',      // an instant, written in UTC
+  localdatetime: 'DATETIME(6)', // a wall-clock reading, written as its digits
   object:   'JSON',
   array:    'JSON'
 };
@@ -43,30 +45,16 @@ var NATIVE_TO_LOGICAL = {
   float: 'number', double: 'number', bit: 'boolean',
   // 'date' maps to its OWN logical type — see reconcile.js. A DATE column
   // created as DATETIME acquires a midnight that shifts under a timezone.
-  date: 'date', datetime: 'datetime', timestamp: 'datetime',
+  // DATETIME has no zone — its digits are copied as they are (dateValues.js).
+  // TIMESTAMP is an instant, read in UTC (the session is pinned to it below).
+  date: 'date', datetime: 'localdatetime', timestamp: 'datetime',
   time: 'datetime', year: 'datetime',
   json: 'object'
 };
 
 
-// A calendar date, as YYYY-MM-DD, with NO timezone conversion.
-//
-// toISOString() would convert to UTC first, which is exactly the bug: a Date
-// holding 2026-01-05 local becomes 2026-01-04 in UTC anywhere east of
-// Greenwich. The local getters are the right ones here precisely because a
-// business date has no instant to convert.
-function toDateOnly(v) {
-  if (v === null || v === undefined) return v;
-  if (v instanceof Date) {
-    if (isNaN(v.getTime())) return null;
-    return v.getFullYear() + '-' +
-      String(v.getMonth() + 1).padStart(2, '0') + '-' +
-      String(v.getDate()).padStart(2, '0');
-  }
-  // Already a date string — take the date part and leave the rest alone.
-  var m = /^(\d{4}-\d{2}-\d{2})/.exec(String(v));
-  return m ? m[1] : v;
-}
+// Dates and times: one shared rule for every driver (dateValues.js).
+var dateValues = require('./dateValues');
 
 var INTERNAL_ID_COL       = '__xeplr_id__';
 var INTERNAL_MOVEMENT_COL = '__xeplr_movement_id__';
@@ -96,6 +84,13 @@ async function connect(config) {
     stringifyObjects:  true
     // multipleStatements stays at its default (off): one statement per query.
   });
+  // THE SESSION IS IN UTC. MySQL hands a TIMESTAMP back in the session's zone
+  // (the server's own unless told), so without this the same instant read
+  // from a server set to India time came back 5½ hours off. Run first on
+  // every connection the pool opens; mysql2 queues it ahead of any query.
+  pool.pool.on('connection', function(conn) {
+    conn.query("SET time_zone = '+00:00'");
+  });
   // READ-ONLY CONNECTIONS — `connect({ ..., readOnly: true })` for SQL the
   // caller did not write itself. Every connection the pool opens is put into
   // read-only transaction mode before it is used, so a write fails.
@@ -262,7 +257,7 @@ function coerceValue(v, type) {
 
   switch (type) {
     case 'string':
-      if (v instanceof Date)     return toMysqlDatetime(v);
+      if (v instanceof Date)     return dateValues.toInstantUtcClock(v);
       if (Array.isArray(v))      return JSON.stringify(v);
       if (typeof v === 'object') return JSON.stringify(v);
       return String(v);
@@ -286,10 +281,13 @@ function coerceValue(v, type) {
       return v;                    // let MySQL reject
 
     case 'date':
-      return toDateOnly(v);
+      return dateValues.toDateOnly(v);
 
     case 'datetime':
-      return toMysqlDatetime(v);
+      return dateValues.toInstantUtcClock(v);
+
+    case 'localdatetime':
+      return dateValues.toLocalDateTime(v);
 
     case 'object':
     case 'array':
@@ -301,13 +299,6 @@ function coerceValue(v, type) {
   }
 }
 
-// 'YYYY-MM-DD HH:MM:SS.mmm' in UTC — the format MySQL DATETIME accepts.
-// Unparseable input passes through so MySQL rejects it (→ error table).
-function toMysqlDatetime(v) {
-  var d = (v instanceof Date) ? v : new Date(v);
-  if (isNaN(d.getTime())) return v;
-  return d.toISOString().slice(0, 23).replace('T', ' ');
-}
 
 async function getTableSchema(pool, tableName, schema) {
   var r = await query(pool,

package/lib/drivers/db/postgres.js

@@ -22,8 +22,9 @@
 //   string  → TEXT
 //   number  → NUMERIC          (integer + float both handled)
 //   boolean → BOOLEAN
-//   date    → TIMESTAMPTZ      (user rule: "always datetime, never date-only")
-//   datetime→ TIMESTAMPTZ
+//   date          → DATE         (the same day — dateValues.js)
+//   datetime      → TIMESTAMPTZ  (an instant)
+//   localdatetime → TIMESTAMP    (no zone; its digits as they were)
 //   object  → JSONB
 //   array   → JSONB
 
@@ -33,6 +34,7 @@ var TYPE_MAP = {
   boolean:  'BOOLEAN',
   date:     'DATE',
   datetime: 'TIMESTAMPTZ',
+  localdatetime: 'TIMESTAMP',
   object:   'JSONB',
   array:    'JSONB'
 };
@@ -60,7 +62,17 @@ async function connect(config) {
     user:     config.user,
     password: config.password,
     database: config.database,
-    max:      config.maxConnections || 10
+    max:      config.maxConnections || 10,
+    // THE ZONELESS TYPES COME BACK AS TEXT. node-pg turns a `date` and a
+    // `timestamp` into a JS Date read in THIS PROCESS's zone, so the same row
+    // read on a server in India and one in New York came back as two
+    // different instants — and a date a day apart. As text they are exactly
+    // the digits stored. `timestamptz` (1184) is a real instant and stays a
+    // Date.
+    types: { getTypeParser: function(oid, format) {
+      if (oid === 1082 || oid === 1114) return function(text) { return text; };
+      return pg.types.getTypeParser(oid, format);
+    } }
   });
   if (config.readOnly) pool.__xeplrReadOnly = true;
   return pool;
@@ -98,24 +110,9 @@ async function query(pool, sql, params) {
 
 function toPgType(type) { return TYPE_MAP[type] || 'TEXT'; }
 
-// A calendar date, as YYYY-MM-DD, with NO timezone conversion.
-//
-// toISOString() would convert to UTC first, which is exactly the bug: a Date
-// holding 2026-01-05 local becomes 2026-01-04 in UTC anywhere east of
-// Greenwich. The local getters are the right ones here precisely because a
-// business date has no instant to convert.
-function toDateOnly(v) {
-  if (v === null || v === undefined) return v;
-  if (v instanceof Date) {
-    if (isNaN(v.getTime())) return null;
-    return v.getFullYear() + '-' +
-      String(v.getMonth() + 1).padStart(2, '0') + '-' +
-      String(v.getDate()).padStart(2, '0');
-  }
-  // Already a date string — take the date part and leave the rest alone.
-  var m = /^(\d{4}-\d{2}-\d{2})/.exec(String(v));
-  return m ? m[1] : v;
-}
+// Dates and times: one shared rule for every driver (dateValues.js).
+var dateValues = require('./dateValues');
+var toDateOnly = dateValues.toDateOnly;
 
 
 // Double-quote a Postgres identifier, escaping embedded quotes.
@@ -251,8 +248,10 @@ function coerceValue(v, type) {
       return toDateOnly(v);
 
     case 'datetime':
-      if (v instanceof Date)         return v.toISOString();
-      return v;                       // strings pass through; PG parses
+      return dateValues.toInstantIso(v);
+
+    case 'localdatetime':
+      return dateValues.toLocalDateTime(v);
 
     case 'object':
     case 'array':
@@ -395,7 +394,17 @@ async function rollbackMovement(pool, tableName, movementId) {
   return result;
 }
 
+/**
+ * A zoned date-time column that holds zoneless values, retyped to zoneless with
+ * the same digits (read in UTC — how they were written). See the uploader's
+ * bootstrap for when this runs.
+ */
+function buildRetypeToLocalDateTimeSql(tableName, column) {
+  return 'ALTER TABLE ' + quoteIdent(tableName) + ' ALTER COLUMN ' + quoteIdent(column) + ' TYPE timestamp USING ' + quoteIdent(column) + " AT TIME ZONE 'UTC'";
+}
+
 module.exports = {
+  buildRetypeToLocalDateTimeSql: buildRetypeToLocalDateTimeSql,
   requires: ['pg'],
 
   // Connection lifecycle

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 };
+  }
+};