@genomdev/docx

Mints the identity a node keeps for as long as the document is open. Numbers rather than strings: they are compared and hashed on every edit and every incremental relayout, and a document of a million paragraphs would pay for a million strings. Unique within one document and meaningless outside it — an address that survives a file is a different thing, and lives in `@genomdev/core`'s locators. This is all that is left of what was once `model/source.ts`. The model used to carry, beside every node, three numbers saying where in the original file that node stood, so that a save could copy those characters back verbatim. That bought a byte-for-byte round trip and cost the one thing that mattered more: **the document was not a value.** It could not be saved without the file it came from, could not be handed to another process, and held a claim on bytes nobody else could see. The model now holds what it understands and nothing else, and a save is a serialisation of that and nothing else.

Computes list numbers by walking the document in order. Deliberately *not* implemented with CSS counters, which is how most web-based DOCX viewers do it. CSS counters break in exactly the situations this viewer is built for: they cannot produce Word's `%1.%2` multi-level patterns without generating a rule per level, they are computed by the browser in document order and therefore give wrong numbers as soon as pages are virtualised and only part of the document exists in the DOM, and they cannot express `startOverride` on a per-instance basis. Computing the numbers here makes them plain text: correct under virtualisation, correct when printing, selectable, and searchable.

A handle on a paragraph, which is an id and not a node. Every method reads the current version, so a reference taken before an edit still names the same paragraph after it — including after an edit to that paragraph, which replaced the node the caller would otherwise be holding.

A handle on a story other than the body: a running head, a foot, a note. Everything a story can be asked is what the session can be asked of the body, with the story named — so anything written against the body works against a header by taking one of these instead.

A handle on a table; the same contract as {@link ParagraphRef}.

The document's text, addressed by character position. Deliberately not a string. Building one would mean choosing a code page for the whole document up front, and a document with a Cyrillic quotation in a Greek report has two. It would also cost the memory of the text twice over for documents where only a page is ever looked at.

Resolves theme colour and font references into concrete values. Word rarely writes a literal colour. It writes "accent1, 40% lighter", encoded as a theme slot plus `themeTint`/`themeShade` modifiers, and the actual RGB lives in `theme1.xml`. A viewer that reads only `w:color/@w:val` renders every themed document in black, which is the single most visible difference between a correct DOCX renderer and an approximate one.

`w:ptab`: a place in the column rather than a stop on the ruler. It is how a running head puts a title on the left and a page number on the right with no stop declared anywhere — and treated as an ordinary tab it advances by the default interval instead, which leaves the page number a third of the way across. The width it returns may be negative, and deliberately: the place it names is a place, not an advance, and a paragraph whose indent has already spent the line is exactly where that matters. An academic report's footer indents past the right margin and then asks for a right-hand `w:ptab`, and Word answers by setting the page number ending at the margin — one line, where clamping the tab to a pixel gives two and takes six pixels off the text area of every page. A width cannot be negative, so the caller makes the distance up with a negative margin, which moves what follows without giving the line a box it has to find room for.

Where the left edge of an anchored box lands, in points across the sheet. The same shape as the vertical rule with one thing more: the anchor may state an *alignment* rather than an offset, and then the box is put against an edge of its base or centred in it. `float-across-*` puts a square inch of picture two inches along — five documents, one page each — and the text says where it landed: stated box left which is from page, 192 192 the sheet's left edge, plus 192 from margin, 192 288 the text area's left edge (96), plus 192 from column, 192 288 the same, in a section of one column align right 601.7 the box's right edge on the text area's right align centre 348.9 the box centred in the text area `column` and `margin` came out identical and had to: the probe's section has one column, so the two are the same span. What a column anchor does in a two-column section is not measured. `inside` and `outside` — of both the bases and the alignments — are about which side of a spread the page is on, and are answered here as `left` and `right`, which is right for a document printed one side and a guess for one printed two.

Where the top of an anchored box lands, in points down the sheet. The base and the offset, and nothing else — which sounds too simple to need measuring and was not: nothing in the corpus had ever put `relativeFrom` to Word, every probe until now anchoring from the paragraph where one base looks like another. `float-anchored-from-page`, `-margin`, `-paragraph` and `-line` put the same square inch of picture at the same half inch of offset and differ in nothing else. Which lines Word shortens says where the box landed: base box which is page 48 … 144 the top of the sheet, plus 48 margin 144 … 240 the top of the text area (96), plus 48 paragraph 197.7 … 293.7 the top of the anchoring paragraph (149.7), plus 48 `line` came out identical to `paragraph`, and had to: the anchor sits in the first line of its paragraph, so the two origins are the same point. What a `line` anchor does in the *second* line of a paragraph is not measured. The margin bases other than `margin` itself — `topMargin`, `bottomMargin`, `insideMargin`, `outsideMargin` — are not measured either, and are answered here from the text area, which is right for `topMargin` and a guess for the rest.

Appends blocks to the end of a container: the body, a cell or a content block.

Applies a character `grpprl`. `base` is what is already in force, and it matters for more than convenience: a toggle's operand can say "invert whatever you inherited", which cannot be answered without it.

Applies a paragraph `grpprl`.

The operand as a signed sixteen-bit value: every measurement in twips is one.

The operand as a signed thirty-two-bit value.

From one baseline to the next, in points. The quantity a PDF actually shows, and the one a line height is mistaken for. What separates two baselines is the room left under the first and the room taken above the second, so two lines of different heights are not the height of either.

What the borders add at a seam, in points — and nothing where they meet. Two paragraphs carrying the *same* border are one bordered block to Word: it draws no rule between them and adds no space. `paragraph-borders-that-meet` steps a bare 17.92px between three paragraphs that all state `w:sz="4"` with a point of space, and 4.64px more than a line between a border of four and one of eight — which is the first's bottom and the second's top, both. Compared on the width and the space alone, which is what this carries. Two borders alike in those and different in colour would be merged here and drawn apart by Word; no probe asks, and the corpus has not been read for it.

What a paragraph's border adds above or below its text, in points. The rule itself and the space it asks for, both outside the text. A border `w:val="none"` is not one and states no size; a size of zero is a hairline Word still draws, and the corpus has both.

Every offset in a string at which a line may start.

Whether a line may begin after this character, whatever follows it. Asked of the character before an object, where what follows is not text at all. `U+FFFC` is the object replacement character, whose line-break class is `CB` — the standard's own way of saying "an object stands here" — so the question is put to the algorithm exactly as the algorithm expects it.

Whether a line may end after `left` and begin with `right`. Kept for the callers that hold two characters and no more — a seam between two spans in the browser path. It is a **weaker** question than the one the algorithm answers, because the rules that need context cannot see any: a pair is asked as if it were the whole of the text, so `sot` and `eot` stand either side of it. Prefer {@link breakPoints} over the whole string wherever the whole string is to hand.

Builds the blocks of one story.

How wide a cell's content may be, in twips. The column it occupies less the margins beside it, which is the width the lines of the cell are broken to. `table-cell-text-width` states 108 twips on both sides of a 2500-twip column: Word begins the first cell's text at 103.2 pixels against a table edge of 96.0, and the second cell's at 270.0 — the edge, the column, and the margin again.

The first record of a type among a record's immediate children.

Where the columns of a row begin, in twips from the table's left edge. The running sum of the grid, which is what a cell's `w:gridSpan` is counted against and what says which column a cell of a short row belongs to.

The width of each column, in twips.

The same widths in CSS pixels, which is what a comparison is read in.

Width available to one column, accounting for the gaps between columns. Unequal columns declare their own widths; equal ones split the remaining space. `max(0, …)` rather than the raw arithmetic: `columns-space-12000` asks for a gap wider than the text area, and Word answers with columns of no width at all — one character to the line — rather than with columns that overlap.

A document turned into what the engine takes, and the engine's answer. Exported because more than one tool needs it and a second copy would drift: `geometry-view.mjs` draws what this returns, and drawing something other than what was measured would be worse than drawing nothing.

Height of the text area, i.e. the page minus its vertical margins.

Width of the text area, i.e. the page minus its horizontal margins.

The face nearest a character's own where its own has no glyph for it. Word draws a character its face lacks in something that has it, and the difference is not decorative: `.notdef` is half an em in Calibri, and a line of them holds twice the text it should.

Cuts a piece too wide for the room into pieces that fit. Word's one break inside a word. It offers no opportunity there and would not take one if it did — but a token wider than the column has to end somewhere, and Word ends it at the column's edge: `break-inside-a-token` sets ten twenty-six character tokens in a 2000-twip column and Word answers `aaaaaaaa/bbbbbbbb/cc` and `cccccc` — a cut in the middle of a run of the same letter, at no punctuation and no boundary of any kind. The slash, the stop, the comma, the colon, the bracket and the underscore all read alike, which is what says the cut is the column and not the character. Never less than a character, or a column narrower than one letter would take for ever. **Cutting the word rather than the piece was built and refused.** A token is not always one piece — `nl-09a49d274e30` writes 252 ellipses as three runs — and cut piece by piece their three tails stand on one line together: 1344px of text in a 672px column, which `tools/compare/overrun.mjs` sees and the page count cannot. Pouring the whole run of pieces through the column instead mends that document's lines exactly (39 and 33, Word's own) and costs `legal-91fd8fe7b274` its page count: 1606 exact against 1607. Grouping by `breakBefore` alone also cost `it-dc1d8d29bc77`; grouping by "no break and no space" fixed that and not the other. What decided it is that the repair is worth almost nothing on the axis it was built for: three lines of the corpus's 2841 that stand past the paper. The rest come from elsewhere — pictures and tables wider than their column — so this is not where that problem lives. **Measured again at 1744 exact page counts**, carrying the width from one piece to the next and resetting it wherever a line may begin: the same two documents change hands — `nl-09a49d274e30` won, `legal-91fd8fe7b274` lost — and `pl-063a569635f2` goes from nine pages to ten against Word's eight. 1744 exact either way, 44 pages of error against 43. And that document says where the real fault is. Its dotted rule comes out 1375.5px on a 632px line even after the cut, because the cut sizes a piece to the *whole* room while the line it lands on already holds 481px of text. What is missing is not a wider notion of the token but the emergency cut being made where the remaining room is known, which is `chooseLines` and not here.

The document language's code page, for a document with no font information.

A bulleted or numbered list a builder can actually make. Word's own defaults, because they are what a reader expects a list to look like and because a builder that asked for them would be asking a caller to know the format. Three levels, which is as deep as a generated document goes in practice; a caller wanting more supplies its own definitions. The indents are Word's: 720 twips a level, with the marker hanging 360 back from the text — which is what makes the text of every item line up whatever the marker's width.

The styles a generated document actually uses, and nothing beyond them.

The used width of every column, in the same unit the demands were given in.

The faces of one document, resolved by name against the written tables.

Whether the run's East Asian slot is Times New Roman over an even pair. §2.1.88 b's second bullet and §2.1.88 d, which are the same rule written twice. Compared case-insensitively because a document may write `Times New Roman` in any casing and Word matches families that way.

How markup is named in the register, in reports and in error messages. `w:spacing in pPr` for an element, `w:spacing@w:beforeAutospacing` for an attribute. The prefix is the canonical one of the specification rather than the one the file happened to use, so that the same gap in two documents is one line and not two.

Every block of a tree, in document order, descending into tables.

The file extension a media part should carry, from its content type. The extension matters more than it looks: `[Content_Types].xml` declares types **by extension**, so a part named `.bin` and declared `image/png` is a part Word will not render. The list is what the corpus actually holds.

Содержимое документа Word — без зонтика и без чужих форматов в графе. Для того, кто знает, какой у него файл. Принимает и уже открытый документ: вьюверу незачем разбирать файл второй раз, чтобы поискать в нём.

The families a document might ask for, so a caller can load their tables. Every name the walk could reach, for the names the document actually uses: the name itself, its measured stand-ins, its codepage-stripped form, its family, the script's stand-ins, the alternative the file names, the document's default, the shape's stand-ins and the last resorts. A superset, deliberately — loading a table nobody asks for costs a fetch, and missing one costs the deterministic path.

Reads a pair by name, or a zero-length one when the document has no such part.

Extracts the field type — the first token of the instruction — in upper case.

Every record of a type, at any depth.

Removes structured document tags, lifting their content to where they stood. A content control is a wrapper, not content: `w:sdt` marks a region as a date picker or a drop-down or a bound field, and what a reader sees is the `w:sdtContent` inside it. Nothing that consumes the document — the renderer, the extractor, the search index — has any use for the wrapper. It lives here rather than in either consumer because both of them number the blocks they walk, and those numbers are addresses. A renderer that flattens and an extractor that nests produce two different numbering schemes for the same document, and every address minted by one lands somewhere else in the other — silently, and only in the documents that happen to use a content control. One function with two callers cannot drift.

The key a family name is looked up by: quotes off, spaces out, lower case. The same fold `wordLineRatio` uses, and deliberately no more than that. NFKC would fold `ＭＳ 明朝` onto `MS 明朝`, which is tidier and wrong: the full-width spelling is a *different* name to Windows, and the whole point of the alias is that the two names have to be told apart to be joined.

The slot a code point takes, by [MS-OI29500] §2.1.88 b. Astral characters are answered as the table's fallthrough answers everything it does not list — `hAnsi` — rather than by their surrogate halves: a caller that hands over a whole code point is asking about the character, and the surrogate rows are about UTF-16 units.

The text a counter shows in a given format.

The column widths of a table that states no `w:tblGrid`. The grid is optional, and a table without one is not a table without columns: the cells say how wide they are, in `w:tcW`, and Word reads the columns off them. `administrative-a6c03313c613` is one — no grid at all, `w:tblW` of 5000 `pct` and one cell a row saying the same — and read as a grid of nothing its every column came out nought wide, so every word in it wrapped and its 107 pages became 215. The widest row decides how many columns there are, which is what a grid would have said. A cell that states no width of its own takes an equal share of whatever the ones that do have left.

What `w:overflowPunct` lets hang, for a run written in this language. Nothing hangs outside the four: Word's own dialog offers the setting beside the other East Asian typography options, and a Latin paragraph has no hanging punctuation whatever `w:overflowPunct` says. Which of the four actually hangs is a separate question, measured rather than documented — see `hangsPunctuation` in `line-break.ts`.

Four spellings, from the most specific to the least. `w:spacing@w:line in pPr` names one attribute of one element in one place; `@w:rsidR` names one that hangs off half the elements in the format; and `w:lsdException@*` names an element whose every attribute is bookkeeping — without which the register would need a line for each of the five hundred that a `latentStyles` block writes.

The reason this markup is passed over, or `undefined` when there is none.

Concatenates the text of inline nodes, expanding links, fields and revisions.

Whether a run of element names is in the order the schema states. The check the writers are held to. Names the schema does not list are refused rather than ignored: an element nobody put in the order is an element whose position nobody has checked.

Inserts blocks before or after a node. Before and after rather than "at an index", because an index is a position in an array the caller cannot see and a neighbour is a thing it can name.

The index of the interval containing `position`. Binary search rather than a scan: a document of any size has thousands of character-formatting runs, and every character of text asks this question.

Whether a node is the frame of a group and says how many members follow it.

Whether a paragraph's composition depends only on the paragraph. The three kinds of sequential state named in this file's note, detected by looking: a list membership, a note reference, or a field. Anything else is a function of its own contents and can be reused.

Whether this drawing is a chart frame the writer can point back at its part.

Whether this drawing is a SmartArt frame with all four of its parts named. All four, because `dgm:relIds` requires all four. A diagram read before the model kept the other three — or one written by a producer that left an attribute out — cannot be written back as a diagram, and saying so is better than writing a frame Word offers to repair.

Whether the model holds enough of a drawing to write it back at all.

Whether the model holds enough of this drawing to write it back. A relationship to a media part and an extent, and nothing standing in the way — a text box, a diagram, a chart or a shape is more than a picture and the model does not hold the rest of it.

Whether the model holds enough of this drawing to write it as a shape. An extent and either something to draw or something to say. A drawing with neither a look nor a text box is a frame around nothing, and writing an invisible empty rectangle is worse than reporting that it was dropped: it takes room on the page and shows nothing.

Whether the model holds enough of this shape to write it back. Almost always. A VML shape carries its own style string, and a shape with a style has a place and a size; one without has neither and there is nothing to write. A group is judged by its own box for the same reason — its children's coordinates mean nothing without it.

Which of the four languages a `w:lang/@w:eastAsia` tag names, if any. Chinese is split by script and not by country: `zh-TW`, `zh-HK` and `zh-MO` are written in traditional characters and take the traditional list; `zh-CN` and `zh-SG` take the simplified one. A tag naming the script outright — `zh-Hant`, which Word writes for some templates — says so directly.

The set actually in force for a language, given what the document says. See the note at the head of the file for the order of precedence, which is [MS-OI29500]'s and not the standard's.

Lays the blocks out on pages. Greedy, one block at a time, which is what Word does: a block is broken into lines at the column's width, the lines are dropped onto the page until it is full, and what is left starts the next page. Nothing an earlier page holds is revisited when a later one fills up.

Lays an equation out. `display` is `m:oMathPara` — an equation on a line of its own, which takes the roomier of every pair of constants the table states. An inline equation takes the tighter, so that a fraction in a sentence does not open the line.

The height of one line, in points.

Finds a block by id, anywhere in the tree, with the path that reaches it.

Extracts the plain text of a math expression. Used for text extraction and search, where an equation should contribute its symbols rather than being silently dropped.

A part name for a picture, and it must not collide with one already there. `word/media/image1.png` is the convention, and a package being written may already hold `image1.png` — copied through from the source — so the number walks until it finds a name nobody has taken.

Whether a box would take room from a line, without working out how much. The question a paragraph asks before it decides to break its lines itself: one that meets no float can be broken to a single width, and one that does cannot.

Merges border sets edge by edge.

Merges the header story's text boxes into the body's, keeping both indexes.

The line the type needs before `w:spacing` has its say, in points.

Watches everything the readers pass over until the returned function is called. The hooks are static on the parser — the readers are hot loops and threading an option through every one of them would cost more than the feature is worth — so this is process-wide and must be undone.

Opens a Word document. The main part is parsed in a single streaming pass, while the supporting parts that a given rendering may not need — headers, footers, footnotes, comments — are left to be loaded on demand. That matters more than it sounds: a document with fifteen section-specific headers pays for the two that are actually displayed.

The space between two paragraphs, in points. **The larger of the two, not their sum.** Three probes settle it, each ruling out one reading the others cannot: - `contextual-spacing` states `before` and `after` both at 240 twips and Word puts 16.00px between the lines — 240 twips exactly, where the sum would be 32px. That disposes of adding them. - `empty-paragraph-height` has a separator with `before` 400 and `after` 0, and Word gives it its 400 twips. That disposes of reading only `after`. - `line-spacing-default-two-paragraphs` has `after` 160 and `before` 0, and Word gives it its 160. That disposes of reading only `before`. A table cell is no exception, and neither is a blank paragraph in one. This once summed the seam where a written paragraph met a blank one in a cell, on a reading of two drifting rows of `forms-99782b65f187`, and `educational-57592f55761a` contradicted it: its title cell puts 105 twips after the title and 240 before a blank line, Word opens 240, and the sum made the row 7px tall and floated the page's table off by as much. `cell-blank-paragraph-seam` asks directly — written to blank and blank to written, 40 against 40, 105 against 240 and the reverse, at single and at one-and-a-half lines — and every seam is the larger of the two. `w:contextualSpacing` then suppresses a paragraph's own space where its neighbour names the same style — and only the same style: the probe puts two different contextual styles next to each other and Word keeps the space between them.

From the last baseline of one paragraph to the first of the next, in points. The same arithmetic as {@link baselineStepOf} with the space between them added, which is what a reference shows at a paragraph boundary and what makes such a step useless as a reading of a line's height.

Reads a sequence of records. Stops at the first header it cannot believe rather than continuing, because a wrong length here does not lose one record — it puts the reader in the middle of somebody's pixel data, where every eight bytes look like a header.

Parses a border container: `w:pBdr`, `w:tblBorders`, `w:tcBorders`, `w:pgBorders`. `w:start` and `w:left` name the same edge, and a file may carry both: the first is what the strict standard writes and the second what the transitional one kept from Word 2007. Where both are present the logical spelling wins, whichever came first in the file — [MS-OI29500] §2.1.1758 through §2.1.1765 say it eight times over, once for each of the four containers' two edges. Reading them into one case, as this did, made the answer depend on the order a writer happened to emit them in.

Parses `w:tcPr`.

Parses a whole chart part.

Parses the drawing Word cached for a SmartArt diagram. The part is a flat shape tree with absolute geometry, so it needs no knowledge of the diagram algorithm that produced it.

Parses `fontTable.xml`.

Parses `numbering.xml`. The part has three kinds of top-level content: abstract definitions holding the actual level formatting, concrete instances that paragraphs reference and which may override individual levels, and picture bullets. Keeping the indirection intact matters — two lists sharing an abstract definition must still number independently.

Parses `w:pPr`.

Reads the piece table out of the `Clx`. The `Clx` is a sequence of blocks: any number of `Prc` blocks, which carry formatting for the pieces and are of no use to a reader, and then exactly one `Pcdt` holding the table itself. Walking rather than seeking is what makes the `Prc` blocks skippable, and they do occur.

Reads a plex.

A plex with no elements, only boundaries.

Parses `w:trPr`.

Parses `w:rPr`. Must be called positioned on the `w:rPr` start tag; returns with the parser on the matching end tag.

Parses `settings.xml`.

Parses `styles.xml`. Styles are stored exactly as written, with no inheritance resolved. Flattening `w:basedOn` chains at parse time is tempting but wrong: the resolution order differs between paragraph properties, run properties and the thirteen conditional table blocks, and a flattened style can no longer answer "was this value set here or inherited", which the table style cascade needs. Resolution lives in {@link StyleResolver }, where it is memoised per style id.

Reads the stylesheet and resolves it into the shared model. Resolution happens here rather than being left to the style resolver because the two formats disagree about what a style stores. WordprocessingML stores the *difference* from the parent, and so does this — but a `grpprl` is applied to a starting point, and for a style that starting point is its parent's resolved properties. Applying each style's modifiers to nothing gives a document whose headings lose everything they inherited.

Parses `w:tblPr` or `w:tblPrEx`.

Parses `theme1.xml`.

Reads the anchors of one story. The plex is keyed by character position, so the result is looked up with the position of the `0x08` that stands for the shape.

Reads every character-formatting page the bin table points at. Eagerly rather than on demand, and deliberately: the pages are a few hundred for a large document, they are scattered so reading them one at a time is the slowest possible access pattern, and every one of them will be needed by the time the document has been laid out once.

Reads every paragraph-formatting page. Each entry is one paragraph, which makes this plex the document's paragraph list as much as its formatting: the boundaries it gives are exactly the ones the paragraph marks in the text imply, and having both is how a reader can tell a paragraph mark from a byte that merely looks like one.

Reads every picture the document's store lists. The store holds one entry per picture and, in Word, almost never the picture itself: the entry carries an offset into a *delay stream*, and the delay stream is `WordDocument`. So the pictures sit among the text, in the one place a reader of the drawing layer would not think to look, and a store that appears to hold nothing is the normal case rather than an empty document.

Reads a section's `grpprl` out of `WordDocument`. A `SED` points at it rather than holding it, and the pointer is `FFFFFFFF` when the section carries no properties of its own at all.

Indexes every shape in the document by its identifier. Both drawings are walked — the body's and the headers' — into one index, because an anchor names a shape and says nothing about which drawing it is in, and the two identifier spaces do not overlap.

Reads which stretch of the text box story belongs to which shape. The entries carry an identifier, and it took a corpus to establish what that identifier is: not the shape's `lTxid` property, which is what the name suggests and which turns out to be an index shifted sixteen bits, but the shape's own **identifier**. A document with one text box has a shape numbered 1026 and an entry saying 1026; the shape's `lTxid` says 65536.

Removes a node by id.

How many rows repeat at the top of every page the table reaches. `w:tblHeader` marks a row as a heading, and Word repeats **all** of the marked ones, not the first alone — but only while they run unbroken from the top of the table: a row marked in the middle of one is not a heading and Word draws it where it stands. `table-header-row-repeats` marks two rows of a table a hundred and twenty long. Word opens page two with `Header first` at the very top of the text area and `Header second` a line below it, and page three the same — both rows, in order, with no space above them beyond the table's own.

Replaces a node by id, rebuilding only the path down to it. Answers the same array when the id is not there, so a caller can tell a change that did nothing from one that did.

Resolves the effective definition of a list level. Walks instance → override → abstract definition, following `numStyleLink` indirection when an instance points at a numbering style rather than at a concrete definition.

The room left for one line beside the floats it meets, as the runs it may use. **Several runs, not one.** A box in the middle of a column leaves room on both sides of it and Word uses both: `float-wrap-side-bothsides` puts a square inch in the middle of a 601.7-pixel column and Word sets one line as two fragments, 96.0 to 223.4 and 404.1 to 661.7. `bothSides` is also the default, so this is the ordinary case and not the exotic one. The sweep says what each value does, on the same picture in the same place: wrapText where the text goes bothSides 96…223 *and* 404…694 — both, on one line left 96…270 only right 404…694 only largest 404…694 — the same as right, the right being the wider An earlier reading of this took the wider side always, which is right for a box against a margin — where the narrow side is nothing — and wrong for one in the middle, which is what the default does most.

The height of one row, in points.

All three property tables of a shape, merged in the order they override.

Binary search for the span covering a file offset.

The width of a cell that spans several columns of the grid, in twips. The sum of the columns it covers, and nothing taken off for the rules between them. `table-grid-span` puts a cell over the first two of three 2000-twip columns and an ordinary row of three beneath it as a ruler: the ruler's cells begin at 96.7, 230.1 and 363.4 pixels — 133.3 apart, which is 2000 twips — and the cell after the span begins at 363.4 exactly, where the third column does. The vertical rule between the merged columns costs the span nothing.

The heights of a run of rows a cell is merged down, in points. A vertically merged cell is not in any one of its rows: its text runs through all of them, and the rows together have to be tall enough to hold it. Where they already are, nothing moves; where they are not, the shortfall lands on the **last** row of the run. `table-vertical-merge` shows both halves. A cell of five words is merged down three rows beside three cells of one line each, and Word sets its three lines 17.92px apart — one line, continuously, paying no attention to the rows — while the neighbours sit at 129.15, 147.07 and 167.71. The first two rows are exactly a line tall, and the third is not: it carries what is left.

Walks a `grpprl`. Stops at the first opcode it cannot size rather than guessing, because a misread length does not produce one wrong property — it desynchronises the stream and every property after it is read out of the middle of an operand.

The declared stop a tab at `currentX` reaches, or nothing where it falls through to the default interval. The first stop strictly to the right of the current position wins. The margin is a shade wider than the guard a right-aligned stop leaves behind it, so that the stop a tab has just reached is never chosen again — which would ask the same text to end twice at the same place and collapse the tab to nothing.

Makes unaccounted markup an error for the duration of the returned handle. For development runs and tests, never for a viewer: against real files this throws constantly, and that is the point — it is a search for the gaps, not a way to read documents.

Faces to fall back on when the one the document names is not installed. Word does this itself and calls it font substitution: it keeps a table of metric-compatible pairs and, finding neither the named face nor a mapping, picks something of the right shape. A viewer that passes the name straight to CSS and stops gets the browser's last-resort face instead, which has neither the metrics nor the look — every line comes out a different width, and the comparison reports it in the same shape as a real defect. Two rules, both of which the corpus asks for by name: - The metric-compatible clones. Liberation Serif is Times New Roman's metrics to the glyph and is what LibreOffice writes when it saves a document that used one; five documents in the corpus name it and none of them means a different typeface. - A weight or a slope carried in the family name. `Arial Bold` is not a family and no system has it — it is Arial, and the boldness is already on the run. Dropping the trailing style word finds the family that exists.

What a tab at `currentX` advances by. `following` is the width of the text between this tab and the next. It is a function and not a number because only a stop that *ends* its text at the stop needs it, and measuring it is the expensive half of laying out a tab: the browser walks the nodes after the tab with a `Range`. Most tabs are left-aligned and never ask.

Where the top of a floating table lands, in points down the sheet. `w:tblpPr` takes a table out of the flow and puts it where its anchors say, with the text running around it — the same idea as an anchored drawing, a separate implementation in Word, and its own vocabulary: `text` where a drawing says `paragraph`, and `w:tblpY` in twips where a drawing has EMU. `float-table-from-page`, `-margin` and `-text` put the same two-inch table two inches down and differ in nothing else: vertAnchor table top which is page 192 the top of the sheet, plus 192 margin 287.8 the top of the text area (96), plus 192 text 341.8 where the table stood in the flow (149.7), plus 192 The text wraps around it as it does around a drawing: the table occupies 96 to 288 and the lines beside it begin at 289.

The run that decides the line, or nothing where the line has none. Tallest is not largest: a face's line is a multiple of its size and the multiples differ by six per cent between the faces of an ordinary document, so eleven-point Calibri needs 13.42 points where twelve-point Times needs 13.8 — the *smaller* run is the taller line. `line-height-owner-plus-smaller- calibri` puts that pair to Word and Word answers with the Times line.

A toggle's operand. Bold, italic and their nineteen relatives are stored as a byte with four meanings, not two: off, on, and the two that make sense only against something inherited — leave as inherited, and invert it. A style that turns bold on and a paragraph inside it that says "invert" is how Word writes a heading whose emphasised words are set roman.

Walks every block in a subtree, descending into tables and content blocks. A generator rather than an array: callers usually stop early (finding the first section break, locating a bookmark) and materialising the whole document as a flat list would defeat the point of a streaming parser.

Reading a Word document as content. The hard parts, in the order they bite: A Word document is not one stream. The body, each header, each footer, each footnote and each comment are separate flows, and numbering them as if they were one would make every address after the first footnote wrong. So each gets its own locator flow and its own walk. A list is not a list. Word stores a paragraph with a numbering reference, not a nested structure, and the number itself is nowhere in the file — it is the paragraph's position among its neighbours, resolved through a definition that may restart partway down. So the numbers are computed here, in document order, and the flat sequence of numbered paragraphs is folded back into the tree it was drawn as. A heading is a claim, not a fact. `w:outlineLevel` and the built-in heading styles both say so and they disagree; a document whose author never used a heading style has no headings, and inventing them from type size gives a table of contents made of pull quotes.

Walks every inline node, descending into hyperlinks, fields and revisions.

A cell spanning several columns, widening them until they hold it. CSS 2.1: "For each cell that spans more than one column, increase the minimum widths of the columns it spans so that together, they are at least as wide as the cell. Do the same for the maximum widths." The same ladder as above decides which of the spanned columns grows, which is why it is one function. Applied after every single-column cell has had its say, and in order of increasing span, so that a cell over two columns settles before one over three has to reason about them.

The widest run of room a line has, or nothing where it has none. For a caller that sets one run of words to a line and does not divide it — which is every caller until the line breaker learns to.

The width a `w:tblW` or `w:tcW` means, in twips. `pct` is in fiftieths of a per cent — 5000 is the whole of it — and what it is a per cent *of* is what the caller passes: the text area for a table, the table for a cell.

The paragraph's own left indent, as a stop, where the paragraph hangs. That is what a hanging indent is *for*: the label sits out in the margin, a tab carries the reader to the indent, and every line after the first starts there. Legal drafting and anything converted from it writes list items exactly so — a tab, `(a)`, a tab, the text — and without the implicit stop the second tab falls through to the default interval or, when the declared stop lies just behind it, to nothing at all. The text then abuts the label: `(a)be made in writing`. Left-aligned, and only when the paragraph hangs: an indent with no hanging part is where the text already begins, so a stop there would advance by nothing. ## `w:doNotUseIndentAsNumberingTabStop` is not honoured, and neither is it by Word ECMA-376 Part 4 §14.8.3 declares a flag for exactly this stop — "specifies that applications shall not use the custom tab stop generated by the hanging indent when advancing the text after the numbering" — and 53 documents of the corpus set it, more than any other compatibility flag we do not read. Implementing it makes no difference because Word does not implement it. `compat-indent-as-numbering-gap-{on,off}` are the same document but for the flag, numbered `w:ind w:left="1000" w:hanging="360"`: the number is drawn at 640 twips, the implied stop is at 1000, and the first default stop past the number is at 720 — the two readings are 280 twips apart and cannot be confused. Word draws the text at 1002 twips in both. `-mode12-` asks the question again of a document that declares itself Word 2007, in case the transitional flag were honoured only in a transitional mode: 1002 twips again. `-stop-` is the calibration pair at `left="360"`, where both readings would land in the same place, and it agrees with itself. So Word does not place the text after a number by finding a tab stop at all where the indent is one — it places it at the indent, and the flag has nothing to switch off. The stop below stays unconditional.

Carries the running parts of one section forward into the next. Headers and footers are the one part of a section that is *not* self contained. Word writes a complete `w:sectPr` for everything else — page size, margins, columns — but a header reference is written only where the header changes. Everywhere else the section is linked to the one before it, which is exactly what the "Link to Previous" button in Word's header editor controls, and what its absence from the file means. The link is per type. A section may replace the default header and keep inheriting the first-page and even-page ones, and a report that changes its running title at each chapter while keeping one title page does precisely that. Inheriting all-or-nothing puts the wrong title on every chapter after the first. There is no way to declare "no header here": to break the link and show nothing, Word references a header part that is empty. Absence therefore always means inherit, never means none — a distinction that matters, because a section that reserved no room for an inherited header would run its text under it.

Word's ratio for the first family of a stack that has one. The stack is read left to right, as CSS resolves it: the first family the table knows is the one the text will actually be set in, and a fallback named after it never gets the chance to decide the line.

Writes a run of blocks: the contents of a `w:body`, a cell or a header.

`w:tcPr`, in `CT_TcPrBase` order.

`a:graphicData` holding the one element that names a chart part.

`a:graphicData` holding the four relationships a diagram is reached by.

Writes a group and returns the members it could not write. The return is not an error: a group holding a chart is a group whose other shapes are still worth drawing, and the caller reports what was dropped by the same route it reports everything else. An empty array is a whole group.

Inline content, grouped back into the runs it came from. The model flattens a `w:r` into the nodes it produced — a run holding text, a tab and a break becomes three nodes — so writing one node per element would turn one run into three, each with its own copy of the formatting. That is valid and it is not what the file said, and on a document of a million runs it is three times the size. So nodes are regrouped: consecutive nodes sharing one formatting object go back into one `w:r`.

Writes an equation as `m:oMath`, or as `m:oMathPara` where it stood alone. Never inside a `w:r`. `m:oMath` is paragraph content in the schema — a sibling of the runs, not a child of one — and an equation written inside a run is a document Word offers to repair. See `writeRun`, which closes the run around it.

A paragraph, built from the model. The section properties of a paragraph that ends a section are written inside `w:pPr`, which is where the format puts them and which is the one part of a paragraph's properties that is not formatting.

`w:pPr`, in `CT_PPrBase` order.

`w:trPr`, in `CT_TrPrBase` order.

`w:rPr`, in `EG_RPrBase` order. Written even when it holds nothing only if the caller asks: an empty `w:rPr` is legal, Word writes them, and a run whose properties are empty is better off with no element at all.

`w:sectPr`, in `EG_SectPrContents` order. The one property element whose *absence* is not the same as its default. A section states its page, its margins and its columns whether or not they differ from anything, because a `w:sectPr` is what makes a section — and the references to its running heads and its page numbering are the parts a reader notices missing first: a report whose letterhead is gone, a chapter that starts numbering at one. Everything here was written because a comparison of two *models* said it was being lost. Nothing about the text of those documents changed, which is why `tools/write/model.mjs` exists.

The `wps:wsp` itself, without the graphic data around it. Written under `a:graphicData` for a shape standing on its own, and directly inside `wpg:wgp` for one that is a member of a group. `place` gives the member its rectangle in the group's coordinate space; a shape on its own sits at the origin of a space its frame has already positioned.

The graphic data of a shape, for the frame `drawing.ts` puts around it. Called with the writer positioned inside `a:graphic`, which is where every kind of drawing becomes its own kind.

A table, and the two things about writing one that are easy to get wrong. `w:tblGrid` is not optional in practice: Word lays a table out from the grid, and a table written without one is drawn with every column the same width whatever the cells say. And `w:tblPr` comes before it, before the rows, and nothing may come between them.

`w:tblPr`, in `CT_TblPrBase` order.

Writes a `w:pict` holding one VML shape or group.

An abstract list definition, `w:abstractNum`.

External content embedded by reference, `w:altChunk`.

The places an anchor may be counted from, in points down the sheet.

What one placeholder character in the text refers to.

One entry of a shape's property table. The table is two lists in one record, and that is the whole subtlety of it. First a fixed-size array of (identifier, value) pairs; then, appended after the array in the same order, the payloads of whichever of those pairs said their value was a length rather than a value. Reading only the array gives a shape whose picture is "eighteen bytes" instead of a picture.

One record: its header, and either its bytes or its children.

A line's own vertical extent, which is what decides whether a box touches it.

One block, placed, with its lines.

Everything the builder needs that is not the text itself.

Options controlling which optional content the body parser keeps.

What starts and what ends at each character position.

Anything on a line that is not text the breaker may cut: a picture, a tab already sized against its stop, a numbering label, or the padding and border of a boxed run. Its width is given, not measured. What differs between them is only what a break may do around them, which is what the two flags say.

An explicit line break, `<w:br/>`: the line ends here and the next begins. Not a paragraph boundary — the spacing around a paragraph is not paid — and not a space either. A paragraph that writes one and has it dropped comes out as one long line, which fits several of Word's on each of ours and gives a document a third of the pages it should have.

One cell of a row, with whatever it holds.

Cell-level formatting, `w:tcPr`.

The room a cell keeps beside its content, in twips.

A chart to put in a document, said in the least a chart can be said in. The full `ChartDefinition` is what a chart *read from a file* comes back as — axes with ids, plots with gap widths, every colour of every series — and almost none of it is what somebody inserting a chart wants to type. This is the short form: what kind, what the categories are called, and one or more named series of numbers. {@link DocumentBuilder.chart} fills in the rest with what Word own Insert Chart produces.

One `c:*Chart` inside the plot area.

One value of a series, with the point it belongs to.

Character formatting for one stretch of the file.

A colour as DrawingML writes it: a source plus modifiers on it.

One column, as the distribution needs to see it.

A comment from `comments.xml`.

What a second composition of the same document need not do again. `composeDocument` turns a parsed document into what the layout engine takes, and for a document of a thousand pages that is the most expensive thing the viewer does after parsing: every run resolved through the style cascade, every family resolved through the substitution chain, every piece of text cut into the spans the line breaker works on. Doing it again after a keystroke changed one paragraph is doing it again for the other two hundred thousand. The cache is keyed on the **node object**, which is what makes it work at all: the edit layer replaces a node rather than mutating one — see `edit/tree.ts` — so after an edit every paragraph but the one that changed is the very same object it was, and identity answers "did this change?" exactly and in one comparison. ## What is not cached, and why that is not a compromise A composition is not a pure function of a paragraph. Three things carry state along the walk: - **a list's number**, which depends on every numbered paragraph before it; - **a footnote's mark**, which is counted from one over the document; - **a `LISTNUM` field**, which advances a counter of its own. A paragraph that touches any of them is composed afresh. That is not a limitation worked around but the honest reading of what those paragraphs are: their composition depends on their neighbours, so their composition cannot be reused when their neighbours may have moved. Everything else — which is the great majority of every document measured — is a function of the paragraph, the width it is set in and the margin it is set against, and those three are the key.

The blocks, the first section's page, and what is drawn on every page.

What the caller has to supply because a pure function cannot know it.

What one document's walk carries with it. Every field is settled once, from the document, before the first block is built; none of them changes because of anything the walk finds, except {@link ComposeState.sheet}, which follows the section in force. It is a parameter and not a module variable, and that is the difference between a tool and a package. The tool it came from wrote in as many words that it "reads one document at a time, and never two at once" — true of a corpus run, false of a viewer with two tabs open. Held in the module, the second document to start would take the first's page size halfway through.

Which conditional table-style formats apply to a row, cell or paragraph. Word encodes this as a bit string in `w:cnfStyle`; the decoded flags are what the style resolver needs in order to layer `firstRow`, `band1Horz` and the rest on top of the base table style.

A grouping node produced by flattening a structured document tag. Content controls carry semantics (a date picker, a repeating section) that the viewer does not act on, but discarding the wrapper entirely would lose the tag name that documents and tooling rely on for navigation.

What the converters need to know about the document around them.

A Word document, built from nothing. The shortest path from data to a `.docx`, and the reason the whole write side exists in the shape it does: ```ts const document = createDocument({ title: 'Quarterly report' }); document.heading('Quarterly report'); document.paragraph('Revenue rose by eleven per cent.'); document.table([ ['Region', 'Revenue'], ['North', '1 204'], ], { header: true }); await writeFile('report.docx', (await document.save()).bytes); ``` It is a thin arrangement over {@link EditSession}: every method builds nodes and puts them through a step, so a document being generated and a document being edited are the same object with the same undo, and code written against one works against the other. That is not symmetry for its own sake — the common real task is *neither* of them alone but both: open a template, fill in its content controls, append a table, save.

One transform applied to a colour, `a:lumMod` and its siblings. Kept as a list rather than resolved fields because the transforms compose in document order, and SmartArt relies on that: a colour list shifts hue, saturation and luminance together to spread one accent colour across the nodes of a diagram.

A position and size in EMU, with the rotation applied about its centre.

A run of text inside a diagram shape. Properties come from `a:rPr`.

A bookmark, in character positions.

A font as the document declares it.

What a shape turns out to be.

What the document itself knows about the faces it names.

A ruled page: `w:docGrid`, which lines snap to.

What a document exposes about the pictures it holds outside a package.

The pictures a document holds, and how they reach a package being written. A `.docx` saved back to a `.docx` needs none of this: the media parts are in the package already and are copied through as the compressed bytes they were. Two cases are not that: - **`.doc` converted to `.docx`.** The pictures live in the binary file's own store, keyed by names like `doc-picture-3`, and the package being written has no such parts and no relationships pointing at them. Without this, the drawings are written referring to relationships that do not exist — which Word draws as an empty frame with a red cross, and which no comparison of the extracted *text* would ever notice. - **a picture a caller added**, which has bytes and nothing else. The contract is deliberately small: name the pictures, and hand over the bytes of one. Everything else — the part name, the extension, the content type, the relationship — is the writer's arithmetic.

Selected values from `settings.xml` that affect rendering.

A parsed Word document. Everything needed to render, search or convert the document, and nothing that depends on how it will be displayed. Headers, footers, footnotes and comments are loaded lazily: a document may carry dozens of header parts of which a given rendering uses two.

An image or shape produced by DrawingML, `w:drawing`.

A document open for editing. The public shape is the ordinary one — `edit.paragraph(id).setText(...)`, `edit.undo()`, `edit.save()` — and underneath every one of those is a step over an immutable tree. The two halves are worth stating separately because choosing them together is the whole design: **Why the surface is mutable-looking.** Anyone who has written this kind of code before has written it against Aspose, DocIO or python-docx, and in all three a document is an object you change. A functional surface — `document = edit(document, step)` — is honest and nobody wants it for generating a report: it turns four lines into fourteen and every one of them threads a variable. **Why the inside is not.** Undo, redo, knowing what changed, replaying an edit that arrived from somewhere else, and re-laying out only the paragraphs that moved are five different things and they are all the same thing: they need the version before and the version after to both exist. A tree that was mutated has only one. The reference a caller holds is a {@link ParagraphRef}, which is an id and not a node. It never goes stale: the node it names is looked up in the current version each time, so an edit somewhere else does not invalidate it — and neither does an edit to the paragraph itself.

A face, as far as placing text on a page is concerned.

A field: `PAGE`, `NUMPAGES`, `TOC`, `REF`, `HYPERLINK`, and so on. Both the simple form (`w:fldSimple`) and the complex form (a `w:fldChar` begin/separate/end sequence) are normalised into this single node, because the distinction is a serialisation detail that no consumer should have to know about. `result` holds the text Word last computed, which is what gets displayed for any field the viewer does not evaluate itself.

A rectangle on the page, in points from the top-left of the text area.

A font declared in `fontTable.xml`.

The four script slots Word resolves a font family from.

What the run says about itself, as far as the slot is concerned.

A header or footer part.

A header or footer reference, `w:headerReference` / `w:footerReference`.

The places a horizontal anchor may be counted from, in points across the sheet.

A picture placed in the text, as the character that stands for it says. Word puts one character in the flow — `0x01` — and everything about the picture is somewhere else: a modifier on the character gives an offset into the `Data` stream, and at that offset is a header saying how big the picture is, followed by a drawing container holding the picture itself. The size is two numbers, not one. `dxaGoal` is the picture's natural size and `mx` is what the author scaled it to, so a photograph dragged to half its size has an unchanged `dxaGoal` and an `mx` of five hundred. Using the first alone puts every resized picture on the page at the size it was before somebody resized it.

What a document says in `settings.xml` about the sets.

One language's two lists.

What a caller may ask of a layout beyond its blocks. All three are about *not holding the whole document at once*. A page of dense text is some hundreds of lines and some thousands of spans; a thousand pages of it is millions of objects, and a viewer that draws three of them at a time has no use for the other nine hundred and ninety-seven. The engine still lays the document out from the beginning — where a page ends depends on every page before it, and no arrangement of options changes that — but what it *keeps* is the caller's to decide.

One chosen line, as a half-open range of pieces.

One line: how tall it is and how far down it the baseline sits, in points.

An arrowhead at one end of a line, `a:headEnd` and `a:tailEnd`.

One line, placed.

Line numbering in the margin, `w:lnNumType`.

The room one line of a paragraph has: where it begins and how wide it is. Two numbers and not one, because the things that narrow a line do not all narrow it from the right. A first-line indent moves its left edge in; a hanging indent moves it out; a floating object on the left of the column moves every line beside it in and the ones above and below it back. The offset is measured from where a *continuation* line of the paragraph begins, so an ordinary paragraph's later lines have an offset of nought.

A run, as far as the line it sits on is concerned.

`w:spacing`, as far as the line is concerned.

One piece of markup nothing read, as the observer receives it.

An equation's box, and what stands inside it.

A node of the OMML tree, kept close to the source markup.

What the face can say about itself, in em fractions and pixels.

One run of text inside an equation, placed against the box's baseline.

An Office Math (OMML) expression, converted to MathML by the renderer.

A measurement together with the unit it was declared in, `ST_TblWidth`.

A footnote or endnote.

A footnote, as far as the page is concerned: the blocks it is made of. Where it goes is not stated because it is not the note's to state — Word sets every note referenced on a page at the foot of that page, in order, upwards from the bottom margin.

The parsed contents of `numbering.xml`.

A concrete list instance, `w:num`. Paragraphs reference instances, not abstract definitions. The indirection exists so two lists can share formatting while numbering independently, and it is also where per-instance level overrides live.

One level of a list definition, `w:lvl`.

`w:numPr`: which list a paragraph belongs to, and how deep in it. Both halves are optional and separately so, because a style states them separately. `Heading2` says `<w:ilvl w:val="1"/>` and no `w:numId` at all — "whatever list applies to me, I am its second level" — and reading that as "no numbering" drops the level of every outline-numbered heading in the document. The pair is absent only where the paragraph stated neither.

The computed label of one numbered paragraph.

What Word puts in `fcDggInfo`. The drawing group first — which holds the store every picture in the document lives in — and then up to two drawings, one for the body and one for the headers. Each is introduced by a single byte saying which it is, and that byte is the thing to trust: documents exist whose two drawings are in the other order, and reading them by position puts the header's shapes in the body.

A block this engine will not place, and will not pretend to.

Opening a Word 97-2003 document. The result is a {@link DocxDocument} — the same object `.docx` produces, and deliberately so. The alternative, and the one most projects take, is to convert the binary file into an OOXML package and hand that to the existing reader; it is easier to start and worse to finish, because everything the document says then has to survive being written out in a second format and read back. Producing the model directly means the viewer, the extractor and the addressing scheme work on a 1997 document with no code that knows it is one.

Options accepted when opening a Word document.

How the edge of a shape is drawn, `a:ln`.

An entry of the document outline, derived from heading paragraphs.

The frame Word draws round a page, `w:pgBorders`. Where it sits is as much a part of it as which edges are drawn: the same border set measured from the paper and measured from the text is two different frames, one round the sheet and one round the type area.

One page, placed.

Page number format for the section, `w:pgNumType`.

The page, as the section states it.

Paragraph formatting for one paragraph, and the style it is based on.

A rule drawn above or below a paragraph.

A paragraph, resolved: everything the geometry needs and nothing else.

Paragraph-level formatting, `w:pPr`.