reamkit 1.16.0 → 1.18.0

package/dist/esm/core/document-model/types.d.ts

@@ -29,7 +29,16 @@ export interface RunProperties {
     readonly bold?: boolean;
     readonly italic?: boolean;
     readonly underline?: UnderlineStyle;
+    /** §17.3.2.40 `w:u @w:color` — the underline's own colour, when it has one. */
+    readonly underlineColorHex?: string;
     readonly strike?: boolean;
+    /** §17.3.2.5 `w:caps` — the run is DISPLAYED in capitals, whatever it stores. */
+    readonly caps?: boolean;
+    /**
+     * §17.3.2.33 `w:smallCaps` — displayed in capitals, with the letters that
+     * were lower case set smaller.
+     */
+    readonly smallCaps?: boolean;
     readonly fontSizePt?: Pt;
     readonly colorHex?: string;
     readonly fontFamily?: FontFamilyMap;
@@ -44,6 +53,16 @@ export interface RunProperties {
      * the tagged-PDF per-element `/Lang`; does not affect visual layout.
      */
     readonly lang?: string;
+    /**
+     * §17.3.2.32 `w:rPr/w:shd` — the background painted behind the run's own
+     * glyphs, already blended from the pattern, its colour and the fill.
+     */
+    readonly shadingColorHex?: string;
+    /**
+     * §17.3.2.35 `w:rPr/w:spacing` — extra space between the run's characters
+     * (negative tightens). Word states it in twentieths of a point.
+     */
+    readonly letterSpacingPt?: Pt;
 }
 /**
  * ECMA-376 Part 1 §17.3.1 — Paragraph Properties (`pPr`). All lengths in
@@ -55,19 +74,136 @@ export interface RunProperties {
  * indent of 360 twips becomes `indentFirstLine = -18pt` — the first line ends up
  * 360 twips to the left of `indentLeft`).
  */
+/**
+ * §17.3.1.38 `w:tab` — one stop in a paragraph's tab list: where the text after
+ * a tab character goes, how it sits against that position, and what fills the
+ * gap on the way there.
+ */
+export interface TabStop {
+    /**
+     * Distance from the text margin, in points (`w:pos`, twips). Ignored when
+     * {@link relativeTo} names an edge — a §17.3.3.15 `w:ptab` positions against
+     * the column itself, whose width only the layout knows.
+     */
+    readonly positionPt: Pt;
+    /**
+     * §17.3.3.15 `w:ptab` — an ABSOLUTE position tab, which goes to the middle
+     * or the far side of the text column rather than to a stated distance.
+     */
+    readonly relativeTo?: 'center' | 'right';
+    /** §17.18.90 ST_TabJc — how the text after the tab sits against the stop. */
+    readonly alignment: 'left' | 'center' | 'right' | 'decimal';
+    /** §17.18.89 ST_TabTlc — the character drawn across the gap. */
+    readonly leader?: 'dot' | 'hyphen' | 'underscore' | 'middleDot';
+}
+/**
+ * §17.3.1.11 `w:framePr` — the paragraph is a floating TEXT FRAME: it leaves
+ * the flow, takes the box this describes, and the body text wraps around it.
+ * Consecutive paragraphs carrying the same frame are one frame together.
+ */
+export interface FrameProperties {
+    /** `w:w` — the frame's width. Absent ⇒ as wide as the text needs. */
+    readonly widthPt?: Pt;
+    /** `w:h` with `w:hRule` — `exact` pins the height, anything else fits the text. */
+    readonly heightPt?: Pt;
+    readonly heightRule?: 'auto' | 'exact' | 'atLeast';
+    /** `w:x`/`w:y` — the offset from whatever `hAnchor`/`vAnchor` names. */
+    readonly xPt?: Pt;
+    readonly yPt?: Pt;
+    /** `w:xAlign`/`w:yAlign` — an alignment instead of an offset. */
+    readonly xAlign?: 'left' | 'center' | 'right' | 'inside' | 'outside';
+    readonly yAlign?: 'top' | 'center' | 'bottom' | 'inside' | 'outside';
+    readonly hAnchor?: 'text' | 'margin' | 'page';
+    readonly vAnchor?: 'text' | 'margin' | 'page';
+    /** §17.18.104 ST_Wrap — how the body text runs past the frame. */
+    readonly wrap?: 'auto' | 'around' | 'none' | 'notBeside' | 'tight' | 'through';
+    readonly hSpacePt?: Pt;
+    readonly vSpacePt?: Pt;
+}
 export interface ParagraphProperties {
     readonly styleId?: string;
+    /**
+     * §17.7.2 — the `w:pPr` of the TABLE STYLE the paragraph's cell is formatted
+     * by. It is not the paragraph's own formatting: the cascade puts it under the
+     * paragraph's style (docDefaults < table style < numbering < paragraph style
+     * < character style < direct), so it is carried apart from the direct
+     * properties rather than merged into them.
+     */
+    readonly tableStyle?: ParagraphProperties;
+    /**
+     * §17.7.2 — a run layer that ranks BELOW the paragraph's own style and below
+     * the character style a run names: the `w:rPr` of the table style the cell is
+     * formatted by, or the `a:fontRef` colour a gallery-drawn shape lends the
+     * text inside it (§20.1.4.2.14). Carried on the paragraph because every run
+     * of it — and its MARK — reads the same layer.
+     */
+    readonly inheritedRun?: RunProperties;
+    /**
+     * §17.6.17 — the paragraph's mark carries a `w:sectPr`: it is the last
+     * paragraph of its section, and the mark IS the section break. One with no
+     * content of its own therefore prints nothing, not an empty line.
+     */
+    readonly sectionBreak?: boolean;
+    /** §17.3.1.11 — the paragraph floats as a text frame. */
+    readonly frame?: FrameProperties;
+    /**
+     * §17.3.1.41 `w:textDirection` — which way the paragraph's lines run.
+     * `btLr` reads bottom-to-top, `tbRl` top-to-bottom; `lrTb` is the default
+     * and is not recorded.
+     */
+    readonly textDirection?: 'btLr' | 'tbRl';
+    /**
+     * §17.3.1.32 `w:snapToGrid` — whether the paragraph's lines stand on the
+     * section's document grid (§17.6.5). Absent ⇒ they do; Word's header and
+     * footer styles are what usually says otherwise.
+     */
+    readonly snapToGrid?: boolean;
     readonly alignment?: Alignment;
     readonly spacingBefore?: Pt;
     readonly spacingAfter?: Pt;
     readonly spacingLine?: Pt;
     readonly spacingLineRule?: 'auto' | 'exact' | 'atLeast';
+    /**
+     * ECMA-376 Part 1 §17.3.1.9 — `w:contextualSpacing`. The space before and
+     * after is dropped where the neighbour is a paragraph of the SAME style: a
+     * list is written this way, so its items sit together while the list as a
+     * whole keeps its space from the text around it.
+     */
+    readonly contextualSpacing?: boolean;
+    /** ECMA-376 Part 1 §17.3.1.37 — the paragraph's own `w:tabs` stops. */
+    readonly tabs?: ReadonlyArray<TabStop>;
+    /**
+     * §17.3.1.24 `w:pBdr` — rules drawn around the paragraph. `w:space` is the
+     * gap each keeps from the text, carried on the {@link Border} as `spacePt`.
+     */
+    readonly borders?: CellBorders;
+    /** §17.3.1.31 `w:pPr/w:shd` — the paragraph's own background fill. */
+    readonly shading?: CellShading;
     readonly indentLeft?: Pt;
     readonly indentRight?: Pt;
     readonly indentFirstLine?: Pt;
     /** The implicit default run properties for runs in this paragraph (`w:pPr/w:rPr`). */
     readonly runProperties?: RunProperties;
+    /**
+     * §17.3.1.3/§17.3.1.1 — the gap `w:beforeAutospacing`/`w:afterAutospacing`
+     * asks the consumer for, already resolved to a length by the reader (it
+     * depends on the document's compatibility mode). Present only when the
+     * autospacing flag is ON, and it beats the `w:before`/`w:after` beside it.
+     * A separate property because style inheritance is per ATTRIBUTE: a style
+     * based on one that says `beforeAutospacing` inherits the flag even when it
+     * states a `w:before` of its own — which is how tdf104354_firstParaInSection
+     * gets its 75pt before, and taking that literally spread one page over four.
+     */
+    readonly spacingBeforeAuto?: Pt;
+    readonly spacingAfterAuto?: Pt;
     readonly numbering?: NumberingReference;
+    /**
+     * §17.9.4 — a `w:numPr` that names a LEVEL and no `w:numId`: the instance is
+     * whatever the style this one is based on refers to. Word's own Heading 2
+     * says exactly this, and dropped it numbered num-parent-style.docx's headings
+     * 1, 2, 3, 4 where its own text says they should read 1, 1.1, 2, 2.1.
+     */
+    readonly numberingLevel?: number;
     /**
      * ECMA-376 Part 1 §17.3.1.21 — `w:pageBreakBefore`. When true, the paragraph
      * starts on a fresh page even if there is room on the current one.
@@ -89,14 +225,58 @@ export interface ParagraphProperties {
  * {@link Run} alongside (or instead of) `text` so layout can position the image
  * as if it were a glyph in the line box.
  */
+/**
+ * §20.1.2.2.24 `a:ln` on a `pic:spPr` (VML: `@stroked`/`v:stroke`) — the frame
+ * a picture is drawn with. Word's "Picture Border": a rule around the picture
+ * box, not part of the image itself.
+ */
+export interface PictureOutline {
+    readonly colorHex: string;
+    readonly widthPt: Pt;
+}
 export interface InlineImage {
     /**
      * Content-addressed bytes in the document's `ResourceStore`; absent when the
      * source relationship did not resolve (the layout box still reserves space).
      */
     readonly resource?: ResourceId;
+    /** The picture's own frame, when it has one (see {@link PictureOutline}). */
+    readonly outline?: PictureOutline;
+    /**
+     * §20.1.8.40 `a:outerShdw` — the drop shadow under the picture. Word writes
+     * one on every screenshot pasted with a style; drawn nowhere, imgshadow.docx's
+     * six stood flat on the page where both references lift them off it.
+     */
+    readonly shadow?: ShapeShadow;
+    /**
+     * §14.1.2.10 `@gain`/`@blacklevel` — the contrast and brightness the picture
+     * is drawn through, about mid grey: `out = (in - 0.5) * gain + 0.5 + black`.
+     * Word washes a watermark out this way.
+     */
+    readonly wash?: {
+        readonly gain: number;
+        readonly black: number;
+    };
     readonly width: Pt;
     readonly height: Pt;
+    /** §20.1.8.55 `a:srcRect` — the part of the source the frame shows. */
+    readonly crop?: ImageCrop;
+    /** §20.1.7.6 `a:xfrm @rot` — the picture's own rotation (1/60000°, clockwise). */
+    readonly rotation60k?: number;
+    /** §20.1.7.6 `a:xfrm @flipH/@flipV` — the picture drawn mirrored. */
+    readonly flipH?: boolean;
+    readonly flipV?: boolean;
+    /**
+     * §20.4.2.6 `wp:effectExtent` — space the drawing needs BEYOND its extent,
+     * for what a rotation or an effect throws outside the frame. The line box
+     * reserves it; the picture itself is drawn inset by it.
+     */
+    readonly effectExtent?: {
+        readonly leftPt: Pt;
+        readonly topPt: Pt;
+        readonly rightPt: Pt;
+        readonly bottomPt: Pt;
+    };
 }
 /**
  * ECMA-376 Part 1 §22 — OfficeMathML (OMML). A recursive math element tree.
@@ -263,6 +443,11 @@ export interface Run {
      * paragraph's following content starts on a new page.
      */
     readonly pageBreak?: boolean;
+    /**
+     * §17.3.3.1 `w:br w:type="column"` — the text after this run continues in the
+     * NEXT column of the section (or, past the last, on the next page).
+     */
+    readonly columnBreak?: boolean;
 }
 /** ECMA-376 Part 1 §17.3.1 — a paragraph: its {@link ParagraphProperties} and runs. */
 export interface Paragraph {
@@ -302,7 +487,23 @@ export interface Comment {
     readonly done?: boolean;
 }
 /** ECMA-376 Part 1 §17.9 — `w:numFmt` list marker format. */
-export type NumberingFormat = 'decimal' | 'lowerLetter' | 'upperLetter' | 'lowerRoman' | 'upperRoman' | 'bullet' | 'none';
+export type NumberingFormat = 'decimal' | 'decimalZero' | 'decimalFullWidth' | 'ordinal' | 'lowerLetter' | 'upperLetter' | 'lowerRoman' | 'upperRoman'
+/** §17.18.59 — the ten heavenly stems 甲乙丙…, then plain digits. */
+ | 'ideographTraditional'
+/** The twelve earthly branches 子丑寅…, then plain digits. */
+ | 'ideographZodiac'
+/** The formal (anti-fraud) numerals 壹貳參…, composed with 拾佰仟. */
+ | 'ideographLegalTraditional'
+/** Digit-by-digit ideographs: 10 is 一零, not 十. */
+ | 'ideographDigital' | 'koreanDigital2'
+/** Counting ideographs: 10 is 十, 11 is 十一, 21 is 二十一. */
+ | 'chineseCounting' | 'chineseCountingThousand' | 'japaneseCounting' | 'koreanCounting' | 'taiwaneseCounting' | 'taiwaneseCountingThousand'
+/** §17.18.59 — Hebrew numerals (gematria): א, ב, … ט״ו, ט״ז, י״ז … */
+ | 'hebrew1'
+/** The Hebrew alphabet as a plain sequence, cycling past ת. */
+ | 'hebrew2'
+/** ①②③… up to twenty, then plain digits. */
+ | 'decimalEnclosedCircle' | 'chicago' | 'bullet' | 'none';
 /** A paragraph's list reference (`w:numPr`): the numbering instance id + level. */
 export interface NumberingReference {
     readonly numId: string;
@@ -315,9 +516,28 @@ export interface NumberingLevel {
     readonly format: NumberingFormat;
     /** §17.9.11 `w:lvlText` — the marker template (e.g. `"%1."`). */
     readonly lvlText: string;
+    /**
+     * §17.9.9 `w:lvlPicBulletId` → §17.9.21 `w:numPicBullet` — the level's bullet
+     * is a PICTURE, not a character, and the `w:lvlText` is only the fallback
+     * glyph Word writes beside it.
+     */
+    readonly picBullet?: PictureBullet;
+    /**
+     * §17.9.10 `w:isLgl` — every level of this level's marker is printed in
+     * DECIMAL, whatever format the level it names asks for. Word calls it legal
+     * numbering: "Sect I.01" becomes "Sect 1.01".
+     */
+    readonly isLegal?: boolean;
     readonly paragraphProperties: ParagraphProperties;
     readonly runProperties: RunProperties;
 }
+/** §17.9.21 `w:numPicBullet` — the image a level uses in place of a bullet. */
+export interface PictureBullet {
+    /** Content-addressed bytes. A bullet whose picture does not resolve is not one. */
+    readonly resource: ResourceId;
+    readonly widthPt: Pt;
+    readonly heightPt: Pt;
+}
 /** §17.9.1 `w:abstractNum` — a reusable list definition keyed by level. */
 export interface AbstractNumbering {
     readonly id: string;
@@ -327,6 +547,18 @@ export interface AbstractNumbering {
 export interface NumberingInstance {
     readonly numId: string;
     readonly abstractNumId: string;
+    /**
+     * §17.9.27/§17.9.28 `w:lvlOverride/w:startOverride` — where THIS instance
+     * starts a level, by `w:ilvl`, whatever the abstract definition says. Absent
+     * when the instance takes the abstract starts unchanged.
+     */
+    readonly startOverrides?: ReadonlyMap<number, number>;
+    /**
+     * §17.9.27 `w:lvlOverride/w:lvl` — a level this instance REDEFINES whole,
+     * shadowing the abstract definition's. NumberingWOverrides.docx rewrites all
+     * nine levels of one instance this way.
+     */
+    readonly levelOverrides?: ReadonlyMap<number, NumberingLevel>;
 }
 /** The parsed `word/numbering.xml`: abstract definitions + their instances. */
 export interface Numbering {
@@ -344,6 +576,8 @@ export type StyleType = 'paragraph' | 'character' | 'table' | 'numbering';
 export interface TableStyleLayer {
     readonly borders?: CellBorders;
     readonly cellMargins?: CellMargins;
+    /** §17.4.65 `w:tblInd` — the table indent a whole-table layer declares. */
+    readonly indentPt?: Pt;
     readonly shading?: CellShading;
     readonly runProperties?: RunProperties;
     readonly paragraphProperties?: ParagraphProperties;
@@ -385,12 +619,14 @@ export interface StyleSheet {
     readonly styles: ReadonlyMap<string, Style>;
 }
 /** §17.18.2 ST_Border — a cell-border line style (the subset Ream renders). */
-export type BorderStyle = 'none' | 'single' | 'double' | 'thick' | 'dotted' | 'dashed' | 'dashDot' | 'dashDotDot';
+export type BorderStyle = 'none' | 'single' | 'double' | 'thick' | 'dotted' | 'dashed' | 'dashSmallGap' | 'dashDot' | 'dashDotDot';
 /** One border edge: its line style plus optional width and colour. */
 export interface Border {
     readonly style: BorderStyle;
     readonly width?: Pt;
     readonly colorHex?: string;
+    /** §17.3.1.24 `w:space` — how far a paragraph rule stands off its text. */
+    readonly spacePt?: Pt;
 }
 /** §17.4.39 `w:tcBorders` — the per-edge borders of a cell (or table). */
 export interface CellBorders {
@@ -480,6 +716,14 @@ export type CellMerge = 'start' | 'middle' | 'end';
 /** §17.4.30 `w:tcPr` — a cell's properties: span/merge, chrome, and CF overlays. */
 export interface CellProperties {
     readonly width?: Pt;
+    /**
+     * §17.4.72 `w:tcW w:type="pct"` — the cell's preferred width as a share of
+     * the table (`w`/5000). Held apart from {@link width} because a percentage
+     * cannot be resolved until the table's own width is known.
+     */
+    readonly widthFraction?: number;
+    /** §17.18.90 ST_TblWidth — which of the two above the cell actually declared. */
+    readonly widthType?: 'auto' | 'dxa' | 'pct' | 'nil';
     readonly colSpan?: number;
     readonly merge?: CellMerge;
     readonly borders?: CellBorders;
@@ -512,6 +756,11 @@ export interface CellProperties {
      * to clip against and lets the browser decide.
      */
     readonly noWrap?: boolean;
+    /**
+     * §17.4.20 `w:hideMark` — the cell's end-of-cell mark is not counted when the
+     * row's height is measured, so an EMPTY cell that says so adds nothing at all.
+     */
+    readonly hideMark?: boolean;
     /**
      * The cell holds a NUMBER under a format of its own, so it may not be shown
      * truncated: a date cut to "4/30/201" is not a shorter date, it is the wrong
@@ -534,11 +783,27 @@ export interface RowProperties {
     readonly heightRule?: 'auto' | 'atLeast' | 'exact';
     readonly cantSplit?: boolean;
     readonly isHeader?: boolean;
+    /**
+     * §17.4.14 `w:gridBefore` — how many grid columns the row leaves empty
+     * before its first cell, which is how a row starts part-way across a table.
+     */
+    readonly gridBefore?: number;
     /**
      * Force this row to begin a new page (xlsx manual `<rowBreaks>`). The renderer
      * flushes the page before the row, then repeats any leading header rows.
      */
     readonly pageBreakBefore?: boolean;
+    /**
+     * §17.4.7 `w:cnfStyle` — the conditional formats of the table style this row
+     * takes, whatever its position says. Word's calendar templates give a SECOND
+     * header row `w:firstRow="1"` so it is painted like the first.
+     */
+    readonly conditional?: RowConditionalFormat;
+}
+/** §17.4.7 — the row-level conditional-format flags a `w:cnfStyle` declares. */
+export interface RowConditionalFormat {
+    readonly firstRow?: boolean;
+    readonly lastRow?: boolean;
 }
 /**
  * §17.4.62 `w:tblLook` — which of the table style's conditional formats apply.
@@ -572,6 +837,18 @@ export interface TableProperties {
      * Centers or right-aligns a table narrower than the content width; absent ⇒ left.
      */
     readonly alignment?: 'left' | 'center' | 'right';
+    /**
+     * §17.4.65 `w:tblInd` — how far the table's leading edge stands in from the
+     * text margin. Distinct from {@link alignment}, which shares out the slack a
+     * narrow table leaves.
+     */
+    readonly indentPt?: Pt;
+    /**
+     * §17.4.58 `w:tblpPr` — the table FLOATS: it is placed at an anchor of its
+     * own and the text runs past it, exactly as an anchored drawing does. Read
+     * into the same {@link FloatAnchor} the drawings use.
+     */
+    readonly float?: FloatAnchor;
     /**
      * A sticky-pane hint from a frozen worksheet view (E-SHEET SE3): the first
      * `rows` rows / `cols` columns stay pinned while the rest scrolls. Consumed
@@ -606,12 +883,51 @@ export interface Table {
  * ECMA-376 Part 1 §20.4.2.8 — a block-level image (`wp:inline` picture extent).
  * EMU = English Metric Units: 914400 per inch (1 pt = 12700 EMU).
  */
+/**
+ * §20.1.8.55 `a:srcRect` — how much of each edge of the source picture is cut
+ * away before it is fitted to its frame, as a fraction of the source (so 0.25
+ * on `left` drops its left quarter). Absent edges are zero.
+ */
+export interface ImageCrop {
+    readonly left: number;
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+}
 export interface ImageBlock {
     /** §20.4.2.3 — present when the drawing is anchored (floating). */
     readonly float?: FloatAnchor;
     readonly resource?: ResourceId;
+    /** The picture's own frame, when it has one (see {@link PictureOutline}). */
+    readonly outline?: PictureOutline;
+    /**
+     * §20.1.8.40 `a:outerShdw` — the drop shadow under the picture. Word writes
+     * one on every screenshot pasted with a style; drawn nowhere, imgshadow.docx's
+     * six stood flat on the page where both references lift them off it.
+     */
+    readonly shadow?: ShapeShadow;
+    /**
+     * §14.1.2.10 `@gain`/`@blacklevel` — the contrast and brightness the picture
+     * is drawn through, about mid grey: `out = (in - 0.5) * gain + 0.5 + black`.
+     * Word washes a watermark out this way.
+     */
+    readonly wash?: {
+        readonly gain: number;
+        readonly black: number;
+    };
     readonly width: Pt;
     readonly height: Pt;
+    /** §20.1.8.55 `a:srcRect` — the part of the source the frame shows. */
+    readonly crop?: ImageCrop;
+    /** §20.1.7.6 `a:xfrm @rot` — the picture's own rotation (1/60000°, clockwise). */
+    readonly rotation60k?: number;
+    /** §20.1.7.6 `a:xfrm @flipH/@flipV` — the picture drawn mirrored. */
+    readonly flipH?: boolean;
+    readonly flipV?: boolean;
+    /** `wp14:sizeRelH/V` — a size stated as a share of the page or margins. */
+    readonly relativeSize?: RelativeSize;
+    /** §20.4.2.6 `wp:effectExtent` — space reserved around the picture (see {@link InlineImage}). */
+    readonly effectExtent?: InlineImage['effectExtent'];
     readonly paragraphProperties: ParagraphProperties;
     /** `wp:docPr @descr/@title` — alternate text for the tagged-PDF Figure (`/Alt`). */
     readonly altText?: string;
@@ -669,13 +985,30 @@ export interface ShapeGeometry {
     readonly adjust?: ReadonlyMap<string, number>;
     readonly custom?: CustomGeometry;
 }
-/** A shape's fill mode (`a:noFill`/`a:solidFill`/`a:gradFill`). */
-export type ShapeFillKind = 'none' | 'solid' | 'gradient';
-/** A shape's fill: none, a solid colour, or a {@link ShapeGradient}. */
+/** A shape's fill mode (`a:noFill`/`a:solidFill`/`a:gradFill`/`a:blipFill`). */
+export type ShapeFillKind = 'none' | 'solid' | 'gradient' | 'picture';
+/** A shape's fill: none, a solid colour, a {@link ShapeGradient}, or a picture. */
 export interface ShapeFill {
     readonly kind: ShapeFillKind;
     readonly colorHex?: string;
     readonly gradient?: ShapeGradient;
+    /**
+     * §20.1.8.14 `a:blipFill` — the picture painted across the shape's box. A
+     * DrawingML picture IS a shape with one of these, which is how a `pic:pic`
+     * inside a group reaches the page.
+     */
+    readonly imageResource?: ResourceId;
+    /**
+     * §20.1.8.30 `a:stretch/a:fillRect` (or an `a:srcRect` beside it) — the part
+     * of the picture the box shows, as the fractions cut from each side.
+     */
+    readonly imageCrop?: ImageCrop;
+    /**
+     * §20.1.2.3.1 `a:alpha` / §14.1.2.5 `@opacity` — how opaque the fill is,
+     * `0..1`. Absent is opaque. The colour above is the fill's own, NOT composited
+     * over the paper: what is behind the shape shows through it.
+     */
+    readonly alpha?: number;
 }
 /** §20.1.10.49 ST_PresetLineDashVal — a shape outline's preset dash pattern. */
 export type ShapeDash = 'solid' | 'dot' | 'dash' | 'dashDot' | 'lgDash' | 'lgDashDot' | 'sysDash' | 'sysDot';
@@ -684,8 +1017,45 @@ export interface ShapeLine {
     readonly width?: Pt;
     readonly colorHex?: string;
     readonly dash?: ShapeDash;
+    /**
+     * §20.1.8.21 `a:custDash` — the author's own pattern: dash/space lengths as
+     * MULTIPLES of the line width, in the order they are drawn.
+     */
+    readonly customDash?: ReadonlyArray<number>;
     readonly cap?: 'flat' | 'round' | 'square';
     readonly fill?: 'solid' | 'none';
+    /** §20.1.8.24 `a:headEnd` — the decoration at the line's first point. */
+    readonly headEnd?: LineEnd;
+    /** §20.1.8.42 `a:tailEnd` — the decoration at the line's last point. */
+    readonly tailEnd?: LineEnd;
+}
+/**
+ * §20.1.8.24 / §20.1.8.42 — an arrowhead (or other decoration) at one end of a
+ * line: its shape plus the width and length steps `ST_LineEndWidth` /
+ * `ST_LineEndLength` name.
+ */
+export interface LineEnd {
+    readonly type: 'triangle' | 'stealth' | 'diamond' | 'oval' | 'arrow';
+    readonly width?: 'sm' | 'med' | 'lg';
+    readonly length?: 'sm' | 'med' | 'lg';
+}
+/**
+ * `wp14:sizeRelH` / `wp14:sizeRelV` — the drawing's size as a PERCENTAGE of
+ * the page or the margins rather than the extent beside it. Word 2010 writes
+ * it in the `wp14` namespace, with the extent as the fallback for readers that
+ * do not know it.
+ */
+export interface RelativeSize {
+    readonly widthPct?: number;
+    /**
+     * §20.4.3.6 ST_SizeRelFromH — what the percentage is OF. `margin` is the text
+     * area; the rest are the bands around it, and a drawing sized against one is
+     * a fraction of that band alone (tdf123324 asks for 150% of the top margin).
+     */
+    readonly widthFrom?: 'margin' | 'page' | 'leftMargin' | 'rightMargin';
+    readonly heightPct?: number;
+    /** §20.4.3.7 ST_SizeRelFromV — the vertical twin. */
+    readonly heightFrom?: 'margin' | 'page' | 'topMargin' | 'bottomMargin';
 }
 /** §20.1.7.6 `a:xfrm` — a shape's rotation (1/60000°, clockwise) + flips. */
 export interface ShapeTransform {
@@ -701,6 +1071,32 @@ export interface ShapeTextBody {
     readonly insetRight?: Pt;
     readonly insetBottom?: Pt;
     readonly anchor?: 't' | 'ctr' | 'b';
+    /**
+     * §20.1.10.83 ST_TextVerticalType (`a:bodyPr @vert`) — text set along the
+     * box's long axis rather than across it. `vert` reads top-to-bottom (turned a
+     * quarter clockwise), `vert270` bottom-to-top.
+     */
+    readonly vertical?: 'vert' | 'vert270';
+    /**
+     * §20.1.10.28 `a:spAutoFit` — the SHAPE follows its text: its height is
+     * whatever the text needs, whatever the stated box says.
+     */
+    readonly autoFit?: boolean;
+    /**
+     * §14.1.2.22 `v:textpath @fitshape` — the TEXT follows the shape: legacy
+     * WordArt is set at whatever size fills the box it was drawn in.
+     */
+    readonly fitToBox?: boolean;
+    /**
+     * `wps:txbx @id` / `wps:linkedTxbx @id @seq` — the chain of boxes this one
+     * belongs to. Text that overruns a box continues in the next of its chain;
+     * `seq` 0 is the box that holds the words, and the rest carry none of their
+     * own.
+     */
+    readonly chain?: {
+        readonly id: string;
+        readonly seq: number;
+    };
 }
 /**
  * A block-level DrawingML shape (§20.1): its size, {@link ShapeGeometry}, fill,
@@ -723,15 +1119,29 @@ export interface ShapeShadow {
     /** 0..1, from the shadow colour's `a:alpha` (absent ⇒ opaque). */
     readonly alpha: number;
 }
+/**
+ * §20.5.2.17 `wpg:wgp` — one member of a drawing group, and where it sits: the
+ * offsets are from the group's own top-left corner, already mapped out of the
+ * group's child coordinate space.
+ */
+export interface ShapeGroupChild {
+    readonly shape: ShapeBlock;
+    readonly xPt: Pt;
+    readonly yPt: Pt;
+}
 export interface ShapeBlock {
     /** §20.4.2.3 — present when the drawing is anchored (floating). */
     readonly float?: FloatAnchor;
     readonly width: Pt;
     readonly height: Pt;
+    /** §20.5.2.17 — the shapes a group holds, drawn inside its own box. */
+    readonly children?: ReadonlyArray<ShapeGroupChild>;
     readonly geometry: ShapeGeometry;
     readonly fill: ShapeFill;
     readonly line?: ShapeLine;
     readonly transform?: ShapeTransform;
+    /** `wp14:sizeRelH/V` — a size stated as a share of the page or margins. */
+    readonly relativeSize?: RelativeSize;
     readonly text?: ShapeTextBody;
     /** §20.1.8.40 — the shape's drop shadow, direct or from its style reference. */
     readonly shadow?: ShapeShadow;
@@ -833,6 +1243,8 @@ export interface ChartLineStyle {
     readonly none?: boolean;
     readonly colorHex?: string;
     readonly widthPt?: number;
+    /** §20.1.10.49 `a:prstDash` — the rule's dash pattern, when it names one. */
+    readonly dash?: ShapeDash;
 }
 /** A parsed chart (§21.2): its type, title, categories, series and rendering options. */
 export interface Chart {
@@ -898,6 +1310,16 @@ export interface Chart {
      */
     readonly frameFillHex?: string;
     readonly frameLineHex?: string;
+    /** The frame rule's width and dash, when it states them. */
+    readonly frameLineWidthPt?: number;
+    readonly frameLineDash?: ShapeDash;
+    /**
+     * §21.2.2.145 `c:plotArea/c:spPr` — the plot rectangle's own fill and rule,
+     * which sit inside the frame. Chart_Plot_BorderLine_Style.docx rules its plot
+     * in a heavy orange dash-dot.
+     */
+    readonly plotFillHex?: string;
+    readonly plotLine?: ChartLineStyle;
     /**
      * §21.2.2.121 `c:valAx/c:numFmt@formatCode` — the number format the value
      * axis's tick labels and the data labels are drawn in, in the same code
@@ -952,6 +1374,11 @@ export interface PageMargins {
     readonly left: Pt;
     readonly header?: Pt;
     readonly footer?: Pt;
+    /**
+     * §17.6.11 `w:gutter` — the binding space, added to the left margin (or to
+     * the top, when `w:settings/w:gutterAtTop` says so).
+     */
+    readonly gutter?: Pt;
 }
 /** §17.10 — which page class a header/footer reference applies to. */
 export type HeaderFooterType = 'default' | 'first' | 'even';
@@ -971,6 +1398,22 @@ export interface SectionProperties {
      * of the section uses the `first` header/footer references.
      */
     readonly titlePg?: boolean;
+    /**
+     * §17.6.12 `w:pgNumType w:start` — the number the section's first page is
+     * printed with. Absent ⇒ the count carries on from the section before.
+     */
+    readonly pageNumberStart?: number;
+    /** §17.6.8 `w:lnNumType` — line numbers printed in the margin beside the text. */
+    readonly lineNumbering?: {
+        /** Print every `countBy`-th line (default 1). */
+        readonly countBy: number;
+        /** The number the count starts at (default 1). */
+        readonly start: number;
+        /** How far the number stands off the text (`w:distance`); absent ⇒ Word's quarter inch. */
+        readonly distancePt?: Pt;
+        /** §17.18.55 — where the count restarts. */
+        readonly restart: 'newPage' | 'newSection' | 'continuous';
+    };
     /**
      * ECMA-376 §17.15.1.36 — `w:evenAndOddHeaders` toggle in `word/settings.xml`
      * (document-wide, not per-section). When true even-numbered pages use the
@@ -979,6 +1422,28 @@ export interface SectionProperties {
     readonly evenAndOddHeaders?: boolean;
     /** §17.6.4 `w:cols` — multi-column section layout. */
     readonly columns?: SectionColumns;
+    /**
+     * §17.6.10 `w:pgBorders` — the rules drawn around the page. `offsetFrom`
+     * says what each edge's `spacePt` is measured from: the paper's edge, or the
+     * text margin it stands outside of.
+     */
+    readonly pageBorders?: {
+        readonly borders: CellBorders;
+        readonly offsetFrom: 'page' | 'text';
+    };
+    /**
+     * §17.6.22 `w:type` — where the section starts. `continuous` starts it on the
+     * page already in hand rather than a fresh one; everything else (nextPage,
+     * and the odd/even/column variants we do not distinguish) starts a page.
+     */
+    readonly sectionStart?: 'continuous' | 'nextPage';
+    /**
+     * §17.6.5 `w:docGrid` — the line grid a `lines`/`linesAndChars` section rules
+     * its text onto, as the pitch in points. Every line of the section's text is
+     * as tall as a whole number of these, however tall its own font makes it.
+     * Absent ⇒ no grid (`w:type="default"`, or none stated).
+     */
+    readonly gridLinePitchPt?: Pt;
 }
 /**
  * §20.4.2.3 `wp:anchor` — a floating drawing's placement. v1 honours
@@ -986,16 +1451,67 @@ export interface SectionProperties {
  * modes (square/tight/through) and `topAndBottom` stay in flow as blocks.
  */
 export interface FloatAnchor {
-    readonly wrap: 'none' | 'square' | 'tight' | 'through' | 'topAndBottom';
+    /**
+     * §20.4.2.3 / §17.18.104 — how body text runs past the drawing. `notBeside`
+     * is the FRAME's own mode: the drawing keeps the place its anchor names, but
+     * no text may stand beside it, so its band spans the whole column.
+     */
+    readonly wrap: 'none' | 'square' | 'tight' | 'through' | 'topAndBottom' | 'notBeside';
     readonly behind?: boolean;
+    /**
+     * §20.4.2.3 `wp:anchor @relativeHeight` — the z-order among the floats on the
+     * page: the higher number is drawn over the lower, whatever their order in
+     * the document.
+     */
+    readonly zOrder?: number;
     readonly posH?: {
-        readonly relativeFrom: 'margin' | 'page' | 'column';
+        /**
+         * §20.4.3.3 ST_RelFromH. `leftMargin`/`rightMargin` are the margin BANDS
+         * beside the text area, which is where a marginal note is placed:
+         * tdf103573.docx centres one box in each, and read as plain `margin` they
+         * both landed in the middle of the text and printed over each other.
+         */
+        readonly relativeFrom: 'margin' | 'page' | 'column' | 'leftMargin' | 'rightMargin';
         readonly offsetPt?: Pt;
         readonly align?: 'left' | 'center' | 'right';
     };
     readonly posV?: {
-        readonly relativeFrom: 'margin' | 'page' | 'paragraph' | 'line';
+        /**
+         * §20.4.3.4 ST_RelFromV. `topMargin`/`bottomMargin` measure from the top
+         * edge of the margin BAND they name — page-content-bottom.docx hangs a
+         * square 312pt above the bottom margin, and read as plain `margin` it went
+         * off the top of the page.
+         */
+        readonly relativeFrom: 'margin' | 'page' | 'paragraph' | 'line' | 'topMargin' | 'bottomMargin';
         readonly offsetPt?: Pt;
+        /**
+         * §20.4.3.1 `wp:align` (VML: `mso-position-vertical`) — a KEYWORD rather
+         * than an offset, which is how Word centres a watermark in its page.
+         */
+        readonly align?: 'top' | 'center' | 'bottom';
+    };
+    /**
+     * §20.4.2.3 `@wrapText` on the wrap element — which side(s) of the drawing
+     * text may stand on. `bothSides` is the default and the only value that
+     * fills BOTH gaps; `left`/`right` name one, `largest` the wider.
+     */
+    readonly wrapSide?: 'bothSides' | 'left' | 'right' | 'largest';
+    /**
+     * §20.4.2.3 `wp:anchor @layoutInCell` (VML `o:allowincell`) — present and
+     * false when a drawing anchored inside a TABLE CELL is placed against the
+     * page rather than against the cell. Absent means the default: the cell is
+     * the frame every `relativeFrom` is measured in.
+     */
+    readonly inCell?: boolean;
+    /**
+     * §20.4.2.3 `wp:anchor @distT/@distB/@distL/@distR` — how far the wrapped
+     * text stands off each edge of the drawing. Absent sides are 0.
+     */
+    readonly wrapDist?: {
+        readonly topPt: Pt;
+        readonly bottomPt: Pt;
+        readonly leftPt: Pt;
+        readonly rightPt: Pt;
     };
 }
 /**
@@ -1009,6 +1525,8 @@ export interface SectionColumns {
         readonly widthPt: number;
         readonly spacePt: number;
     }>;
+    /** §17.6.4 `w:sep` — a vertical rule drawn down the middle of every gutter. */
+    readonly separator?: boolean;
 }
 /**
  * One section descriptor for a multi-section document (ECMA-376 §17.6.17). Each