reamkit 1.24.0 → 1.25.1

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/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
@@ -1169,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.

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

@@ -0,0 +1,17 @@
+import { ResolvedParagraphProperties } from './style-cascade/index.js';
+/**
+ * The heading level (1–6) a paragraph's resolved properties describe, or
+ * `undefined` when it is body text.
+ *
+ * @param resolved The paragraph's fully-resolved properties.
+ * @returns The heading level 1–6, or `undefined` for body text.
+ */
+export declare function headingLevelOf(resolved: ResolvedParagraphProperties): number | undefined;
+/**
+ * The heading level a `"Heading N"` / `"Title"` / `"Subtitle"` style id names,
+ * for a heading style that declares no outline level of its own.
+ *
+ * @param styleId The paragraph's style id, if it has one.
+ * @returns The heading level 1–6, or `undefined` when the id names no heading.
+ */
+export declare function headingLevelFromStyleId(styleId: string | undefined): number | undefined;

package/dist/esm/core/outline.js

@@ -0,0 +1,30 @@
+//#region src/core/outline.ts
+/** The deepest heading level the consuming media can express. */
+var MAX_HEADING_LEVEL = 6;
+/**
+* The heading level (1–6) a paragraph's resolved properties describe, or
+* `undefined` when it is body text.
+*
+* @param resolved The paragraph's fully-resolved properties.
+* @returns The heading level 1–6, or `undefined` for body text.
+*/
+function headingLevelOf(resolved) {
+	const lvl = resolved.outlineLevel;
+	if (lvl !== void 0 && lvl >= 0 && lvl <= 8) return Math.min(lvl + 1, MAX_HEADING_LEVEL);
+	return headingLevelFromStyleId(resolved.styleId);
+}
+/**
+* The heading level a `"Heading N"` / `"Title"` / `"Subtitle"` style id names,
+* for a heading style that declares no outline level of its own.
+*
+* @param styleId The paragraph's style id, if it has one.
+* @returns The heading level 1–6, or `undefined` when the id names no heading.
+*/
+function headingLevelFromStyleId(styleId) {
+	if (styleId === void 0) return void 0;
+	const m = /^Heading\s*([1-9])$/i.exec(styleId);
+	if (m) return Math.min(Number(m[1]), MAX_HEADING_LEVEL);
+	if (/^(Title|Subtitle)$/i.test(styleId)) return 1;
+}
+//#endregion
+export { headingLevelOf };

package/dist/esm/core/style-cascade/resolver.js

@@ -136,6 +136,7 @@ function mergeRun(base, override) {
 		rtl: override.rtl ?? base.rtl,
 		...lang !== void 0 ? { lang } : {},
 		...(override.shadingColorHex ?? base.shadingColorHex) !== void 0 ? { shadingColorHex: override.shadingColorHex ?? base.shadingColorHex } : {},
+		...(override.textOutline ?? base.textOutline) !== void 0 ? { textOutline: override.textOutline ?? base.textOutline } : {},
 		...(override.letterSpacingPt ?? base.letterSpacingPt) !== void 0 ? { letterSpacingPt: override.letterSpacingPt ?? base.letterSpacingPt } : {}
 	};
 }

package/dist/esm/core/style-cascade/types.d.ts

@@ -1,4 +1,4 @@
-import { Alignment, CellBorders, CellShading, FontFamilyMap, FrameProperties, NumberingReference, RunProperties, TabStop, UnderlineStyle, VerticalAlign } from '../document-model/index.js';
+import { Alignment, CellBorders, CellShading, FontFamilyMap, FrameProperties, NumberingReference, RunProperties, TabStop, TextOutline, UnderlineStyle, VerticalAlign } from '../document-model/index.js';
 import { Pt } from '../ir/index.js';
 /**
  * A run's fully-resolved properties: every field required because the cascade
@@ -30,6 +30,8 @@ export interface ResolvedRunProperties {
     readonly shadingColorHex?: string;
     /** §17.3.2.35 — extra space between the run's characters, in points. */
     readonly letterSpacingPt?: Pt;
+    /** §21.1.2.3.9 — a line drawn round the glyphs themselves. */
+    readonly textOutline?: TextOutline;
 }
 /**
  * A paragraph's fully-resolved properties: every field required, the cascade

package/dist/esm/excel/sheet-to-flow.d.ts

@@ -42,6 +42,16 @@ export interface ProjectSheetOptions {
      * supplies it; absent, the code is dropped exactly as before.
      */
     readonly fileName?: string;
+    /**
+     * Open each printed sheet with a heading carrying its NAME.
+     *
+     * Off by default, and deliberately: a printed page shows no tab name — Excel
+     * and Calc both emit it nowhere — so the paginated targets must not see one.
+     * A flowed target has no pages to tell one sheet from the next by, and a
+     * workbook rendered without them is a pile of tables with nothing to say
+     * which is which; markdown asks for this, and gets `# Sheet1`.
+     */
+    readonly sheetHeadings?: boolean;
 }
 /**
  * Project a {@link SheetDoc} into a {@link FlowDoc} (E-SHEET SA2): each grid sheet

package/dist/esm/excel/sheet-to-flow.js

@@ -67,7 +67,20 @@ function projectSheetDoc(sheet, options = {}) {
 		const sheetSection = withHeaderFooter(sectionFromWorksheet(ws.grid), ws, headersFooters, scaleSink.value, sheet.styles.fonts[0]?.sizePt, printed, options.fileName, sheet.themePalette, options.now);
 		if (printed === 0) firstSheetSection = sheetSection;
 		sheetSections.push(sheetSection);
-		if (printed > 0) body.push({
+		if (options.sheetHeadings === true) body.push({
+			kind: "paragraph",
+			paragraph: {
+				properties: {
+					outlineLevel: 0,
+					...printed > 0 ? { pageBreakBefore: true } : {}
+				},
+				runs: [{
+					text: ws.name,
+					properties: {}
+				}]
+			}
+		});
+		else if (printed > 0) body.push({
 			kind: "paragraph",
 			paragraph: PAGE_BREAK_PARAGRAPH
 		});

package/dist/esm/html/html-writer.js

@@ -1,4 +1,5 @@
 import { FEATURES } from "../core/ir/features.js";
+import { headingLevelOf } from "../core/outline.js";
 import { detectImageFormat } from "../core/images.js";
 import { PathBuilder, flipTransform, svgPathData } from "../core/vector.js";
 import { EMPTY_STYLE_SHEET, resolveParagraphProperties, resolveRunProperties } from "../core/style-cascade/resolver.js";
@@ -321,8 +322,8 @@ function emitOneShape(out, shape, ctx) {
 }
 function emitParagraph(out, p, ctx) {
 	const resolved = resolveParagraphProperties(p.properties, EMPTY_STYLE_SHEET);
-	const lvl = resolved.outlineLevel;
-	const tag = lvl !== void 0 && lvl >= 0 && lvl <= 8 ? `h${Math.min(lvl, 5) + 1}` : "p";
+	const lvl = headingLevelOf(resolved);
+	const tag = lvl !== void 0 ? `h${String(lvl)}` : "p";
 	const style = paragraphCss(resolved);
 	const dir = resolved.bidi ? " dir=\"rtl\"" : "";
 	const anchored = (p.bookmarks ?? []).filter((b) => ctx.referencedAnchors.has(b));

package/dist/esm/index.d.ts

@@ -49,6 +49,9 @@ export type { FontProvider, FontRequest, FontAnswer } from './core/fonts/provide
 export { svgWriter, writeSvg } from './svg/svg-writer.js';
 export type { SvgWriteOptions } from './svg/svg-writer.js';
 export { htmlWriter, writeHtml } from './html/html-writer.js';
+export { markdownWriter, writeMarkdown } from './markdown/markdown-writer.js';
+export type { StreamFilter, StreamFilters } from './pdf-reader/document.js';
+export type { MarkdownWriteOptions } from './markdown/markdown-writer.js';
 export { docxWriter, writeDocx } from './word/docx-writer.js';
 export { layoutStyledDocument } from './layout/styled-layout.js';
 export type { LaidOutDocument } from './layout/page-doc.js';

package/dist/esm/index.js

@@ -17,8 +17,9 @@ import { readXlsx, xlsxReader } from "./excel/xlsx-reader.js";
 import { NO_FONT, callerFontProvider, chainProviders, embeddedDocFontProvider, isEmbeddingRestricted, localFontProvider, readOs2FsType, remoteFontProvider } from "./core/fonts/provider.js";
 import { docxWriter, writeDocx } from "./word/docx-writer.js";
 import { htmlWriter, writeHtml } from "./html/html-writer.js";
+import { markdownWriter, writeMarkdown } from "./markdown/markdown-writer.js";
 import { svgWriter, writeSvg } from "./svg/svg-writer.js";
 import { createConverter } from "./core/converter/facade.js";
 import { WrongPasswordError, isEncryptedPackage } from "./core/crypto/offcrypto.js";
 import { Ream } from "./core/converter/ream.js";
-export { ConversionLossError, FEATURES, FontRegistry, NO_FONT, Ream, ResourceStore, WrongPasswordError, callerFontProvider, chainProviders, createConverter, createHyphenator, createLanguageHyphenator, docxReader, docxWriter, eighthPtToPt, embeddedDocFontProvider, emuToPt, fetchFontSet, formatLoss, getHyphenator, halfPtToPt, htmlWriter, inchToPt, isEmbeddingRestricted, isEncryptedPackage, layoutStyledDocument, localFontProvider, mmToPt, parseTtf, pt, pxToPt, readDocx, readOs2FsType, readXlsx, remoteFontProvider, renderStyledPdf, resolveFamilyKey, signPdf, splitPatternBundle, subsetTtf, svgWriter, twipsToPt, writeDocx, writeHtml, writeSvg, xlsxReader };
+export { ConversionLossError, FEATURES, FontRegistry, NO_FONT, Ream, ResourceStore, WrongPasswordError, callerFontProvider, chainProviders, createConverter, createHyphenator, createLanguageHyphenator, docxReader, docxWriter, eighthPtToPt, embeddedDocFontProvider, emuToPt, fetchFontSet, formatLoss, getHyphenator, halfPtToPt, htmlWriter, inchToPt, isEmbeddingRestricted, isEncryptedPackage, layoutStyledDocument, localFontProvider, markdownWriter, mmToPt, parseTtf, pt, pxToPt, readDocx, readOs2FsType, readXlsx, remoteFontProvider, renderStyledPdf, resolveFamilyKey, signPdf, splitPatternBundle, subsetTtf, svgWriter, twipsToPt, writeDocx, writeHtml, writeMarkdown, writeSvg, xlsxReader };

package/dist/esm/layout/page-doc.js

@@ -14,7 +14,7 @@ function paintPlan(commands) {
 			behind.push(c);
 			continue;
 		}
-		if (c.z !== void 0 && c.type !== "line" && c.type !== "fill" && c.type !== "border") {
+		if (c.z !== void 0 && c.type !== "fill" && c.type !== "border" && (c.type !== "line" || c.pictureId !== void 0)) {
 			const key = c.pictureId !== void 0 ? `p${c.pictureId}` : `i${orderOf.size}`;
 			const run = ordered.get(key);
 			if (run) run.push(c);

package/dist/esm/layout/styled-layout.js

@@ -4,6 +4,7 @@ import { shapeText } from "../core/font/opentype-layout.js";
 import { createFontMeasure } from "../core/font/measure.js";
 import { halfPtToPt, pt } from "../core/ir/units.js";
 import { ResourceStore } from "../core/ir/resources.js";
+import { headingLevelOf } from "../core/outline.js";
 import { prepareImage } from "../core/images.js";
 import { PathBuilder, flipTransform } from "../core/vector.js";
 import { isEmf, readEmf } from "../core/metafile/emf.js";
@@ -1049,6 +1050,7 @@ function layoutShapeBlock(shape, options, fontResources, imageResources, content
 	const textLineGaps = /* @__PURE__ */ new Map();
 	let textHeightPt = 0;
 	const vertical = text?.vertical;
+	const upright = text?.upright;
 	const warp = text?.warp;
 	if (text && text.content.length > 0) {
 		const innerWidth = warp ? Number.MAX_SAFE_INTEGER : vertical ? Math.max(1, heightPt - insetTopPt - insetBottomPt) : Math.max(1, widthPt - insetLeftPt - insetRightPt);
@@ -1235,6 +1237,7 @@ function layoutShapeBlock(shape, options, fontResources, imageResources, content
 		insetTopPt,
 		insetBottomPt,
 		anchor: text?.anchor ?? "t",
+		...upright ? { upright } : {},
 		...vertical ? { vertical } : {},
 		...shape.altText ? { altText: shape.altText } : {},
 		...shape.float ? { float: shape.float } : {}
@@ -1885,6 +1888,9 @@ function chartPageItems(laid, x, bottomYUp, pageHeight, structId) {
 var nextPictureId = 1;
 function emitShapeText(sh, x, bottomYUp, sink, pageHeight, figId) {
 	if (sh.textLines.length === 0) return;
+	const turnDeg = sh.upright === true || sh.flipH || sh.flipV ? 0 : -(sh.rotation60k || 0) / 6e4;
+	const centreX = x + sh.widthPt / 2;
+	const centreY = bottomYUp + sh.heightPt / 2;
 	if (sh.vertical) {
 		const up = sh.vertical === "vert270";
 		const innerHeight = Math.max(1, sh.heightPt - sh.insetTopPt - sh.insetBottomPt);
@@ -1894,12 +1900,13 @@ function emitShapeText(sh, x, bottomYUp, sink, pageHeight, figId) {
 			const lineOffset = alignmentOffset(line.resolved.alignment, line.contentWidthPt, innerHeight);
 			const off = lineBaselineOffset(line, line.resolved);
 			const baselineAcross = up ? across + h - off : across + off;
+			const origin = spinAboutCentre(up ? x + baselineAcross : x + sh.widthPt - baselineAcross, up ? bottomYUp + sh.insetBottomPt + lineOffset : bottomYUp + sh.heightPt - sh.insetTopPt - lineOffset, centreX, centreY, turnDeg);
 			sink.push({
 				type: "line",
 				line,
-				originX: pt(up ? x + baselineAcross : x + sh.widthPt - baselineAcross),
-				baselineY: pt(pageHeight - (up ? bottomYUp + sh.insetBottomPt + lineOffset : bottomYUp + sh.heightPt - sh.insetTopPt - lineOffset)),
-				rotationDeg: up ? 90 : -90,
+				originX: pt(origin.x),
+				baselineY: pt(pageHeight - origin.y),
+				rotationDeg: (up ? 90 : -90) + turnDeg,
 				...figId !== void 0 ? { structId: figId } : {}
 			});
 			across += h;
@@ -1939,17 +1946,44 @@ function emitShapeText(sh, x, bottomYUp, sink, pageHeight, figId) {
 			return;
 		}
 		const indentLeft = line.resolved.indentLeft + (line.firstLine ? line.resolved.indentFirstLine : 0);
+		const origin = spinAboutCentre(x + sh.insetLeftPt + indentLeft + lineOffset, textY + lineBaselineOffset(line, line.resolved), centreX, centreY, turnDeg);
 		sink.push({
 			type: "line",
 			line,
-			originX: pt(x + sh.insetLeftPt + indentLeft + lineOffset),
-			baselineY: pt(pageHeight - (textY + lineBaselineOffset(line, line.resolved))),
+			originX: pt(origin.x),
+			baselineY: pt(pageHeight - origin.y),
+			...turnDeg !== 0 ? { rotationDeg: turnDeg } : {},
 			...figId !== void 0 ? { structId: figId } : {}
 		});
 		textY -= sh.textLineGaps?.get(i) ?? 0;
 	});
 }
 /**
+* A point spun about another, counter-clockwise in the y-up page frame.
+*
+* @param px  The point's x.
+* @param py  The point's y (y-up).
+* @param cx  The centre's x.
+* @param cy  The centre's y (y-up).
+* @param deg How far to turn, counter-clockwise; zero returns the point.
+* @returns The turned point.
+*/
+function spinAboutCentre(px, py, cx, cy, deg) {
+	if (deg === 0) return {
+		x: px,
+		y: py
+	};
+	const rad = deg * Math.PI / 180;
+	const cos = Math.cos(rad);
+	const sin = Math.sin(rad);
+	const dx = px - cx;
+	const dy = py - cy;
+	return {
+		x: cx + dx * cos - dy * sin,
+		y: cy + dx * sin + dy * cos
+	};
+}
+/**
 * §20.1.9.10 — place a WordArt body's lines in the block's own frame and hand
 * each one the warp that maps that frame onto the shape's box.
 *
@@ -4339,16 +4373,8 @@ function resolveCellBorders(cellBorders, tableBorders, rowIdx, colStart, colEnd,
 	return out;
 }
 function paragraphStructType(resolved) {
-	const lvl = resolved.outlineLevel;
-	if (lvl !== void 0 && lvl >= 0 && lvl <= 8) return `H${Math.min(lvl, 5) + 1}`;
-	return headingFromStyleId(resolved.styleId) ?? "P";
-}
-function headingFromStyleId(styleId) {
-	if (!styleId) return null;
-	const m = /^Heading\s*([1-9])$/i.exec(styleId);
-	if (m) return `H${Math.min(Number(m[1]), 6)}`;
-	if (/^(Title|Subtitle)$/i.test(styleId)) return "H1";
-	return null;
+	const lvl = headingLevelOf(resolved);
+	return lvl !== void 0 ? `H${String(lvl)}` : "P";
 }
 function dominantParagraphLang(lines) {
 	const counts = /* @__PURE__ */ new Map();

package/dist/esm/markdown/markdown-writer.d.ts

@@ -0,0 +1,41 @@
+import { DocumentWriter, WriteResult } from '../core/ir/adapters.js';
+import { FlowDoc } from '../core/ir/flow.js';
+/** Options for {@link writeMarkdown}. */
+export interface MarkdownWriteOptions {
+    /**
+     * How a picture reaches the output. `'dataUri'` (the default) inlines the
+     * bytes as a `data:` URI, keeping the single-blob {@link WriteResult}
+     * contract and the zero-I/O promise; `'link'` emits a relative
+     * `./media/…` path and records that the bytes were not written anywhere;
+     * `'drop'` omits pictures entirely.
+     */
+    readonly images?: 'dataUri' | 'link' | 'drop';
+    /**
+     * What a page break becomes. `'drop'` (the default) leaves it out and
+     * reports it: a paginated document breaks its pages wherever the layout
+     * needs to, and a rule at every one of them would litter the text. `'rule'`
+     * writes a `---` thematic break instead, which is what a SLIDE DECK wants —
+     * the `.pptx` and `.ppt` readers mark each slide boundary with a page break,
+     * and it is the only structure a deck has.
+     */
+    readonly pageBreaks?: 'rule' | 'drop';
+}
+/**
+ * Render a {@link FlowDoc} to GitHub-Flavored Markdown (ir-design §7).
+ *
+ * A flow medium: no pagination, no layout engine and no fonts, so this is a
+ * pure, zero-I/O transform. Markdown says far less than the document model
+ * does — alignment, indents, colour, font metrics, tab stops and page
+ * geometry have no expression at all — so those are dropped and reported as
+ * {@link Loss} entries, deduplicated so one recurring omission reports once.
+ *
+ * @param flow    The format-neutral interlayer document tree.
+ * @param options Picture handling; see {@link MarkdownWriteOptions}.
+ * @returns The encoded Markdown bytes plus the recorded {@link Loss} list.
+ */
+export declare function writeMarkdown(flow: FlowDoc, options?: MarkdownWriteOptions): WriteResult;
+/**
+ * The flow-medium {@link DocumentWriter} adapter (id `'md'`), wrapping
+ * {@link writeMarkdown}, with the set of {@link FEATURES} it renders.
+ */
+export declare const markdownWriter: DocumentWriter<FlowDoc>;