docgen-utils 1.0.19 → 1.0.21

package/README.md

@@ -1,6 +1,6 @@
 # DocGen
 
-Converts HTML into DOCX, PPTX and vice versa.
+Converts HTML into DOCX, PPTX and vice versa. Runs in browsers (via bundled JS) and Node.js (via CLI). Published as `docgen-utils` on npm.
 
 ## Key Components
 
@@ -8,41 +8,52 @@ Converts HTML into DOCX, PPTX and vice versa.
 
 | File       | Description                                                    |
 | ---------- | -------------------------------------------------------------- |
-| `build.sh` | Builds the library                                             |
+| `build.sh` | Builds the library (TypeScript → esbuild bundles)              |
 | `dist/`    | Output directory containing production-ready minified JS files |
 
+### Package Structure
+
+| Package            | Description                                                                       |
+| ------------------ | --------------------------------------------------------------------------------- |
+| `packages/docs/`   | DOCX pipeline — 13 TypeScript files for HTML↔DOCX conversion                     |
+| `packages/slides/` | PPTX pipeline — 8 TypeScript files + vendored PptxGenJS for HTML↔PPTX conversion |
+| `packages/shared/` | Cross-cutting utilities — DOM parser shim, proxy-aware HTTP client, font mappings |
+| `packages/cli/`    | Node.js CLI (`docgen` command) — dispatches to import/export subcommands          |
+
 ## Usage
 
-### Build
+## Install dependencies
 
 ```bash
-npm run build
+npm install --registry=https://registry.npmjs.org
 ```
 
-### CLI
-The CLI is used in the agent sandbox to transform artifacts.
+### Build
 
 ```bash
-node dist/cli.js import docx --file=file.docx --out-dir=./output
-node dist/cli.js import pptx --file=file.pptx --out-dir=./output
-node dist/cli.js export docs --file=file.html --out-dir=./output
-node dist/cli.js export slides --files=slide-1.html,slide-2.html --out-dir=./output
+npm run build
 ```
 
-### Deploy
+### CLI
+
+The CLI is used in the agent sandbox to transform artifacts.
 
 ```bash
-az login
-npm run deploy
+alias docgen='npx tsx packages/cli'
+docgen import docx --file=file.docx --out-dir=./output [--name=<filename>]
+docgen import pptx --file=file.pptx --out-dir=./output [--name=<filename>]
+docgen export docs --file=file.html --out-dir=./output [--name=<filename>] [--pageless]
+docgen export slides --files=slide-1.html,slide-2.html --out-dir=./output [--name=<filename>]
 ```
 
 ## Visual Comparison
 
 The `output` directory contains the rendered output in target formats. e.g. DOCX or PPTX vs HTML
 
-- Files in `test-data/docs/` → converted to DOCX → `docx-render.jpg`
-- Files in `test-data/slides/` → converted to PPTX → `pptx-render.jpg`
-- Files in `test-data/pptx/` → imported to HTML → `html-render.jpg`
+- Files in `test-data/docs/` (27 HTML files) → converted to DOCX → `docx-render.jpg`
+- Files in `test-data/slides/` (90 HTML files) → converted to PPTX → `pptx-render.jpg`
+- Files in `test-data/pptx/` (145 PPTX files) → imported to HTML → `html-render.jpg`
+- Files in `test-data/docx/` (22 DOCX files) → imported to HTML → `html-render.jpg`
 
 ### Prerequisites
 
@@ -57,6 +68,8 @@ brew install --cask libreoffice
 brew install poppler
 # Chromium for Playwright
 npx playwright install chromium
+# Install fonts for accurate rendering
+npx tsx scripts/install-fonts/index.ts
 ```
 
 ### Usage
@@ -79,11 +92,39 @@ Import a PPTX file (PPTX -> HTML):
 npm run generate-output -- test-data/pptx/presentation.pptx
 ```
 
+Import a DOCX file (DOCX -> HTML):
+
+```bash
+npm run generate-output -- test-data/docx/document.docx
+```
+
 Process multiple files:
 
 ```bash
-npm run generate-all-docs-output   # All docs
-npm run generate-all-slides-output # All slides
+npm run generate-all-docs-output   # All docs (HTML→DOCX)
+npm run generate-all-slides-output # All slides (HTML→PPTX)
+npm run generate-all-docx-output   # All DOCX imports (DOCX→HTML)
+npm run generate-all-pptx-output   # All PPTX imports (PPTX→HTML)
+```
+
+### Roundtrip Testing
+
+Full roundtrip tests convert HTML→DOCX/PPTX→HTML and compare the result:
+
+```bash
+npm run roundtrip -- test-data/docs/doc-1.html       # Single doc roundtrip
+npm run roundtrip -- test-data/slides/slide-1.html    # Single slide roundtrip
+npm run roundtrip-all-docs                             # All docs (no AI diff)
+npm run roundtrip-all-slides                           # All slides (no AI diff)
+```
+
+### AI-Powered Visual Diff
+
+Compare two rendered images using Claude vision API (requires `ANTHROPIC_API_KEY`):
+
+```bash
+npm run ai-diff <image1.jpg> <image2.jpg>
+npm run ai-diff -- <image1.jpg> <image2.jpg> --question="Is the text shadow rendering correctly?"
 ```
 
 ### Output
@@ -110,10 +151,16 @@ output/
 │   ├── diff.jpg              # Visual diff highlighting differences
 │   ├── output.html           # Generated HTML (all slides concatenated)
 │   └── report.json           # Comparison metrics
+├── metrics.json              # Aggregated quality metrics across all tests
 └── ...
 ```
 
+### Quality Metrics
+
+A pre-commit hook automatically aggregates all `report.json` files into `output/metrics.json`, tracking quality baselines by conversion type (docx-export, pptx-export, docx-import, pptx-import).
+
 **Metrics explained:**
 
 - **pixelDiff.percentDiff** - Percentage of pixels that differ between the two images (lower is better)
 - **ssim.mssim** - Structural Similarity Index (0-1, higher is better). Values above 0.9 indicate very similar images
+- **Quality Score** - Composite score 0-100 for roundtrip tests (target ≥85)