reamkit 1.23.0 → 1.25.0

package/README.md

@@ -1,10 +1,10 @@
 # Ream
 
-> Read Word, Excel, PowerPoint and PDF — and convert any of them to PDF, SVG, HTML, DOCX or XLSX. From scratch, in the browser. No LibreOffice, no headless Office, no commercial SDK.
+> Read Word, Excel, PowerPoint and PDF — and convert any of them to PDF, SVG, HTML, Markdown, DOCX or XLSX. From scratch, in the browser. No LibreOffice, no headless Office, no commercial SDK.
 
 Ream parses **seven document formats** — the modern Office Open XML trio (`.docx`,
 `.xlsx`, `.pptx`), `.pdf`, and the legacy binary `.doc` / `.xls` / `.ppt` — into one
-format-neutral interlayer, then renders that to **PDF, SVG, HTML, DOCX or XLSX**.
+format-neutral interlayer, then renders that to **PDF, SVG, HTML, Markdown, DOCX or XLSX**.
 It is implemented directly from the **ECMA-376** (OOXML), **ISO 32000 / 19005**
 (PDF / PDF/A), and Microsoft's binary-format specifications — no wrapper around
 LibreOffice, headless Office, or any commercial SDK. Pure TypeScript/JavaScript on
@@ -14,7 +14,7 @@ Node.js, serverless and edge runtimes.
 |            |                                                                                             |
 | ---------- | ------------------------------------------------------------------------------------------- |
 | **Reads**  | `.docx` · `.xlsx` · `.pptx` · `.pdf` · legacy `.doc` · `.xls` · `.ppt`                       |
-| **Writes** | `.pdf` (incl. PDF/A-1/2/3, PDF/UA-1, signed, encrypted) · `.svg` · `.html` · `.docx` · `.xlsx` |
+| **Writes** | `.pdf` (incl. PDF/A-1/2/3, PDF/UA-1, signed, encrypted) · `.svg` · `.html` · `.md` · `.docx` · `.xlsx` |
 
 ## Install
 
@@ -42,6 +42,7 @@ const doc = Ream.parse(bytes);            // docx, xlsx, pptx or pdf — sniffed
 const pdf = await doc.convert('pdf');     // async — fetches a font if needed
 const svg = await doc.convert('svg');     // same parse, different target
 const html = await doc.convert('html');   // flowed HTML — needs no fonts at all
+const md   = await doc.convert('md');     // GitHub-Flavored Markdown — same, narrower
 const docx = await doc.convert('docx');   // write WordprocessingML back out
 const xlsx = await doc.convert('xlsx');   // write SpreadsheetML back (xlsx source)
 
@@ -160,7 +161,7 @@ automatically from the document's `docProps/core.xml`), `attachments`
 
 ### Lower-level APIs
 
-- `docxReader` / `xlsxReader`, `svgWriter`, `htmlWriter`, `docxWriter` — the `@experimental`
+- `docxReader` / `xlsxReader`, `svgWriter`, `htmlWriter`, `markdownWriter`, `docxWriter` — the `@experimental`
   reader/writer interfaces of the interlayer, for building custom pipelines (and
   keeping unused formats out of your bundle); `layoutStyledDocument` produces the
   frozen page model (`PageItem` pages in a top-left `Pt` frame) the page-based
@@ -190,17 +191,27 @@ preview, flowed HTML export, and **docx + xlsx output** (write WordprocessingML
 tagged PDF from its structure tree (headings, tables, lists, reading order), an
 untagged one heuristically from glyph positions (lines, paragraphs, headings,
 and a clean two-column split). It lifts back the text (via each font's
-`/ToUnicode`), raster images (JPEG verbatim; PNG/Flate/LZW/CCITT-fax decoded and
-re-encoded), `/Link` hyperlinks, form-XObject content, and filled / stroked /
-gradient vector shapes. It reads modern compressed files (cross-reference + object
-streams) and encrypted ones (RC4 / AES — the user password is passed to
-`Ream.parse(bytes, { password })`, defaulting to the permissions-only case).
+`/ToUnicode`, or the embedded program's own `cmap` where there is none), the
+font programs themselves, raster images (JPEG verbatim; PNG/Flate/LZW/CCITT-fax
+decoded and re-encoded), `/Link` hyperlinks, form-XObject content, annotation
+appearances, and the page's artwork: filled / stroked / gradient shapes,
+clipping paths, tiling patterns, constant alpha, and the Type 3 glyphs that are
+drawings rather than letters. It reads modern compressed files (cross-reference
++ object streams) and encrypted ones (RC4 / AES — the user password is passed to
+`Ream.parse(bytes, { password })`, defaulting to the permissions-only case); a
+filter it does not carry can be handed to it through
+`Ream.parse(bytes, { filters })`.
+
+A form or a drawing is not a reflowable document, so
+`Ream.parse(bytes, { pdfLayout: 'positional' })` reads the page instead: every
+line stands where its glyphs stand, beside the artwork, the way up the page is
+shown.
 
 **Reads PowerPoint, too.** `Ream.parse` accepts a `.pptx` and turns each slide
 into a page at the deck size — text boxes (with run formatting, alignment,
 bullets and indents), layout/master placeholders, pictures, shapes, DrawingML
 tables, embedded charts, theme colours, slide backgrounds, grouped shapes and
-hyperlinks — then converts onward to PDF, SVG, HTML or DOCX like any source.
+hyperlinks — then converts onward to PDF, SVG, HTML, Markdown or DOCX like any source.
 
 **Reads legacy `.doc`, `.xls` and `.ppt`, too.** The binary Word / Excel /
 PowerPoint 97–2003 formats (OLE2/CFB) parse through a shared container reader: a
@@ -217,7 +228,7 @@ text (with run and paragraph formatting), embedded images, per-shape placement
 (anchored text boxes and pictures at their slide rectangles) and decorative
 autoshapes (preset or exact freeform geometry, with fill / line colours resolved
 through the slide's colour scheme), one page per slide — all convert onward to PDF,
-SVG, HTML, or back to `.docx` / `.xlsx` like any source.
+SVG, HTML, Markdown, or back to `.docx` / `.xlsx` like any source.
 
 See [`CHANGELOG.md`](./CHANGELOG.md) for the release history; the docs
 [**Scope**](https://reamkit.dev/guides/scope/) guide has the full feature matrix

package/dist/esm/core/bmp.d.ts

@@ -0,0 +1,33 @@
+/** One decoded bitmap: chunky 8-bit samples, plus alpha when the file carries it. */
+export interface DecodedBmp {
+    readonly width: number;
+    readonly height: number;
+    /** Row-major RGB samples, `width * height * 3` long. */
+    readonly data: Uint8Array;
+    /** One byte per pixel, present only when the file states real transparency. */
+    readonly alpha?: Uint8Array;
+    /** `biXPelsPerMeter`/`biYPelsPerMeter` turned into pixels per inch. */
+    readonly dpiX?: number;
+    readonly dpiY?: number;
+}
+/** Whether these bytes open with the `BM` signature of a bitmap FILE. */
+export declare function isBmp(bytes: Uint8Array): boolean;
+/**
+ * MS-ODRAW §2.2.28 — a `BlipDIB`'s payload is a bitmap without its 14-byte
+ * BITMAPFILEHEADER, which the Escher record makes redundant. Put it back.
+ *
+ * @param dib The bytes from the DIB header onwards.
+ * @returns A complete BMP file, or `undefined` when the header does not read
+ *          as a bitmap at all.
+ */
+export declare function dibToBmp(dib: Uint8Array): Uint8Array | undefined;
+/**
+ * Decode a Windows bitmap into 8-bit RGB samples.
+ *
+ * @param bytes A complete BMP file (`BM` signature included).
+ * @returns The samples, their size and any alpha channel.
+ * @throws Error when the file is malformed, or carries a bitmap this does not
+ *         read — a JPEG or PNG smuggled inside a DIB (`BI_JPEG`/`BI_PNG`),
+ *         which is a whole other file wearing a bitmap header.
+ */
+export declare function decodeBmp(bytes: Uint8Array): DecodedBmp;

package/dist/esm/core/bmp.js

@@ -0,0 +1,276 @@
+//#region src/core/bmp.ts
+var FILE_HEADER_BYTES = 14;
+var CORE_HEADER_BYTES = 12;
+var INFO_HEADER_BYTES = 40;
+var MAX_PIXELS = 4e7;
+var BI_RGB = 0;
+var BI_RLE8 = 1;
+var BI_RLE4 = 2;
+var BI_BITFIELDS = 3;
+var BI_ALPHABITFIELDS = 6;
+/** Whether these bytes open with the `BM` signature of a bitmap FILE. */
+function isBmp(bytes) {
+	return bytes.length >= FILE_HEADER_BYTES && bytes[0] === 66 && bytes[1] === 77;
+}
+/**
+* MS-ODRAW §2.2.28 — a `BlipDIB`'s payload is a bitmap without its 14-byte
+* BITMAPFILEHEADER, which the Escher record makes redundant. Put it back.
+*
+* @param dib The bytes from the DIB header onwards.
+* @returns A complete BMP file, or `undefined` when the header does not read
+*          as a bitmap at all.
+*/
+function dibToBmp(dib) {
+	const head = readDibHeader(dib, 0);
+	if (!head) return void 0;
+	const offBits = FILE_HEADER_BYTES + head.headerBytes + head.maskBytes + head.paletteBytes;
+	const out = new Uint8Array(FILE_HEADER_BYTES + dib.length);
+	const view = new DataView(out.buffer);
+	out[0] = 66;
+	out[1] = 77;
+	view.setUint32(2, out.length, true);
+	view.setUint32(10, offBits, true);
+	out.set(dib, FILE_HEADER_BYTES);
+	return out;
+}
+/**
+* Decode a Windows bitmap into 8-bit RGB samples.
+*
+* @param bytes A complete BMP file (`BM` signature included).
+* @returns The samples, their size and any alpha channel.
+* @throws Error when the file is malformed, or carries a bitmap this does not
+*         read — a JPEG or PNG smuggled inside a DIB (`BI_JPEG`/`BI_PNG`),
+*         which is a whole other file wearing a bitmap header.
+*/
+function decodeBmp(bytes) {
+	if (!isBmp(bytes)) throw new Error("BMP: not a bitmap");
+	const file = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const head = readDibHeader(bytes, FILE_HEADER_BYTES);
+	if (!head) throw new Error("BMP: unreadable header");
+	const { width, height, topDown, bitCount, compression } = head;
+	if (width <= 0 || height <= 0) throw new Error("BMP: empty bitmap");
+	if (width * height > MAX_PIXELS) throw new Error("BMP: image too large");
+	if (compression === 4 || compression === 5) throw new Error("BMP: embedded JPEG/PNG bitmaps are not supported");
+	const stated = file.getUint32(10, true);
+	const computed = FILE_HEADER_BYTES + head.headerBytes + head.maskBytes + head.paletteBytes;
+	const pixelsAt = stated >= computed && stated < bytes.length ? stated : computed;
+	const palette = readPalette(bytes, FILE_HEADER_BYTES + head.headerBytes, head);
+	const count = width * height;
+	const data = new Uint8Array(count * 3);
+	const rowOf = (y) => topDown ? y : height - 1 - y;
+	if (compression === BI_RLE8 || compression === BI_RLE4) {
+		const indices = decodeRle(bytes.subarray(pixelsAt), width, height, compression === BI_RLE4);
+		for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
+			const at = (rowOf(y) * width + x) * 3;
+			const p = (indices[y * width + x] ?? 0) * 3;
+			data[at] = palette[p] ?? 0;
+			data[at + 1] = palette[p + 1] ?? 0;
+			data[at + 2] = palette[p + 2] ?? 0;
+		}
+		return {
+			width,
+			height,
+			data,
+			...density(head)
+		};
+	}
+	const stride = ((width * bitCount + 31) / 32 | 0) * 4;
+	const alpha = head.alphaMask !== 0 ? new Uint8Array(count) : void 0;
+	const shifts = {
+		r: maskShift(head.redMask),
+		g: maskShift(head.greenMask),
+		b: maskShift(head.blueMask),
+		a: maskShift(head.alphaMask)
+	};
+	for (let y = 0; y < height; y++) {
+		const row = pixelsAt + y * stride;
+		if (row + stride > bytes.length + stride) break;
+		for (let x = 0; x < width; x++) {
+			const at = (rowOf(y) * width + x) * 3;
+			if (bitCount <= 8) {
+				const p = paletteIndex(bytes, row, x, bitCount) * 3;
+				data[at] = palette[p] ?? 0;
+				data[at + 1] = palette[p + 1] ?? 0;
+				data[at + 2] = palette[p + 2] ?? 0;
+				continue;
+			}
+			if (bitCount === 24) {
+				const o = row + x * 3;
+				data[at] = bytes[o + 2] ?? 0;
+				data[at + 1] = bytes[o + 1] ?? 0;
+				data[at + 2] = bytes[o] ?? 0;
+				continue;
+			}
+			const raw = bitCount === 16 ? (bytes[row + x * 2] ?? 0) | (bytes[row + x * 2 + 1] ?? 0) << 8 : ((bytes[row + x * 4] ?? 0) | (bytes[row + x * 4 + 1] ?? 0) << 8 | (bytes[row + x * 4 + 2] ?? 0) << 16 | (bytes[row + x * 4 + 3] ?? 0) << 24) >>> 0;
+			data[at] = channel(raw, head.redMask, shifts.r);
+			data[at + 1] = channel(raw, head.greenMask, shifts.g);
+			data[at + 2] = channel(raw, head.blueMask, shifts.b);
+			if (alpha) alpha[rowOf(y) * width + x] = channel(raw, head.alphaMask, shifts.a);
+		}
+	}
+	const opaque = alpha?.every((v) => v === 0) ?? true;
+	return {
+		width,
+		height,
+		data,
+		...alpha && !opaque ? { alpha } : {},
+		...density(head)
+	};
+}
+function readDibHeader(bytes, at) {
+	if (bytes.length < at + 4) return void 0;
+	const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const headerBytes = v.getUint32(at, true);
+	const core = headerBytes === CORE_HEADER_BYTES;
+	if (!core && headerBytes < INFO_HEADER_BYTES) return void 0;
+	if (bytes.length < at + headerBytes) return void 0;
+	const width = core ? v.getInt16(at + 4, true) : v.getInt32(at + 4, true);
+	const rawHeight = core ? v.getInt16(at + 6, true) : v.getInt32(at + 8, true);
+	const planes = core ? v.getUint16(at + 6, true) : v.getUint16(at + 12, true);
+	const bitCount = core ? v.getUint16(at + 8, true) : v.getUint16(at + 14, true);
+	const compression = core ? BI_RGB : v.getUint32(at + 16, true);
+	if (planes !== 1) return void 0;
+	if (![
+		1,
+		2,
+		4,
+		8,
+		16,
+		24,
+		32
+	].includes(bitCount)) return void 0;
+	if (compression > 6) return void 0;
+	if (width <= 0 || rawHeight === 0) return void 0;
+	const clrUsed = core ? 0 : v.getUint32(at + 32, true);
+	const inHeader = headerBytes >= 52;
+	const maskBytes = !inHeader && (compression === BI_BITFIELDS || compression === BI_ALPHABITFIELDS) ? compression === BI_ALPHABITFIELDS ? 16 : 12 : 0;
+	const maskAt = inHeader ? at + 40 : at + headerBytes;
+	const stated = compression === BI_BITFIELDS || compression === BI_ALPHABITFIELDS || inHeader;
+	const readMask = (i) => stated && bytes.length >= maskAt + (i + 1) * 4 ? v.getUint32(maskAt + i * 4, true) : 0;
+	const defaults = bitCount === 16 ? [
+		31744,
+		992,
+		31
+	] : [
+		16711680,
+		65280,
+		255
+	];
+	const red = readMask(0) || defaults[0];
+	const green = readMask(1) || defaults[1];
+	const blue = readMask(2) || defaults[2];
+	const alphaMask = headerBytes >= 56 && bytes.length >= maskAt + 16 ? v.getUint32(maskAt + 12, true) : 0;
+	const paletteEntryBytes = core ? 3 : 4;
+	return {
+		headerBytes,
+		maskBytes,
+		paletteBytes: (bitCount <= 8 ? clrUsed || 1 << bitCount : 0) * paletteEntryBytes,
+		paletteEntryBytes,
+		width,
+		height: Math.abs(rawHeight),
+		topDown: rawHeight < 0,
+		bitCount,
+		compression,
+		redMask: red,
+		greenMask: green,
+		blueMask: blue,
+		alphaMask,
+		pxPerMeterX: core ? 0 : v.getInt32(at + 24, true),
+		pxPerMeterY: core ? 0 : v.getInt32(at + 28, true)
+	};
+}
+/** The palette as flat RGB triples, whichever entry width the header uses. */
+function readPalette(bytes, at, head) {
+	const entries = head.paletteBytes / head.paletteEntryBytes;
+	const out = new Uint8Array(entries * 3);
+	for (let i = 0; i < entries; i++) {
+		const o = at + i * head.paletteEntryBytes;
+		out[i * 3] = bytes[o + 2] ?? 0;
+		out[i * 3 + 1] = bytes[o + 1] ?? 0;
+		out[i * 3 + 2] = bytes[o] ?? 0;
+	}
+	return out;
+}
+/** The palette index of one pixel of a 1/2/4/8-bit row. */
+function paletteIndex(bytes, row, x, bitCount) {
+	if (bitCount === 8) return bytes[row + x] ?? 0;
+	const perByte = 8 / bitCount;
+	return (bytes[row + (x / perByte | 0)] ?? 0) >> 8 - bitCount * (x % perByte + 1) & (1 << bitCount) - 1;
+}
+/** How far right a mask's field sits, so its bits can be read off. */
+function maskShift(mask) {
+	if (mask === 0) return 0;
+	let shift = 0;
+	while ((mask >>> shift & 1) === 0) shift++;
+	return shift;
+}
+/** One channel of a packed pixel, stretched to the full byte range. */
+function channel(raw, mask, shift) {
+	if (mask === 0) return 0;
+	const width = (mask >>> shift).toString(2).length;
+	const value = (raw & mask) >>> shift;
+	const max = (1 << width) - 1;
+	return max === 0 ? 0 : Math.round(value * 255 / max);
+}
+/** §biXPelsPerMeter — the resolution the bitmap claims, in pixels per inch. */
+function density(head) {
+	if (head.pxPerMeterX <= 0 || head.pxPerMeterY <= 0) return {};
+	return {
+		dpiX: head.pxPerMeterX * .0254,
+		dpiY: head.pxPerMeterY * .0254
+	};
+}
+/**
+* §BI_RLE8 / §BI_RLE4 — run-length rows of palette indices.
+*
+* Each pair is either a run (a non-zero count and the index to repeat) or an
+* escape (a zero count and a code): 0 ends the row, 1 ends the bitmap, 2 is a
+* delta that skips forward, and anything else is that many literal pixels,
+* padded to a two-byte boundary.
+*
+* @param data   The bytes from the first run onwards.
+* @param width  The bitmap's width in pixels.
+* @param height Its height in rows.
+* @param four   Whether this is the four-bit form, which packs two indices per byte.
+* @returns One palette index per pixel, top row first.
+*/
+function decodeRle(data, width, height, four) {
+	const out = new Uint8Array(width * height);
+	let x = 0;
+	let y = 0;
+	let at = 0;
+	const put = (index) => {
+		if (x < width && y < height) out[y * width + x] = index;
+		x++;
+	};
+	while (at + 1 < data.length && y < height) {
+		const count = data[at];
+		const value = data[at + 1];
+		at += 2;
+		if (count > 0) {
+			for (let i = 0; i < count; i++) put(four ? i % 2 === 0 ? value >> 4 : value & 15 : value);
+			continue;
+		}
+		if (value === 0) {
+			x = 0;
+			y++;
+			continue;
+		}
+		if (value === 1) break;
+		if (value === 2) {
+			x += data[at] ?? 0;
+			y += data[at + 1] ?? 0;
+			at += 2;
+			continue;
+		}
+		const bytesUsed = four ? (value + 1) / 2 | 0 : value;
+		for (let i = 0; i < value; i++) {
+			const byte = data[at + (four ? i / 2 | 0 : i)] ?? 0;
+			put(four ? i % 2 === 0 ? byte >> 4 : byte & 15 : byte);
+		}
+		at += bytesUsed + bytesUsed % 2;
+	}
+	return out;
+}
+//#endregion
+export { decodeBmp, dibToBmp, isBmp };

package/dist/esm/core/converter/facade.d.ts

@@ -9,10 +9,10 @@ import { ProjectSheetOptions } from '../../excel/sheet-to-flow.js';
 /** Options for a {@link Converter.convert} call (extends the docx PDF options). */
 export interface ConvertOptions extends ConvertDocxOptions {
     /**
-     * Target: 'pdf' (default), 'svg' (page-stack preview), 'html'/'docx' (flowed),
-     * or 'xlsx' (the native grid writer — spreadsheet input only).
+     * Target: 'pdf' (default), 'svg' (page-stack preview), 'html'/'md'/'docx'
+     * (flowed), or 'xlsx' (the native grid writer — spreadsheet input only).
      */
-    readonly to?: 'pdf' | 'svg' | 'html' | 'docx' | 'xlsx';
+    readonly to?: 'pdf' | 'svg' | 'html' | 'md' | 'docx' | 'xlsx';
     /**
      * Strict mode (handoff v1 §5): throw ConversionLossError on the first
      * recorded loss instead of returning it in the report.

package/dist/esm/core/converter/facade.js

@@ -14,6 +14,7 @@ import { flowRenderOptions } from "./project.js";
 import { writeDocx } from "../../word/docx-writer.js";
 import { writeXlsx } from "../../excel/xlsx-writer.js";
 import { writeHtml } from "../../html/html-writer.js";
+import { writeMarkdown } from "../../markdown/markdown-writer.js";
 import { writeSvg } from "../../svg/svg-writer.js";
 import { convertDocxToPdf } from "../../word/docx-to-pdf.js";
 import { convertXlsxToPdf } from "../../excel/xlsx-to-pdf.js";
@@ -87,6 +88,17 @@ function createConverter(opts = {}) {
 				losses
 			};
 		}
+		if (to === "md") {
+			const { doc: flow, losses: readLosses } = readToFlow(reader, bytes, rest.now ? { now: rest.now } : void 0);
+			losses.push(...readLosses);
+			const markdown = writeMarkdown(flow);
+			losses.push(...markdown.losses);
+			if (strict && losses.length > 0) throw new ConversionLossError(losses[0]);
+			return {
+				bytes: markdown.bytes,
+				losses
+			};
+		}
 		if (to === "xlsx") {
 			const { doc, losses: readLosses } = reader.read(bytes);
 			losses.push(...readLosses);

package/dist/esm/core/converter/ream.d.ts

@@ -6,9 +6,10 @@ import { Loss } from '../ir/index.js';
 import { DocumentReader } from '../ir/adapters.js';
 import { FlowDoc } from '../ir/flow.js';
 import { SheetDoc } from '../ir/sheet.js';
+import { StreamFilters } from '../../pdf-reader/document.js';
 import { SignatureOptions, StyledRenderOptions } from '../../pdf/index.js';
 /** The output formats {@link Ream.convert} can produce. */
-export type ReamTarget = 'pdf' | 'svg' | 'html' | 'docx' | 'xlsx';
+export type ReamTarget = 'pdf' | 'svg' | 'html' | 'md' | 'docx' | 'xlsx';
 /** Options for {@link Ream.parse}. */
 export interface ReamParseOptions {
     /** Reader registry override; defaults to the built-in docx + xlsx readers. */
@@ -20,6 +21,30 @@ export interface ReamParseOptions {
      * encryption (EP14); an encrypted OOXML package always names a password.
      */
     readonly password?: string;
+    /**
+     * PDF only: what to read out of the page. `'flow'` (the default) reconstructs
+     * a re-flowable document — paragraphs and tables in reading order, from the
+     * structure tree where the file has one. `'positional'` keeps the page as a
+     * page: every line stands where its glyphs stand, beside the rules and fills
+     * the page draws. A form or a drawing needs the second; a report to be edited
+     * or converted to markdown needs the first.
+     */
+    readonly pdfLayout?: 'flow' | 'positional';
+    /**
+     * PDF only: decoders for `/Filter` names the reader does not implement
+     * (§7.4). A filter it cannot undo leaves that stream unread — and when the
+     * unread one is the cross-reference, the whole document is missing — so a
+     * caller who needs such a file supplies the decoder rather than the library
+     * carrying one for every filter anyone might write:
+     *
+     * ```ts
+     * import { brotliDecompressSync } from 'node:zlib';
+     * Ream.parse(pdf, { filters: { BrotliDecode: (b) => brotliDecompressSync(b) } });
+     * ```
+     *
+     * Absent, or throwing, the filter is reported unreadable by name.
+     */
+    readonly filters?: StreamFilters;
 }
 /**
  * Options for {@link Ream.convert} and {@link Ream.convertWithReport}. Extends
@@ -62,6 +87,25 @@ export interface ReamConvertOptions extends Omit<StyledRenderOptions, 'registry'
      * the code resolves, and omitted it is dropped exactly as before.
      */
     readonly fileName?: string;
+    /**
+     * Markdown only: how a picture reaches the output — inlined as a `data:` URI
+     * (the default), named under `./media/` for a caller that writes the bytes
+     * itself, or dropped. See {@link MarkdownWriteOptions}.
+     */
+    readonly images?: 'dataUri' | 'link' | 'drop';
+    /**
+     * Markdown only: what a page break becomes — nothing (the default), or the
+     * `---` thematic break a slide deck wants between its slides. See
+     * {@link MarkdownWriteOptions}.
+     */
+    readonly pageBreaks?: 'rule' | 'drop';
+    /**
+     * Markdown from a SPREADSHEET only: open each sheet with a heading carrying
+     * its tab name. On by default — markdown has no pages to tell one sheet from
+     * the next by, so without them a workbook is a pile of tables with nothing to
+     * say which is which. Set `false` for the bare tables.
+     */
+    readonly sheetNames?: boolean;
 }
 /**
  * The object face of the library: parse a document once into the format-neutral
@@ -121,9 +165,9 @@ export declare class Ream {
     /**
      * Convert the parsed document to `to`, returning the output bytes together with
      * the accumulated {@link Loss} report (read-time losses plus any added while
-     * writing). HTML, DOCX and XLSX are produced straight from the interlayer — no
-     * layout, no fonts, zero I/O; SVG and PDF run the layout engine and resolve
-     * fonts first.
+     * writing). HTML, Markdown, DOCX and XLSX are produced straight from the
+     * interlayer — no layout, no fonts, zero I/O; SVG and PDF run the layout
+     * engine and resolve fonts first.
      *
      * @param to      The target format. `'xlsx'` requires a spreadsheet source.
      * @param options Font resolution and target-specific options.

package/dist/esm/core/converter/ream.js

@@ -12,6 +12,7 @@ import { flowRenderOptions } from "./project.js";
 import { writeDocx } from "../../word/docx-writer.js";
 import { writeXlsx } from "../../excel/xlsx-writer.js";
 import { writeHtml } from "../../html/html-writer.js";
+import { writeMarkdown } from "../../markdown/markdown-writer.js";
 import { writeSvg } from "../../svg/svg-writer.js";
 import { DEFAULT_READERS, resolveFontsViaChain, toFlowDoc } from "./facade.js";
 import { familiesInFlow } from "../fonts/families.js";
@@ -85,7 +86,11 @@ var Ream = class Ream {
 		}
 		const reader = readers.find((r) => r.sniff(source));
 		if (!reader) throw new Error(`Unrecognized document format (readers: ${readers.map((r) => r.id).join(", ")})`);
-		const { doc, losses } = reader.read(source, { password: options.password });
+		const { doc, losses } = reader.read(source, {
+			password: options.password,
+			...options.pdfLayout ? { pdfLayout: options.pdfLayout } : {},
+			...options.filters ? { filters: options.filters } : {}
+		});
 		const sheet = doc.kind === "sheet" ? doc : void 0;
 		return new Ream(toFlowDoc(doc), sheet, losses, bytes, reader.id);
 	}
@@ -107,9 +112,9 @@ var Ream = class Ream {
 	/**
 	* Convert the parsed document to `to`, returning the output bytes together with
 	* the accumulated {@link Loss} report (read-time losses plus any added while
-	* writing). HTML, DOCX and XLSX are produced straight from the interlayer — no
-	* layout, no fonts, zero I/O; SVG and PDF run the layout engine and resolve
-	* fonts first.
+	* writing). HTML, Markdown, DOCX and XLSX are produced straight from the
+	* interlayer — no layout, no fonts, zero I/O; SVG and PDF run the layout
+	* engine and resolve fonts first.
 	*
 	* @param to      The target format. `'xlsx'` requires a spreadsheet source.
 	* @param options Font resolution and target-specific options.
@@ -132,6 +137,22 @@ var Ream = class Ream {
 				losses
 			};
 		}
+		if (to === "md") {
+			const markdown = writeMarkdown(this.sheet && options.sheetNames !== false ? projectSheetDoc(this.sheet, {
+				...options.now ? { now: options.now } : {},
+				...options.fileName ? { fileName: options.fileName } : {},
+				sheetHeadings: true
+			}) : flow, {
+				...options.images ? { images: options.images } : {},
+				...options.pageBreaks ? { pageBreaks: options.pageBreaks } : {}
+			});
+			losses.push(...markdown.losses);
+			this.enforceStrict(options, losses);
+			return {
+				bytes: markdown.bytes,
+				losses
+			};
+		}
 		if (to === "docx") {
 			const docx = writeDocx(flow);
 			losses.push(...docx.losses);

package/dist/esm/core/document-model/index.d.ts

@@ -5,4 +5,4 @@
  *
  * @packageDocumentation
  */
-export type { AbstractNumbering, Alignment, Border, BorderStyle, BodyElement, Comment, CellBorders, CellMerge, DocumentInfo, CellMargins, CellProperties, CellShading, CellDataBar, CellIcon, CellIconShape, CellSparkline, Chart, ChartBlock, ChartDataPoint, ChartLineStyle, ChartMarker, ChartMarkerSymbol, ChartSeries, ChartType, CustomGeometry, CustomPathCmd, DocumentModel, FontFamilyMap, HeaderFooterReference, HeaderFooterType, ImageBlock, ImageCrop, InlineImage, MathAccent, MathBar, MathDelimiter, MathEqArray, MathFraction, MathFunc, MathGroupChr, MathLimit, MathMatrix, MathNary, MathNode, MathRadical, MathRow, MathRun, MathScript, Numbering, NumberingFormat, NumberingInstance, NumberingLevel, PictureBullet, PictureOutline, NumberingReference, PageMargins, PageSize, Paragraph, ParagraphProperties, FrameProperties, RelativeSize, TabStop, Run, RunProperties, RowConditionalFormat, RowProperties, Section, FloatAnchor, SectionColumns, SectionProperties, ShapeBlock, ShapeShadow, ShapeDash, ShapeFill, ShapeFillKind, ShapeGeometry, ShapeGroupChild, ShapeLine, LineEnd, ShapeTextBody, ShapeTransform, Style, StyleSheet, StyleType, Table, TableCell, TableLook, TableProperties, TableStyleCondition, TableStyleConditionType, TableStyleLayer, TableRow, UnderlineStyle, VerticalAlign, } from './types.js';
+export type { AbstractNumbering, Alignment, Border, BorderStyle, BodyElement, Comment, CellBorders, CellMerge, DocumentInfo, CellMargins, CellProperties, CellShading, CellDataBar, CellIcon, CellIconShape, CellSparkline, Chart, ChartBlock, ChartDataPoint, ChartLineStyle, ChartMarker, ChartMarkerSymbol, ChartSeries, ChartType, CustomGeometry, CustomPathCmd, DocumentModel, FontFamilyMap, HeaderFooterReference, HeaderFooterType, ImageBlock, ImageCrop, InlineImage, MathAccent, MathBar, MathDelimiter, MathEqArray, MathFraction, MathFunc, MathGroupChr, MathLimit, MathMatrix, MathNary, MathNode, MathRadical, MathRow, MathRun, MathScript, Numbering, NumberingFormat, NumberingInstance, NumberingLevel, PictureBullet, PictureOutline, NumberingReference, PageMargins, PageSize, Paragraph, ParagraphProperties, FrameProperties, RelativeSize, TabStop, Run, RunProperties, TextOutline, RowConditionalFormat, RowProperties, Section, FloatAnchor, SectionColumns, SectionProperties, ShapeBlock, ShapeShadow, ShapeDash, ShapeFill, ShapeFillKind, ShapeGeometry, ShapeGroupChild, ShapeLine, LineEnd, ShapeTextBody, ShapeTransform, Style, StyleSheet, StyleType, Table, TableCell, TableLook, TableProperties, TableStyleCondition, TableStyleConditionType, TableStyleLayer, TableRow, UnderlineStyle, VerticalAlign, } from './types.js';

package/dist/esm/core/document-model/types.d.ts

@@ -63,6 +63,17 @@ export interface RunProperties {
      * (negative tightens). Word states it in twentieths of a point.
      */
     readonly letterSpacingPt?: Pt;
+    /**
+     * §21.1.2.3.9 `a:rPr/a:ln` — a line drawn round the glyphs themselves, which
+     * DrawingML puts on a run and ISO 32000-1 §9.3.6 calls a text rendering mode
+     * that strokes as well as fills.
+     */
+    readonly textOutline?: TextOutline;
+}
+/** A line drawn round a run's glyphs: its colour and how wide the pen is. */
+export interface TextOutline {
+    readonly colorHex: string;
+    readonly widthPt: Pt;
 }
 /**
  * ECMA-376 Part 1 §17.3.1 — Paragraph Properties (`pPr`). All lengths in
@@ -787,6 +798,13 @@ export interface CellProperties {
      * is a word-processor table's default.
      */
     readonly verticalAlign?: 'top' | 'center' | 'bottom';
+    /**
+     * §17.4.71 `w:textDirection` / §21.1.3.17 `a:tcPr@vert` — the cell's text is
+     * turned a quarter: `vert` reads top-to-bottom (turned clockwise), `vert270`
+     * bottom-to-top. Its lines then run along the cell's HEIGHT and stack across
+     * its width, which is what makes a narrow header column readable.
+     */
+    readonly textDirection?: 'vert' | 'vert270';
 }
 /** §17.4.81 `w:trPr` — a table row's properties: height, split/header flags. */
 export interface RowProperties {
@@ -1043,6 +1061,16 @@ export interface ShapeFill {
         readonly sx: number;
         readonly sy: number;
     };
+    /**
+     * Where the grid of copies is anchored. DrawingML pins it to the shape's
+     * top-left corner (§20.1.8.58 `a:tile @algn`, which defaults to `tl`); an
+     * MS-ODRAW texture fill (§2.3.7.13 `fillOriginX`/`fillOriginY`, both
+     * defaulting to nothing) centres it on the shape instead. It only shows when
+     * the copies do not divide the box evenly — and it shows most when ONE copy
+     * is larger than the box, where the difference is which part of the picture
+     * is visible at all.
+     */
+    readonly tileFromCentre?: boolean;
     /**
      * §20.1.8.14 `a:blipFill` — the picture painted across the shape's box. A
      * DrawingML picture IS a shape with one of these, which is how a `pic:pic`
@@ -1152,6 +1180,12 @@ export interface ShapeTextBody {
      * quarter clockwise), `vert270` bottom-to-top.
      */
     readonly vertical?: 'vert' | 'vert270';
+    /**
+     * §20.1.10.55 `a:bodyPr @upright` — the words stay level however far the
+     * shape is turned. bnc762542.xlsx turns each legend label a quarter and asks
+     * for this, and every reader draws those labels lying flat.
+     */
+    readonly upright?: boolean;
     /**
      * §20.1.10.28 `a:spAutoFit` — the SHAPE follows its text: its height is
      * whatever the text needs, whatever the stated box says.
@@ -1162,6 +1196,26 @@ export interface ShapeTextBody {
      * WordArt is set at whatever size fills the box it was drawn in.
      */
     readonly fitToBox?: boolean;
+    /**
+     * §20.1.9.10 `a:prstTxWarp` — DrawingML WordArt: the preset curve the text is
+     * bent through, and the `a:avLst` `adj` guide when the file states one. The
+     * warped text does not wrap and is stretched to fill the shape's box, so the
+     * size its runs state stops deciding how large it is drawn. `textNoShape` is
+     * not carried: it is the enumeration's "no warp" member, and a body under it
+     * is an ordinary text box.
+     */
+    readonly warp?: {
+        readonly preset: string;
+        readonly adjust?: number;
+    };
+    /**
+     * §20.1.10.42 `a:normAutofit` — the text SHRINKS to fit the box, and only
+     * shrinks: a size that already fits is left alone. PowerPoint writes the
+     * scale it settled on into `@fontScale` and that is applied at parse; this
+     * is for the text that arrives without one, which is every box of a diagram
+     * laid out from its layout part rather than from a cached drawing.
+     */
+    readonly shrinkToFit?: boolean;
     /**
      * `wps:txbx @id` / `wps:linkedTxbx @id @seq` — the chain of boxes this one
      * belongs to. Text that overruns a box continues in the next of its chain;