js.documents 1.81.7 → 1.81.8

package/README.md

@@ -713,6 +713,23 @@ To run a single test file: `pnpm vitest run src/path/to/file.test.ts`.
 
 ## Fidelity
 
+The prose below is authoritative; this table is a quick-reference summary of it, not a separate claim. Read as **row → column**. `✓` lossless (every construct the source expresses survives), `~` bounded (a small, named set of exceptions), `✗` lossy (real, structural loss — reconstruction from geometry, or a target vocabulary with no construct to receive something), `✗✗` severe (the worst case in the package, two lossy layers stacked), `→` one-way (no reverse exists, or ever will), `–` no direct conversion function. `.odm`/`.odb` are not `DocumentFormat` members (an ODF master document has no single target format; a database front end's tables/queries/reports are three unrelated output shapes) and so sit outside this table entirely — see their own Usage sections above.
+
+| ↓ from \ to → | docx | pptx | xlsx | odt | odp | ods | odg | odf | markdown | pdf |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| **docx** | — | – | – | ✓ | – | – | – | – | ✗ | ~ |
+| **pptx** | – | — | – | – | ✓ | – | – | – | – | ~ |
+| **xlsx** | – | – | — | – | – | ~ | – | – | – | ~ |
+| **odt** | ✓ | – | – | — | – | – | – | – | ✗ | ~ |
+| **odp** | – | ✓ | – | – | — | – | – | – | – | ~ |
+| **ods** | – | – | ~ | – | – | — | – | – | – | ~ |
+| **odg** | – | – | – | – | – | – | — | – | – | ~ |
+| **odf** | – | – | – | – | – | – | – | — | – | → |
+| **markdown** | ~ | – | – | ~ | – | – | – | – | — | ~ |
+| **pdf** | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | – | ✗✗ | — |
+
+27 of the 90 possible directional pairs have a real, ergonomic conversion function; PDF is the hub every format but `odf` round-trips through. `document-cli` and `document-mcp` add no conversion logic of their own, so this fidelity is identical across all three.
+
 **docx/pptx/odt/odp/ods/odg → PDF** is a genuine layout render: the docx/odt flow/pagination engine and the pptx/odp direct-placement engine both produce real positioned text, images, tables, and (for docx/odt) numbered/bulleted lists, styled through the full cascade (theme fonts/colours, `basedOn` chains, placeholder inheritance for docx/pptx; `style:default-style`/`style:parent-style-name` chains for odt/odp). `odg` renders its vector primitives (rect/ellipse/line/path, the last emitted as real PDF `m`/`l`/`c`/`h` content-stream operators, not a polygon approximation of any curve) and reuses the pptx/odp direct-placement engine's own shape conversion for whatever text it also carries. It is a faithful **visual approximation**, not a pixel- or line-identical reproduction of what Word/PowerPoint/Writer/Impress/Draw would themselves render — how close depends on which typeface the document asks for and whether it embedded one, see the font-resolution gotcha above.
 
 **odf → PDF (`odfToPdf`), and a formula embedded inside odt/odp/ods,** render **faithful mathematical typesetting**, not a static image or a plain-text placeholder: real box-model layout (script/limit positioning, fraction/radical geometry with correct rule thickness, table column alignment, `mathvariant` → Mathematical Alphanumeric Symbols mapping) through the embedded STIX Two Math font, with genuine per-glyph metrics (advance width, italic correction, top-accent attachment) and font-wide layout constants (axis height, fraction/radical rule thickness and gaps, script shift amounts) parsed directly from that font's own `MATH` table — not approximated or hand-tuned. A vertical fence around a tall construct genuinely stretches too, assembled from the font's own `MathVariants` pieces and sized to what it wraps, rather than drawn at a fixed base size — and an over/under-brace spanning its own `munder`/`mover`/`munderover` base stretches horizontally on the identical basis, sized to that base's own width. The honest limits: `msqrt`/`mroot` still draw a hand-built radical sign rather than the font's own stretched one (a structural reason, not because the font data is unavailable — see the Gotchas entries above); `mover`/`munder` centre geometrically rather than at the font's own declared accent-attachment point; and the operator dictionary and Greek `mathvariant` mapping each cover a deliberately bounded, common-case set rather than the full specification. For a formula anchored to a spreadsheet **cell**, position is genuinely resolved against that sheet's real column/row geometry (verified end to end against a real LibreOffice-authored `.ods`), but the rendered **size** comes from the same frame-height heuristic every engine uses, which over-estimates for a stacked formula — see the Gotchas entry on `formulaSizePtFromFrame`. **`pdfToOdf` (PDF → structured MathML) is not attempted, on either direction** — recovering a semantic operator tree (is this pair of glyphs a fraction, or a coincidentally stacked pair of ordinary characters? is a raised glyph a superscript, or just a smaller font size used for emphasis?) from nothing but positioned glyphs and paths is a categorically different, OCR-adjacent problem, with no geometry-reconstruction analogue anywhere else in this package: `reconstructWordprocessing`/`reconstructPresentation` recover paragraph/shape *structure* from geometry, never semantic *meaning* the way recognising a fraction would require.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js.documents",
-  "version": "1.81.7",
+  "version": "1.81.8",
   "description": "Bidirectional docx/pptx <-> PDF conversion and a read+write editable OOXML document model, built on ooxml.js and Zod 4 codecs.",
   "type": "module",
   "repository": {