otomate 0.2.1 → 0.3.1

package/guides/html-to-docx-and-back.md

@@ -0,0 +1,476 @@
+# HTML → docx → HTML, with tracked changes
+
+A complete, end-to-end walkthrough of converting HTML to a Word document with
+tracked changes, reimporting it, accepting the revisions, and confirming the
+round-trip is lossless. Every step here is backed by a real test at
+`packages/otomate/src/__tests__/e2e-tracked-changes.test.ts` — if you copy the
+snippets verbatim they will run.
+
+> **Prerequisites.** Node ≥ 20 **or any modern browser** (Deno, Bun, workers,
+> edge runtimes also work — the library uses the Web Crypto API internally
+> and has no Node-specific imports). `otomate` installed. All `writeDocx` /
+> `readDocx` / `writeDiffDocx` calls are **async** — always `await` them.
+> `readHtml` / `writeHtml` / `renderDiffHtml` / `diff` are synchronous.
+
+---
+
+## Overview — the 7 stages
+
+```
+HTML            → Stage 1 → UDM (oldTree)
+  ↓ edit
+HTML'           → Stage 2 → UDM (newTree)
+  ↓
+diff(old, new)  → Stage 3 → DiffResult + annotated HTML preview
+  ↓
+writeDiffDocx   → Stage 4 → .docx with <w:ins> / <w:del>
+  ↓
+readDocx        → Stage 5 → UDM + tracked-changes HTML render
+  ↓ "accept all"
+writeHtml       → Stage 6 → plain HTML, revisions applied
+  ↓
+assert equal    → Stage 7 → writeHtml(newTree)  // lossless round-trip
+```
+
+The invariant that proves everything works: **the output of stage 6 must be
+byte-for-byte identical to `writeHtml(newTree)`**. If that equality holds, the
+diff you computed in stage 3 survived the docx round-trip intact, and "accept
+all revisions" recovered exactly the edit you wanted.
+
+---
+
+## Stage 1 — Generate rich HTML and parse it
+
+```typescript
+import { readHtml } from "otomate";
+
+const originalHtml = `<style>
+  .title { color: #1e3a5f; font-family: Georgia; font-size: 24pt; }
+  .callout { background-color: #fff8e1; border: 1pt solid #fbbf24; }
+  .critical { color: #dc2626; font-weight: bold; }
+</style>
+<h1 class="title">Q1 2024 Product Roadmap</h1>
+<p>Welcome to the <strong>first quarter</strong> roadmap covering
+   our <em>strategic priorities</em>.</p>
+<h2>Initiatives</h2>
+<ul>
+  <li>
+    <p>Infrastructure improvements</p>
+    <ul>
+      <li>
+        <p>Database migration</p>
+        <blockquote>
+          <p>The migration must complete before <u>March 15th</u>.</p>
+        </blockquote>
+      </li>
+    </ul>
+  </li>
+</ul>
+<table>
+  <thead><tr><th>Metric</th><th>Q4</th><th>Q1 Target</th></tr></thead>
+  <tbody><tr><td>Revenue</td><td>$1.2M</td><td>$1.5M</td></tr></tbody>
+</table>
+<div class="callout">
+  <p class="critical">Risks identified:</p>
+  <ul><li><p>Integration delays</p></li></ul>
+</div>`;
+
+const oldTree = readHtml(originalHtml);
+```
+
+**What's in `oldTree`:**
+
+- The UDM tree — a `root` with block children (`h1`, `p`, `h2`, `ul`, `table`, `div`).
+- `oldTree.data.css.classRules` — auto-extracted from the inline `<style>` block (no need to pass `options.css` explicitly; it merges with whatever you do pass).
+- `classes: string[]` on every element that had an HTML `class` attribute.
+- Nesting depth ≥ 5 (the blockquote path alone goes `ul → li → ul → li → blockquote → p → text`).
+
+---
+
+## Stage 2 — Modify the document
+
+Generate an edited version. For the diff engine to exercise every code path
+you want a mix of edit kinds:
+
+| Kind | Effect in docx output |
+|---|---|
+| Text change | `<w:del>` + `<w:ins>` on a per-character/word run |
+| Root-level paragraph insertion | `<w:ins>` wrapping each run of the new paragraph |
+| Root-level node deletion | `<w:del>` wrapping the deleted block's text |
+
+```typescript
+let modifiedHtml = originalHtml;
+modifiedHtml = modifiedHtml.replace(
+  "Q1 2024 Product Roadmap",
+  "Q1 2024 Product & Engineering Roadmap",
+);
+modifiedHtml = modifiedHtml.replace("March 15th", "March 30th");
+modifiedHtml = modifiedHtml.replace("$1.5M", "$1.8M");
+modifiedHtml = modifiedHtml.replace(
+  "</h1>",
+  `</h1>\n<p class="summary">This quarter focuses on scale and accessibility.</p>`,
+);
+// Delete the entire callout div (a root-level node)
+modifiedHtml = modifiedHtml.replace(/<div class="callout">[\s\S]*?<\/div>/, "");
+
+const newTree = readHtml(modifiedHtml);
+```
+
+> ⚠️ **Only root-level deletes render as `<w:del>` in the docx.**
+> `writeDiffDocx` renders deletes via a Pass 2 that filters for
+> `op.path.length === 1`. A delete nested inside a list or table will survive
+> in the snapshot (so the round-trip still works) but **will not show up as a
+> revision mark** in Word. See the troubleshooting section below.
+
+---
+
+## Stage 3 — Diff and render an annotated HTML preview
+
+```typescript
+import { diff, renderDiffHtml } from "otomate";
+
+const delta = diff(oldTree, newTree);
+console.log(delta.stats);
+// { nodesAdded: 1, nodesDeleted: 1, nodesMoved: 0, nodesModified: 0, textChanges: 3 }
+
+// The signature is (oldTree, newTree, delta) — NOT (delta, oldTree, newTree).
+// See troubleshooting #3 below.
+const diffHtml = renderDiffHtml(oldTree, newTree, delta);
+```
+
+`diffHtml` is a standalone HTML string with `<ins>` and `<del>` markers plus
+`data-diff="insert|delete|update"` attributes. It's the canonical preview
+format — use it to show reviewers what will change before you commit the
+edit to a Word document.
+
+**Accepted options:** `{ insClass, delClass, modClass, moveClass, inlineStyles, side }`. `side: "old" | "new" | "merged"` controls whether you render the old view, the new view, or a combined view with both insertions and deletions visible. The default is `"merged"` which is what you want for a diff preview.
+
+---
+
+## Stage 4 — Write a tracked-changes `.docx`
+
+```typescript
+import { writeDiffDocx } from "otomate";
+import { writeFileSync } from "node:fs";
+
+const trackedBuf = await writeDiffDocx(newTree, delta, {
+  author: "Jane Editor",
+  date: "2024-04-07T12:00:00Z",
+});
+writeFileSync("roadmap-tracked.docx", trackedBuf);
+```
+
+The resulting file opens in Microsoft Word with all changes as revisions. Word's
+**Review → Accept All** and **Review → Reject All** buttons work correctly
+because each `<w:ins>` / `<w:del>` has a unique `w:id` and carries the author
+and date you supplied.
+
+**What the writer does internally:**
+
+1. Builds lookup maps of insert/delete/updateText operations indexed by tree path.
+2. Renders `newTree` with diff-aware converters that wrap inserted runs in `<w:ins>` and split text changes into `<w:del>` (old) + `<w:ins>` (new) segments.
+3. **Pass 2** splices root-level deleted blocks into their approximate old position, each wrapped in `<w:del>` with the deleted block's text content extracted recursively.
+4. Embeds the UDM snapshot (bound to the `document.xml` hash) so `readDocx` can round-trip perfectly.
+
+**Verify the XML actually contains tracked changes:**
+
+```typescript
+import { extractDocx } from "otomate";
+
+const parts = await extractDocx(trackedBuf);
+const docXml = parts.document;
+
+// Both revision types must be present.
+if (!docXml.includes("<w:ins")) throw new Error("no insertions emitted");
+if (!docXml.includes("<w:del")) throw new Error("no deletions emitted");
+
+// Every revision id must be unique.
+const ids = [...docXml.matchAll(/<w:(?:ins|del)\s+w:id="(\d+)"/g)].map(m => m[1]);
+if (new Set(ids).size !== ids.length) throw new Error("duplicate revision ids");
+```
+
+---
+
+## Stage 5 — Re-import the `.docx` and render tracked HTML
+
+```typescript
+import { readDocx } from "otomate";
+
+const rereadTree = await readDocx(trackedBuf);
+```
+
+`readDocx` sees `word/otomate-udm.json` inside the ZIP, validates its
+`__docHash` against the current `document.xml`, and (because we haven't
+touched the file) returns `newTree` back from the snapshot — lossless.
+
+To get **HTML comprehensive of rendered tracked changes** — i.e., a view
+showing both the accepted and rejected content so a reviewer can see what
+will change — feed `rereadTree` back through `renderDiffHtml` with the
+**same delta** you computed in stage 3:
+
+```typescript
+const rereadTrackedHtml = renderDiffHtml(oldTree, rereadTree, delta);
+// Contains <ins> for insertions, <del> for deletions, data-diff-* markers.
+```
+
+You need both `oldTree` and the delta because the OOXML path loses the
+diff-operation metadata — `<w:ins>` / `<w:del>` tell Word what to render but
+don't encode the structural tree mapping the diff engine needs to reproduce
+the preview. Keep the `delta` object around if you want to re-render the
+tracked-changes view later.
+
+---
+
+## Stage 6 — Accept all changes
+
+Accepting all revisions is the same as taking the "new" side of the diff,
+which is exactly what `rereadTree` already is (it came from the snapshot of
+`newTree`). So "accept all" is just:
+
+```typescript
+import { writeHtml } from "otomate";
+
+const acceptedHtml = writeHtml(rereadTree);
+```
+
+No `<ins>`, no `<del>`, no `data-diff-*` attributes — just clean HTML with
+the edits applied.
+
+If you need to **reject** all changes instead, serialize `oldTree`:
+
+```typescript
+const rejectedHtml = writeHtml(oldTree);  // equivalent to "reject all"
+```
+
+For mixed accept/reject (per-revision decisions) you'd need to replay the
+diff operations selectively against `oldTree`. The library doesn't currently
+ship an `applyDiff(tree, opsToApply)` helper; if you need this, walk
+`delta.operations` yourself and reconstruct the tree by picking which ops to
+include.
+
+---
+
+## Stage 7 — Prove the round-trip is lossless
+
+```typescript
+import assert from "node:assert/strict";
+
+const expectedAcceptedHtml = writeHtml(newTree);
+assert.equal(
+  acceptedHtml,
+  expectedAcceptedHtml,
+  "round-trip broke: accepted HTML does not match the expected modified HTML",
+);
+```
+
+This is the strongest possible assertion: byte-for-byte equality between
+the accepted state (stage 6) and the direct serialization of `newTree`.
+If the equality holds, every part of the pipeline — diff computation,
+docx tracked-changes serialization, ZIP packing, OOXML re-parsing, snapshot
+validation, HTML serialization — is lossless end to end.
+
+**You can also spot-check individual changes:**
+
+```typescript
+// Every insertion made it into the output.
+assert.ok(acceptedHtml.includes("Engineering Roadmap"));   // heading edit
+assert.ok(acceptedHtml.includes("March 30th"));            // blockquote edit
+assert.ok(acceptedHtml.includes("$1.8M"));                 // table edit
+assert.ok(acceptedHtml.includes("focuses on scale"));      // new paragraph
+
+// Every deletion was applied.
+assert.ok(!acceptedHtml.includes("March 15th"));
+assert.ok(!acceptedHtml.includes("$1.5M"));
+assert.ok(!acceptedHtml.includes("Risks identified"));     // deleted callout
+```
+
+---
+
+## Troubleshooting
+
+Every item in this section is a trap we hit while building the test that
+this guide is based on, **or** a subtle pitfall you will hit the first time
+you integrate the library. Read the whole list before writing any code.
+
+### 1. `diffResult.operations is not iterable` / `Cannot read property 'type' of undefined` inside `renderDiffHtml`
+
+**Cause.** Wrong argument order on `renderDiffHtml`. The correct signature is:
+
+```typescript
+renderDiffHtml(oldTree, newTree, diffResult, options?)
+```
+
+It is **not** `(diffResult, oldTree, newTree)`. An easy way to remember:
+`renderDiffHtml` parallels `diff` in that the trees come first.
+
+**Fix.** Pass the arguments in the order `(oldTree, newTree, delta)`.
+
+### 2. Deleted content is missing from the generated docx
+
+**Symptom.** The diff engine reports a delete (visible in `delta.stats.nodesDeleted`), but Word opens the file with no `<w:del>` anywhere and the deleted content simply isn't there.
+
+**Cause.** `writeDiffDocx` only renders **root-level** deletes as `<w:del>`. Its pass 2 filters for `op.path.length === 1`, so a delete nested inside a list item, table cell, or blockquote will not produce any OOXML revision mark. The tree snapshot still contains the correct state, so `readDocx` will round-trip correctly, but Word won't show a strike-through for that deletion.
+
+**Fix.** If you need a deletion to show up as a tracked change in Word, restructure the edit so the deleted node is a direct child of `root`. If that's not possible (e.g. deleting a single list item), you have two options:
+
+- Accept the limitation — the change still applies when the user clicks "Accept All", just without a visible revision mark for that specific delete.
+- Mutate via an insert of an empty node at the same position plus text replacement, turning the delete into an `updateText` op which *is* rendered as `<w:del>` + `<w:ins>` inside the paragraph.
+
+### 3. Tracked changes show up in the `.docx` but not in my re-rendered HTML preview
+
+**Symptom.** Stage 4's XML contains `<w:ins>` and `<w:del>`, but stage 5's `renderDiffHtml` output has no `<ins>` or `<del>` markers.
+
+**Cause.** You passed the wrong tree or delta to `renderDiffHtml`. The function needs **the original `oldTree`**, **the re-imported tree** (`rereadTree`, which equals `newTree` via the snapshot), and **the original delta** you computed in stage 3. Passing `oldTree, newTree, delta` renders correctly. Passing `rereadTree, rereadTree, delta` won't — there's nothing to compare against.
+
+**Fix.** Keep `oldTree` and `delta` in scope through the whole pipeline. Don't try to "rediscover" the diff from `rereadTree` alone — the snapshot path gives you a clean `newTree`, not the edit history.
+
+### 4. "File is corrupt" / "Word found unreadable content" dialog
+
+If Word complains when opening your `.docx`, one of these usually matches:
+
+| Symptom in the dialog | Cause | Fix |
+|---|---|---|
+| Word offers to "repair" the document | Schema-order violation inside `<w:rPr>` or `<w:pPr>`, or empty `<w:tr>` with no `<w:tc>`, or missing `<w:tblGrid>`, or invalid content in text | All of these are fixed inside the library. If you see one, update to the latest version. |
+| "The name in the end tag... must match the start tag" | The text you fed in contained raw XML control characters (`\x00`–`\x1F`) that aren't valid in XML 1.0 | `esc()` strips these automatically via `sanitizeText` — you shouldn't hit this in normal use, but if you're passing binary data as text, clean it first |
+| "Cannot find a part of the document" | You edited the `.docx` ZIP by hand and forgot to update `[Content_Types].xml` | Let the library produce the ZIP; don't unzip/rezip manually |
+
+### 5. `acceptedHtml` doesn't match `writeHtml(newTree)` exactly
+
+**Symptom.** Stage 7's `assert.equal` fails. The two strings differ in whitespace, attribute order, or similar cosmetic details.
+
+**Cause.** Something mutated the tree between stages. Common culprits:
+
+- You modified `newTree` after computing `delta` — now `newTree` and the snapshot disagree.
+- You wrote the docx, opened it in Word, saved it, then read it back — the snapshot hash is invalidated and `readDocx` falls back to OOXML parsing, which is lossier than the snapshot path. You'll see `div`/`figure` flattened into paragraphs, `data.html.*` attributes stripped, and custom marks dropped.
+- You passed a different diff to `renderDiffHtml` in stage 5 than you used in stage 4.
+
+**Fix.** Treat `oldTree`, `newTree`, and `delta` as immutable once computed. If you must edit in Word before round-tripping back, expect lossy results — the snapshot is only valid for documents otomate wrote and nothing has touched since.
+
+### 6. `readHtml` returns a tree with no CSS rules even though my HTML has a `<style>` block
+
+**Symptom.** `(tree.data as any)?.css` is `undefined` after calling `readHtml(htmlWithStyle)`.
+
+**Cause.** One of:
+
+- Your `<style>` element has no class selectors or element selectors — e.g. it only has `@media` queries, pseudo-classes (`:hover`), attribute selectors, or `@keyframes`. The CSS parser only extracts simple class (`.foo`) and element (`h1`) selectors; everything else is silently skipped. This is by design — OOXML has no way to express `:hover` anyway.
+- You're on an older version of `@otomate/html` that doesn't auto-extract inline `<style>` blocks. Before version 0.2, you had to pass the CSS as a string via `readHtml(html, { css: "..." })`. Current versions auto-extract.
+
+**Fix.** Check the selectors you're using. If they're all simple class or element selectors, update to a version with auto-extraction. If you need `:hover`-style selectors for some reason, strip them to plain `.class` selectors before passing to `readHtml`.
+
+### 7. Custom CSS class names produce weird-looking Word styles
+
+**Symptom.** A class named `"my-fancy class!"` shows up as `"myfancyclass"` in the generated Word document, and Word style IDs truncate at 31 characters.
+
+**Cause.** Style IDs in OOXML are restricted to `[A-Za-z0-9_\-:]` and a maximum of 31 characters per ECMA-376 §17.7.4.9. The library sanitizes CSS class names (via `sanitizeStyleId`) when mapping them to Word style IDs: disallowed characters are stripped, and names longer than 31 characters are truncated.
+
+**Fix.** If you want 1:1 fidelity between CSS class names and Word style IDs, keep your class names alphanumeric (plus `_`, `-`, `:`) and ≤ 31 characters. If you can't, the sanitized name is what you'll see — but the styling will still apply, because the library generates a unique style element per sanitized ID.
+
+### 8. `await` was skipped and `writeFileSync` wrote a `Promise` literal
+
+**Symptom.** Your `.docx` file contains the literal text `[object Promise]` instead of actual bytes.
+
+**Cause.** You forgot to `await` a call to `writeDocx`, `writeDiffDocx`, or `readDocx`. Those three functions are async. `readHtml`, `writeHtml`, `renderDiffHtml`, and `diff` are synchronous. **Always check the return type.**
+
+**Fix.**
+
+```typescript
+// Wrong
+writeFileSync("out.docx", writeDocx(tree));
+
+// Right
+writeFileSync("out.docx", await writeDocx(tree));
+```
+
+### 9. `readDocx(filePath)` throws `buffer.slice is not a function`
+
+**Symptom.** You passed a string file path to `readDocx` and got a runtime error about `.slice` or `.byteLength`.
+
+**Cause.** `readDocx` expects an `ArrayBuffer` or `Uint8Array`, **not** a filesystem path. It has no filesystem access — it's a pure buffer parser so it works the same in Node and the browser.
+
+**Fix.**
+
+```typescript
+import { readFileSync } from "node:fs";
+import { readDocx } from "otomate";
+
+const buf = readFileSync("input.docx");   // Buffer (subclass of Uint8Array)
+const tree = await readDocx(buf);
+```
+
+### 10. Running the library in a browser — things that used to break but no longer do
+
+As of `@otomate/docx@0.3.1` / `otomate@0.3.1`, the library has **zero Node-only imports**. Snapshot hashing goes through `globalThis.crypto.subtle.digest` (Web Crypto API) and the base64 fallback in the ZIP reader uses `globalThis.btoa`. Both are available in Node ≥ 20 and every modern browser. If you're on an older version and see `createHash is not a function` or `Buffer is not defined` at load time or runtime, upgrade to ≥ 0.3.1.
+
+If you're still seeing a `tsc --noEmit` complaint about `Cannot find name 'Buffer'` or `Cannot find module 'node:crypto'` in your own downstream code (not from inside the library), that's a tsconfig issue in your project — add `@types/node` to your devDeps if you actually use Node globals, or remove stale references if you don't.
+
+And install `@types/node` as a devDep.
+
+### 11. Hyperlinks I added programmatically collide with existing hyperlinks on round-trip
+
+**Symptom.** You read a `.docx`, added hyperlinks to the tree, and wrote it back — now some hyperlinks point to the wrong URL.
+
+**Cause.** OOXML hyperlinks are keyed by `r:id` into `word/_rels/document.xml.rels`. If the input file already had hyperlinks using `rId100`, `rId101`, etc., the writer needs to allocate fresh rIds that don't collide. The library handles this automatically via `nextRIdFor` which scans the existing rels for the highest used rId and seeds past it — **but only if `tree.data.docx.relationships` is preserved on the input tree**. If you built the tree from scratch or stripped `data.docx`, you might clash.
+
+**Fix.** When round-tripping, don't strip `tree.data.docx`. When building from scratch, don't worry — there are no pre-existing rIds to collide with.
+
+### 12. Numbered lists in the output all continue from the previous list's counter
+
+**Symptom.** You have two `<ol>` elements and the second one starts at "4" instead of "1".
+
+**Cause.** Earlier versions of the library shared `numId="2"` across all ordered lists, so Word treated them as one continuous sequence. Current versions allocate a fresh `w:numId` per top-level list (via `allocNumId`) and inject matching `<w:num>` entries into `numbering.xml`, so each list gets its own counter.
+
+**Fix.** Update to the latest version. If you're stuck on an old one, insert an explicit `start: 1` into the list node.
+
+### 13. Diff engine drops changes deep inside a large subtree
+
+**Symptom.** Editing a few words inside a paragraph nested six levels deep shows no change in the diff result.
+
+**Cause.** The diff engine uses a Dice-coefficient threshold (default `0.5`) for bottom-up matching — subtrees that are more than 50% similar are considered "the same" and their differences are merged into a single `updateText` operation rather than generating insert/delete pairs. If the similarity falls just above the threshold, small edits can get lost in the noise.
+
+**Fix.** Pass `diff(oldTree, newTree, { diceThreshold: 0.3 })` to make the matcher more sensitive. Lower values catch more fine-grained changes at the cost of more total operations.
+
+### 14. Running the e2e test locally — stale `dist/` trap
+
+**Symptom.** The test imports from `otomate` (the umbrella), fails with an assertion that feels wrong — e.g., "inline `<style>` should have been extracted into data.css" — even though the source code clearly does the extraction.
+
+**Cause.** The umbrella package imports from `@otomate/html`, `@otomate/docx`, etc. via their **built `dist/` directories**, not their source. If you made changes to a sub-package's source but haven't rebuilt it, the umbrella will still use the stale dist.
+
+**Fix.** Before running tests that exercise the umbrella, rebuild the sub-packages:
+
+```bash
+pnpm --filter @otomate/core --filter @otomate/diff --filter @otomate/css-docx \
+     --filter @otomate/inject --filter @otomate/html --filter @otomate/docx \
+     build
+```
+
+Or use `tsx` to import directly from the sub-package sources if you're iterating rapidly.
+
+---
+
+## Running the test that backs this guide
+
+The canonical reference implementation of this flow is a real test file:
+
+```bash
+cd packages/otomate
+pnpm test  # runs every test including e2e-tracked-changes.test.ts
+```
+
+Or to run just the e2e test:
+
+```bash
+cd packages/otomate
+node --test --import tsx src/__tests__/e2e-tracked-changes.test.ts
+```
+
+The test exercises every stage in this guide with explicit assertions, so if
+the library regresses on any part of the pipeline, that test will fail with
+a message like `[stage 4] document.xml is missing any <w:del> elements` —
+pinpointing exactly where the breakage is.
+
+## See also
+
+- **`SKILL.md`** (next to this file) — condensed entry-point reference and pattern recipes
+- **`README.md`** (repo root) — architecture overview and diff algorithm details
+- **`packages/docx/src/__tests__/realworld.test.ts`** — end-to-end tests against a dozen real-world HTML fixtures
+- **ECMA-376 §17.13.5** — the OOXML tracked-changes schema (`<w:ins>`, `<w:del>`, `<w:moveFrom>`, etc.) if you want to understand the output format at the byte level

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "otomate",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Universal document diffing library — structure-aware, string-level, multi-format",
   "type": "module",
   "main": "./dist/otomate.umd.cjs",
@@ -15,11 +15,14 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "SKILL.md",
+    "guides"
   ],
   "scripts": {
     "build": "vite build && tsc --emitDeclarationOnly",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "node --test --import tsx src/__tests__/*.test.ts"
   },
   "devDependencies": {
     "@otomate/core": "workspace:*",
@@ -28,6 +31,8 @@
     "@otomate/docx": "workspace:*",
     "@otomate/css-docx": "workspace:*",
     "@otomate/inject": "workspace:*",
+    "@types/node": "^25.5.2",
+    "tsx": "^4.19.0",
     "typescript": "^5.7.0",
     "vite": "^6.0.0"
   },