bun-docx 0.10.0 → 0.11.0

package/README.md

@@ -82,6 +82,11 @@ docx insert FILE --after p3 --table --rows N --cols N [--widths "A,B,C"] [--tabl
 docx insert FILE --after p3 --image SRC [--alt TEXT] [--width INCHES] [--height INCHES]   # SRC = path, data: URI, or http(s) URL
 docx insert FILE --after p3 --code "..." [--language LANG]    # one CodeBlock paragraph per \n; --language → syntax highlight
 docx insert FILE --after p3 --code-file PATH [--language LANG] | --code-file -    # same, from file or stdin
+docx insert FILE --after p3 --task checked|unchecked --text "..." [--list-level N]   # GFM task list item
+docx insert FILE --after p3 --list bullet|ordered --text "..." [--list-level N]      # plain list item
+docx insert FILE --after p3 --equation "x^2 + y^2" [--display]   # LaTeX → OMML via temml + own MathML→OMML adapter
+docx edit   FILE --at p3 --task checked|unchecked         # flip an existing task's state; track-changes emits checkboxToggle
+docx edit   FILE --at eq3 --equation "x^3" [--display|--inline]  # replace equation content and/or toggle display mode
 docx edit   FILE --at p3 --text "..." [--no-formatting]   # word-level diff preserves bold/italic on unchanged words
 docx edit   FILE --at p3 --runs '[...]'
 docx edit   FILE --at p3 --code "..." [--language LANG]   # replace paragraph with a code block (expands to N lines)
@@ -212,6 +217,10 @@ Run `docx info locators` for the full reference.
 
 **Cross-format image replacement.** `images replace --at img0 --with new.png` detects the new MIME type via `Bun.file().type`, renames the part (`word/media/image1.jpeg` → `word/media/image1.png`), rewrites the relationship `Target`, and ensures `[Content_Types].xml` has a `<Default>` for the new extension.
 
+**GFM task lists.** Paragraphs in a list whose leading content is a Word checkbox content control (`<w:sdt><w14:checkbox/></w:sdt>`) surface as `paragraph.taskState: "checked" | "unchecked"` in the AST and render as `- [ ]` / `- [x]` in markdown. The reader strips the SDT subtree and its trailing space run from `runs` so the AST carries only the task text; the SDT survives untouched in the underlying `XmlNode` tree so a read→edit→save round-trip preserves every checkbox. The reader also recognizes the **Word-for-Web Checklist** shape — a bulleted list whose level-0 bullet character is Wingdings ☐ (U+F0A8), with `<w:strike>` on the paragraph-mark marking "done" — since Web silently strips SDT content controls when it authors new task lists. Both shapes were confirmed empirically against Microsoft Word for Mac desktop, Word for Web, and LibreOffice. On the emit side we always produce SDT. **Authoring**: `insert --task checked|unchecked --text "..."` creates a fresh task line (inherits the anchor's numId if it's already a list, otherwise allocates a new bullet list); `--list-level N` nests; `--list bullet|ordered` makes a plain list item without a checkbox. `edit --at pN --task checked|unchecked` flips an existing task's state in place. **Tracked toggles** (checking or unchecking under track-changes) surface as the `checkboxToggle` tracked-change kind in `track-changes list`; accept keeps the new state, reject restores the prior glyph AND flips `w14:checked` back (inferred from the kept glyph, since Word stores no separate prior-value record).
+
+**Math equations.** `<m:oMath>` and `<m:oMathPara>` (the Office Math markup Word, Pandoc, and LibreOffice all emit) surface as `EquationRun.latex` in the AST — reconstructed LaTeX, not the legacy plaintext concatenation. Markdown render emits `$…$` inline and `$$…$$` for display equations, so a doc full of academic equations round-trips through Pandoc with high fidelity. The walker handles fractions, super/sub/mixed scripts, roots (incl. nth roots), n-ary operators (sum/product/integral/contour), accents (hat/bar/vec — both Word's combining-diacritic and Pandoc's spacing-overscript encodings), delimited expressions, matrices, aligned equation arrays, and function operators (`\sin`/`\lim`/`\log` promoted from upright-styled runs). Unrecognized OMML constructs degrade per-subtree to plaintext (`EquationRun.text` is kept as a fallback) so a niche construct doesn't corrupt the surrounding equation. **Authoring**: `insert --equation "x^2 + y^2 = r^2" [--display]` inserts an inline or display equation from LaTeX (parsed by [temml](https://github.com/ronkok/Temml) for the LaTeX-side spec coverage, then walked into OMML by our own MathML → OMML adapter — no LGPL deps). `edit --at eqN --equation NEW_LATEX` replaces the content; `--display` / `--inline` toggle the mode. `eqN` locators address equations in document order.
+
 **Code blocks + inline code.** `insert --code TEXT` (or `--code-file PATH`, `-` for stdin) splits content on `\n` and emits one `<w:p>` per source line, all styled `CodeBlock` (Courier New, indent, adjacent-paragraph spacing collapse) with runs styled `Code` (monospace character style — defensive in case Word doesn't cascade the paragraph font). Both styles get provisioned in `styles.xml` automatically. `--language LANG` syntax-highlights via [lowlight](https://github.com/wooorm/lowlight) (highlight.js); 37 common languages are bundled — `bash`, `c`, `cpp`, `csharp`, `css`, `diff`, `go`, `graphql`, `ini`, `java`, `javascript`, `json`, `kotlin`, `less`, `lua`, `makefile`, `markdown`, `objectivec`, `perl`, `php`, `php-template`, `plaintext`, `python`, `python-repl`, `r`, `ruby`, `rust`, `scss`, `shell`, `sql`, `swift`, `typescript`, `vbnet`, `wasm`, `xml`, `yaml`. Unknown languages degrade silently to uncolored runs. The palette is GitHub-light inspired (keywords red, strings dark-blue, comments gray, …) and unmapped highlight.js classes fall through with no color. For an inline ``code`` span inside a normal paragraph, use `--runs` JSON with `runStyle: "Code"` (the S8 markdown walker will make this ergonomic via the `\`code\`` shorthand). On `docx read`, consecutive `CodeBlock` paragraphs collapse into one GFM fenced block (`` ``` `` … `` ``` ``); inline `runStyle: "Code"` runs render with backticks.
 
 **Image insertion.** `insert --image SRC` resolves SRC from a file path, a `data:` URI, or an `http(s)` URL (bounded fetch: 10s timeout, 25 MB cap streamed per-chunk so the limit holds even if `Content-Length` lies), writes the bytes to `word/media/imageN.ext`, mints an `image` relationship, and registers the extension's content-type `<Default>`. Pixel dimensions are read from the PNG/JPEG/GIF header and converted to EMU (1px = 9525 EMU at 96 dpi) for `<wp:extent>`; `--width`/`--height` override in inches, and supplying one alone scales the other to preserve aspect. The drawing is a standard inline `<w:drawing><wp:inline>` picture (`a:`/`pic:` namespaces declared on the subtree). Under track-changes the inserted run is wrapped in `<w:ins>` like any other inserted content. **HEIC/HEIF** input (common from iPhones) is transcoded to JPEG before embedding — Word can't render HEIC — so students can drop a `.heic` straight in; detection is by file header, not just extension. **SVG input is sanitized** before embedding (`<script>`, `on*` handlers, `<foreignObject>`, animation events, external `href`/`xlink:href`, and `data:image/svg+xml` self-references are stripped; XXE is rejected at parse time by `fast-xml-parser`) so an attacker-controlled SVG can't smuggle active content into the doc. **Remote fetches block non-public addresses** — private, loopback, link-local, and cloud-metadata ranges are refused, and HTTP redirects are followed manually with the same check at every hop, so an agent steered into `http://169.254.169.254/...` or `http://10.0.0.1/admin` is short-circuited.