odf-kit 0.9.6 → 0.9.8

package/README.md

@@ -1,6 +1,6 @@
 # odf-kit
 
-Generate, fill, read, and convert OpenDocument Format files (.odt, .ods) in TypeScript and JavaScript. Convert HTML to ODT. Works in Node.js and browsers. No LibreOffice dependency — pure spec-compliant ODF.
+Generate, fill, read, and convert OpenDocument Format files (.odt, .ods) in TypeScript and JavaScript. Convert HTML, Markdown, and TipTap JSON to ODT. Works in Node.js and browsers. No LibreOffice dependency — pure spec-compliant ODF.
 
 **[Documentation & examples →](https://githubnewbie0.github.io/odf-kit/)**
 
@@ -8,7 +8,7 @@ Generate, fill, read, and convert OpenDocument Format files (.odt, .ods) in Type
 npm install odf-kit
 ```
 
-## Six ways to work with ODF files
+## Nine ways to work with ODF files
 
 ```typescript
 // 1. Build an ODT document from scratch
@@ -41,7 +41,43 @@ const bytes = await htmlToOdt(html, { pageFormat: "A4" });
 ```
 
 ```typescript
-// 3. Build an ODS spreadsheet from scratch
+// 3. Convert Markdown to ODT
+import { markdownToOdt } from "odf-kit";
+
+const markdown = `
+# Meeting Notes
+
+Attendees: **Alice**, Bob, Carol
+
+## Action Items
+
+- Send report by Friday
+- Review budget on Monday
+`;
+const bytes = await markdownToOdt(markdown, { pageFormat: "A4" });
+```
+
+```typescript
+// 4. Convert TipTap/ProseMirror JSON to ODT
+import { tiptapToOdt } from "odf-kit";
+
+// editor.getJSON() returns TipTap JSONContent
+const bytes = await tiptapToOdt(editor.getJSON(), { pageFormat: "A4" });
+
+// With pre-fetched images (e.g. from IPFS or S3)
+const images = { [imageUrl]: await fetchImageBytes(imageUrl) };
+const bytes2 = await tiptapToOdt(editor.getJSON(), { images });
+
+// With custom node handler for app-specific extensions
+const bytes3 = await tiptapToOdt(editor.getJSON(), {
+  unknownNodeHandler: (node, doc) => {
+    if (node.type === "callout") doc.addParagraph(`⚠️ ${extractText(node)}`);
+  },
+});
+```
+
+```typescript
+// 5. Build an ODS spreadsheet from scratch
 import { OdsDocument } from "odf-kit";
 
 const doc = new OdsDocument();
@@ -56,7 +92,7 @@ const bytes = await doc.save();
 ```
 
 ```typescript
-// 4. Fill an existing .odt template with data
+// 6. Fill an existing .odt template with data
 import { fillTemplate } from "odf-kit";
 
 const template = readFileSync("invoice-template.odt");
@@ -74,7 +110,7 @@ writeFileSync("invoice.odt", result);
 ```
 
 ```typescript
-// 5. Read an existing .odt file
+// 7. Read an existing .odt file
 import { readOdt, odtToHtml } from "odf-kit/reader";
 
 const bytes = readFileSync("report.odt");
@@ -83,7 +119,16 @@ const html  = odtToHtml(bytes);            // styled HTML string
 ```
 
 ```typescript
-// 6. Convert .odt to Typst for PDF generation
+// 8. Read an existing .ods spreadsheet
+import { readOds, odsToHtml } from "odf-kit/ods-reader";
+
+const bytes = readFileSync("data.ods");
+const model = readOds(bytes);              // structured model — typed values
+const html  = odsToHtml(bytes);            // HTML table string
+```
+
+```typescript
+// 9. Convert .odt to Typst for PDF generation
 import { odtToTypst } from "odf-kit/typst";
 import { execSync } from "child_process";
 
@@ -103,12 +148,13 @@ npm install odf-kit
 Node.js 22+ required. ESM only. Sub-exports:
 
 ```typescript
-import { OdtDocument, OdsDocument, htmlToOdt, fillTemplate } from "odf-kit"; // build + convert + fill
-import { readOdt, odtToHtml }                                from "odf-kit/reader"; // read + HTML
-import { odtToTypst, modelToTypst }                          from "odf-kit/typst";  // Typst/PDF
+import { OdtDocument, OdsDocument, htmlToOdt, markdownToOdt, tiptapToOdt, fillTemplate } from "odf-kit";
+import { readOdt, odtToHtml } from "odf-kit/odt-reader";
+import { readOds, odsToHtml } from "odf-kit/ods-reader";
+import { odtToTypst, modelToTypst }          from "odf-kit/typst";
 ```
 
-Works in Node.js, browsers, Deno, Bun, and Cloudflare Workers. The only runtime dependency is [fflate](https://github.com/101arrowz/fflate) for ZIP packaging — no transitive dependencies.
+Works in Node.js, browsers, Deno, Bun, and Cloudflare Workers. Runtime dependencies: [fflate](https://github.com/101arrowz/fflate) for ZIP, [marked](https://marked.js.org/) for Markdown parsing.
 
 ---
 
@@ -248,13 +294,6 @@ doc.addParagraph((p) => {
 });
 ```
 
-In a browser, use `fetch()` or a file input instead of `readFile()`:
-
-```javascript
-const response = await fetch("logo.png");
-const logo = new Uint8Array(await response.arrayBuffer());
-```
-
 ### Links and bookmarks
 
 ```typescript
@@ -327,8 +366,6 @@ sheet.addRow([
 
 ### Row and cell formatting
 
-Options on `addRow()` apply to all cells in the row. Per-cell options inside an `OdsCellObject` override the row defaults.
-
 ```typescript
 // Bold header row with background
 sheet.addRow(["Month", "Revenue", "Notes"], {
@@ -340,32 +377,23 @@ sheet.addRow(["Month", "Revenue", "Notes"], {
 // Mixed: row default + per-cell override
 sheet.addRow([
   "January",
-  { value: 12500, type: "float", color: "#006600" },  // green text on this cell only
+  { value: 12500, type: "float", color: "#006600" },
   "On track",
 ], { italic: true });
 ```
 
-Available formatting options: `bold`, `italic`, `fontSize`, `fontFamily`, `color`, `underline`, `backgroundColor`, `border`, `borderTop/Bottom/Left/Right`, `align`, `verticalAlign`, `padding`, `wrap`.
-
 ### Date formatting
 
 ```typescript
-// Document-level default
 doc.setDateFormat("DD/MM/YYYY");  // "YYYY-MM-DD" | "DD/MM/YYYY" | "MM/DD/YYYY"
-
-// Per-row or per-cell override
 sheet.addRow([{ value: new Date("2026-12-25"), type: "date", dateFormat: "MM/DD/YYYY" }]);
 ```
 
-The `office:date-value` attribute always stores the ISO date — display format is separate.
-
 ### Column widths and row heights
 
 ```typescript
 sheet.setColumnWidth(0, "4cm");
 sheet.setColumnWidth(1, "8cm");
-
-sheet.addRow(["Header"]);
 sheet.setRowHeight(0, "1.5cm");
 ```
 
@@ -373,51 +401,90 @@ sheet.setRowHeight(0, "1.5cm");
 
 ```typescript
 const doc = new OdsDocument();
-doc.setMetadata({ title: "Annual Report", creator: "Acme Corp" });
-
-const q1 = doc.addSheet("Q1");
+const q1 = doc.addSheet("Q1").setTabColor("#4CAF50");
+const q2 = doc.addSheet("Q2").setTabColor("#2196F3");
 q1.addRow(["Month", "Revenue"], { bold: true });
 q1.addRow(["January", 12500]);
-q1.addRow(["March", 14800]);
 
-const q2 = doc.addSheet("Q2");
-q2.addRow(["Month", "Revenue"], { bold: true });
-q2.addRow(["April", 15300]);
+const q2sheet = doc.addSheet("Summary");
+q2sheet.addRow(["Total", 27700]);
 
 const bytes = await doc.save();
 ```
 
----
+### Number formats
 
-## Convert: HTML to ODT
+```typescript
+sheet.addRow([{ value: 9999, type: "float", numberFormat: "integer" }]);           // 9,999
+sheet.addRow([{ value: 1234.567, type: "float", numberFormat: "decimal:2" }]);     // 1,234.57
+sheet.addRow([{ value: 0.1234, type: "percentage", numberFormat: "percentage" }]); // 12.34%
+sheet.addRow([{ value: 0.075, type: "percentage", numberFormat: "percentage:1" }]);// 7.5%
+sheet.addRow([{ value: 1234.56, type: "currency", numberFormat: "currency:EUR" }]);// €1,234.56
+sheet.addRow([{ value: 99.99, type: "currency", numberFormat: "currency:USD:0" }]);// $100
 
-`htmlToOdt()` converts an HTML string to a `.odt` file. This is the missing conversion direction — the entire industry converts ODT→HTML for web display. `htmlToOdt` brings content back into the open standard with no LibreOffice, no Pandoc, and no server-side dependencies.
+// Row-level number format — applies to all cells in the row
+sheet.addRow([1000, 2000, 3000], { numberFormat: "integer" });
+```
 
-The primary use case is Nextcloud Text ODT export: Nextcloud Text produces clean, well-formed HTML that maps directly to ODT elements.
+### Merged cells
 
-### Basic usage
+```typescript
+// Span across 3 columns
+sheet.addRow([{ value: "Q1 Sales Report", type: "string", colSpan: 3, bold: true }]);
+sheet.addRow(["Region", "Units", "Revenue"]);
+
+// Span across 2 rows
+sheet.addRow([{ value: "North", type: "string", rowSpan: 2 }, "Jan", 12500]);
+sheet.addRow(["Feb", 14200]); // "North" continues from above
+
+// Combined colSpan + rowSpan
+sheet.addRow([{ value: "Big Cell", type: "string", colSpan: 2, rowSpan: 2 }, "C"]);
+```
+
+### Freeze rows and columns
 
 ```typescript
-import { htmlToOdt } from "odf-kit";
+// Freeze the header row
+sheet.addRow(["Name", "Amount", "Date"], { bold: true });
+sheet.freezeRows(1);
 
-const html = `
-  <h1>Meeting Notes</h1>
-  <p>Attendees: <strong>Alice</strong>, Bob, Carol</p>
-  <h2>Action Items</h2>
-  <table>
-    <tr><th>Owner</th><th>Task</th><th>Due</th></tr>
-    <tr><td>Alice</td><td>Send report</td><td>Friday</td></tr>
-  </table>
-`;
+// Freeze first column
+sheet.freezeColumns(1);
+
+// Both
+sheet.freezeRows(1).freezeColumns(1);
+```
 
-// A4 is the default — correct for Europe and most of the world
-const bytes = await htmlToOdt(html);
+### Hyperlinks in cells
 
-// US letter
-const bytes = await htmlToOdt(html, { pageFormat: "letter" });
+```typescript
+sheet.addRow([{
+  value: "odf-kit on GitHub",
+  type: "string",
+  href: "https://github.com/GitHubNewbie0/odf-kit",
+}]);
+```
+
+### Sheet tab color
+
+```typescript
+doc.addSheet("Q1").setTabColor("#4CAF50");  // green
+doc.addSheet("Q2").setTabColor("#2196F3");  // blue
+doc.addSheet("Q3").setTabColor("#F44336");  // red
 ```
 
-Both fragment HTML (`<h1>...</h1><p>...</p>`) and full documents (`<html><body>...</body></html>`) are accepted.
+---
+
+## Convert: HTML to ODT
+
+`htmlToOdt()` converts an HTML string to a `.odt` file. The primary use case is Nextcloud Text ODT export and any web-based editor that stores content as HTML.
+
+```typescript
+import { htmlToOdt } from "odf-kit";
+
+const bytes = await htmlToOdt(html);                          // A4 default
+const bytes = await htmlToOdt(html, { pageFormat: "letter" }); // US letter
+```
 
 ### Page formats
 
@@ -429,31 +496,70 @@ Both fragment HTML (`<h1>...</h1><p>...</p>`) and full documents (`<html><body>.
 | `"A3"` | 29.7 × 42 cm | 2.5 cm | Large format |
 | `"A5"` | 14.8 × 21 cm | 2 cm | Small booklets |
 
+### Supported HTML elements
+
+**Block:** `<h1>`–`<h6>`, `<p>`, `<ul>`, `<ol>`, `<li>` (nested), `<table>` / `<tr>` / `<td>` / `<th>`, `<blockquote>`, `<pre>`, `<hr>`, `<figure>` / `<figcaption>`, `<div>` / `<section>` (transparent).
+
+**Inline:** `<strong>`, `<em>`, `<u>`, `<s>`, `<sup>`, `<sub>`, `<a href>`, `<code>`, `<mark>`, `<span style="">`, `<br>`.
+
+---
+
+## Convert: Markdown to ODT
+
+`markdownToOdt()` converts any CommonMark Markdown string to ODT. Accepts the same options as `htmlToOdt()`.
+
 ```typescript
-// Landscape with custom margins
-const bytes = await htmlToOdt(html, {
-  pageFormat: "A4",
-  orientation: "landscape",
-  marginTop: "1.5cm",
-  marginBottom: "1.5cm",
-});
+import { markdownToOdt } from "odf-kit";
 
-// With metadata
-const bytes = await htmlToOdt(html, {
+const bytes = await markdownToOdt(markdownString, { pageFormat: "A4" });
+const bytes = await markdownToOdt(markdownString, {
   pageFormat: "letter",
-  metadata: { title: "Meeting Notes", creator: "Alice" },
+  metadata: { title: "My Document", creator: "Alice" },
 });
 ```
 
-### Supported HTML elements
+Supports headings, paragraphs, bold, italic, lists (nested), tables, links, blockquotes, code blocks, and horizontal rules.
+
+---
+
+## Convert: TipTap/ProseMirror JSON to ODT
+
+`tiptapToOdt()` converts TipTap/ProseMirror `JSONContent` directly to ODT. No dependency on `@tiptap/core` — walks the JSON tree as a plain object. This is the most direct integration path for any TipTap-based editor (dDocs, Outline, Novel, BlockNote, etc.).
 
-**Block:** `<h1>`–`<h6>`, `<p>`, `<ul>`, `<ol>`, `<li>` (nested lists supported), `<table>` / `<thead>` / `<tbody>` / `<tr>` / `<td>` / `<th>`, `<blockquote>` (indented), `<pre>` (monospace), `<hr>` (paragraph with bottom border), `<figure>` / `<figcaption>`, `<div>` / `<section>` / `<article>` / `<main>` (transparent).
+**Conversion happens entirely in your environment.** No document content is sent to external services — unlike cloud-based ODT conversion APIs. Suitable for sensitive documents, air-gapped environments, and applications with GDPR or data sovereignty requirements.
 
-**Inline:** `<strong>` / `<b>`, `<em>` / `<i>`, `<u>`, `<s>` / `<del>`, `<sup>`, `<sub>`, `<a href>`, `<code>` (monospace), `<mark>` (highlight), `<span style="">` (inline CSS), `<br>` (line break).
+```typescript
+import { tiptapToOdt } from "odf-kit";
+
+// Basic usage
+const bytes = await tiptapToOdt(editor.getJSON(), { pageFormat: "A4" });
+
+// With pre-fetched images
+const images = {
+  "https://example.com/photo.jpg": jpegBytes,
+  "ipfs://Qm...": ipfsImageBytes,
+};
+const bytes = await tiptapToOdt(editor.getJSON(), { images });
+
+// With custom node handler for app-specific extensions
+const bytes = await tiptapToOdt(editor.getJSON(), {
+  unknownNodeHandler: (node, doc) => {
+    if (node.type === "callout") {
+      doc.addParagraph(`⚠️ ${node.content?.[0]?.content?.[0]?.text ?? ""}`)
+    }
+  },
+});
+```
+
+### Supported TipTap nodes
 
-**Inline CSS on `<span>`:** `color`, `font-size` (px/pt/em), `font-family`, `font-weight`, `font-style`, `text-decoration`.
+**Block:** `doc`, `paragraph`, `heading` (1–6), `bulletList`, `orderedList`, `listItem` (nested), `blockquote`, `codeBlock`, `horizontalRule`, `hardBreak`, `image`, `table`, `tableRow`, `tableCell`, `tableHeader`.
 
-**Images:** skipped in v1 — v2 will add an `images` option for pre-fetched bytes.
+**Marks:** `bold`, `italic`, `underline`, `strike`, `code`, `link`, `textStyle` (color, fontSize, fontFamily), `highlight`, `superscript`, `subscript`.
+
+**Images:** Data URIs are decoded and embedded directly. Other URLs are looked up in the `images` option. Unknown URLs emit a `[Image: alt]` placeholder paragraph.
+
+**Unknown nodes:** Silently skipped by default. Provide `unknownNodeHandler` to handle custom extensions.
 
 ---
 
@@ -484,15 +590,6 @@ Product: {product} — Qty: {qty} — Price: {price}
 {/items}
 ```
 
-```typescript
-fillTemplate(template, {
-  items: [
-    { product: "Widget", qty: 5, price: "$125" },
-    { product: "Gadget", qty: 3, price: "$120" },
-  ],
-});
-```
-
 ### Conditionals
 
 ```
@@ -501,13 +598,7 @@ You qualify for a {percent}% discount!
 {/showDiscount}
 ```
 
-Falsy values (`false`, `null`, `undefined`, `0`, `""`, `[]`) remove the block. Truthy values include it. Loops and conditionals nest freely.
-
-### How it works
-
-LibreOffice often fragments typed text like `{name}` across multiple XML elements due to editing history or spell check. odf-kit handles this automatically with a two-pass pipeline: first it reassembles fragmented placeholders, then replaces them with data. Headers and footers in `styles.xml` are processed alongside the document body.
-
-Template syntax follows [Mustache](https://mustache.github.io/) conventions, established for document templating by [docxtemplater](https://docxtemplater.com/). odf-kit's engine is a clean-room implementation built for ODF — no code from either project was used.
+Falsy values (`false`, `null`, `undefined`, `0`, `""`, `[]`) remove the block. Truthy values include it.
 
 ---
 
@@ -516,94 +607,133 @@ Template syntax follows [Mustache](https://mustache.github.io/) conventions, est
 `odf-kit/reader` parses `.odt` files into a structured model and renders to HTML.
 
 ```typescript
-import { readOdt, odtToHtml } from "odf-kit/reader";
-import { readFileSync } from "fs";
+import { readOdt, odtToHtml } from "odf-kit/odt-reader";
 
 const bytes = readFileSync("report.odt");
-
-// Structured model
 const model = readOdt(bytes);
-console.log(model.body);        // BodyNode[]
-console.log(model.pageLayout);  // PageLayout
-console.log(model.header);      // HeaderFooterContent
-
-// Styled HTML
-const html = odtToHtml(bytes);
+const html  = odtToHtml(bytes);
 
-// With tracked changes mode
+// Tracked changes
 const final    = odtToHtml(bytes, {}, { trackedChanges: "final" });
 const original = odtToHtml(bytes, {}, { trackedChanges: "original" });
 const marked   = odtToHtml(bytes, {}, { trackedChanges: "changes" });
 ```
 
-### What the reader extracts
+---
 
-**Tier 1 — Structure:** paragraphs, headings, tables, lists, images, notes, bookmarks, fields, hyperlinks, tracked changes (all three ODF-defined modes: final/original/changes).
+## Read: ODS Spreadsheets
 
-**Tier 2 — Styling:** span styles (bold, italic, font, color, highlight, underline, strikethrough, superscript, subscript), image float/wrap mode, footnotes/endnotes, cell and row background colors, style inheritance and resolution.
+`odf-kit/ods-reader` parses `.ods` files into a structured model and renders to HTML.
 
-**Tier 3 — Layout:** paragraph styles (alignment, margins, padding, line height), table column widths, page geometry (size, margins, orientation), headers and footers (all four zones: default, first page, left/right), sections, tracked change metadata (author, date).
+```typescript
+import { readOds, odsToHtml } from "odf-kit/ods-reader";
+import { readFileSync } from "fs";
+
+const bytes = readFileSync("data.ods");
+
+// Structured model — typed JavaScript values
+const model = readOds(bytes);
+for (const sheet of model.sheets) {
+  console.log(sheet.name);
+  for (const row of sheet.rows) {
+    for (const cell of row.cells) {
+      console.log(cell.colIndex, cell.type, cell.value);
+      // e.g. 0 "float" 1234.56
+      // e.g. 1 "string" "Hello"
+      // e.g. 2 "date" Date { 2026-01-15 }
+      // e.g. 3 "formula" 100  (cell.formula = "=SUM(A1:A10)")
+      // e.g. 4 "covered" null (part of a merged cell)
+    }
+  }
+}
 
-### Document model types
+// HTML table
+const html = odsToHtml(bytes);
+
+// Fast mode — values only, no formatting
+const model2 = readOds(bytes, { includeFormatting: false });
+```
+
+### Cell types
+
+| Type | `value` | Notes |
+|------|---------|-------|
+| `"string"` | `string` | |
+| `"float"` | `number` | Includes percentage and currency cells |
+| `"date"` | `Date` (UTC) | |
+| `"boolean"` | `boolean` | |
+| `"formula"` | cached result | `cell.formula` has original string e.g. `"=SUM(A1:A10)"` |
+| `"empty"` | `null` | |
+| `"covered"` | `null` | Covered by a merge — correct `colIndex` always maintained |
+
+### Merged cells
+
+Primary cells have `colSpan` and/or `rowSpan`. Covered cells have `type: "covered"`, `value: null`, and the correct physical `colIndex` — no offset confusion.
 
 ```typescript
-import type {
-  OdtDocumentModel,
-  BodyNode,          // ParagraphNode | HeadingNode | TableNode | ListNode |
-                     // ImageNode | SectionNode | TrackedChangeNode
-  ParagraphNode,
-  HeadingNode,
-  TableNode,
-  ListNode,
-  ImageNode,
-  SectionNode,
-  TrackedChangeNode,
-  InlineNode,        // TextNode | SpanNode | ImageNode | NoteNode |
-                     // BookmarkNode | FieldNode | LinkNode
-  PageLayout,
-  ReadOdtOptions,
-} from "odf-kit/reader";
+// A1:C1 merged — reading row 0:
+// cell 0: { type: "string", value: "Header", colSpan: 3 }
+// cell 1: { type: "covered", value: null, colIndex: 1 }
+// cell 2: { type: "covered", value: null, colIndex: 2 }
+// cell 3: { type: "string", value: "D1", colIndex: 3 }  ← always correct
 ```
 
 ---
 
 ## Typst: ODT to PDF
 
-`odf-kit/typst` converts `.odt` files to [Typst](https://typst.app/) markup for PDF generation. No LibreOffice, no headless browser — just the Typst CLI.
-
 ```typescript
 import { odtToTypst, modelToTypst } from "odf-kit/typst";
-import { readFileSync, writeFileSync } from "fs";
-import { execSync } from "child_process";
 
-// Convenience wrapper — ODT bytes → Typst string
 const typst = odtToTypst(readFileSync("letter.odt"));
 writeFileSync("letter.typ", typst);
 execSync("typst compile letter.typ letter.pdf");
-
-// From a model (if you already have one from readOdt)
-import { readOdt } from "odf-kit/reader";
-const model  = readOdt(readFileSync("letter.odt"));
-const typst2 = modelToTypst(model);
 ```
 
-Both functions return a plain string — no filesystem access, no CLI dependency, no side effects. You control how the `.typ` file is compiled. Works in any JavaScript environment including browsers.
+---
+
+## API Reference
 
-### Tracked changes in Typst output
+### htmlToOdt / markdownToOdt
 
 ```typescript
-import type { TypstEmitOptions } from "odf-kit/typst";
+function htmlToOdt(html: string, options?: HtmlToOdtOptions): Promise<Uint8Array>
+function markdownToOdt(markdown: string, options?: HtmlToOdtOptions): Promise<Uint8Array>
 
-const options: TypstEmitOptions = { trackedChanges: "final" };     // accepted text only
-const options2: TypstEmitOptions = { trackedChanges: "original" }; // before changes
-const options3: TypstEmitOptions = { trackedChanges: "changes" };  // annotated markup
+interface HtmlToOdtOptions {
+  pageFormat?: "A4" | "letter" | "legal" | "A3" | "A5"; // default: "A4"
+  orientation?: "portrait" | "landscape";
+  marginTop?: string;
+  marginBottom?: string;
+  marginLeft?: string;
+  marginRight?: string;
+  metadata?: { title?: string; creator?: string; description?: string };
+}
 ```
 
-See the [complete ODT to PDF with Typst guide](https://githubnewbie0.github.io/odf-kit/guides/odt-to-typst-pdf.html) for installation, font setup, and real-world examples.
+### tiptapToOdt
 
----
+```typescript
+function tiptapToOdt(json: TiptapNode, options?: TiptapToOdtOptions): Promise<Uint8Array>
 
-## API Reference
+interface TiptapNode {
+  type: string;
+  text?: string;
+  attrs?: Record<string, unknown>;
+  content?: TiptapNode[];
+  marks?: TiptapMark[];
+}
+
+interface TiptapMark {
+  type: string;
+  attrs?: Record<string, unknown>;
+}
+
+interface TiptapToOdtOptions extends HtmlToOdtOptions {
+  images?: Record<string, Uint8Array>;
+  unknownNodeHandler?: (node: TiptapNode, doc: OdtDocument) => void;
+}
+```
 
 ### OdtDocument
 
@@ -621,56 +751,20 @@ See the [complete ODT to PDF with Typst guide](https://githubnewbie0.github.io/o
 | `addPageBreak()` | Insert page break |
 | `save()` | Generate `.odt` as `Promise<Uint8Array>` |
 
-### OdsDocument
+### OdsDocument / OdsSheet
 
 | Method | Description |
 |--------|-------------|
-| `setMetadata(options)` | Set title, creator, description |
-| `setDateFormat(format)` | Set default date display format (`"YYYY-MM-DD"` \| `"DD/MM/YYYY"` \| `"MM/DD/YYYY"`) |
-| `addSheet(name)` | Add a sheet tab — returns `OdsSheet` |
-| `save()` | Generate `.ods` as `Promise<Uint8Array>` |
-
-### OdsSheet
-
-| Method | Description |
-|--------|-------------|
-| `addRow(values, options?)` | Add a row of cells with optional formatting defaults |
-| `setColumnWidth(colIndex, width)` | Set column width (e.g. `"4cm"`) |
-| `setRowHeight(rowIndex, height)` | Set row height (e.g. `"1cm"`) |
-
-### OdsCellValue
-
-```typescript
-type OdsCellValue =
-  | string          // → string cell
-  | number          // → float cell
-  | boolean         // → boolean cell
-  | Date            // → date cell
-  | null            // → empty cell
-  | undefined       // → empty cell
-  | OdsCellObject;  // → explicit type (required for formulas)
-
-interface OdsCellObject extends OdsCellOptions {
-  value: string | number | boolean | Date | null;
-  type: "string" | "float" | "date" | "boolean" | "formula";
-}
-```
-
-### htmlToOdt
-
-```typescript
-function htmlToOdt(html: string, options?: HtmlToOdtOptions): Promise<Uint8Array>
-
-interface HtmlToOdtOptions {
-  pageFormat?: "A4" | "letter" | "legal" | "A3" | "A5"; // default: "A4"
-  orientation?: "portrait" | "landscape";
-  marginTop?: string;
-  marginBottom?: string;
-  marginLeft?: string;
-  marginRight?: string;
-  metadata?: { title?: string; creator?: string; description?: string };
-}
-```
+| `doc.setMetadata(options)` | Set title, creator, description |
+| `doc.setDateFormat(format)` | Set default date display format |
+| `doc.addSheet(name)` | Add a sheet tab — returns `OdsSheet` |
+| `doc.save()` | Generate `.ods` as `Promise<Uint8Array>` |
+| `sheet.addRow(values, options?)` | Add a row of cells |
+| `sheet.setColumnWidth(index, width)` | Set column width |
+| `sheet.setRowHeight(index, height)` | Set row height |
+| `sheet.freezeRows(N?)` | Freeze top N rows (default 1) |
+| `sheet.freezeColumns(N?)` | Freeze left N columns (default 1) |
+| `sheet.setTabColor(color)` | Set sheet tab color |
 
 ### fillTemplate
 
@@ -678,31 +772,11 @@ interface HtmlToOdtOptions {
 function fillTemplate(templateBytes: Uint8Array, data: TemplateData): Uint8Array
 ```
 
-`TemplateData` is `Record<string, unknown>` — any JSON-serializable value.
-
 | Syntax | Description |
 |--------|-------------|
 | `{tag}` | Replace with value |
-| `{object.property}` | Dot notation for nested objects |
-| `{#tag}...{/tag}` | Loop (array) or conditional (truthy/falsy) |
-
-### readOdt / odtToHtml
-
-```typescript
-function readOdt(bytes: Uint8Array, options?: ReadOdtOptions): OdtDocumentModel
-function odtToHtml(
-  bytes: Uint8Array,
-  htmlOptions?: HtmlOptions,
-  readOptions?: ReadOdtOptions
-): string
-```
-
-### odtToTypst / modelToTypst
-
-```typescript
-function odtToTypst(bytes: Uint8Array, options?: TypstEmitOptions): string
-function modelToTypst(model: OdtDocumentModel, options?: TypstEmitOptions): string
-```
+| `{object.property}` | Dot notation |
+| `{#tag}...{/tag}` | Loop or conditional |
 
 ### TextFormatting
 
@@ -710,9 +784,9 @@ function modelToTypst(model: OdtDocumentModel, options?: TypstEmitOptions): stri
 {
   bold?: boolean,
   italic?: boolean,
-  fontSize?: number | string,    // 12 or "12pt"
+  fontSize?: number | string,
   fontFamily?: string,
-  color?: string,                // "#FF0000" or "red"
+  color?: string,
   underline?: boolean,
   strikethrough?: boolean,
   superscript?: boolean,
@@ -721,37 +795,6 @@ function modelToTypst(model: OdtDocumentModel, options?: TypstEmitOptions): stri
 }
 ```
 
-### TableOptions / CellOptions
-
-```typescript
-// TableOptions
-{ columnWidths?: string[], border?: string }
-
-// CellOptions (extends TextFormatting)
-{
-  backgroundColor?: string,
-  border?: string,
-  borderTop?: string, borderBottom?: string,
-  borderLeft?: string, borderRight?: string,
-  colSpan?: number,
-  rowSpan?: number,
-}
-```
-
-### PageLayout
-
-```typescript
-{
-  width?: string,           // "21cm" (A4 default)
-  height?: string,          // "29.7cm"
-  orientation?: "portrait" | "landscape",
-  marginTop?: string,       // "2cm" default
-  marginBottom?: string,
-  marginLeft?: string,
-  marginRight?: string,
-}
-```
-
 ---
 
 ## Platform support
@@ -763,7 +806,7 @@ function modelToTypst(model: OdtDocumentModel, options?: TypstEmitOptions): stri
 | Deno, Bun | ✅ Full |
 | Cloudflare Workers | ✅ Full |
 
-ESM only. Zero Node-specific APIs in the library source — enforced at the TypeScript level, guaranteeing cross-platform compatibility.
+ESM only. Zero Node-specific APIs in the library source — enforced at the TypeScript level.
 
 ---
 
@@ -771,11 +814,11 @@ ESM only. Zero Node-specific APIs in the library source — enforced at the Type
 
 **ODF is the ISO standard (ISO/IEC 26300) for documents.** It's the default format for LibreOffice, mandatory for many governments and public sector organisations, and the best choice for long-term document preservation.
 
-- **Single runtime dependency** — fflate for ZIP. No transitive dependencies.
+- **Two runtime dependencies** — fflate (ZIP) and marked (Markdown parsing). No transitive dependencies.
 - **Spec-compliant output** — every generated file passes the OASIS ODF validator. Enforced on every commit by CI.
 - **Multiple ODF formats** — ODT documents and ODS spreadsheets from the same library.
-- **Six complete capability modes** — build ODT, build ODS, convert HTML→ODT, fill templates, read, convert to Typst/PDF. Not just generation.
-- **HTML→ODT conversion** — the missing direction. Bring web content back into the ISO open standard with no LibreOffice or Pandoc dependency.
+- **Eight complete capability modes** — build ODT, build ODS, convert HTML→ODT, convert Markdown→ODT, convert TipTap JSON→ODT, fill templates, read, convert to Typst/PDF.
+- **TipTap/ProseMirror integration** — direct JSON→ODT conversion for any TipTap-based editor, no intermediate HTML step.
 - **Zero-dependency Typst emitter** — the only JavaScript library with built-in ODT→Typst conversion for PDF generation.
 - **TypeScript-first** — full types across all sub-exports.
 - **Apache 2.0** — use freely in commercial and open source projects.
@@ -787,8 +830,10 @@ ESM only. Zero Node-specific APIs in the library source — enforced at the Type
 | Feature | odf-kit | simple-odf | docxtemplater |
 |---------|---------|------------|---------------|
 | Generate .odt from scratch | ✅ | ⚠️ flat XML only | ❌ |
-| Generate .ods from scratch | ✅ | ❌ | ❌ |
+| Generate .ods from scratch | ✅ merged cells, freeze, number formats, hyperlinks | ❌ | ❌ |
 | Convert HTML → ODT | ✅ | ❌ | ❌ |
+| Convert Markdown → ODT | ✅ | ❌ | ❌ |
+| Convert TipTap JSON → ODT | ✅ | ❌ | ❌ |
 | Fill .odt templates | ✅ | ❌ | ✅ .docx only |
 | Read .odt files | ✅ | ❌ | ❌ |
 | Convert to HTML | ✅ | ❌ | ❌ |
@@ -801,29 +846,35 @@ ESM only. Zero Node-specific APIs in the library source — enforced at the Type
 
 ## Specification compliance
 
-odf-kit targets ODF 1.2 (ISO/IEC 26300). Generated files include proper ZIP packaging (mimetype stored uncompressed as the first entry per spec), manifest, metadata, and all required namespace declarations. The OASIS ODF validator runs on every push via GitHub Actions.
+odf-kit targets ODF 1.2 (ISO/IEC 26300). Generated files include proper ZIP packaging, manifest, metadata, and all required namespace declarations. The OASIS ODF validator runs on every push via GitHub Actions.
 
 ---
 
 ## Version history
 
-**v0.9.2** — `htmlToOdt()`: HTML→ODT conversion with page format presets (A4/letter/legal/A3/A5), full inline formatting, lists, tables, blockquote, pre, hr, and inline CSS. `addLineBreak()` on `ParagraphBuilder`. `borderBottom` on `ParagraphOptions`. 769 tests passing.
+**v0.9.8** — ODS reader: `readOds()` and `odsToHtml()` via `odf-kit/ods-reader`. Typed values, formula strings, merged cell handling, formatting, metadata. `odf-kit/odt-reader` alias added. 889 tests passing.
 
-**v0.9.0** — ODS spreadsheet generation: `OdsDocument`, multiple sheets, auto-typed cells, formulas, date formatting (ISO/DMY/MDY), row and cell formatting, column widths, row heights, style deduplication. 707 tests passing.
+**v0.9.7** — ODS enhancements: number formats (integer, decimal:N, percentage, currency), merged cells (colSpan/rowSpan), freeze rows/columns, hyperlinks in cells, sheet tab color. 849 tests passing.
 
-**v0.8.0** — `odf-kit/typst` sub-export: `odtToTypst()` and `modelToTypst()`. Zero-dependency ODT→Typst emitter for PDF generation via Typst CLI. 650+ tests passing.
+**v0.9.6** — `tiptapToOdt()`: TipTap/ProseMirror JSON→ODT conversion. `TiptapNode`, `TiptapMark`, `TiptapToOdtOptions` types. `unknownNodeHandler` for custom extensions. Image support via pre-fetched bytes map. 817 tests passing.
 
-**v0.7.0** — Tier 3 reader: paragraph styles, page geometry, headers/footers (all four zones), sections, tracked changes (all three ODF modes). `SectionNode`, `TrackedChangeNode` added to `BodyNode` union.
+**v0.9.5** — `markdownToOdt()`: Markdown→ODT via marked + htmlToOdt. 786 tests passing.
 
-**v0.6.0** — Tier 2 reader: span styles, image float/wrap, footnotes/endnotes, bookmarks, fields, cell/row styles, full style inheritance.
+**v0.9.4** — ODS datetime auto-detection (nonzero UTC time → datetime format). ODS formula `xmlns:of` namespace fix (Err:510 resolved).
 
-**v0.5.0** — `odf-kit/reader` sub-export: `readOdt()`, `odtToHtml()`. Tier 1: paragraphs, headings, tables, lists, images, notes, tracked changes.
+**v0.9.2** — `htmlToOdt()`: HTML→ODT conversion with page format presets, full inline formatting, lists, tables, blockquote, pre, hr, and inline CSS. 769 tests passing.
 
-**v0.4.0** — Generation repair: 16 spec compliance gaps fixed, OASIS ODF validator added to CI.
+**v0.9.0** — ODS spreadsheet generation: `OdsDocument`, multiple sheets, auto-typed cells, formulas, date formatting, row and cell formatting, column widths, row heights. 707 tests passing.
 
-**v0.3.0** — Template engine: loops, conditionals, dot notation, automatic XML fragment healing.
+**v0.8.0** — `odf-kit/typst`: `odtToTypst()` and `modelToTypst()`. Zero-dependency ODT→Typst emitter for PDF generation.
 
-**v0.2.0** — Migrated to fflate (zero transitive dependencies).
+**v0.7.0** — Tier 3 reader: paragraph styles, page geometry, headers/footers, sections, tracked changes (all three ODF modes).
+
+**v0.6.0** — Tier 2 reader: span styles, image float/wrap, footnotes/endnotes, bookmarks, fields, cell/row styles.
+
+**v0.5.0** — `odf-kit/reader`: `readOdt()`, `odtToHtml()`. Tier 1 parsing.
+
+**v0.3.0** — Template engine: loops, conditionals, dot notation, automatic XML fragment healing.
 
 **v0.1.0** — Programmatic ODT creation: text, tables, page layout, lists, images, links, bookmarks.
 
@@ -831,8 +882,6 @@ odf-kit targets ODF 1.2 (ISO/IEC 26300). Generated files include proper ZIP pack
 
 ## Guides
 
-Full walkthroughs and real-world examples on the documentation site:
-
 - [Generate ODT files in Node.js](https://githubnewbie0.github.io/odf-kit/guides/generate-odt-nodejs.html)
 - [Generate ODT files in the browser](https://githubnewbie0.github.io/odf-kit/guides/generate-odt-browser.html)
 - [Fill ODT templates in JavaScript](https://githubnewbie0.github.io/odf-kit/guides/fill-odt-template-javascript.html)
@@ -860,21 +909,6 @@ npm run build
 npm test
 ```
 
-Full pipeline before submitting a PR:
-
-```bash
-npm run format:check
-npm run lint
-npm run build
-npm test
-```
-
----
-
-## Acknowledgments
-
-Template syntax follows [Mustache](https://mustache.github.io/) conventions, established for document templating by [docxtemplater](https://docxtemplater.com/). odf-kit's engine is a clean-room implementation purpose-built for ODF — no code from either project was used.
-
 ---
 
 ## License