documents.js 1.46.0 → 1.46.1

package/README.md

@@ -30,7 +30,7 @@ npm install documents.js
 
 ## Usage
 
-The eight round-trip ergonomic conversions (docx/pptx/odt/odp ⇄ PDF), plus `odsToPdf`/`odgToPdf`'s one-directional additions (there is no `pdfToOds` yet — PDF → spreadsheet reconstruction needs general vector-path tracking in the PDF reader that doesn't exist yet; there is no `pdfToOdg` either, for the equivalent reason on the drawing side — see [Gotchas](#gotchas-and-quirks)):
+The eight round-trip ergonomic conversions (docx/pptx/odt/odp ⇄ PDF), plus `odsToPdf`/`odgToPdf`'s one-directional additions (there is no `pdfToOds`/`pdfToOdg` yet — the PDF reader's general vector-path tracking both directions need now exists (`src/pdf/interpret.ts`), but the reconstruction algorithms themselves, `reconstructSpreadsheet`/`reconstructDrawing`, are not yet built — see [Gotchas](#gotchas-and-quirks)):
 
 ```ts
 import { docxToPdf, odgToPdf, odpToPdf, odsToPdf, odtToPdf, pdfToDocx, pdfToOdp, pdfToOdt, pptxToPdf, pdfToPptx } from 'documents.js';
@@ -206,8 +206,9 @@ To run a single test file: `pnpm vitest run src/path/to/file.test.ts`.
 - **The docx⇄PDF and pptx⇄PDF conversions are explicitly not round-trip-lossless** — in deliberate contrast to `ooxml.js`'s own `packageCodec`, which is byte/part-faithful by design. See [Fidelity](#fidelity).
 - **`odpToPdf`/`pdfToOdp` needed zero new layout code.** `readOdpContent` (`src/odf/odp/read.ts`) produces the identical `presentation` `ContentDocument` shape `readPptxContent` does, so it feeds `convertPresentationToLayout` unmodified — including the existing hidden-annotation speaker-notes mechanism below, which carries odp's `presentation:notes` through to the PDF with no new notes-handling code at all; `pdfToOdp` reuses `reconstructPresentation` unmodified too, the same architectural bet `pdfToOdt` already proved for `reconstructWordprocessing`. The genuinely new work for the reverse direction was the live-view editor itself (`src/edit/odp/*`) — see Architecture above.
 - **`OdpShape.rotationDeg` writes a real `draw:transform`, built on `odf.js`'s own transform machinery.** It is the write-side inverse of `odf.js`'s `resolveOdfShapeGeometry` (`typed/shared/transform.ts`), built on that module's own exported `applyOdfTransform` rather than a hand-rolled rotation matrix, so it inherits that module's own empirically-verified rotate/translate composition order and sign convention by construction. Unlike `PptxShape` (see the `colSpan`/`rowSpan` gotcha below, which pptx still has and odp does not), `buildOdpPackage` writes a rotated shape's rotation back correctly — verified both by this package's own tests and by opening a fresh, editor-built `.odp` in actual LibreOffice.
-- **`odsToPdf` is one-directional — there is no `pdfToOds` yet, and no `reconstructSpreadsheet`.** Unlike odt/odp, going from PDF back to a spreadsheet needs general vector-path tracking in the PDF reader (`src/pdf/interpret.ts` currently only tracks the specific `re` rectangle operator, discarding general `m`/`l`/`c` path construction) so a reconstructed sheet's gridlines can be detected from the recovered geometry — that infrastructure doesn't exist yet. `buildOdsPackage` (`src/edit/ods/content.ts`) is built and exported, ready for `pdfToOds` to call the moment path tracking lands; nothing currently calls it.
-- **`odgToPdf` is one-directional — there is no `pdfToOdg`, and no `reconstructDrawing`, even though the odg live-view editor and `buildOdgPackage` both now exist.** Reconstructing a `ContentDrawPage`'s own vector-primitive geometry (which recovered path is a rect vs. a genuine curve, where one shape ends and another begins) from PDF geometry alone is a fundamentally different, unstarted problem from `reconstructWordprocessing`/`reconstructPresentation`'s own paragraph/shape geometry clustering — the same `src/pdf/interpret.ts` gap `odsToPdf`'s own gotcha above describes (no general `m`/`l`/`c` path tracking) blocks this direction too, on top of needing its own reconstruction algorithm even once that infrastructure exists. `buildOdgPackage` (`src/edit/odg/content.ts`) is built and exported, ready for `pdfToOdg` to call the moment both land; nothing currently calls it, mirroring `buildOdsPackage`'s own identical situation.
+- **`src/pdf/interpret.ts` now tracks general vector paths, not just axis-aligned `re` rectangles.** `m`/`l`/`c`/`v`/`y`/`h` (and `re` itself, per its own ISO 32000-1 definition as a 4-point rectangle subpath) accumulate real subpaths — CTM-transformed line/cubic segments, open or closed — and any paint operator (`f`/`F`/`f*`/`S`/`s`/`B`/`B*`/`b`/`b*`) emits a `LayoutPath` item when the path isn't reducible to the simple single-`re`-on-an-axis-aligned-CTM case (which still takes the original, unchanged `LayoutRect` fast path). Verified both by dedicated tests and by a genuine `writePath` → `writePdf` → `readPdf` round trip recovering the original `LayoutPath` value exactly. This is the shared infrastructure both `pdfToOds` and `pdfToOdg` below need — it exists now, but neither conversion function itself does yet.
+- **`odsToPdf` is one-directional — there is no `pdfToOds` yet, and no `reconstructSpreadsheet`.** The PDF-side blocker (general vector-path tracking, needed to detect a reconstructed sheet's gridlines from recovered geometry) is resolved — see the `interpret.ts` gotcha above. What's still missing is `reconstructSpreadsheet` itself: the actual gridline-detection/text-clustering-into-a-grid algorithm. `buildOdsPackage` (`src/edit/ods/content.ts`) is built and exported, ready for `pdfToOds` to call the moment that algorithm lands; nothing currently calls it.
+- **`odgToPdf` is one-directional — there is no `pdfToOdg`, and no `reconstructDrawing`, even though the odg live-view editor and `buildOdgPackage` both now exist.** The PDF-side blocker (general vector-path tracking) is resolved — see the `interpret.ts` gotcha above. What's still missing is `reconstructDrawing` itself: mapping recovered `LayoutRect`/`LayoutPath`/`LayoutText`/`LayoutImage` geometry back onto ODF shapes (which recovered path is a rect vs. a genuine curve, where one shape ends and another begins) — a fundamentally different, unstarted problem from `reconstructWordprocessing`/`reconstructPresentation`'s own paragraph/shape geometry clustering, though genuinely more tractable since a drawing has no semantic structure to infer, only shapes to map near-1:1. `buildOdgPackage` (`src/edit/odg/content.ts`) is built and exported, ready for `pdfToOdg` to call the moment that algorithm lands; nothing currently calls it, mirroring `buildOdsPackage`'s own identical situation.
 - **A vector primitive's own fill/stroke needed a self-contained graphic-family style writer, not `odf.js`'s own `StyleRegistry`.** `'graphic'` is a recognised `StyleFamily` member (`odf.js`'s `src/styles/registry.ts`), but `StylePropertiesSchema`/`buildStylePropertyElements` (`properties.ts`/`serialize.ts`) only ever model text/paragraph formatting and never emit a `style:graphic-properties` element for any family — extending that shared package for one narrow, documents.js-local need (`draw:fill(-color)`/`draw:stroke` + `svg:stroke-color`/`svg:stroke-width`) would be scope creep into a foreign package for a two-attribute-group writer this package can express directly. `src/edit/odg/style.ts` is that writer: it still reuses `odf.js`'s general append-only style-editing invariant (a setter always mints a fresh `style:style` and repoints `draw:style-name`, never mutates an existing entry — verified by the same `assertAutomaticStylesOnlyAppended` helper `OdpEditor`'s own live-view fidelity test uses) and `src/edit/odt/automatic-styles.ts`'s `ensureAutomaticStyles`/`nextStyleName` (the "find-or-create `office:automatic-styles`, mint the next unused name" logic every other hand-rolled style helper in this package already shares), rather than a third reimplementation of either.
 - **A path vector's own `svg:d` is cross-checked against `odf.js`'s real parser, not merely asserted to "look plausible".** `src/edit/odg/svg-path.ts`'s `buildSvgPathData` is the write-side inverse of `odf.js`'s `parseOdfPathData`; `OdgPathVector.subpaths` re-derives its value by reparsing the actual written `svg:viewBox`/`svg:d` through that exact function (plus `parseOdfViewBox`/`buildOdfSubpaths`) on every read, rather than echoing back whatever `ContentSubpath[]` the caller originally passed to `addPath` — so every read is itself a live round-trip proof, and this module's own test suite additionally feeds `buildSvgPathData`'s output straight into `parseOdfPathData` to confirm point-for-point recovery.
 - **A newly added vector/shape's paint order is expressed purely as document order, with no `draw:z-index` ever written.** This matches `odf.js`'s own reader-side convention exactly (`typed/draw/shapes.ts`'s `paintOrderKey`: honour an explicit `draw:z-index` when present, otherwise fall back to document order — and real LibreOffice output never emits one, it reorders elements instead), so `OdgPage.addRect`/`addEllipse`/`addLine`/`addPath`/`addTextBox`/`addImage` simply append to `draw:page`'s own children in call order and nothing more is needed for a later `add*` call to paint in front of an earlier one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "documents.js",
-  "version": "1.46.0",
+  "version": "1.46.1",
   "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": {