@beyondwork/docx-react-component 1.0.103 → 1.0.105

package/src/model/canonical-document.ts

@@ -906,8 +906,8 @@ export interface CanonicalParagraphFormatting {
    * templates for side-by-side "instructional column + body column"
    * paragraphs and for drop-caps.
    *
-   * Added 2026-04-23 per `docs/KNOWN-ISSUES-VISUAL.md §2.3 "w:framePr
-   * 2-column inset text frames"`. Before this type existed, L01's parser
+   * Added 2026-04-23 after the visual issue-register finding on `w:framePr`
+   * 2-column inset text frames. Before this type existed, L01's parser
    * fell through to `OpaqueBlockNode` whenever `<w:pPr>` contained
    * `<w:framePr>`, which hid the paragraph from L04 pagination and L11
    * render. Canonical representation unblocks downstream adoption.
@@ -1472,6 +1472,8 @@ export interface FieldRegistryEntry {
   readonly displayText: string;
   /** Paragraph index in document order where this field appears. */
   readonly paragraphIndex: number;
+  /** Stable story key for the story that owns this field instance. */
+  readonly storyKey?: string;
   /** Runtime refresh status. */
   readonly refreshStatus: FieldRefreshStatus;
   /** Parsed field switches carried from FieldNode.switches. Present only for REF/PAGEREF/NOTEREF/TOC entries with recognized switches. */
@@ -1846,6 +1848,25 @@ export interface OpaqueInlineNode {
 
 // ---- Complex rendering inline nodes (read-only previews) ----
 
+export type PreserveOnlyObjectFallbackHint =
+  | "drawing-inline"
+  | "drawing-floating"
+  | "chart"
+  | "smartart"
+  | "shape"
+  | "wordart"
+  | "vml-shape"
+  | "ole-object"
+  | "opaque-object";
+
+export interface PreserveOnlyObjectSizing {
+  readonly sourceId?: string;
+  readonly display: "inline" | "floating" | "unknown";
+  readonly extentEmu?: { widthEmu: number; heightEmu: number };
+  readonly fallbackHint: PreserveOnlyObjectFallbackHint;
+  readonly relationshipIds?: string[];
+}
+
 /**
  * Read-only preview of a chart (c:chart). The original drawing XML is stored in
  * rawXml for lossless round-trip export. If a fallback image was present in
@@ -1872,6 +1893,7 @@ export interface ChartPreviewNode {
    */
   readonly parsedData?: ChartModel;
   readonly rawXml: string;
+  readonly preserveOnlyObject?: PreserveOnlyObjectSizing;
 }
 
 /**
@@ -1882,6 +1904,7 @@ export interface SmartArtPreviewNode {
   readonly type: "smartart_preview";
   readonly previewMediaId?: string;
   readonly rawXml: string;
+  readonly preserveOnlyObject?: PreserveOnlyObjectSizing;
 }
 
 /**
@@ -1913,6 +1936,7 @@ export interface ShapeNode {
    */
   readonly txbxBlocks?: BlockNode[];
   readonly rawXml: string;
+  readonly preserveOnlyObject?: PreserveOnlyObjectSizing;
 }
 
 /**
@@ -1924,6 +1948,7 @@ export interface WordArtNode {
   readonly text: string;
   readonly geometry?: string;
   readonly rawXml: string;
+  readonly preserveOnlyObject?: PreserveOnlyObjectSizing;
 }
 
 /**
@@ -1936,6 +1961,7 @@ export interface VmlShapeNode {
   readonly text?: string;
   readonly shapeType?: string;
   readonly rawXml: string;
+  readonly preserveOnlyObject?: PreserveOnlyObjectSizing;
 }
 
 /**
@@ -2110,6 +2136,7 @@ export interface ShapeContent {
    */
   readonly txbxBlocks?: BlockNode[];
   readonly rawXml: string;
+  readonly preserveOnlyObject?: PreserveOnlyObjectSizing;
 }
 
 export interface TextBoxBodyProperties {
@@ -2129,7 +2156,7 @@ export interface DrawingFrameNode {
     | ShapeContent
     | ChartPreviewNode
     | SmartArtPreviewNode
-    | { type: "opaque"; rawXml: string };
+    | { type: "opaque"; rawXml: string; preserveOnlyObject?: PreserveOnlyObjectSizing };
 }
 
 export interface OpaqueBlockNode {
@@ -4388,6 +4415,10 @@ function validateFieldRegistryEntry(
     });
   }
 
+  if (record.storyKey !== undefined) {
+    expectString(record.storyKey, `${path}.storyKey`, issues);
+  }
+
   if (
     typeof record.refreshStatus !== "string" ||
     !FIELD_REFRESH_STATUSES.has(record.refreshStatus as FieldRefreshStatus)