@apertura/docx

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.

Resolves the effective formatting of paragraphs, runs and table parts. This is where a DOCX viewer is right or wrong. The cascade defined by ECMA-376 has six layers and a specific order, and skipping any of them produces output that looks almost correct on simple files and visibly wrong on real ones: 1. `w:docDefaults` — the document-wide baseline, over Word's own defaults. 2. The table style, when inside a table, including its conditional blocks. 3. The numbering definition attached to the paragraph's list level. 4. The paragraph style chain, resolved from the root of `w:basedOn` downwards. 5. The character style chain, for run properties. 6. Direct formatting on the paragraph or run. Numbering sits *above* the paragraph style, which is the opposite of the intuitive order and is what Word does — see `resolveParagraph`. Every resolution is memoised. A document has millions of runs but a handful of distinct (style, direct-formatting) pairs, and because the parser interns property objects the cache can be keyed on identity through a `WeakMap`, making a repeat lookup a pointer hash rather than a structural comparison.

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.

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.

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.

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

Converts a counter value into the textual form of a number format.

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.

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.

Merges border sets edge by edge.

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.

Parses a border container: `w:pBdr`, `w:tblBorders`, `w:tcBorders`, `w:pgBorders`.

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`.

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 `w:sectPr`. Must be called positioned on the opening tag. Missing values fall back to {@link DEFAULT_SECTION} rather than to zero: a section that omits `w:pgSz` is inheriting Word's default page, not declaring a zero-sized one.

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.

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

Parses `theme1.xml`.

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.

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.

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.

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

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.

An abstract list definition, `w:abstractNum`.

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

Options controlling which optional content the body parser keeps.

Cell-level formatting, `w:tcPr`.

A chart part, reduced to what is drawn.

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

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

One series of a plot.

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

A comment from `comments.xml`.

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.

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`.

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 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 font declared in `fontTable.xml`.

The four script slots Word resolves a font family from.

A header or footer part.

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

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

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

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

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

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.

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`.

The computed label of one numbered paragraph.

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.

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

Paragraph-level formatting, `w:pPr`.

A picture used as a bullet, `w:numPicBullet`.

A picture used as a fill rather than drawn as itself, `a:blipFill`.

The fully resolved property sets of a style chain.

Tracked-change metadata attached to a run, paragraph mark, row or cell.

A tracked insertion or deletion wrapping inline content.

Row-level formatting, `w:trPr`.

Character-level formatting, `w:rPr`.

An outer shadow cast by a shape, `a:effectLst/a:outerShdw`.

The visual style of a DrawingML shape.

What strict mode refuses to walk past.

A named style from `styles.xml`.

The complete style table of a document. Holds both the named styles and the document defaults, which sit at the bottom of the cascade and are the reason an empty paragraph still has a font.

A character from a symbol font, `w:sym`.

Where a cell sits in its table, used to select conditional formats.

Table-level formatting, `w:tblPr`.

Formatting contributed by a table style to the content of one cell.

One conditional block of a table style.

Tab stop, `w:tab`.

A theme colour scheme, from `theme1.xml`.

A legacy VML shape, `w:pict`. Word still writes these for text boxes.

Border style, `ST_Border`.

`c:grouping`, which decides whether values stack.

How the marks of one plot are laid out.

Where the legend goes, `c:legendPos`.

How the interior of a shape is painted.

Line spacing rule, `w:spacing/@w:lineRule`.

Number format of a list level, `ST_NumberFormat`. Only the values that actually occur in documents are enumerated; the schema defines several dozen more for East Asian numbering systems, which fall back to decimal.

What separates the number from the paragraph text, `w:suff`.

How a section starts relative to the previous one, `w:type`.

Fill pattern, `ST_Shd`.

Conditional formatting slot of a table style, `w:tblStylePr/@w:type`. A table style is not one set of properties but up to thirteen, each applying to a different region of the table. Getting banding and header rows right is impossible without modelling them separately.

Text underline, `ST_Underline`.

A4 portrait with one-inch margins: what Word gives a document that carries no `w:sectPr` at all. Measured: the corpus's two files without one — LibreOffice's `n751117` and pandoc's `definition_list` — come back from Word at 793.6 by 1122.56 pixels. That is the machine's own default page rather than a fact about the format, and it is not the same answer Word gives a `w:sectPr` that merely omits `w:pgSz`; see `SCHEMA_PAGE_SIZE`.

The docx parser plugin for {@link FormatRegistry }. `canOpen` looks inside the ZIP: the extension cannot be trusted, and every OOXML format shares one signature. Opening the package for the check is cheap — only the central directory and `[Content_Types].xml` are read — and the result is cached by the archive, so the subsequent `open` pays nothing twice.

An empty property object, shared so that the common case allocates nothing.

Document content model. A discriminated union keyed by a numeric `kind`. Numbers rather than strings because the renderer and the layout engine switch on this field for every node of a document that may hold millions of them, and integer dispatch compiles to a jump table where string dispatch does not. The tree deliberately holds no CSS and no layout results. Those belong to the renderer and the layout engine respectively, and keeping them out is what allows the same parsed document to be laid out at several zoom levels, or used headlessly for text extraction and conversion.