bun-docx 0.14.1 → 0.16.0

package/README.md

@@ -89,11 +89,16 @@ docx find    FILE (--highlight COLOR|any | --color HEX | --bold | --italic | --u
 docx wc      FILE [LOCATOR] [--accepted | --baseline | --current] [--json]
 docx outline FILE [--style-prefix S] [--json]
 docx styles  FILE [--used] [--at STYLEID] [--json]   # the style catalog (not in the body) — what --style NAMEs exist
+docx styles  --catalog [--json]                      # built-in styles you can apply on demand (Title, Heading1–9, Quote, …), no FILE needed
+docx styles  set    FILE --at STYLEID [--bold --color HEX --size PT --font NAME --space-before PT --indent-left IN …]   # restyle every paragraph/run that uses the style
+docx styles  create FILE STYLEID [--type paragraph|character] [--name "…"] [--based-on STYLEID] [--next STYLEID] [formatting]   # define a new custom style
 docx render  FILE [--out DIR] [--engine word|libreoffice|auto] [--dpi N] [--pages 1-N] [--format png|jpg]
 
 docx comments      list FILE [--include-resolved] [--thread cN]
 docx footnotes     list FILE
 docx endnotes      list FILE
+docx headers       list FILE
+docx footers       list FILE
 docx images        list FILE
 docx hyperlinks    list FILE
 docx track-changes list FILE
@@ -110,15 +115,37 @@ normal edits in place, `read --ast` is the lossless view, and `docx sections` /
 (only when a value differs from the document default, so a plain document stays
 clean):
 
+- **Per-paragraph style/spacing/indent** — the most common annotation — rides a
+  `<!-- docx:p pN style="Caption" align="center" space-after="6pt" line-spacing="1" indent-left="0.25in" -->`
+  note, emitted deviation-only (only the attrs that differ from the style/document
+  default). Each attribute maps to the matching `edit`/`insert` flag (`--style`,
+  `--alignment`, `--space-before`/`--space-after`, `--line-spacing`,
+  `--indent-left`/`--indent-right`/`--first-line`/`--hanging`), so an agent reads a
+  value and re-applies it. The paragraph's locator rides this note as its leading `pN`
+  token, so an annotated paragraph does NOT also get a bare `<!-- pN -->` (only
+  undeviating paragraphs get the bare locator). Full properties are in `read --ast`.
 - **Section breaks** render as `<!-- docx:section sN cols="2" type="continuous" -->`
   on their own line — never a bare `---` (that's a thematic break, and emitting it
   for a section silently turned layout into border paragraphs). A hand-authored
   `---` now unambiguously means a thematic break.
-- **Page geometry** rides a leading `<!-- docx:page orientation="landscape"
+- **Page geometry** rides a leading `<!-- docx:page sN orientation="landscape"
   size="…in" margins="…in" text-width="…in" -->` note when the page deviates from
-  US-Letter-portrait-1″ — `text-width` is the usable column width. Exact twips are
-  in `read --ast` (on each section break: `pageWidth`/`pageHeight`/`pageOrientation`/
-  `margin*`).
+  US-Letter-portrait-1″ — `text-width` is the usable column width, and the leading
+  `sN` is the section to re-apply against. A `varies="by-section"` attribute is added
+  when a later section's page setup differs from the leading one — and in that case
+  the note fires **even if page 1 is plain default Letter-portrait-1″** (it then shows
+  just `text-width` + `varies="by-section"`), warning that the geometry shown describes
+  only the leading section; use `read --ast` for every section's exact geometry.
+  Exact twips are in `read --ast` (on each
+  section break: `pageWidth`/`pageHeight`/`pageOrientation`/`margin*`). Set it for the
+  WHOLE document with `docx sections --orientation/--size/--margins` (no `--at` →
+  every section gets it, so a multi-section doc doesn't leave the trailing section
+  behind), one section with `docx sections --at sN …`, or at `create` time; under
+  track-changes it records as one `<w:sectPrChange>` per section (accept/reject in Word).
+  Changing margins/size also **auto-realigns right-edge tab columns** (résumé
+  dates/locations): a LEFT tab calibrated to the old margins would overflow and wrap
+  at the new width, so page setup converts each to a RIGHT tab flush at the new
+  margin and reports how many it fixed — no second `--tabs right` step needed.
 - **Tables** carry a leading `<!-- docx:table t0 widths="1,2,3in" borders="double" -->`
   when columns are uneven or borders deviate from the default, plus a per-cell
   `<!-- docx:cell t0:r0c0 gridSpan="2" vMerge="continue" shading="FFE699" -->`
@@ -129,16 +156,38 @@ clean):
   `float`/`wrap`/`align`/`overflow` only when they deviate (an inline, in-bounds
   image shows just its size). `overflow` flags an image wider than the usable text
   column (`ImageRun.floating`/`wrap`/`align` + EMU extents in `read --ast`).
+- **Headers / footers** surface as `<!-- docx:header text="Quarterly Report" -->`
+  / `<!-- docx:footer text="Page {page} of {pages}" -->` notes (the `type` attr
+  appears only for `first`/`even`). Fields read as tokens — `{page}` `{pages}`
+  `{date}` `{time}` `{styleref:NAME}` `{filename}` `{title}` `{author}` (`{time}`
+  read-only). A marginal that's
+  the same on every section rides the top; one that **differs by section** renders at
+  that section's **start** (alongside the `docx:section` note, which also renders at
+  the section's start with `applies-to="… (below)"`), so each hint reads right before
+  the content it governs. The text lives in the comment attribute
+  so the importer drops it (it can't re-inject into the body); full entries are in
+  `read --ast` under `headers`/`footers` (`Marginal[]`). Set with `docx
+  headers`/`docx footers`.
+- **Track-changes state** rides a head `<!-- docx:track-changes on -->` line when the
+  document's tracking toggle is enabled (deviation-only — off emits nothing), so an
+  agent sees that subsequent edits will be redlined without inspecting `settings.xml`.
+  Toggle it with `docx track-changes FILE on|off`; the three tracked-change read views
+  (`--accepted`/`--current`/`--baseline`) are covered under the review loop below.
 
 ### Mutate (change FILE in place; `--dry-run`, `-v` everywhere; `-o PATH` on every mutator except `create`, whose positional FILE is already the output)
 
 ```sh
-docx create FILE [--title T] [--author A] [--text "..." | --from PATH.md | --from -] [--force]
+docx create FILE [--title T] [--author A] [--text "..." | --text-file PATH | --from PATH.md | --from -] [--orientation O] [--size SIZE] [--margins M] [--header "..."] [--footer "..." | --page-numbers] [--force]
 docx insert FILE (--after | --before) LOCATOR <content>   # LOCATOR = pN | tN | sN | tN:rRcC:pK
+docx insert FILE (--at-start | --at-end) <content>        # no locator — prepend / append to the document
 docx edit   FILE --at LOCATOR <content>                   # LOCATOR = pN | pN:S-E | pN-pM | sN | eqN | tN:rRcC:pK[:S-E]
-docx delete FILE --at LOCATOR                             # LOCATOR = pN | pN-pM | tN | sN
-docx sections FILE --at LOCATOR --columns N [--type T]    # LOCATOR = pN-pM | pN (wrap a range in N columns) | sN (recount an existing section). Multi-column layout lives HERE, not in insert.
+docx delete FILE --at LOCATOR                             # LOCATOR = pN | pN-pM | tN | sN | tN:rRcC:pK (cell paragraph)
+docx sections FILE [--at LOCATOR] [--columns N] [--type T] [--orientation O] [--size SIZE] [--margins M]   # LOCATOR = pN-pM | pN (wrap a range in N columns) | sN (edit one section's columns/type/page geometry). Multi-column layout AND page setup live HERE. PAGE GEOMETRY (margins/orientation/size) with NO --at applies to the WHOLE document (every section); --at sN targets one. Columns/type need --at.
+docx styles set-default-font FILE "Font Name" [--size N] [--all]   # document-wide font: sets styles.xml docDefaults + theme major/minor; --all also repoints styles/runs that pin their own font
 docx replace FILE PATTERN REPLACEMENT [--regex] [--ignore-case] [--all] [--limit N] [--current | --baseline] [--exact] [--track] [--dry-run]
+#   Keeps the run's formatting (bold/font) and any tabs — the no-rebuild way to fill a
+#   formatted/tabbed template line (e.g. "**Org Name**⇥Date"); don't hand-build --runs to refill it.
+#   A span edit (find → edit --at pN:S-E --text NEW) does the same by locator.
 
 # Batch — apply many changes from ONE read (no re-reading between edits). Keys
 # on each JSONL line mirror the command's flags; all locators address the doc as
@@ -154,17 +203,37 @@ docx delete  FILE --batch drop.jsonl        # { at } per line — whole blocks (
 # insert/edit content selectors (run "docx insert --help" / "docx edit --help" for the full list):
 #   --text "..." [--style NAME] [--alignment A] [--color HEX] [--bold] [--italic] [--url URL]
 #       (a newline in --text becomes a line break <w:br/>, a tab becomes <w:tab/> — verse/addresses stay line-per-line)
+#   paragraph spacing/indent (insert + edit, alone or with content, per-entry in --batch, across a range):
+#       --space-before PT --space-after PT --line-spacing N(=1|1.5|2|single|double, or 15pt / "15pt atLeast")
+#       --indent-left IN --indent-right IN --first-line IN --hanging IN  (points / inches; first-line ⊥ hanging;
+#       left/right/first-line accept a negative value to outdent into the margin; hanging stays non-negative)
+#       Under track-changes these record a tracked <w:pPrChange> (accept/reject in Word) — even when they ride
+#       along with --text; read surfaces them as a deviation-only <!-- docx:p … space-after="6pt" --> hint.
 #   edit --tabs right   fix a line whose tabbed-over content WRAPS (read flags it as `docx:layout … warn`,
 #       and prints ONE consolidated fix-all summary at the top): swaps the fragile LEFT tab for a RIGHT tab
 #       flush at the margin so a long value (e.g. a city) never wraps. Rides along with --text, works
 #       per-entry in --batch, and on a RANGE (edit --at pN-pM --tabs right) cures every tab line at once.
-#   edit --text ""      rejected (it would leave an invisible blank paragraph) — use `delete` to remove the
-#       line, or `--runs '[]'` to blank it but keep an empty spacer.
+#   edit --text ""      REMOVES the line (same as `delete`; a table cell's last paragraph is blanked, not
+#       deleted, so the cell stays valid). In --batch, `{"at":"pN","text":""}` or `{"at":"pN","delete":true}`
+#       removes a line — so a form-fill is ONE sweep: fill the cells with values, drop the leftover
+#       placeholder lines. Use `--runs '[]'` to blank a paragraph but keep an empty spacer. (Empty
+#       `--text` can't ride along with --clear/run-formatting/--style/--alignment/--tabs — those exit
+#       with a USAGE error; use `--runs '[]'` to keep a formatted empty spacer instead.) A SPAN's
+#       `--text ""` (pN:S-E) still deletes just those characters.
 #   --runs '[{"type":"text","text":"X","bold":true}]'
+#   --text-file PATH                               # (insert/create) LITERAL multi-paragraph text, NOT parsed — every char verbatim,
+#       each newline = a new paragraph. For prose GFM would corrupt: "3. note" stays "3.", *x* / [t](u) / bare URLs / {++x++} untouched.
 #   --markdown "..." | --markdown-file PATH        # GFM + math + CriticMarkup + inline HTML formatting → blocks
 #   --code "..." | --code-file PATH [--language LANG]
 #   --equation "x^2 + y^2" [--display]   (insert; edit also accepts --inline)
 #   --clear bold,italic,highlight,color,size,font,…|all   (edit; strip run formatting, keep text)
+#   --bold --italic --underline --strike --color HEX --highlight NAME --shade HEX --font NAME --size PT
+#       --caps --smallcaps --superscript --subscript   (edit; SET run formatting on EXISTING text —
+#       the inverse of --clear. Alone they format a span/paragraph/range in place; with --text they
+#       fill AND format. Like --clear, applied directly — not recorded as a tracked change.)
+#       NOTE: in a single no-content call (or one --batch entry) these run-format SET flags and the
+#       paragraph properties (--style/--alignment/--space-*/--line-spacing/--indent-*/--first-line/
+#       --hanging/--tabs) can't ride together — use separate calls/entries, or add --text to set both.
 #   --task checked|unchecked | --list bullet|ordered [--list-level N]   (insert)
 #   --task checked|unchecked                                            (edit, flip in place)
 #   --table --rows N --cols N [--widths "A,B,C"] [--table-width V] [--borders S] [--layout L]   (insert)
@@ -185,6 +254,17 @@ docx endnotes  add    FILE --at pN[:offset] (--text "..." | --runs JSON | --mark
 docx endnotes  edit   FILE --at enN (--text "..." | --runs JSON | --markdown TEXT)
 docx endnotes  delete FILE --at enN
 
+# Headers & footers (one shared impl — "marginals"). Default placement is every
+# page, all sections (--at sN targets one). Content: ONE primary source, except
+# --text + one field = two-zone (text left, field right at a content-edge tab).
+docx headers set   FILE [--at sN] [--type default|first|even | --first-page | --even | --odd] \
+                        [--text "..."] [--align left|center|right] \
+                        [--page-number [--of-pages] | --date [--date-format FMT] | --style-ref STYLE | --field filename|title|author] \
+                        [--track] [--author NAME]
+docx headers clear FILE [--at sN] [--type T | --first-page | --even | --odd]
+docx footers set   FILE …   # identical flags, kind=footer (e.g. --page-number --of-pages → "Page X of Y")
+docx footers clear FILE …
+
 docx images extract FILE --to DIR [--at imgN]            # --to = output directory; --at picks one image
 docx images replace FILE --at imgN --with ./new.png
 docx images delete  FILE --at imgN
@@ -210,7 +290,7 @@ docx track-changes reject FILE (--at tcN [--at tcM ...] | --at revN | --all)
 ```
 
 > **One rule to memorize: addressing an existing thing is always `--at`.**
-> `comments reply/resolve/delete`, `footnotes/endnotes edit/delete`, `images extract/replace/delete`, `hyperlinks replace/delete`, `tables *`, `track-changes accept/reject`, `edit`, and `delete` all take `--at LOCATOR`. The exceptions are positional or directional by nature: `insert` uses `--after`/`--before LOCATOR`; `read` slices with `--from`/`--to LOCATOR`; `wc` takes a positional `[LOCATOR]`; `find`/`replace` take a positional `QUERY`/`PATTERN`. `images extract --to DIR` is an *output directory*, not a locator.
+> `comments reply/resolve/delete`, `footnotes/endnotes edit/delete`, `images extract/replace/delete`, `hyperlinks replace/delete`, `tables *`, `track-changes accept/reject`, `edit`, and `delete` all take `--at LOCATOR`. The exceptions are positional or directional by nature: `insert` uses `--after`/`--before LOCATOR` (or `--at-start`/`--at-end` for the document boundaries, no locator); `read` slices with `--from`/`--to LOCATOR`; `wc` takes a positional `[LOCATOR]`; `find`/`replace` take a positional `QUERY`/`PATTERN`. `images extract --to DIR` is an *output directory*, not a locator.
 
 ## Output contract
 
@@ -230,13 +310,13 @@ The CLI is built for non-interactive agents. **Exit code is the success signal**
 | Command class | Default stdout on success | `--verbose` |
 | ------------- | ------------------------- | ----------- |
 | **Mutator that mints a new handle** — `comments add`→`cN`, `comments reply`→`cN`, `footnotes/endnotes add`→`fnN`/`enN`, `hyperlinks add`→`linkN`, `insert`→the new `pN` | the bare locator(s), **one per line** (a multi-block `--markdown` insert prints several) | full `{ok:true,…}` ack |
-| **Mutator with no new handle** — `edit`, `delete`, `replace`, `create`, `comments resolve/delete`, `images replace/delete`, `hyperlinks replace/delete`, `footnotes/endnotes edit/delete`, `tables *`, `track-changes accept/reject` & toggle | **one-line confirmation** — `<operation> <target>` (e.g. `edit t1:r0c1:p0`, `edit 7 changes`, `replace 0 occurrences replaced`) (exit `0`) | full `{ok:true,…}` ack |
+| **Mutator with no new handle** — `edit`, `delete`, `replace`, `create`, `comments resolve/delete`, `images replace/delete`, `hyperlinks replace/delete`, `footnotes/endnotes edit/delete`, `headers/footers set/clear`, `tables *`, `track-changes accept/reject` & toggle | **one-line confirmation** — `<operation> <target>` (e.g. `edit t1:r0c1:p0`, `edit 7 changes`, `replace 0 occurrences replaced`) (exit `0`) | full `{ok:true,…}` ack |
 | `find` | matched span locators, one per line (no matches → nothing, exit `0`) | `--json` → `{ totalMatches, query, view, matches:[…], normalizedQuery? }` |
 | `wc` | the bare count (whole-doc adds a tab-separated `sections` column, like `wc`) | `--json` → `{ words, scope, view, sections? }` |
 | `outline` | indented `LOCATOR⇥TEXT` tree (two spaces per level) | `--json` → nested `[{ id, locator, level, style, text, children }]` |
-| `read` | GFM Markdown, each paragraph trailed by `<!-- pN -->` | `--ast` → the JSON AST body (`docx info schema`) |
+| `read` | GFM Markdown; each paragraph carries its `pN` locator once — a trailing bare `<!-- pN -->` on plain paragraphs, or the leading token of its `<!-- docx:p pN … -->` note when one is emitted | `--ast` → the JSON AST body (`docx info schema`) |
 | `render` | image paths, one per line | `--verbose` → `{ok, operation, path, engine, output, pages}` |
-| `* list` (all six `list` verbs) | a **bare JSON array**; each item's `id` is its `--at` handle | — |
+| `* list` (all eight `list` verbs) | a **bare JSON array**; each item's `id` is its `--at` handle | — |
 
 `--dry-run` always prints a preview object (no `ok`) and writes nothing; it wins over `-o/--output`.
 
@@ -249,6 +329,7 @@ Locators come in two flavors. **Positional block ids** (`pN`, `tN`, `sN`) are de
 | `pN` / `tN` / `sN` (block ids) | `docx read FILE` (the `<!-- pN -->` trailers), `docx read FILE --ast`, `docx outline FILE` (heading `pN`s), or `docx render` page images | `read`, `edit`, `insert`, `delete`, `wc`, `find` results |
 | `cN` (comment) | `docx comments list FILE` | `comments reply/resolve/delete --at` |
 | `fnN` / `enN` (foot/endnote) | `docx footnotes list FILE` / `docx endnotes list FILE` | `footnotes/endnotes edit/delete --at` |
+| `hdrN` / `ftrN` (header/footer) | `docx headers list FILE` / `docx footers list FILE` (or `read --ast`) | addressed by section+type, not the id: `headers/footers set --at sN --type T` |
 | `imgN` (image) | `docx images list FILE` | `images extract/replace/delete --at` |
 | `linkN` (hyperlink) | `docx hyperlinks list FILE` | `hyperlinks replace/delete --at` |
 | `tcN` (tracked change) | `docx track-changes list FILE` | `track-changes accept/reject --at` |
@@ -280,7 +361,7 @@ cN  imgN  linkN  fnN  enN  tcN  eqN          entity ids (comment / image / hyper
 | ---- | ----------- |
 | `pN`, `tN`, `sN`, `tN:rRcC:pK` (blocks) | `read --from/--to`, `insert --after/--before`, `wc`, `comments add` |
 | `pN`, `pN:S-E`, `pN-pM`, `sN`, `eqN`, `tN:rRcC:pK`, `tN:rRcC:pK:S-E` | `edit --at` (span/cell forms strip or replace just that range) |
-| `pN`, `pN-pM`, `tN`, `sN` | `delete --at` |
+| `pN`, `pN-pM`, `tN`, `sN`, `tN:rRcC:pK` | `delete --at` |
 | `pN:S-E`, `pN:S-pM:E`, `tN:rRcC:pK:S-E` (spans) | `comments add --at`, `hyperlinks add --at` (single paragraph), `find`/`wc` results |
 | `pN[:offset]` (point) | `footnotes/endnotes add --at` |
 | `cN` / `fnN` / `enN` / `imgN` / `linkN` / `tcN` (entities) | the matching noun's `--at` (the `c`/`fn`/`en`/`img`/`link`/`tc` prefix is optional) |
@@ -333,6 +414,12 @@ docx track-changes accept doc.docx --at tc0 --at tc2   # or --all
 
 **Markdown dialect.** `create --from`, `insert/edit --markdown`, and the note bodies all parse the same GFM + math + CriticMarkup + inline-HTML-formatting dialect (remark + remark-gfm + remark-math + an in-house inline-surgery transform), composing the existing OOXML emitters. `read` emits a compatible dialect, so the read → edit → write loop round-trips (lossless for paragraphs, lists, and nested blockquotes; code/tables/math/headings inside a blockquote intentionally escape to top level on import). `read --ast` is the fully lossless JSON form.
 
+**Literal text — the parser-free channel.** When you want prose inserted *exactly* — reviewer notes, quoted excerpts, anything where Markdown would misfire — use `create --text-file PATH` / `insert --text-file PATH` (or `-` for stdin). Every character lands verbatim and each newline starts a new paragraph; nothing is interpreted, so `3. note` stays `3.` (no ordered-list renumber), and `*x*`, `[t](u)`, bare URLs, and `{++x++}` are kept as written. This exists because GFM corruption isn't always escapable: bare URLs autolink with no escape sequence at all, and CriticMarkup eats `{++…++}` regardless of backslashes — so a literal path is the only safe way to author untouched prose.
+
+**Document-wide font.** `docx styles set-default-font FILE "Times New Roman"` sets the font in the two places a font actually lives — `word/styles.xml` `<w:docDefaults>` (the formal default) *and* the theme font scheme (`word/theme/theme1.xml`, major + minor `<a:latin>`), since real Word docs resolve their fonts *through* the theme and touching only one silently loses to the other. Body text and theme-following headings both adopt it; styles or runs that pin their own font (a code block's monospace, a deliberately-Arial run) are preserved and named in the ack, with `--all` to repoint even those. `--size N` sets the default size on the same write.
+
+**Edit & create styles.** `docx styles set FILE --at Heading1 --color 1F4E79 --size 16 --bold` rewrites the *style definition* in `word/styles.xml`, so every paragraph or run that uses the style picks up the change at once ("make all Heading 1s green") — the same run-/paragraph-formatting flags as `edit` (color/font/size/highlight/underline/caps + alignment/spacing/indentation for paragraph styles). `docx styles create FILE Callout --color C00000 --bold` mints a new paragraph or character style that `insert/edit --style Callout` can then apply. Editing an un-materialized built-in (`--at Heading3` on a doc that never used it) provisions it first; a paragraph with its own *direct* formatting keeps it (the override wins — the definition edit never touches the body). Style edits are **not** tracked changes even under track-changes — matching Word, which applies style-definition edits to `styles.xml` directly with no redline.
+
 **Run formatting beyond bold/italic.** Properties markdown has no native syntax for — text color, theme color, highlight, shading, underline (all 18 styles + color), super/subscript, small/all caps, font, and size — are emitted as the **HTML a markdown reader actually renders**, so the output looks right in GitHub, VS Code, Obsidian, and browsers (Pandoc `[text]{…}` spans render as literal brackets in all of those). `read` emits semantic tags where they exist — `<mark>overdue</mark>`, `<sup>x</sup>`, `<sub>2</sub>` — a `<span style="color:#C00000">…</span>` for the CSS-expressible properties, and `data-*` attributes for the OOXML-only ones CSS can't express (theme colors, underline styles); `insert/edit --markdown` parses them back losslessly, and a leading `<!-- docx:base font="Arial" size="8pt" -->` note declares the document's dominant font/size once so the body isn't buried in per-run repetition. Bold/italic/strike/code/links stay native (`**`/`*`/`~~`/`` ` ``/`[](…)`). Because the inline-surgery transform scans whole sibling sequences, a CriticMarkup marker or span can straddle other formatting — `{++**bold insertion**++}` is tracked correctly. An invalid enum value (e.g. a bogus highlight name) fails with a clear error rather than silently vanishing. Inserted plain content inherits the surrounding paragraph's font/size so it blends in.
 
 **Visual verification.** `docx render` is the only command that needs an external runtime: it drives Microsoft Word (macOS via `osascript`, Windows via PowerShell COM — the ground-truth renderer) or LibreOffice (`soffice`, cross-platform) to produce a PDF, then rasterizes in-process via the bundled `@hyzyla/pdfium` WASM package — no poppler/pdftoppm/ImageMagick needed. Agents that consume PNGs use this to verify edits, diff accept/reject before-vs-after, or generate screenshots.