@beyondwork/docx-react-component 1.0.55 → 1.0.57

package/src/model/canonical-document.ts

@@ -36,7 +36,7 @@ const CANONICAL_DOCUMENT_TOP_LEVEL_KEYS = [
   "diagnostics",
 ] as const;
 
-const CANONICAL_DOCUMENT_OPTIONAL_KEYS = ["subParts", "fieldRegistry"] as const;
+const CANONICAL_DOCUMENT_OPTIONAL_KEYS = ["subParts", "fieldRegistry", "fontTable"] as const;
 
 const ID_PATTERNS = {
   styleId: /^[A-Za-z_][A-Za-z0-9._-]{0,127}$/,
@@ -72,8 +72,11 @@ export interface CanonicalDocument {
   subParts?: SubPartsCatalog;
   /** Package-backed field registry for supported field families. */
   fieldRegistry?: FieldRegistry;
+  /** Parsed fontTable.xml. Undefined when the package has no fontTable part. */
+  fontTable?: CanonicalFontTable;
 }
 
+
 export interface DocumentMetadata {
   title?: string;
   subject?: string;
@@ -89,11 +92,34 @@ export interface StylesCatalog {
   paragraphs: Record<string, ParagraphStyleDefinition>;
   characters: Record<string, CharacterStyleDefinition>;
   tables: Record<string, TableStyleDefinition>;
+  /**
+   * `w:type="numbering"` styles — preserve-only. Word emits these for
+   * style-linked list families (List Bullet, List Number). Canonical
+   * consumers do not apply numbering via these styles; they survive
+   * only for round-trip fidelity.
+   */
+  numberingStyles?: Record<string, NumberingStyleDefinition>;
   latentStyles?: Record<string, LatentStyleDefinition>;
   fromPackage?: boolean;
   docDefaults?: DocumentDefaults;
 }
 
+/** A `<w:style w:type="numbering">` entry. Preserve-only. */
+export interface NumberingStyleDefinition {
+  styleId: string;
+  displayName: string;
+  kind: "numbering";
+  isDefault: boolean;
+  basedOn?: string;
+  aliases?: string[];
+  /**
+   * The `<w:numId w:val="..."/>` inside the `<w:pPr><w:numPr>` subtree,
+   * when present. Consumers that later resolve numbering-type styles to
+   * numbering instances (Lane 3a) will use this.
+   */
+  numberingInstanceId?: string;
+}
+
 export interface ParagraphStyleDefinition {
   styleId: string;
   basedOn?: string;
@@ -101,6 +127,17 @@ export interface ParagraphStyleDefinition {
   outlineLevel?: number;
   numbering?: ParagraphStyleNumberingReference;
   displayName: string;
+  /**
+   * Alternate display names parsed from `<w:aliases w:val="A,B"/>`
+   * (ECMA-376 §17.7.4.2). Comma-separated in source; stored as array.
+   */
+  aliases?: string[];
+  /**
+   * `<w:autoRedefine/>` — when true, Word re-records paragraph direct
+   * formatting into the style definition as the user types (ECMA-376
+   * §17.7.4.3). Round-trip preservation only; no render effect.
+   */
+  autoRedefine?: boolean;
   kind: "paragraph";
   isDefault: boolean;
   paragraphProperties?: CanonicalParagraphFormatting;
@@ -124,6 +161,8 @@ export interface CharacterStyleDefinition {
   styleId: string;
   basedOn?: string;
   displayName: string;
+  /** See `ParagraphStyleDefinition.aliases`. */
+  aliases?: string[];
   kind: "character";
   isDefault: boolean;
   runProperties?: CanonicalRunFormatting;
@@ -139,6 +178,8 @@ export interface TableStyleDefinition {
   styleId: string;
   basedOn?: string;
   displayName: string;
+  /** See `ParagraphStyleDefinition.aliases`. */
+  aliases?: string[];
   kind: "table";
   isDefault: boolean;
   formatting?: TableStyleFormatting;
@@ -157,6 +198,42 @@ export interface LatentStyleDefinition {
 export interface NumberingCatalog {
   abstractDefinitions: Record<string, AbstractNumberingDefinition>;
   instances: Record<string, NumberingInstance>;
+  /**
+   * `<w:numPicBullet>` media-catalog entries keyed by `w:numPicBulletId`.
+   * Each entry preserves the raw drawing/pic XML plus a resolved media
+   * pointer when the bullet references a relationship-backed image.
+   * Consumed by numbering-prefix when `NumberingLevelDefinition.picBulletId`
+   * is set (ECMA-376 §17.9.19). Rendering is Lane 6 territory.
+   */
+  numPicBullets?: Record<string, NumPicBullet>;
+}
+
+/**
+ * A single `<w:numPicBullet>` entry — picture-bullet image catalog.
+ *
+ * OOXML allows either a drawingML `<w:drawing>` (modern) or a VML `<w:pict>`
+ * (legacy) inside the element. We preserve the raw XML for a byte-identical
+ * round-trip and, when possible, resolve the `r:embed` / `r:id` to a media
+ * catalog entry so the renderer can look up the bitmap without re-parsing.
+ */
+export interface NumPicBullet {
+  /** `w:numPicBulletId` attribute value — the lookup key. */
+  numPicBulletId: string;
+  /** Verbatim XML for the `<w:numPicBullet>` element. */
+  rawXml: string;
+  /**
+   * Resolved media-catalog media id when the bullet's inner image references
+   * a relationship we could resolve at parse time. Undefined when the
+   * bullet uses an unresolved blipRef or a VML path.
+   */
+  mediaId?: string;
+  /**
+   * Bullet cell extent in EMU (English Metric Units) when parsed from the
+   * drawing's `wp:extent` — lets the renderer size the bullet image without
+   * round-tripping through a new measurement pass. Undefined for VML paths.
+   */
+  widthEmu?: number;
+  heightEmu?: number;
 }
 
 export interface AbstractNumberingDefinition {
@@ -188,6 +265,12 @@ export interface NumberingLevelDefinition {
   paragraphGeometry?: NumberingLevelParagraphGeometry;
   runProperties?: CanonicalRunFormatting;
   restartAfterLevel?: number;
+  /**
+   * `<w:lvlPicBulletId w:val="N"/>` reference — picks the matching entry
+   * from `NumberingCatalog.numPicBullets`. When set, the marker renders as
+   * an inline image instead of a text glyph. ECMA-376 §17.9.12.
+   */
+  picBulletId?: string;
 }
 
 export interface NumberingLevelOverrideDefinition {
@@ -257,9 +340,28 @@ export interface FootnoteDefinition {
   blocks: BlockNode[];
 }
 
+/**
+ * Separator and continuation-separator content parsed from the special
+ * footnote/endnote entries with `w:type="separator"` and
+ * `w:type="continuationSeparator"`.
+ *
+ * Content is stored as raw inner XML (the run children of the <w:p>) so
+ * Lane 3a page-chrome can render the horizontal rule without re-parsing.
+ */
+export interface FootnoteSeparators {
+  /** Raw XML of the <w:r> children inside the separator paragraph. */
+  separatorContent?: string;
+  /** Raw XML of the <w:r> children inside the continuationSeparator paragraph. */
+  continuationSeparatorContent?: string;
+}
+
 export interface FootnoteCollection {
   footnotes: Record<string, FootnoteDefinition>;
   endnotes: Record<string, FootnoteDefinition>;
+  /** Separator content parsed from footnotes.xml special entries. */
+  footnoteSeparators?: FootnoteSeparators;
+  /** Separator content parsed from endnotes.xml special entries. */
+  endnoteSeparators?: FootnoteSeparators;
 }
 
 export interface ThemeColorScheme {
@@ -336,6 +438,12 @@ export interface DocumentSettings {
    * appears in the re-emitted output.
    */
   unmodelledSettingsChildren?: string[];
+  /**
+   * Parsed from `<w:clrSchemeMapping>` in settings.xml. Maps document-level
+   * color style slot names to physical clrScheme slots. Absent when the
+   * element was not present in the document (identity mapping applies).
+   */
+  clrSchemeMapping?: ClrSchemeMapping;
 }
 
 export interface SubPartsCatalog {
@@ -346,6 +454,12 @@ export interface SubPartsCatalog {
   finalSectionProperties?: SectionProperties;
   resolvedTheme?: ResolvedTheme;
   settings?: DocumentSettings;
+  /**
+   * Fully materialized theme for runtime resolution — combines theme1.xml
+   * color/font scheme with the clrSchemeMapping from settings.xml.
+   * Available after CO1 load wiring lands in docx-session.ts.
+   */
+  canonicalTheme?: CanonicalTheme;
 }
 
 export interface ResolvedTheme {
@@ -354,6 +468,55 @@ export interface ResolvedTheme {
   minorFont?: string;
 }
 
+/**
+ * Document-level color style slot name from `<w:clrSchemeMapping>`.
+ * These are the attribute names on the XML element (e.g. `w:bg1`).
+ */
+export type ClrSchemeMappingSlot =
+  | "bg1" | "bg2" | "t1" | "t2"
+  | "accent1" | "accent2" | "accent3" | "accent4" | "accent5" | "accent6"
+  | "hlink" | "followedHyperlink";
+
+/**
+ * Physical slot name in the `<a:clrScheme>` color scheme (theme1.xml).
+ */
+export type ThemeColorSlot =
+  | "dk1" | "lt1" | "dk2" | "lt2"
+  | "accent1" | "accent2" | "accent3" | "accent4" | "accent5" | "accent6"
+  | "hlink" | "folHlink";
+
+/**
+ * Re-maps document-level color style slot names to physical `clrScheme` slot
+ * names. Parsed from `<w:clrSchemeMapping>` in settings.xml.
+ *
+ * Keys are the attribute local names (e.g. "bg1", "t1", "accent1").
+ * Values are the target clrScheme slot (e.g. "lt1", "dk1").
+ *
+ * An absent key means identity mapping — the slot resolves to its own name.
+ */
+export type ClrSchemeMapping = Partial<Record<ClrSchemeMappingSlot, ThemeColorSlot>>;
+
+/**
+ * Fully materialized theme for runtime resolution. Combines the color scheme,
+ * optional font scheme, and the clrSchemeMapping from settings.xml.
+ *
+ * `themeHash` and `clrMapHash` are stable content-derived strings used as
+ * cache keys per CLAUDE.md §3 (cache keys must be structural, not revisionToken).
+ *
+ * Populated during document load when theme1.xml is present. Absent in
+ * documents with no theme part.
+ */
+export interface CanonicalTheme {
+  clrScheme: ThemeColorScheme;
+  fontScheme?: ThemeFontScheme;
+  /** Resolved clrSchemeMapping: styleSlot → clrScheme slot name. Empty = identity. */
+  clrMap: ClrSchemeMapping;
+  /** Stable content hash of clrScheme.colors (sorted key:value pairs). */
+  themeHash: string;
+  /** Stable content hash of clrMap (sorted key:value pairs). */
+  clrMapHash: string;
+}
+
 // ---- Inline footnote reference node ----
 
 export interface FootnoteRefNode {
@@ -391,7 +554,8 @@ export type DocumentNode =
   | SmartArtPreviewNode
   | ShapeNode
   | WordArtNode
-  | VmlShapeNode;
+  | VmlShapeNode
+  | DrawingFrameNode;
 
 export interface DocumentRootNode {
   type: "doc";
@@ -554,6 +718,32 @@ export interface DocumentDefaults {
   run?: CanonicalRunFormatting;
 }
 
+/** Materialized `fontTable.xml` — one entry per `<w:font>` element. */
+export interface CanonicalFontTable {
+  fonts: Record<string, CanonicalFontEntry>;
+}
+
+/** Metadata for a single `<w:font>` element from fontTable.xml. */
+export interface CanonicalFontEntry {
+  /** `w:name` attribute — the key used in rFonts references. */
+  name: string;
+  /**
+   * `w:family` value. Qualitative category per ECMA-376 §17.8.3.10.
+   * "roman" = proportional serif, "swiss" = proportional sans-serif,
+   * "modern" = fixed-pitch, "script" = handwriting, "decorative" = display.
+   */
+  family?: "roman" | "swiss" | "modern" | "script" | "decorative";
+  /** `w:pitch` value — "fixed" maps to monospace metrics. */
+  pitch?: "fixed" | "variable" | "default";
+  /**
+   * Windows charset code from `w:charset w:val`.
+   * 2 = Symbol font (charset override required for correct glyph mapping).
+   */
+  charset?: number;
+  /** `w:altName` — substitution name when the primary font is unavailable. */
+  altName?: string;
+}
+
 export interface ParagraphNode {
   type: "paragraph";
   styleId?: string;
@@ -691,12 +881,25 @@ export interface TableStyleFormatting {
     shading?: CellShading;
     verticalAlign?: "top" | "center" | "bottom";
   };
+  /**
+   * `<w:pPr>` directly inside the table style body — applies to every
+   * cell paragraph by default. Conditional-region pPr (inside
+   * `<w:tblStylePr>`) is not captured here; see Lane 3a follow-up.
+   */
+  paragraphProperties?: CanonicalParagraphFormatting;
+  /**
+   * `<w:rPr>` directly inside the table style body — applies to every
+   * run in every cell paragraph by default.
+   */
+  runProperties?: CanonicalRunFormatting;
 }
 
 export interface TableNode {
   type: "table";
   styleId?: string;
+  /** @deprecated Use `unknownPropertyChildren`. Kept for snapshot back-compat. */
   propertiesXml?: string;
+  unknownPropertyChildren?: UnknownPropertyChild[];
   gridColumns: number[];
   rows: TableRowNode[];
   width?: TableWidth;
@@ -715,7 +918,9 @@ export interface TableNode {
 
 export interface TableRowNode {
   type: "table_row";
+  /** @deprecated Use `unknownPropertyChildren`. Kept for snapshot back-compat. */
   propertiesXml?: string;
+  unknownPropertyChildren?: UnknownPropertyChild[];
   cells: TableCellNode[];
   gridBefore?: number;
   widthBefore?: TableWidth;
@@ -731,7 +936,9 @@ export interface TableRowNode {
 
 export interface TableCellNode {
   type: "table_cell";
+  /** @deprecated Use `unknownPropertyChildren`. Kept for snapshot back-compat. */
   propertiesXml?: string;
+  unknownPropertyChildren?: UnknownPropertyChild[];
   gridSpan?: number;
   verticalMerge?: "restart" | "continue";
   children: BlockNode[];
@@ -893,6 +1100,8 @@ export interface FieldRegistryEntry {
   paragraphIndex: number;
   /** Runtime refresh status. */
   refreshStatus: FieldRefreshStatus;
+  /** Parsed field switches carried from FieldNode.switches. Present only for REF/PAGEREF/NOTEREF/TOC entries with recognized switches. */
+  switches?: FieldNode["switches"];
 }
 
 /**
@@ -957,6 +1166,10 @@ export interface SectionProperties {
   footerReferences?: HeaderFooterReference[];
   sectionType?: "continuous" | "nextPage" | "evenPage" | "oddPage" | "nextColumn";
   titlePage?: boolean;
+  /** Per-section footnote configuration (ECMA-376 §17.11.12). Overrides file-level defaults. */
+  footnotePr?: FootnoteProperties;
+  /** Per-section endnote configuration (ECMA-376 §17.11.4). Overrides file-level defaults. */
+  endnotePr?: EndnoteProperties;
   /**
    * Unmodelled direct children of `<w:sectPr>` captured verbatim for
    * round-trip. Mirrors `CanonicalParagraphFormatting.unknownPropertyChildren`
@@ -968,6 +1181,35 @@ export interface SectionProperties {
   unknownPropertyChildren?: UnknownPropertyChild[];
 }
 
+/**
+ * Per-section footnote numbering + placement configuration.
+ *
+ * `pos` — where footnotes render: `pageBottom` (default), `beneathText`
+ * (immediately after content flow), `sectEnd` (at end of this section),
+ * `docEnd` (at end of document — converts to endnote-like behavior).
+ * `numFmt` — numbering glyph format for the footnote marker.
+ * `numStart` — starting number for the first footnote in the restart scope.
+ * `numRestart` — when to reset the footnote counter: `continuous` (never),
+ * `eachSect` (at each section break), `eachPage` (at every page boundary).
+ *
+ * Defined per ECMA-376 §17.11.11–.18. The same child-element shape serves
+ * both `<w:footnotePr>` (inside sectPr or settings.xml) and its endnote
+ * counterpart; `EndnoteProperties` aliases this shape.
+ */
+export interface FootnoteProperties {
+  pos?: "pageBottom" | "beneathText" | "sectEnd" | "docEnd";
+  numFmt?: "decimal" | "upperRoman" | "lowerRoman" | "upperLetter" | "lowerLetter" | "chicago" | "none";
+  numStart?: number;
+  numRestart?: "continuous" | "eachSect" | "eachPage";
+}
+
+/**
+ * Per-section endnote configuration. Structurally identical to
+ * `FootnoteProperties`; kept as a distinct type so future divergence
+ * (e.g. endnote-only switches) has a home without breaking callers.
+ */
+export type EndnoteProperties = FootnoteProperties;
+
 export interface PageSize {
   width: number;
   height: number;
@@ -1046,7 +1288,8 @@ export type InlineNode =
   | SmartArtPreviewNode
   | ShapeNode
   | WordArtNode
-  | VmlShapeNode;
+  | VmlShapeNode
+  | DrawingFrameNode;
 
 export interface TextNode {
   type: "text";
@@ -1207,6 +1450,97 @@ export interface VmlShapeNode {
   rawXml: string;
 }
 
+export interface AnchorGeometry {
+  display: "inline" | "floating";
+  extent: { widthEmu: number; heightEmu: number };
+  wrapMode: "none" | "square" | "tight" | "through" | "topAndBottom";
+  positionH?: { relativeFrom: string; align?: string; offset?: number };
+  positionV?: { relativeFrom: string; align?: string; offset?: number };
+  distMargins?: { top?: number; bottom?: number; left?: number; right?: number };
+  relativeHeight?: number;
+  behindDoc?: boolean;
+  layoutInCell?: boolean;
+  allowOverlap?: boolean;
+  simplePos?: boolean;
+  docPr?: { id: string; name?: string; descr?: string };
+}
+
+export interface PictureContent {
+  type: "picture";
+  blipRef: string;
+  /** Resolved media catalog ID (e.g. "media:word/media/image1.png"), populated by parse-drawing. */
+  mediaId?: string;
+  /** Absolute package path for media catalog lookup. */
+  packagePartName?: string;
+  srcRect?: { top: number; bottom: number; left: number; right: number };
+  stretch?: boolean;
+  rotation?: number;
+  flipH?: boolean;
+  flipV?: boolean;
+  presetGeom?: string;
+  /** Original w:drawing XML slice, preserved for lossless round-trip serialization. */
+  rawXml?: string;
+}
+
+export interface ShapeContent {
+  type: "shape";
+  geometry?: string;
+  /**
+   * Shape fill — solid, gradient, pattern, or none. srgbClr values on solid +
+   * gradient stops + pattern fg/bg are normalized to uppercase hex. schemeClr
+   * tokens are preserved as-is for CO1 theme-color cascade resolution.
+   *
+   * Gradient direction is linear (angle in 60000ths of degree) or path-based
+   * (circle|rect|shape). Pattern uses the raw OOXML `prst` preset token.
+   */
+  fill?:
+    | { kind: "solid"; color: string; colorType: "srgbClr" | "schemeClr" }
+    | { kind: "none" }
+    | {
+        kind: "gradient";
+        stops: Array<{ pos: number; color: string; colorType: "srgbClr" | "schemeClr" }>;
+        direction:
+          | { kind: "linear"; angle: number; scaled?: boolean }
+          | { kind: "path"; path: "circle" | "rect" | "shape" };
+        rotWithShape?: boolean;
+      }
+    | {
+        kind: "pattern";
+        preset: string;
+        fg?: { color: string; colorType: "srgbClr" | "schemeClr" };
+        bg?: { color: string; colorType: "srgbClr" | "schemeClr" };
+      };
+  line?: { color?: string; widthEmu?: number; noLine?: boolean };
+  /** True when the shape's geometry + txbxContent presence make it a text box. */
+  isTextBox?: boolean;
+  /** Raw w:txbxContent XML, preserved for serialization + lossless round-trip. */
+  txbxContentXml?: string;
+  /**
+   * Parsed block-level structure from `w:txbxContent`, populated when a
+   * `blockParser` callback is supplied during parse (CO4 F3.3).
+   *
+   * Type is deliberately structural (`{ type: string; ... }`) rather than
+   * canonical `BlockNode[]` because the recursion stops at the parse layer
+   * before the style + numbering normalization pass that converts
+   * `ParsedBlockNode` → canonical `BlockNode`. Consumers that need the fully
+   * normalized form run normalization on this subtree explicitly. Testing
+   * that `txbxBlocks.length > 0` proves the recursion executed.
+   */
+  txbxBlocks?: ReadonlyArray<{ type: string; [key: string]: unknown }>;
+  rawXml: string;
+}
+
+export interface DrawingFrameNode {
+  type: "drawing_frame";
+  anchor: AnchorGeometry;
+  content:
+    | PictureContent
+    | ShapeContent
+    | { type: "chart_preview"; rawXml: string }
+    | { type: "smartart_preview"; rawXml: string }
+    | { type: "opaque"; rawXml: string };
+}
+
 export interface OpaqueBlockNode {
   type: "opaque_block";
   fragmentId: string;
@@ -1865,6 +2199,71 @@ function validateDocumentNode(
     case "vml_shape":
       expectString(record.rawXml, `${path}.rawXml`, issues);
       return;
+    case "drawing_frame": {
+      const anchor = asPlainObject(record.anchor, `${path}.anchor`, issues);
+      const content = asPlainObject(record.content, `${path}.content`, issues);
+      if (anchor) {
+        const extent = asPlainObject(anchor.extent, `${path}.anchor.extent`, issues);
+        if (anchor.display !== "inline" && anchor.display !== "floating") {
+          issues.push({
+            path: `${path}.anchor.display`,
+            message: "anchor.display must be 'inline' or 'floating'.",
+          });
+        }
+        if (
+          anchor.wrapMode !== "none" &&
+          anchor.wrapMode !== "square" &&
+          anchor.wrapMode !== "tight" &&
+          anchor.wrapMode !== "through" &&
+          anchor.wrapMode !== "topAndBottom"
+        ) {
+          issues.push({
+            path: `${path}.anchor.wrapMode`,
+            message: "anchor.wrapMode must be one of none, square, tight, through, or topAndBottom.",
+          });
+        }
+        if (extent) {
+          if (typeof extent.widthEmu !== "number") {
+            issues.push({
+              path: `${path}.anchor.extent.widthEmu`,
+              message: "anchor.extent.widthEmu must be a number.",
+            });
+          }
+          if (typeof extent.heightEmu !== "number") {
+            issues.push({
+              path: `${path}.anchor.extent.heightEmu`,
+              message: "anchor.extent.heightEmu must be a number.",
+            });
+          }
+        }
+      }
+      if (content) {
+        const contentType = expectString(content.type, `${path}.content.type`, issues);
+        if (
+          contentType !== "picture" &&
+          contentType !== "shape" &&
+          contentType !== "chart_preview" &&
+          contentType !== "smartart_preview" &&
+          contentType !== "opaque"
+        ) {
+          issues.push({
+            path: `${path}.content.type`,
+            message: "drawing_frame.content.type must be picture, shape, chart_preview, smartart_preview, or opaque.",
+          });
+        }
+        if (contentType === "picture") {
+          expectString(content.blipRef, `${path}.content.blipRef`, issues);
+        } else if (
+          contentType === "shape" ||
+          contentType === "chart_preview" ||
+          contentType === "smartart_preview" ||
+          contentType === "opaque"
+        ) {
+          expectString(content.rawXml, `${path}.content.rawXml`, issues);
+        }
+      }
+      return;
+    }
     default:
       issues.push({
         path: `${path}.type`,
@@ -2656,6 +3055,19 @@ function validateDocumentNodeReferences(
         message: "mediaId must reference an existing media catalog item.",
       });
     }
+  } else if (type === "drawing_frame") {
+    const content = asPlainObject(record.content, `${path}.content`, []);
+    if (
+      content &&
+      content.type === "picture" &&
+      typeof content.mediaId === "string" &&
+      !references.mediaIds.has(content.mediaId)
+    ) {
+      issues.push({
+        path: `${path}.content.mediaId`,
+        message: "content.mediaId must reference an existing media catalog item.",
+      });
+    }
   } else if (type === "opaque_inline" || type === "opaque_block") {
     if (typeof record.fragmentId === "string" && !references.fragmentIds.has(record.fragmentId)) {
       issues.push({