@docx4j/core-ts 0.1.0 → 0.1.2

package/README.md

@@ -6,12 +6,18 @@ and font resolution, over the Office Open XML object model of
 [`@docx4j/generated-objects-ts`](https://github.com/plutext/docx4j-generated-objects-ts). Node,
 browsers and Word add-ins.
 
-Status: the Open Packaging layer, the typed parts and the packages (Phase A of
-[CR-001](docs/change-requests/CR-001-engine.md)) are implemented; the resolution utilities
-(`PropertyResolver`, list numbering, fonts: Phase B) are next.
+Status: [CR-001](docs/change-requests/CR-001-engine.md), the engine, is **complete**. The Open
+Packaging layer, the typed parts and the packages (Phase A); `PropertyResolver`, list numbering,
+so a paragraph can be asked for the label Word would paint, and font selection, so a run's font
+resolves through the theme, with paragraph and run reads reporting the formatting that actually
+applies (Phase B); the pptx and xlsx packages with `createPackage()`, the unzipped-directory
+container, `clone()`, and the guides and examples below (Phase C). Every resolution answer is
+held to docx4j's own on 45 documents (`test/golden/`, made by the Java harness in `test/java/`):
+the resolver, the emulator and the selector agree with docx4j `VERSION_17_1_1` exactly.
 
 ```
 npm install @docx4j/core-ts
+npm install xpath        # optional, Node only: XPath over custom XML parts (browsers use document.evaluate)
 ```
 
 ```ts
@@ -39,11 +45,28 @@ const ooxml = await pkg.saveFlatOpc();              // pkg:package, for insertOo
 A part that is never touched is written back byte for byte; `getContents()` (or a view over
 it) marks a part for re-marshalling. `mc:AlternateContent` is resolved when a part is
 unmarshalled, as Word does on open (`{ mcePreprocess: false }` to keep it). Subpaths
-`@docx4j/core-ts/opc`, `/parts`, `/packages` and `/model` give the layers separately.
+`@docx4j/core-ts/opc`, `/parts`, `/packages` and `/model` give the layers separately,
+`/office-js` the `Word` shim (below), and `/node` the one Node-only piece (the unzipped-directory
+container; nothing else in the package imports a `node:` builtin, so a browser or add-in bundle
+never sees one).
+
+### Guides
+
+| | |
+|---|---|
+| [Getting started in Node](docs/guides/getting-started-node.md) | install, load, the content API, save |
+| [In a Word add-in](docs/guides/office-addin.md) | flat OPC in and out, testing add-in code in Node, bundling |
+| [pptx and xlsx](docs/guides/presentationml-spreadsheetml.md) | what the PresentationML and SpreadsheetML packages give |
+| [Parity with docx4j](docs/guides/parity.md) | what the goldens are, and running the harness against a newer docx4j |
+
+Runnable code: [`examples/node/`](examples/node) (create, report, pptx, xlsx, an unzipped
+directory) and [`examples/office-addin/`](examples/office-addin) (a sideloadable Word task pane
+whose edit also runs in Node). `test/examples.test.mjs` runs them all, so they cannot rot.
 
 ### The content API
 
-`Body`, `Paragraph`, `Range` and `Font` follow Office JS's `Word.*` shapes (a compile-time
+`Body`, `Paragraph`, `Range`, `Font`, `Table`, `InlinePicture` and `ContentControl` follow
+Office JS's `Word.*` shapes (a compile-time
 check keeps them assignable to a subset of those types), so add-in code runs against a
 package with its `load` and `sync` lines removed. Hello World, from nothing to a `.docx`:
 
@@ -61,7 +84,7 @@ Editing what is there:
 ```ts
 const body = await pkg.getBody();
 const title = body.insertParagraph('Report', 'Start');
-title.styleBuiltIn = 'Heading 1';
+title.styleBuiltIn = 'Heading1';                       // Word.Style value; title.style reads 'Heading 1'
 title.alignment = 'Centered';
 const [hit] = body.search('quick brown fox');          // across runs
 hit.font.italic = true;                                // runs split at the boundaries
@@ -84,6 +107,129 @@ Docx4j's names are there as aliases (`addParagraphOfText`, `addStyledParagraphOf
 `addObject`, `getContent`), and the tree stays reachable: `paragraph.p` is the `P`,
 `body.content` the live array.
 
+### List numbering
+
+`Emulator` is docx4j's list-numbering emulator: the label Word would paint in front of a
+paragraph, given its `w:pPr`. Counters live in a `NumberingState`, one per **story** — Word
+numbers the body, the headers and footers together, each notes part and each text box from their
+own counters — so a caller walks a story in document order with the state for it.
+
+```ts
+import { WordprocessingMLPackage, Emulator, NumberingStates } from '@docx4j/core-ts';
+
+const pkg = await WordprocessingMLPackage.load(bytes);
+const emulator = await pkg.getNumberingEmulator();   // undefined when the document has no lists
+const states = new NumberingStates();
+const main = pkg.getMainDocumentPart();
+const state = states.forPart(main);                  // states.forPart(headerPart), states.newStory(), ...
+
+for (const paragraph of (await main.getBody()).paragraphs) {
+  const label = emulator?.getNumber(paragraph.p.pPr, state);
+  if (label) console.log(label.numString, label.isBullet, label.indResolved?.left);
+}
+
+Emulator.peek(pkg, pPr, state);        // the same answer, without taking the number
+Emulator.numRefFor(pkg, pPr);          // which list and level, or why Word numbers nothing
+pkg.numberingDefinitionsPart.getIndOf('3', '0');   // the indent that level contributes
+```
+
+Reading labels does not unmarshal `word/numbering.xml`, so a document you only read still saves
+byte for byte. After editing the numbering or styles parts, `await pkg.refresh()`.
+
+### Lists
+
+`Word.List` and `Word.ListItem` over the same numbering, so an add-in's list code runs here
+unchanged. A paragraph knows whether Word numbers it — through its own `w:numPr` or through a
+numbered style — which list it is in and what label it shows.
+
+```ts
+const body = await pkg.getBody();
+
+for (const p of body.paragraphs) {
+  if (p.isListItem) console.log(p.listItem.listString, p.listItem.level, p.text);
+}
+
+body.lists;                     // every list a paragraph of this body names, in order of first use
+body.listLabels();              // Map<P, { listString, level, numId, siblingIndex, isBullet }>, in one walk
+```
+
+`listItem.listString` is the label Word paints, counted by walking the paragraph's story from
+its start — Word's numbering is a running count, so that walk is the answer. Use
+`body.listLabels()` when you want every label at once.
+
+Making and changing lists:
+
+```ts
+const list = await p.startNewList();            // { bullet: true } for the bullet set
+p2.attachToList(list.id, 1);                    // join it, at level 1
+p2.listItem.level = 2;                          // or move it
+p3.detachFromList();
+
+list.setLevelNumbering(0, 'UpperRoman', ['(', 0, ')']);   // w:numFmt and w:lvlText "(%1)"
+list.setLevelBullet(1, 'Square');
+list.setLevelIndents(0, 36, 18);                // points, as Office JS
+list.setLevelStartingNumber(0, 5);
+
+const again = p4.restartList();                 // the same list, numbering again from its start
+```
+
+A level writer changes the `w:abstractNum`, so it copies that definition first when another
+`w:num` shares it — the change stays local to this list. `startNewList()` is asynchronous here
+(Office JS's is not): it copies its definition from docx4j's default `numbering.xml` and adds
+the numbering part when the document has none.
+
+### Change tracking
+
+`pkg.changeTrackingMode` is Office JS's `document.changeTrackingMode`, backed by
+`w:trackRevisions` in the settings part. While it is on, every edit made through the content
+API writes Word's revision markup instead of changing the tree in place: an insertion becomes
+`w:ins`, a deletion `w:del` with `w:delText`, a replacement a `w:del` followed by a `w:ins`, a
+new paragraph's mark `w:pPr/w:rPr/w:ins`, a deleted one `w:pPr/w:rPr/w:del`, and a formatting
+change keeps what was there in `w:rPrChange` or `w:pPrChange`. The author is `pkg.author` and
+the date `pkg.trackedChangeDate` (now, unless you fix one).
+
+```ts
+pkg.author = { name: 'Ada Lovelace' };      // the same author phase G's comments use
+pkg.changeTrackingMode = 'TrackAll';           // await pkg.setChangeTrackingMode(...) on a loaded package
+body.search('quick brown fox')[0].insertText('slow red fox', 'Replace');
+body.replaceText('colour', 'color');           // returns the number replaced, tracked like any other edit
+
+body.text;                                     // the accepted view: w:ins in, w:del out
+body.getText({ view: 'original' });            // the other way round
+
+for (const change of body.getTrackedChanges()) {
+  change.type;        // 'Added' | 'Deleted' | 'Formatted'
+  change.author; change.date; change.text;
+  change.getRange();  // where it is
+}
+body.acceptAll();     // or rejectAll(), or accept()/reject() one at a time
+```
+
+`getTrackedChanges()` is also on `Paragraph` and `Range`. Text and searches read the accepted
+view throughout, so an agent sees the document as it will read once the changes are taken.
+
+### Comments
+
+`getComments()` on the body, a paragraph or a range, and `insertComment` on a range or a
+paragraph, over the four parts Word writes (`w:comments`, `w15:commentsEx`, `w16cid` and
+`w:people`, plus `w16cex` when the document has one); threads, `resolved` (`w15:done`) and
+`delete()` keep them all in step, and any of the parts the document lacks is created with its
+relationship, content type and the `CommentText` and `CommentReference` styles.
+
+```ts
+pkg.author = { name: 'Ada Lovelace', initials: 'AL', email: 'ada@example.com' };   // whose comments these are
+
+const [hit] = body.search('quick brown fox');
+const comment = await hit.insertComment('Is this the right idiom?');
+await comment.reply('Yes, Word writes it this way');
+comment.resolved = true;                       // w15:done
+
+for (const c of await body.getComments()) {    // document order, replies nested
+  console.log(c.authorName, c.creationDate, c.content, c.replies.length, c.getRange().map((r) => r.text));
+  if (c.resolved) await c.delete();            // the comment, its replies, the markers and every side entry
+}
+```
+
 ### XML in
 
 A whole `word/document.xml` becomes the main document part's contents with `setXml`, and a
@@ -107,18 +253,272 @@ import * as el from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
 body.addObject(el.p({ content: [el.r({ content: [el.t({ value: 'Hello World' })] })] }));
 ```
 
-Tables, pictures, `insertOoxml` from a `pkg:package`, custom XML parts, XML mapping and typed
-content controls are the next phases of
-[CR-002](docs/change-requests/CR-002-content-api.md); effective formatting (styles resolved,
-as Office JS reports it) comes with [CR-001](docs/change-requests/CR-001-engine.md) Phase B.
+### Tables, pictures and content controls
+
+`Table`, `TableRow` and `TableCell` are Office JS shapes too; a cell is a `Body` of its own, so
+everything above works inside one:
+
+```ts
+const table = body.insertTable(3, 2, 'End', [['Item', 'Price'], ['apples', '$20']]);
+table.styleBuiltIn = 'TableGrid';           // Word.Style value; table.style is then 'Table Grid', table.styleId 'TableGrid'
+table.headerRowCount = 1;                   // w:tblHeader: the row repeats on every page
+table.getCell(1, 1).value = '$25';
+table.addRows('End', 1, [['pears', '$30']]);
+table.values;                               // [['Item', 'Price'], ['apples', '$25'], ['pears', '$30']]
+body.paragraphs[4].parentTableCell?.cellIndex;
+```
+
+A picture adds its own `ImagePart`, the relationship and a `w:drawing` sized from the image's
+pixels and resolution (96 dpi when the file declares none, as docx4j does), scaled down if it
+is wider than the text area:
+
+```ts
+const picture = body.insertInlinePictureFromBase64(pngBase64, 'End', { altTextDescription: 'The logo' });
+picture.width = 144;                        // points; the height follows the aspect ratio
+picture.imageFormat;                        // 'Png'
+await body.inlinePictures[0].getBase64();
+```
+
+`insertOoxml` takes what Word's does, a flat OPC `pkg:package` string: the body content comes
+over with the parts it references (images, embedded objects) copied in under fresh names and
+relationship ids. A bare fragment works too, as `insertXml`.
+
+```ts
+await body.insertOoxml(await other.saveFlatOpc(), 'End');       // or an add-in's getOoxml() string
+```
+
+Content controls (`w:sdt`) are read at block, row, cell and run level:
+
+```ts
+for (const control of body.contentControls) {
+  console.log(control.form, control.type, control.title, control.tag, control.text);
+}
+body.contentControls[0].insertText('Jane Doe', 'Replace');
+body.contentControls[1].delete(true);       // unwrap, keeping what it held
+```
+
+`Font` and `Paragraph` reads report **effective** formatting - the document defaults, the style
+chain and the numbering level resolved, as Office JS reports it - through docx4j's
+`PropertyResolver` (CR-001 Phase B step 2). Writes are always direct formatting, and
+`paragraph.getFont({ direct: true })`, `range.getFont({ direct: true })` and
+`paragraph.formatting({ direct: true })` read the direct values.
+
+```ts
+const p = (await pkg.getBody()).paragraphs[0];
+p.font.size;                                 // 14: the style's w:sz, not the run's
+p.getFont({ direct: true }).size;             // 0: the run states none
+p.alignment;                                 // 'Left' when nothing states a w:jc, as Word lays it out
+p.formatting({ direct: true }).alignment;     // 'Unknown'
+p.effectivePPr;                               // docx4j's resolved w:pPr, for anything the view does not cover
+```
+
+### Custom XML and content controls
+
+`pkg.customXmlParts` is Office JS's `CustomXmlPartCollection` over the custom XML data storage
+parts, with XPath 1.0 over their DOM: `document.evaluate` in a browser or a Word add-in, the
+optional peer dependency [`xpath`](https://www.npmjs.com/package/xpath) in Node (`npm install
+xpath`; `pkg.xpathEngine` takes any other engine). One `await` warms it, and the node model is
+synchronous from then on:
+
+```ts
+const parts = await pkg.customXmlParts.load();        // parses the DOMs, warms the XPath engine
+const data = pkg.customXmlParts.getItem('{8B049945-9DFE-4726-9DE9-CF5691E53858}');
+data.selectSingleNode('/invoice/customer/name').text;         // 'Joe Bloggs'
+data.selectNodes('/invoice/items/item').map((n) => n.text);
+data.documentElement.appendChildNode('<note>paid</note>');
+```
+
+A content control's `xmlMapping` is its `w:dataBinding`, and the two directions are docx4j's,
+under docx4j's names:
+
+```ts
+const control = (await pkg.getBody()).contentControls[0];
+control.xmlMapping.isMapped;                          // true
+control.xmlMapping.xpath;                             // '/invoice[1]/customer[1]/name[1]'
+control.xmlMapping.customXmlNode.text;                // 'Joe Bloggs'
+
+await pkg.customXmlParts.applyBindings();             // docx4j BindingHandler: XML -> controls
+control.insertText('Jane Doe', 'Replace');            // writes through to the bound node as well
+await pkg.customXmlParts.updateFromContentControls(); // docx4j: controls -> XML
+```
+
+That last pair matters: Word refreshes a bound control from the custom XML part when it opens a
+document, so an edit that only touched `w:sdtContent` would not show.
+
+A new part comes with its properties part, a fresh `ds:itemID` and the relationship from the main
+document part (Word drops a custom XML part the main part does not relate to):
+
+```ts
+const part = pkg.customXmlParts.add('<greeting xmlns="http://example.com/g"><to>World</to></greeting>');
+control.xmlMapping.setMapping('/ns0:greeting[1]/ns0:to[1]', "xmlns:ns0='http://example.com/g'", part);
+control.xmlMapping.setMappingByNode(part.selectSingleNode('/ns0:greeting/ns0:to', "xmlns:ns0='http://example.com/g'"));
+```
+
+Controls are created by wrapping what is there, and the kind-specific views are Office JS's:
+
+```ts
+const control = paragraph.insertContentControl('CheckBox');   // also on body and range
+control.checkboxContentControl.isChecked = true;              // shows ☒, as Word does
+control.title = 'Applies';  control.appearance = 'Tags';  control.cannotDelete = true;
+
+const list = body.paragraphs[1].insertContentControl('DropDownList').dropDownListContentControl;
+list.addListItem('Apples', 'apples');
+```
+
+### Fonts
+
+Two questions, kept apart as they are in docx4j: which **document** font formats each character
+of a run, and which physical face draws that name.
+
+`RunFontSelector` answers the first. It resolves the run's effective properties, resolves every
+theme reference (`w:asciiTheme` and friends) through the theme part for the document's
+`w:themeFontLang`, and then walks the text through the [MS-OI29500] 17.3.2.26 character-range
+table, folding the answer into spans:
+
+```ts
+const main = pkg.getMainDocumentPart();
+const selector = await main.getRunFontSelector();
+
+selector.spans(paragraph.pPr, run.rPr, 'Hello 日本 שלום');
+// [ { text: 'Hello ', documentFont: 'Calibri', bold: false, italic: false,
+//     cs: false, rtl: false, script: 'LATIN' },
+//   { text: '日本',   documentFont: 'MS Gothic', ..., script: 'CJK' },
+//   { text: ' ',      documentFont: 'Calibri',  ..., script: null },
+//   { text: 'שלום',   documentFont: 'Calibri',  ..., script: 'HEBREW' } ]
+
+selector.documentFontFor(paragraph.pPr, run.rPr, 0x1F600);   // one code point
+selector.asciiFontName(effectiveRPr);                        // what `font.name` reports
+selector.defaultFont;                                        // the document's default face
+```
+
+`w:cs` and `w:rtl` are read **by value** (`<w:cs w:val="0"/>` turns an inherited complex-script
+flag off), the symbol fonts are matched case-insensitively, and the space between two East Asian
+words takes the ascii font — each of those verified against Word, in docx4j's CR-016.
+
+A package with **no theme part** is read as coming from a particular version of Word:
+`pkg.fonts.defaultTheme` is `'2023'` (Word 365: Aptos Display / Aptos), `'2013'` (Calibri Light /
+Calibri) or `'2007'` (Cambria / Calibri). `createPackage()` gives a new package that theme's
+theme part, as Word does, so a document created here and one created by docx4j resolve alike.
+
+`Mapper` answers the second question, over a `FontRegistry` the caller supplies — the names the
+consumer can actually draw with. `IdentityPlusMapper` takes the font itself where the registry
+has it, then the document's embedded form, a variant of the name, docx4j's measured substitute
+table (`font-substitutes.xml`: Arial to Arimo, Calibri to Carlito, Cambria to Caladea, Aptos to
+Akasia), the document's own `w:altName` chain, a face of the same class, and finally what Word
+itself draws a font it cannot find:
+
+```ts
+const mapper = await main.getFontMapper();       // IdentityPlusMapper over DEFAULT_FONT_REGISTRY
+mapper.get('Calibri');                           // PhysicalFont { name: 'Carlito Regular', familyName: 'Carlito' }
+mapper.getDecision('Calibri');                   // { source: 'METRIC_CLONE', via: null, widthError: '0.07% ...' }
+
+await main.fontsInUse();                         // every name the document could ask for
+await main.getStylesInUse();                     // the style ids used directly
+
+// your own font environment
+const mine = new IdentityPlusMapper(new SimpleFontRegistry(faces.map((f) => new PhysicalFont(f.fullName, f.family))));
+await main.getFontMapper(mine);
+```
+
+The default registry is the faces docx4j's four font jars carry, which is the environment the
+parity goldens were made in. Reading font files (`PhysicalFonts.discover`, glyph coverage, font
+metrics) is a later CR; the `Mapper` interface is what a consumer with `fontkit` plugs into.
+
+### pptx and xlsx
+
+The Open Packaging layer is one layer for all three formats: a `.pptx` and an `.xlsx` load, round
+-trip byte for byte and save exactly as a `.docx` does, with their parts typed by the same object
+model. What they do not have is the content API, which is WordprocessingML.
+
+```ts
+import { PresentationMLPackage, SpreadsheetMLPackage } from '@docx4j/core-ts';
+
+const deck = await PresentationMLPackage.createPackage({ slideSize: 'SCREEN16x9' });
+await deck.addSlide();
+deck.slideParts;                              // in p:sldIdLst order; .slideMasterParts, .slideLayoutParts
+
+const book = await SpreadsheetMLPackage.createPackage();
+const sheet = book.createWorksheetPart('Sales');   // the tab, its r:id and the worksheet part
+book.worksheetParts;                          // in `sheets` order; .sharedStringsPart, .stylesPart
+```
+
+Both follow docx4j's part set, so the files open in PowerPoint and Excel; the detail is in
+[docs/guides/presentationml-spreadsheetml.md](docs/guides/presentationml-spreadsheetml.md).
+
+### Use in Node: running add-in code against a package
+
+`@docx4j/core-ts/office-js` is a `Word` shim: `Word.run(pkg, fn)` gives the callback a
+`context` whose `document.body` is the package's body, `load()` is a no-op and `context.sync()`
+resolves what was asynchronous. An add-in's batch therefore runs unchanged in a test, in CI,
+or on a server, with the saved `.docx` as the assertion — and a member this package does not
+implement throws `NotSupportedError` naming it, rather than doing nothing.
+
+```ts
+import { WordprocessingMLPackage } from '@docx4j/core-ts';
+import { Word } from '@docx4j/core-ts/office-js';
+
+const pkg = await WordprocessingMLPackage.load(bytes);
+await Word.run(pkg, async (context) => {
+  const paragraphs = context.document.body.paragraphs;
+  paragraphs.load('text');
+  await context.sync();
+
+  paragraphs.items[0].styleBuiltIn = Word.Style.heading1;
+  for (const range of context.document.body.search('draft')) range.font.highlightColor = '#FFFF00';
+  context.document.properties.lastAuthor = 'an add-in';
+  context.document.changeTrackingMode = Word.ChangeTrackingMode.trackAll;
+
+  const ooxml = context.document.body.getOoxml();   // a ClientResult, as in Office JS
+  await context.sync();
+  ooxml.value;                                      // the flat OPC package
+});
+await writeFile('edited.docx', await pkg.save());
+```
+
+`Word.supported` is the set of `Class.member` strings this package implements
+(`Word.supported.has('Body.insertParagraph')`), generated from the compile-time subset, so a
+tool can check a script before running it. The selection an add-in edits is passed in:
+`Word.run(pkg, fn, { selection })`.
+
+`toApiScript` goes the other way: given a paragraph, a range or an element, it emits the
+content-API calls that reproduce it, falling back to `insertXml` for what the verbs cannot say.
+
+```ts
+import { toApiScript } from '@docx4j/core-ts/model';
+
+await toApiScript(body.paragraphs[1]);
+// const p1 = body.insertParagraph('Chapter 1', 'End');
+// p1.styleBuiltIn = 'Heading1';
+// p1.alignment = 'Centered';
+// const r1 = p1.insertText(' (draft)', 'End');
+// r1.font.italic = true;
+```
+
+The bundling rules for an add-in, and a complete sideloadable example, are in
+[docs/guides/office-addin.md](docs/guides/office-addin.md). A generated script reproduces the
+document's *markup*, so it emits direct formatting only, not the effective values the reads
+report (CR-001 Phase B step 2).
 
 ## Development
 
 ```
 npm ci                              # the locked dependencies from npm
 npm run typecheck && npm test       # test = build, then node --test test/*.test.mjs
+npm run typecheck:examples          # examples/office-addin (also run by npm run typecheck)
+npm run generate                    # src/office-js/supported.generated.mts from test/office-js-subset.ts
+npm run generate:fonts              # src/model/fonts/*.generated.mts from a docx4j checkout
 ```
 
+`npm run generate` is committed output: the build does not depend on the script, but `npm test`
+regenerates it so that `Word.supported` stays in step with the Office JS subset.
+`npm run generate:fonts` is committed output too, re-run when docx4j's font tables change; it
+reads a sibling `../docx4j` checkout and records the commit it ran against in each header.
+
+The parity goldens under `test/golden/` are docx4j's own answers for 45 documents, produced by
+the Java harness in [`test/java/`](test/java/README.md) and compared by `test/parity.test.mjs`.
+They are regenerated by hand when docx4j or the fixtures change, and weekly by
+`.github/workflows/parity.yml`, which opens a pull request when docx4j's answer moves.
+
 Releases are published to npm from GitHub Actions; see `RELEASING.md`.
 
 ## Licence

package/dist/model/content/Body.d.mts

@@ -1,10 +1,18 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import type { PropertyResolver } from '../properties/PropertyResolver.mjs';
 import type { XmlPart } from '../../parts/XmlPart.mjs';
 import type { OpcPackage } from '../../packages/OpcPackage.mjs';
-import { type Element } from './tree.mjs';
+import { type Element, type TextViewOptions } from './tree.mjs';
 import { Paragraph } from './Paragraph.mjs';
 import { Range } from './Range.mjs';
+import { Table } from './Table.mjs';
+import { ContentControl, type ContentControlType } from './ContentControl.mjs';
+import { InlinePicture, type InlinePictureOptions } from './InlinePicture.mjs';
 import type { SearchOptions } from './search.mjs';
+import type { Comment } from './Comment.mjs';
+import { type ChangeTracker } from './tracking.mjs';
+import { type TrackedChange } from './TrackedChange.mjs';
+import { type List, type ListLabel } from './List.mjs';
 /** Where a paragraph or table is, for agents and across tool calls (CR-002 section 3.3). */
 export type Address = string | {
     contains: string;
@@ -55,17 +63,71 @@ export declare class Body {
     }, 
     /** The address prefix: 'body', 'header:rId3', 'footer:rId4', 'footnote:2'. */
     prefix?: string, package_?: OpcPackage | undefined);
+    /**
+     * The package's `PropertyResolver`, which every effective-formatting read goes through
+     * (CR-001 Phase B step 2). Throws `PropertyResolverNotCreatedException` when this body has
+     * no package, or the package has not built one yet: building it unmarshals the styles part,
+     * which cannot be done synchronously, so `await pkg.getPropertyResolver()` (or `getBody()`,
+     * which does it) first - or read direct formatting with `{ direct: true }`.
+     */
+    get propertyResolver(): PropertyResolver;
     /** The live content array (docx4j getContent()); block-level elements only, sectPr excluded. */
     get content(): Element[];
     /** Every paragraph in document order, descending into tables and content controls. */
     get paragraphs(): Paragraph[];
-    /** The tables directly in this body (as elements; `Table` views are CR-002 Phase C). */
-    get tables(): BlockElement[];
+    /** The tables directly in this body, as Office JS reports them (nested tables are a cell's). */
+    get tables(): Table[];
+    /** Every content control in this body, in document order, nested ones included. */
+    get contentControls(): ContentControl[];
+    /** Every inline picture in this body, in document order (Office JS Body.inlinePictures). */
+    get inlinePictures(): InlinePicture[];
+    /**
+     * Office JS `body.lists`: every `w:num` a paragraph of this body names, in the order they are
+     * first used (CR-002 phase H). Empty where the document has no numbering part, or where
+     * nothing has read it yet (`await pkg.getBody()` builds the resolver, which does).
+     */
+    get lists(): List[];
+    /**
+     * Every numbered paragraph of this body's **story** with its label, level, list and sibling
+     * index, in one walk (extension). `listItem.listString` walks the story per read, which is
+     * what Word's counting needs; this is the way to ask for all of them at once.
+     *
+     * Keyed by the `w:p` itself: `labels.get(paragraph.p)?.listString`.
+     */
+    listLabels(): Map<wml.P, ListLabel>;
+    /**
+     * A view over a container nested in this body (a cell, a content control), sharing this body's
+     * part and package. The address prefix is the container's own address, so that the addresses a
+     * nested body reports carry on from this one.
+     */
+    sub(container: {
+        content?: Element[];
+    }, prefix?: string): Body;
+    /** The view of a `w:p` somewhere in this body's tree; its container comes from PARENT. */
+    paragraphFor(p: wml.P): Paragraph | undefined;
     /** The text, a paragraph per line. */
     get text(): string;
+    /**
+     * The text in one of the two views (extension; `text` is the accepted one).
+     * `{ view: 'original' }` reads the document as it was before the tracked changes.
+     */
+    getText(options?: TextViewOptions): string;
+    /** The package's change tracker while `changeTrackingMode` is on; undefined when it is off (CR-002 phase F). */
+    get changeTracker(): ChangeTracker | undefined;
     insertParagraph(text: string, location: 'Start' | 'End'): Paragraph;
     /** Text at the start of the first paragraph, the end of the last, or replacing everything with one paragraph. */
     insertText(text: string, location: 'Start' | 'End' | 'Replace'): Range;
+    /**
+     * A table of `rowCount` by `columnCount` cells at the start or end (Office JS insertTable);
+     * `values` fills it row by row. The columns are equal over the section's text width.
+     */
+    insertTable(rowCount: number, columnCount: number, location: 'Start' | 'End', values?: string[][]): Table;
+    /**
+     * Adds the image as a part of this body's part, with a relationship, and shows it in a new
+     * paragraph at the start or the end (Office JS insertInlinePictureFromBase64). An image wider
+     * than the text area is scaled down, as docx4j's CxCy.scale does.
+     */
+    insertInlinePictureFromBase64(base64: string, location: 'Start' | 'End', options?: InlinePictureOptions): InlinePicture;
     insertBreak(type: 'Page' | 'Line', location: 'Start' | 'End'): void;
     /**
      * Inserts block-level elements (docx4j addObject): at the start or end of this body, or
@@ -75,10 +137,41 @@ export declare class Body {
     insertElement(element: Element | Element[], location: 'Start' | 'End' | 'Before' | 'After', target?: Paragraph | BlockElement | Address): Paragraph | BlockElement;
     /** Inserts a WML fragment (one or more w:p / w:tbl / ... as inside document.xml); the standard prefixes are declared for it. */
     insertXml(xml: string, location: 'Start' | 'End' | 'Before' | 'After', target?: Paragraph | BlockElement | Address): Promise<(Paragraph | BlockElement)[]>;
+    /**
+     * Word's `insertOoxml`: a flat OPC `pkg:package` string, whose body content is inserted with
+     * the parts it references (images, embedded objects) copied into this package under fresh
+     * names and relationship ids; styles and numbering are not merged (CR-002 open question 5).
+     * A bare `w:p` / `w:tbl` fragment is accepted too, as `insertXml` takes. Returns the views of
+     * what was inserted, as `insertXml` does, since a package may bring several blocks.
+     */
+    insertOoxml(ooxml: string, location: 'Start' | 'End' | 'Replace' | 'Before' | 'After', target?: Paragraph | BlockElement | Address): Promise<(Paragraph | BlockElement)[]>;
+    /** The package's DOM preprocessor (the MCE one), for fragments and incoming packages. */
+    private preprocessor;
+    private insertContent;
     /** Matches over every paragraph, in document order. */
     search(text: string, options?: SearchOptions): Range[];
-    /** Removes everything (section properties stay). */
+    /**
+     * Replaces every match of `find` with `replace`, last match first so that the offsets of the
+     * ones still to do stay valid (CR-002 section 3.7). Returns the number replaced; tracked when
+     * the package's `changeTrackingMode` is on.
+     */
+    replaceText(find: string, replace: string, options?: SearchOptions): number;
+    /**
+     * Removes everything (section properties stay). While the package tracks changes, every
+     * paragraph is marked deleted and every row's `w:trPr` takes a `w:del` instead.
+     */
     clear(): void;
+    /** Every tracked change in this body, in document order. */
+    getTrackedChanges(): TrackedChange[];
+    /**
+     * Accepts every tracked change, last first so that a paragraph join never disturbs one still
+     * to do (docx4j `AcceptTrackedChanges` is the reference). Returns how many were accepted.
+     */
+    acceptAll(): number;
+    /** Rejects every tracked change, last first. Returns how many were rejected. */
+    rejectAll(): number;
+    /** Every `w:tr` in this body's tables, in document order (rows of nested tables included). */
+    private rowElements;
     /** The part's XML (extension; Office JS getOoxml wraps it in a package). */
     getXml(): Promise<string>;
     /** The element at an address: 'body/3' (fourth block), 'body/3/1/0/2' (table row 1, cell 0, block 2), a paraId, or a text match. */
@@ -104,4 +197,16 @@ export declare class Body {
     /** Gives a new paragraph a w14:paraId when the document already uses them. */
     private assignParaId;
     private usesParaIds;
+    /**
+     * The comments anchored in this body, in document order, with replies nested under their
+     * parent (only top-level comments are in the array). Asynchronous because it unmarshals the
+     * comment parts.
+     */
+    getComments(): Promise<Comment[]>;
+    /**
+     * Wraps everything this body holds in a new content control (Office JS
+     * `Body.insertContentControl`), typed for the kind when one is given; the `w:id` is free in this
+     * body. Returns the control.
+     */
+    insertContentControl(kind?: ContentControlType): ContentControl;
 }