@silurus/ooxml 0.71.0 → 0.72.1

package/dist/{segments-BLmJVJRb.js → segments-2VsQNClV.js}

@@ -1,4 +1,4 @@
-import { w as e } from "./find-cursor-DgyGlCIw.js";
+import { V as e } from "./find-cursor-CABDFafh.js";
 //#region packages/core/src/text/bidi/segments.ts
 function t(t, n) {
 	return t === !0 ? "rtl" : t === !1 ? "ltr" : e().computeLevels(n, "auto").paragraphLevel === 1 ? "rtl" : "ltr";

package/dist/types/docx.d.ts

@@ -69,6 +69,14 @@ export declare type BodyElement = {
      *  separately from `geom` because a section may inherit its geometry yet
      *  still restart / re-format its page numbers. */
     pageNumType?: PageNumType | null;
+    /** ECMA-376 §17.6.20 `<w:textDirection w:val>` — this ENDING section's
+     *  flow direction (TRANSITIONAL ST_TextDirection, same enum and semantics
+     *  as {@link SectionProps.textDirection}), so a vertical (tbRl/btLr)
+     *  non-final section can coexist with a horizontal final section (issue
+     *  #1000). Absent ⇒ horizontal ("lrTb" is collapsed by the parser).
+     *  Carried separately from `geom` (like `pageNumType`) because a section
+     *  may inherit its page geometry yet still set its own flow direction. */
+    textDirection?: string | null;
 };
 
 export declare interface BorderSpec {
@@ -80,17 +88,23 @@ export declare interface BorderSpec {
 /**
  * Populate a highlight overlay layer with one box per matched run-slice.
  *
- * @param layer    the overlay div (cleared and re-sized to the canvas here).
+ * Every box is positioned as a PERCENTAGE of `cssWidth`/`cssHeight`, and the
+ * container's own size is left untouched (`width:100%;height:100%` from the
+ * caller), so the highlights track the canvas's ACTUAL rendered box even when a
+ * consumer scales the canvas down with external CSS — mirroring
+ * {@link buildDocxTextLayer}.
+ *
+ * @param layer    the overlay div (cleared here; sized `100%` by the caller).
  * @param runs     the page's runs (same array the page was rendered/text-layered from).
  * @param matches  the page's matches (run-slices + active flag).
- * @param canvasCssWidth  the rendered canvas's CSS width (e.g. `"700px"`).
- * @param canvasCssHeight the rendered canvas's CSS height.
+ * @param cssWidth  the page's intended CSS width (px, number) — the x-axis % denominator.
+ * @param cssHeight the page's intended CSS height (px, number) — the y-axis % denominator.
  * @param measureForFont  returns a width-measurer primed with a run's `font`
  *                        (the viewer closes over a canvas 2d context). Kept as a
  *                        factory so the font is set once per run, not per glyph.
  * @param colors   optional colour overrides.
  */
-export declare function buildDocxHighlightLayer(layer: HTMLDivElement, runs: DocxTextRunInfo[], matches: DocxHighlightMatch[], canvasCssWidth: string, canvasCssHeight: string, measureForFont: (font: string) => (s: string) => number, colors?: DocxHighlightColors): void;
+export declare function buildDocxHighlightLayer(layer: HTMLDivElement, runs: DocxTextRunInfo[], matches: DocxHighlightMatch[], cssWidth: number, cssHeight: number, measureForFont: (font: string) => (s: string) => number, colors?: DocxHighlightColors): void;
 
 /**
  * Build the transparent text-selection overlay for a rendered docx page: one
@@ -103,11 +117,21 @@ export declare function buildDocxHighlightLayer(layer: HTMLDivElement, runs: Doc
  * the same `DocxTextRunInfo[]` off-thread and ships it back beside the bitmap, so
  * the overlay is built from identical geometry regardless of thread.
  *
- * @param layer            the overlay div (position:relative parent expected).
+ * Every span is positioned as a PERCENTAGE of `cssWidth`/`cssHeight` (the page's
+ * intended CSS-px box), never literal px, and the container's own width/height are
+ * left untouched (the caller sizes it `width:100%;height:100%`). This lets the
+ * overlay track the canvas's ACTUAL rendered box even when a consumer scales the
+ * canvas down with external CSS (`width:100%!important; height:auto`): the
+ * `display:inline-block` wrapper shrinks with the canvas, the `100%` container
+ * follows, and every `%`-placed span scales with it, so nothing overflows the
+ * wrapper into an ancestor's scroll area.
+ *
+ * @param layer            the overlay div (sized `width:100%;height:100%` by the caller).
  * @param runs             per-run geometry from `renderPage({ onTextRun })`.
- * @param canvasCssWidth   the rendered canvas's CSS width (e.g. `"700px"`), used
- *                         to size the overlay to match the canvas.
- * @param canvasCssHeight  the rendered canvas's CSS height.
+ * @param cssWidth         the page's intended CSS width (px, number) — the %
+ *                         denominator for the x axis.
+ * @param cssHeight        the page's intended CSS height (px, number) — the %
+ *                         denominator for the y axis.
  * @param onHyperlinkClick IX1 — invoked when a run carrying a resolved
  *                         {@link HyperlinkTarget} is clicked. A hyperlink run's
  *                         span keeps its transparent glyphs (the visible link
@@ -127,7 +151,7 @@ export declare function buildDocxHighlightLayer(layer: HTMLDivElement, runs: Doc
  *                         a 縦中横 span keeps the bare rotate (no regression for
  *                         callers that do not thread a measurer).
  */
-export declare function buildDocxTextLayer(layer: HTMLDivElement, runs: DocxTextRunInfo[], canvasCssWidth: string, canvasCssHeight: string, onHyperlinkClick?: (target: HyperlinkTarget) => void, measureForFont?: (font: string) => (s: string) => number): void;
+export declare function buildDocxTextLayer(layer: HTMLDivElement, runs: DocxTextRunInfo[], cssWidth: number, cssHeight: number, onHyperlinkClick?: (target: HyperlinkTarget) => void, measureForFont?: (font: string) => (s: string) => number): void;
 
 export declare interface CellBorders {
     top: BorderSpec | null;
@@ -312,6 +336,14 @@ declare interface ChartModel {
     title: string | null;
     categories: string[];
     series: ChartSeries[];
+    /**
+     * §21.2.2.227 `<c:varyColors val="1"/>` on a SINGLE-series bar/column chart:
+     * color each data point (bar) from the theme/palette sequence and list one
+     * legend entry per point, matching Office. Set by the shared parser ONLY for
+     * that non-pie, single-series case (pie/doughnut already vary by point via
+     * `chartType` + `dataPointColors`); absent/false otherwise.
+     */
+    varyColors?: boolean | null;
     /** Show data labels on bars / points / slices. */
     showDataLabels: boolean;
     /** Explicit Y-axis minimum (OOXML `<c:valAx><c:min>`). */
@@ -690,8 +722,9 @@ declare interface ChartModel {
  *  core `renderChart` consumes (identical to what pptx/xlsx pass), so a docx
  *  chart draws at the same quality through the same code path. `widthPt`/
  *  `heightPt` are the `<wp:extent>` natural size. An inline chart flows as an
- *  inline box of that size; an anchored chart (§20.4.2.3) is painted at its
- *  absolute page box by `renderAnchorImages` — both via `renderChart`. */
+ *  inline box of that size; an anchored chart (§20.4.2.3) is painted via
+ *  `registerAnchorFloats` when it wraps text, or by `renderAnchorImages` for
+ *  wrapNone/no-wrap anchors — all paths use `renderChart`. */
 export declare interface ChartRun {
     chart: ChartModel;
     widthPt: number;
@@ -703,6 +736,39 @@ export declare interface ChartRun {
     anchorYPt?: number;
     anchorXFromMargin?: boolean;
     anchorYFromPara?: boolean;
+    /**
+     * Wrap mode for anchored charts (ECMA-376 §20.4.2.16/.17):
+     *   "square" | "topAndBottom" | "none" | "tight" | "through"
+     * Inline charts and undetermined cases leave this undefined. The renderer
+     * treats "tight" and "through" as "square", matching anchored images.
+     */
+    wrapMode?: string;
+    /** Padding top (pt). Anchor-only (ECMA-376 §20.4.2.16/.17). */
+    distTop?: number;
+    /** Padding bottom (pt). Anchor-only (ECMA-376 §20.4.2.16/.17). */
+    distBottom?: number;
+    /** Padding left (pt). Anchor-only (ECMA-376 §20.4.2.16/.17). */
+    distLeft?: number;
+    /** Padding right (pt). Anchor-only (ECMA-376 §20.4.2.16/.17). */
+    distRight?: number;
+    /** wrapText attribute: "bothSides" | "left" | "right" | "largest". */
+    wrapSide?: string;
+    /**
+     * ECMA-376 §20.4.2.3 `wp:anchor/@allowOverlap`. The parser omits this
+     * field when true, so renderers must read it as `allowOverlap ?? true`.
+     */
+    allowOverlap?: boolean;
+    /** ECMA-376 §20.4.3.1 wp:align horizontal: "left" | "center" | "right" |
+     *  "inside" | "outside". */
+    anchorXAlign?: string | null;
+    /** Vertical equivalent of anchorXAlign: "top" | "center" | "bottom". */
+    anchorYAlign?: string | null;
+    /**
+     * ECMA-376 §20.4.3.2 `<wp:positionH/@relativeFrom>` / §20.4.3.5
+     * `<wp:positionV/@relativeFrom>` — the raw anchor placement containers.
+     */
+    anchorXRelativeFrom?: string | null;
+    anchorYRelativeFrom?: string | null;
 }
 
 declare interface ChartSeries {
@@ -975,12 +1041,20 @@ export declare interface DocParagraph {
     shading?: string | null;
     /** Force a page break before this paragraph (w:pageBreakBefore) */
     pageBreakBefore?: boolean;
-    /** Suppress spacing between adjacent same-style paragraphs (w:contextualSpacing) */
+    /** ECMA-376 §17.3.1.9 `<w:contextualSpacing>` — between adjacent SAME-style
+     *  paragraphs, a toggling paragraph drops its OWN contribution to the
+     *  collapsed inter-paragraph gap (per-side, Word-adjudicated — issue #1015;
+     *  see the renderer's `contextualSpacingAdjust`). */
     contextualSpacing?: boolean;
     /** Keep paragraph on same page as the next paragraph (w:keepNext) */
     keepNext?: boolean;
     /** Keep all lines of this paragraph on the same page (w:keepLines) */
     keepLines?: boolean;
+    /** ECMA-376 §17.3.1.29 + §17.3.2.41 — the paragraph MARK's resolved `w:vanish`
+     *  (hidden text). An inkless paragraph whose mark is vanished collapses to zero
+     *  height in the normal/print view (hidden-text off), the same way the parser
+     *  strips hidden runs; the paginator drops it whole. Absent = mark is visible. */
+    markVanish?: boolean;
     /** Widow/orphan control (w:widowControl). ECMA-376 default is true. */
     widowControl?: boolean;
     /** Paragraph borders (w:pBdr) */
@@ -992,6 +1066,17 @@ export declare interface DocParagraph {
     /** Default font family resolved from the style chain. Used to size empty
      *  paragraphs (no runs) with the intended font's line metrics. */
     defaultFontFamily?: string | null;
+    /** Default East Asian font family resolved from the style chain. Empty /
+     *  anchor-only paragraph marks in East Asian documents use this axis for line
+     *  metrics instead of the ASCII fallback. */
+    defaultFontFamilyEastAsia?: string | null;
+    /** ECMA-376 §17.3.1.29 — the paragraph MARK run's resolved `w:color` (direct
+     *  pPr/rPr → pStyle chain → docDefaults; hex 6 without `#`, lowercased; an
+     *  explicit `auto` surfaces as absent, §17.3.2.6). Word formats a numbering
+     *  marker with the level rPr (§17.9.24) layered over the mark's run
+     *  properties, so the renderer uses this as the marker-color fallback when
+     *  {@link NumberingInfo.color} is absent. */
+    paragraphMarkColor?: string | null;
     /**
      * ECMA-376 §17.3.1.6 `<w:bidi>` — right-to-left paragraph. `true` = RTL,
      * `false` = explicitly LTR, absent = unspecified (inherit). The renderer uses
@@ -1069,6 +1154,17 @@ export declare interface DocSettings {
      *  tab stops generated after all custom stops. `undefined` ⇒ the renderer
      *  uses the spec default of 720 twips (36pt). */
     defaultTabStop?: number;
+    /** §17.15.1.18 `w:characterSpacingControl@w:val` — East Asian punctuation /
+     *  character-spacing control. */
+    characterSpacingControl?: string;
+    /** §17.15.3.1 `w:compat/w:useFELayout` — Far East layout compatibility. */
+    useFeLayout?: boolean;
+    /** §17.15.3.1 `w:compat/w:balanceSingleByteDoubleByteWidth` — balance
+     *  single-byte and double-byte widths for East Asian layout. */
+    balanceSingleByteDoubleByteWidth?: boolean;
+    /** §17.15.3.1 `w:compat/w:adjustLineHeightInTable` — apply the section
+     *  document-grid line pitch to text in table cells. */
+    adjustLineHeightInTable?: boolean;
 }
 
 export declare interface DocTable {
@@ -1145,11 +1241,20 @@ export declare interface DocTableCell {
 
 export declare interface DocTableRow {
     cells: DocTableCell[];
+    /** ECMA-376 §17.4.15 `<w:gridBefore>` — shared table-grid columns skipped
+     *  before placing this row's first real cell. Omitted/zero means none. */
+    gridBefore?: number;
+    /** ECMA-376 §17.4.14 `<w:gridAfter>` — shared table-grid columns skipped
+     *  after this row's last real cell. Omitted/zero means none. */
+    gridAfter?: number;
     rowHeight: number | null;
     /** ECMA-376 §17.4.80 hRule. "auto" (default) = informational; "atLeast" =
      *  lower bound; "exact" = fixed clip. */
     rowHeightRule: 'auto' | 'atLeast' | 'exact' | string;
     isHeader: boolean;
+    /** ECMA-376 §17.4.6 `<w:cantSplit>` — when true, the row must not be split
+     *  across page boundaries. Omitted/false rows may split at page boundaries. */
+    cantSplit?: boolean;
 }
 
 export declare class DocxDocument {
@@ -1333,6 +1438,16 @@ export declare interface DocxDocumentModel {
      * entry is absent or classified as "auto".
      */
     fontFamilyClasses?: Record<string, string>;
+    /**
+     * ECMA-376 §17.8.3.29 — per-font pitch from `word/fontTable.xml`
+     * (`<w:pitch>`, ST_Pitch §17.18.66): font name → "fixed" | "variable" |
+     * "default". Present only for fonts that declare `<w:pitch>`. The renderer
+     * pairs this with {@link fontFamilyClasses}: a `family="modern"` face is
+     * treated as monospace ONLY when its pitch is "fixed"; "variable" /
+     * "default" / absent fall through to name-pattern / CJK-sans classification
+     * (§17.8.3.10 `family` classifies the design, not the pitch — issue #855).
+     */
+    fontFamilyPitches?: Record<string, string>;
     /** ECMA-376 §17.8.3.3-.6 — embedded fonts from `word/fontTable.xml`, resolved
      *  to their `.odttf` part paths + fontKey. The viewer de-obfuscates (§17.8.1)
      *  and registers each as a FontFace before pagination so text measures/draws
@@ -1635,6 +1750,12 @@ export declare class DocxScrollViewer implements ZoomableViewer {
      * {@link DocxDocument.getBookmarkPage} (ECMA-376 §17.16.23) and scrolls there
      * with {@link scrollToPage}. An anchor naming no known bookmark is a safe no-op
      * rather than a scroll to a guessed page.
+     *
+     * IX1 — returns `undefined` when `enableHyperlinks` is `false`, the single gate
+     * that disables hyperlink interactivity: {@link buildDocxTextLayer} treats a
+     * missing handler as "render link runs like plain runs", so no hit region,
+     * cursor, tooltip, listener, or navigation is wired (a custom
+     * `onHyperlinkClick` is suppressed too).
      */
     private _hyperlinkHandler;
     /** A width-measurer primed with a run's `font` — used ONLY to clamp a §17.3.2.10
@@ -1643,6 +1764,10 @@ export declare class DocxScrollViewer implements ZoomableViewer {
      *  unavailable so the caller still gets a callable (the overlay then sees scale
      *  1 and leaves the span un-clamped). */
     private _measureForFont;
+    /** A canvas's intended CSS box in px (the % denominators the overlay builders
+     *  expect). Reads the inline `style.width`/`height` set by the render path,
+     *  falling back to the backing-store size when unset; tolerates the `px` suffix. */
+    private _canvasCssPx;
     /** Route an async render failure to `onError`, or `console.error` when none is
      *  set (so failures are never fully silent), and never after teardown. */
     private _reportRenderError;
@@ -1939,6 +2064,13 @@ export declare interface DocxScrollViewerOptions extends Omit<RenderPageOptions,
      *  new tab via core `openExternalHyperlink` (sanitised, noopener,noreferrer);
      *  internal → jump to the page whose text contains the bookmark (best-effort). */
     onHyperlinkClick?: (target: HyperlinkTarget) => void;
+    /** IX1 — master switch for hyperlink interactivity. Default `true`. When
+     *  `false`, the hyperlink machinery is not wired at all: no overlay hit region
+     *  is installed for link runs, so there is no pointer cursor, no title tooltip,
+     *  no default navigation (external new-tab / internal bookmark jump), and
+     *  `onHyperlinkClick` is never called. Links still render exactly as authored
+     *  but are inert, like plain text. */
+    enableHyperlinks?: boolean;
     /** Error callback. When set, `load()` invokes it and resolves (otherwise the
      *  error is rethrown — shared viewer error contract). It ALSO fires for async
      *  per-slot render failures (both main `renderPage` and worker
@@ -2037,12 +2169,22 @@ export declare interface DocxTextRun {
     /** ECMA-376 §17.3.2.20 `<w:lang w:bidi>` — complex-script (RTL) language tag,
      *  lower-cased (e.g. "ar-sa", "ae-ar"). Drives Word's AN digit ordering. */
     langBidi?: string;
+    /** ECMA-376 §17.3.2.34 `<w:snapToGrid>` — false opts this run out of the
+     *  section character grid; absent inherits participation. */
+    snapToGrid?: boolean;
     /** ECMA-376 §17.3.2.35 `<w:spacing w:val>` — character-spacing adjustment in
      *  POINTS (signed): the extra pitch added after each character before the next
      *  is rendered. The renderer feeds it to `ctx.letterSpacing` on BOTH the
      *  measure and paint passes so line breaking / pagination stay consistent.
      *  Absent ⇒ no extra pitch. */
     charSpacing?: number;
+    /** ECMA-376 §17.3.2.14 `<w:fitText>` — manual run-width target in TWIPS
+     *  (`w:val`, 1/20 pt) plus the optional `w:id` that links consecutive runs
+     *  into one region. The arbitrary-precision XSD integer id is serialized as a
+     *  string; numeric synthetic inputs remain supported for layout tests and
+     *  direct model construction. An id-less run is always standalone. */
+    fitTextVal?: number;
+    fitTextId?: string | number;
     /** ECMA-376 §17.3.2.43 `<w:w w:val>` — horizontal text scale as a FRACTION of
      *  normal character width (0.67 = 67%, 2.0 = 200%). Stretches each glyph's
      *  width, not the gap between glyphs. Absent ⇒ 100%. */
@@ -2096,6 +2238,9 @@ export declare interface DocxTextRunInfo {
     fontSize: number;
     /** CSS `font` shorthand used for canvas drawing (e.g. `"bold 16px Arial"`). */
     font: string;
+    /** Uniform per-code-point pitch in CSS px used to draw a horizontal run.
+     *  Absent when the pitch is zero or the run uses vertical / 縦中横 paint. */
+    letterSpacingPx?: number;
     /** ECMA-376 §17.6.20 (tbRl) — when the page is vertical the canvas is the
      *  physical landscape page rotated +90° at paint, so this run's `x`/`y` are the
      *  PHYSICAL top-left the overlay span must sit at, and `transform` is the CSS
@@ -2305,6 +2450,11 @@ export declare class DocxViewer implements ZoomableViewer {
     /** Draw the find-highlight boxes for the current page from its runs. Clears
      *  the overlay when there is no active find. */
     private _buildHighlightLayer;
+    /** The canvas's intended CSS box in px (the % denominators the overlay builders
+     *  expect). Reads the inline `style.width`/`height` set by the render path
+     *  (which mirror the render's logical size), falling back to the backing-store
+     *  dimensions when unset. Parsing tolerates the trailing `px`. */
+    private _canvasCssPx;
     /** A width-measurer primed with `font`, backed by a private 1×1 canvas so it
      *  never disturbs the visible canvas's context state. */
     private _measureForFont;
@@ -2323,6 +2473,12 @@ export declare class DocxViewer implements ZoomableViewer {
      * {@link DocxDocument.getBookmarkPage} (ECMA-376 §17.16.23) and jumps there
      * with {@link goToPage}. An anchor naming no known bookmark is a safe no-op
      * rather than a jump to a guessed page.
+     *
+     * IX1 — returns `undefined` when `enableHyperlinks` is `false`, the single gate
+     * that disables hyperlink interactivity: {@link buildDocxTextLayer} treats a
+     * missing handler as "render link runs like plain runs", so no hit region,
+     * cursor, tooltip, listener, or navigation is wired (a custom
+     * `onHyperlinkClick` is suppressed too).
      */
     private _hyperlinkHandler;
 }
@@ -2352,6 +2508,15 @@ export declare interface DocxViewerOptions extends RenderPageOptions, LoadOption
      *  new tab via core `openExternalHyperlink` (sanitised, noopener,noreferrer);
      *  internal → jump to the page whose text contains the bookmark (best-effort). */
     onHyperlinkClick?: (target: HyperlinkTarget) => void;
+    /** IX1 — master switch for hyperlink interactivity. Default `true`. When
+     *  `false`, the hyperlink machinery is not wired at all: no overlay hit region
+     *  is installed for link runs, so there is no pointer cursor, no title tooltip,
+     *  no default navigation (external new-tab / internal bookmark jump), and
+     *  `onHyperlinkClick` is never called. Links still render exactly as authored
+     *  (their colour/underline are painted on the canvas) but are inert, like plain
+     *  text. Set it to disable clickable links entirely — e.g. in a preview where
+     *  navigation must not leave the current view. */
+    enableHyperlinks?: boolean;
     /** Called on parse or render errors. */
     onError?: (err: Error) => void;
 }
@@ -2583,6 +2748,10 @@ export declare interface ImageRun {
     } | null;
     widthPt: number;
     heightPt: number;
+    /** Effective DrawingML transform for grouped pictures. */
+    rotation?: number;
+    flipH?: boolean;
+    flipV?: boolean;
     /** true = wp:anchor (absolute positioned), false/undefined = wp:inline (flows with text) */
     anchor?: boolean;
     /** X offset in pt (anchor only) */
@@ -3072,6 +3241,19 @@ export declare interface NumberingInfo {
      *  this family. Absent ⇒ the renderer falls back to
      *  {@link NumberingInfo.fontFamily}. */
     fontFamilyEastAsia?: string | null;
+    /** ECMA-376 §17.9.24 — the numbering level rPr's `w:color` (hex 6 without
+     *  `#`, lowercased). Colors the marker glyph only, never the paragraph's
+     *  runs. Absent ⇒ the renderer falls back to
+     *  {@link DocParagraph.paragraphMarkColor} (§17.3.1.29 — Word layers the
+     *  level rPr over the paragraph mark's run properties) and finally to its
+     *  default ink. An explicit `w:val="auto"` is absent here + {@link colorAuto}. */
+    color?: string | null;
+    /** ECMA-376 §17.3.2.6 / ST_HexColorAuto (§17.18.39) — true when the level
+     *  rPr carries an EXPLICIT `w:color w:val="auto"`. Auto names no concrete
+     *  color but is not "unset": it breaks the paragraph-mark fallback, so the
+     *  marker draws the automatic (default) ink instead of
+     *  {@link DocParagraph.paragraphMarkColor}. */
+    colorAuto?: boolean;
     /** ECMA-376 §17.9.9/§17.9.20 — when the level uses a `<w:lvlPicBulletId>`,
      *  the marker is this image (zip path, e.g. `word/media/image1.gif`), drawn in
      *  place of {@link NumberingInfo.text}. Absent ⇒ ordinary text/glyph marker. */
@@ -3298,6 +3480,10 @@ export declare interface RubyAnnotation {
     text: string;
     /** Annotation font size in pt. Word stores this as half-points in `<w:hps>`. */
     fontSizePt: number;
+    /** Distance “between the phonetic guide base text and the phonetic guide
+     *  text” in pt. Word stores this as half-points in `<w:hpsRaise>`
+     *  (ECMA-376 §17.3.3.12). */
+    hpsRaisePt?: number;
 }
 
 export declare interface RunRevision {
@@ -3497,7 +3683,7 @@ export declare interface ShapeRun {
     groupHeightPt?: number | null;
     /** Draw behind text when true (wp:anchor behindDoc="1"). */
     behindDoc?: boolean;
-    /** Document-order index within a group; lower values render first. */
+    /** ECMA-376 §20.4.2.3 `wp:anchor/@relativeHeight`: lower values render first. */
     zOrder: number;
     /** Normalized [0,1] custom-geometry sub-paths. Empty when `presetGeometry`
      *  is set; the renderer chooses between buildCustomPath and buildShapePath. */
@@ -3505,13 +3691,17 @@ export declare interface ShapeRun {
     /** OOXML <a:prstGeom prst> name (e.g. "rect", "ellipse", "rtTriangle").
      *  When set the renderer calls core's buildShapePath with `adjValues`. */
     presetGeometry?: string | null;
-    /** Up to four <a:gd name="adj{n}"> values from prstGeom/avLst (0–100000). */
-    adjValues?: number[];
+    /** <a:gd name="adj{n}"> values from prstGeom/avLst in adj1..adj8 order.
+     *  `null` preserves omitted named guides so the preset engine can use the
+     *  geometry's default for that index. */
+    adjValues?: Array<number | null>;
     fill: ShapeFill | null;
     stroke: string | null;
     strokeWidth?: number;
     /** `<a:ln><a:prstDash val>` — ECMA-376 §20.1.8.48. Absent = solid. */
     strokeDash?: string | null;
+    /** Normalized line cap: `butt` | `round` | `square`. */
+    strokeCap?: CanvasLineCap | null;
     /** `<a:ln><a:headEnd>` line-start decoration (ECMA-376 §20.1.8.3). */
     headEnd?: LineEnd | null;
     /** `<a:ln><a:tailEnd>` line-end decoration (ECMA-376 §20.1.8.3). */
@@ -3556,6 +3746,14 @@ export declare interface ShapeRun {
     textInsetT?: number;
     textInsetR?: number;
     textInsetB?: number;
+    /** ECMA-376 §20.1.10.83 ST_TextVerticalType — the text-body flow direction from
+     *  `<wps:bodyPr vert>` / `<a:bodyPr vert>`. Recognised vertical values:
+     *  "vert" (all glyphs 90° CW, chars T→B, lines R→L), "vert270" (all glyphs 270°
+     *  CW = 90° CCW, chars B→T, lines L→R), and "eaVert" (East-Asian upright: CJK
+     *  stands upright, non-EA rotated 90°, chars T→B, lines R→L). "horz"/absent ⇒
+     *  horizontal (unchanged). Unrecognised values ("mongolianVert", "wordArtVert",
+     *  …) fall back to horizontal until implemented. */
+    textVert?: string | null;
     /** ECMA-376 Part 4 §19.1.2.23 `<v:textpath>` — WordArt text laid on the
      *  shape path (a text watermark). When set the renderer draws this string,
      *  scaled to fill the box (`fitshape`), rotated by {@link ShapeRun.rotation},
@@ -3581,6 +3779,8 @@ export declare interface ShapeText {
      *  (image blocks / legacy single-format paragraphs). Absent for image-only
      *  paragraphs. */
     runs?: ShapeTextRun[];
+    /** ECMA-376 §17.9 paragraph numbering for text-box paragraphs. */
+    numbering?: NumberingInfo | null;
     alignment: string;
     /** ECMA-376 §17.3.1.33 `<w:spacing w:before>` of this text-box paragraph, in
      *  pt — reserved ABOVE the paragraph inside the box. Absent/0 ⇒ no offset. */
@@ -3618,6 +3818,19 @@ export declare interface ShapeText {
      *  base direction for the UAX#9 reordering pass (the body renderer reads the
      *  identical field). */
     bidi?: boolean;
+    /** ECMA-376 §17.3.1.9 `<w:contextualSpacing>` — resolved through the style
+     *  chain in the parser. When set, this text-box paragraph drops its OWN
+     *  contribution to the collapsed gap against an ADJACENT paragraph that
+     *  shares its {@link ShapeText.styleId} (per-side, Word-adjudicated — issue
+     *  #1015; identical to {@link DocParagraph.contextualSpacing} via the
+     *  renderer's `contextualSpacingAdjust`). Absent ⇒ no suppression. */
+    contextualSpacing?: boolean;
+    /** Resolved paragraph style id of this text-box paragraph — the explicit
+     *  `<w:pStyle>`, else the document default paragraph style, else "Normal" (the
+     *  same stable id {@link DocParagraph.styleId} carries). Paired with
+     *  {@link ShapeText.contextualSpacing} to group adjacent same-style paragraphs
+     *  for §17.3.1.9. */
+    styleId?: string | null;
     /** Zip path of an inline image inside this text-box paragraph
      *  (`<w:drawing><wp:inline><a:blip r:embed>`), e.g. `word/media/image1.emf`.
      *  Absent for a text-only paragraph. */
@@ -3650,6 +3863,8 @@ export declare interface ShapeTextRun {
     fontFamilyEastAsia?: string | null;
     bold?: boolean;
     italic?: boolean;
+    /** ECMA-376 §17.3.3.25 ruby annotation (furigana) for text-box runs. */
+    ruby?: RubyAnnotation | null;
 }
 
 export declare interface TableBorders {