otomate 0.3.1 → 0.3.3

package/LICENSE

@@ -0,0 +1,63 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Alessio G.
+Licensed Work:        otomate — Universal Document Diffing Library
+                      The Licensed Work is (c) 2026 Alessio G.
+Additional Use Grant: You may make production use of the Licensed Work,
+                      provided such use does not include offering the
+                      Licensed Work to third parties on a hosted or
+                      embedded basis which is competitive with the
+                      Licensor's products.
+Change Date:          2030-04-03
+Change License:       MIT
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact the Licensor.
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.

package/README.md

@@ -283,6 +283,7 @@ pnpm dev
 | `code` | `<code>` | monospace font | Inline code |
 | `link` | `<a>` | `w:hyperlink` | Hyperlink (with URL) |
 | `highlight` | `<mark>` | `w:highlight` | Highlighted text |
+| `custom` | `<span class="…">` / `<span style="…">` | resolved `w:rPr` | Span classes/style → run properties via `cssClasses` |
 
 ## CSS → docx Style Mapping
 
@@ -305,10 +306,16 @@ When CSS rules are provided, otomate generates real Word styles with OOXML forma
 | `padding-left` / `padding-right` | `w:ind left/right` | Added on top of margin values |
 | `text-indent` | `w:ind firstLine` | Converted to twips |
 | `line-height` | `w:spacing line` | |
-| `border` | `w:pBdr` (all sides) | Shorthand; per-side overrides take priority |
-| `border-top` / `border-bottom` / `border-left` / `border-right` | `w:pBdr` | solid→single, dashed, dotted, double |
+| `border` | `w:pBdr` (paragraph) / `w:tcBorders` (table cell) | Shorthand; per-side overrides take priority |
+| `border-top` / `border-bottom` / `border-left` / `border-right` | `w:pBdr` (paragraph) / `w:tcBorders` (table cell) | solid→single, dashed, dotted, double |
+| `vertical-align` | `w:vAlign` | Table cells only — top/middle/bottom |
+| `height` | `w:trHeight` | Table rows only |
 
-Container CSS (on `div` elements) cascades to all child paragraphs, headings, and list items.
+**Element-level CSS resolution.** Classes are resolved at the OOXML element they describe rather than smeared inline:
+
+- **Divs** — classes propagate to children as run/paragraph properties; inline-only divs become a paragraph; mixed-content divs auto-wrap consecutive inline children into implicit paragraphs; empty divs are dropped.
+- **Tables** — classes on `<table>`, `<tr>`, and `<td>`/`<th>` cascade in CSS specificity order. Cell `background-color` lands on `w:tcPr/w:shd`, borders on `w:tcBorders`, vertical-align on `w:vAlign`, row height on `w:trHeight`. Run/paragraph properties (color, font, weight, alignment) propagate to cell content.
+- **Spans** — class names and inline `style` attributes survive as `custom` marks and resolve to `w:rPr` at write time.
 
 ## Lossless Round-Trip Strategy
 

package/SKILL.md

@@ -54,7 +54,7 @@ The `otomate` umbrella re-exports everything from these sub-packages:
 
 Direct sub-package imports (`import { readDocx } from "@otomate/docx"`) work too and have the same shapes. Prefer the umbrella unless you need to tree-shake aggressively.
 
-## The five entry points
+## The seven entry points
 
 ### `readHtml(html, options?): Root`
 **Sync.** Parses an HTML string into a UDM tree.
@@ -87,6 +87,12 @@ Direct sub-package imports (`import { readDocx } from "@otomate/docx"`) work too
 - All `DocxWriteOptions` fields (e.g. `cssClasses`) are also accepted
 - Returns: `Promise<Uint8Array>`
 
+### `diff(oldTree, newTree): DiffResult`
+**Sync.** Tree-diffs two UDM trees with the three-phase algorithm (top-down hash matching → bottom-up Dice scoring → Myers word-level text diff). Returns a serializable `DiffResult` with typed `operations` (`insert`, `delete`, `move`, `update`, `updateText`). Pair with `writeDiffDocx` to materialize tracked changes, or consume the operations directly.
+
+### `inject(tree, data): Root`
+**Sync.** Replaces `{{placeholders}}` in a UDM tree with values from a free-form JSON object. Supports `{{name}}`, `{{obj.nested}}`, `{{#each items}}…{{/each}}`, `{{#if cond}}…{{else}}…{{/if}}`, and `{{@richField}}` for replacing a paragraph with block-level content. Word content controls (`<w:sdt>`) are surfaced as placeholders automatically by `readDocx`. Returns a new tree — does not mutate the input.
+
 ## Pattern recipes
 
 ### R1. HTML (from a CMS) → branded Word doc with CSS
@@ -280,9 +286,13 @@ All types live in `@otomate/core` and are re-exported from `otomate`. Required f
 | `image` | **`type: "image"`**, **`url: string`** | `alt?: string`, `title?: string` |
 | `inlineCode` | **`type: "inlineCode"`**, **`value: string`** | — |
 
+`InlineNode` in the type system also includes `footnoteReference` and `inlineMath`. They survive parse + diff + UDM round-trip, but the docx writer does not yet render them — they currently emit nothing in `.docx` output. Use sparingly until first-class support lands.
+
 ### Marks (applied to `text` nodes via `marks[]`)
 
-Built-in: `strong`, `emphasis`, `strikethrough`, `underline`, `superscript`, `subscript`, `code`, `link` (needs `attrs.url`), `highlight` (optional `attrs.color`). Custom mark types are allowed — the writer preserves them via the UDM snapshot.
+Built-in: `strong`, `emphasis`, `strikethrough`, `underline`, `superscript`, `subscript`, `code`, `link` (needs `attrs.url`), `highlight` (optional `attrs.color`).
+
+**`custom` marks** — produced by the HTML reader for any `<span>` carrying a `class` and/or `style` attribute. The mark shape is `{ type: "custom", attrs: { className?: string[]; style?: string; id?: string; "data-*"?: unknown } }`. At write time, `attrs.className` is resolved against `cssClasses` and `attrs.style` is parsed inline; both flow through `cssToRunProps` to populate `w:rPr` (color, font, weight, italic, underline, strike, sz, shading). When the same property is set in both class CSS and `style`, `style` wins (CSS specificity by proximity). User-defined custom mark types beyond this are also preserved via the UDM snapshot.
 
 ## CSS → OOXML cheat-sheet
 
@@ -315,6 +325,19 @@ These CSS properties are understood by `writeDocx` (via `@otomate/css-docx`). An
 | `background-color: #fafafa` | `w:shd` |
 | `background: #fafafa` (shorthand) | `w:shd` — first color token wins |
 
+**Table cell properties** (resolved when a CSS class is set on `<table>`, `<tr>`, `<td>`, or `<th>` — cascade order: `cssElements["table"]` → table class → `cssElements["tr"]` → row class → `cssElements["td"|"th"]` → cell class)
+
+| CSS | OOXML | Where it lands |
+|---|---|---|
+| `background-color: #fafafa` | `w:shd` | `w:tcPr` (cell shading, not propagated to runs) |
+| `border` / `border-{top,right,bottom,left}` | `w:tcBorders` | `w:tcPr` (per side) |
+| `vertical-align: top \| middle \| bottom` | `w:vAlign` | `w:tcPr` |
+| `height: 30pt` (on a row) | `w:trHeight` | `w:trPr` (`w:hRule="atLeast"`) |
+| `color`, `font-*`, `font-weight`, `font-style` | `w:rPr` on cell content | propagated to every run inside the cell |
+| `text-align`, `margin-*`, `border` (paragraph) | `w:pPr` on cell content | propagated to every paragraph inside the cell |
+
+Divs follow the same model: a class on a `<div>` cascades into every child paragraph/run. Inline-only divs become a single paragraph; mixed-content divs auto-wrap consecutive inline children into implicit paragraphs; empty divs produce no output.
+
 **Color formats accepted**: named colors, `#rgb`, `#rrggbb`, `#rrggbbaa`, `rgb()`, `rgba()`, `hsl()`, `hsla()`. Alpha is dropped (OOXML has no alpha channel).
 
 **Length units accepted**: `px`, `pt`, `em`, `rem`, `cm`, `mm`, `in`. Percentages (`%`) are **not** supported for paragraph spacing — OOXML has no basis to resolve them against.