@beyondwork/docx-react-component 1.0.103 → 1.0.104

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.103",
+  "version": "1.0.104",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [

package/src/api/public-types.ts

@@ -1223,6 +1223,23 @@ export interface SurfacePictureEffects {
   glow?: { radius: number; color: string; colorType: "srgbClr" | "schemeClr" };
 }
 
+export interface SurfacePreserveOnlyObjectSizing {
+  sourceId?: string;
+  display: "inline" | "floating" | "unknown";
+  extentEmu?: { widthEmu: number; heightEmu: number };
+  fallbackHint:
+    | "drawing-inline"
+    | "drawing-floating"
+    | "chart"
+    | "smartart"
+    | "shape"
+    | "wordart"
+    | "vml-shape"
+    | "ole-object"
+    | "opaque-object";
+  relationshipIds?: string[];
+}
+
 export type SurfaceInlineSegment =
   | {
       segmentId: string;
@@ -1338,6 +1355,20 @@ export type SurfaceInlineSegment =
        * can render `ChartSurface` instead of the fallback bitmap or badge.
        */
       parsedChartId?: string;
+      /**
+       * PE2 preserve-only object handoff. Present for unsupported drawing,
+       * chart, SmartArt, WordArt, VML, and opaque-object previews when import
+       * could recover source ids, relationship ids, fallback hints, or
+       * extents. Layout consumers may size placeholders from this metadata;
+       * it is not a layout computation.
+       */
+      preserveOnlyObject?: SurfacePreserveOnlyObjectSizing;
+      /**
+       * Drawing anchor geometry for preserve-only objects that originated in a
+       * `drawing_frame`. Mirrors image/shape anchor semantics so L04 can join
+       * the object to source/canonical/layout rows without re-parsing OOXML.
+       */
+      anchor?: SurfaceDrawingAnchor;
       state: "locked-preserve-only";
     }
   | {
@@ -1403,6 +1434,7 @@ export type SurfaceInlineSegment =
       isTextBox?: boolean;
       /** Text box body layout from `wps:bodyPr` / `a:bodyPr`. */
       textBoxBody?: SurfaceTextBoxBodyProperties;
+      preserveOnlyObject?: SurfacePreserveOnlyObjectSizing;
       /** First-paragraph plain-text preview when `isTextBox` is true. */
       txbxText?: string;
       /** Run-level marks from the first text-box text run, when available. */
@@ -3609,6 +3641,11 @@ export interface WordReviewEditorPasteEvent {
   source: "paste" | "drop";
 }
 
+export interface WorkflowEventOrigin {
+  readonly source: "api" | "runtime" | "collab" | string;
+  readonly at?: string;
+}
+
 export type WordReviewEditorEvent =
   | {
       type: "ready";
@@ -3724,16 +3761,38 @@ export type WordReviewEditorEvent =
       type: "workflow_overlay_changed";
       documentId: string;
       snapshot: WorkflowScopeSnapshot;
+      origin?: WorkflowEventOrigin;
     }
   | {
       type: "workflow_active_work_item_changed";
       documentId: string;
       activeWorkItemId: string | null;
+      origin?: WorkflowEventOrigin;
     }
   | {
       type: "workflow_metadata_changed";
       documentId: string;
       snapshot: WorkflowMetadataSnapshot;
+      origin?: WorkflowEventOrigin;
+    }
+  | {
+      type: "workflow_shared_state_changed";
+      documentId: string;
+      state: SharedWorkflowState | null;
+      origin: WorkflowEventOrigin;
+    }
+  | {
+      type: "workflow_visibility_policy_changed";
+      documentId: string;
+      kind?: OverlayKind;
+      policy?: OverlayVisibilityPolicy | null;
+      origin: WorkflowEventOrigin;
+    }
+  | {
+      type: "workflow_markup_mode_policy_changed";
+      documentId: string;
+      policy: WorkflowMarkupModePolicy | null;
+      origin: WorkflowEventOrigin;
     }
   | {
       type: "host_annotation_overlay_changed";
@@ -5010,7 +5069,10 @@ export interface WordReviewEditorRef {
    * `replaceText` calls to block with `workflow_comment_only`.
    */
   getWorkflowOverlay(): WorkflowOverlay | null;
-  setSharedWorkflowState(state: SharedWorkflowState | null): void;
+  setSharedWorkflowState(
+    state: SharedWorkflowState | null,
+    origin?: WorkflowEventOrigin,
+  ): void;
   getWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null;
   getInteractionGuardSnapshot(): InteractionGuardSnapshot;
   getWorkflowMarkupSnapshot(): WorkflowMarkupSnapshot;

package/src/api/v3/_runtime-handle.ts

@@ -48,6 +48,7 @@ export type RuntimeApiHandle = Pick<
   | "getCompatibilityReport"
   | "getWarnings"
   | "getRenderSnapshot"
+  | "getDocumentNavigationSnapshot"
   // Canonical document read (ai.inspect + ai.bundle + ai.resolve families,
   // added in refactor/08 Slice 2/3 graduations)
   | "getCanonicalDocument"
@@ -155,6 +156,7 @@ export const RUNTIME_API_HANDLE_SHAPE_CHECK: Record<keyof RuntimeApiHandle, true
   getCompatibilityReport: true,
   getWarnings: true,
   getRenderSnapshot: true,
+  getDocumentNavigationSnapshot: true,
   getCanonicalDocument: true,
   findAllText: true,
   replaceText: true,

package/src/api/v3/ai/outline.ts

@@ -19,7 +19,6 @@ import type {
   DocumentOutlineHeadingSnapshot,
   DocumentOutlineSnapshot,
 } from "../../public-types.ts";
-import { createDocumentNavigationSnapshot } from "../../../runtime/document-navigation.ts";
 import { createDocumentOutlineSnapshot } from "../../../runtime/document-outline.ts";
 import {
   computeBlockPositions,
@@ -68,7 +67,7 @@ export const getDocumentOutlineMetadata: ApiV3FnMetadata = {
   stateClass: "A-canonical",
   persistsTo: "canonical",
   rwdReference:
-    "§AI API § ai.getDocumentOutline. Composes createDocumentNavigationSnapshot (L04/07) with createDocumentOutlineSnapshot (L07) to surface the heading tree. Read-only; no audit emission.",
+    "§AI API § ai.getDocumentOutline. Composes runtime.getDocumentNavigationSnapshot() (L04 graph-derived navigation) with createDocumentOutlineSnapshot (L07) to surface the heading tree. Read-only; no audit emission.",
 };
 
 export function createOutlineFamily(runtime: RuntimeApiHandle) {
@@ -82,11 +81,7 @@ export function createOutlineFamily(runtime: RuntimeApiHandle) {
       const snapshot = runtime.getRenderSnapshot();
       const document = runtime.getCanonicalDocument();
       const selectionHead = snapshot.selection.head;
-      const navigation = createDocumentNavigationSnapshot(
-        document,
-        selectionHead,
-        snapshot.activeStory,
-      );
+      const navigation = runtime.getDocumentNavigationSnapshot();
       const outline = createDocumentOutlineSnapshot({
         navigation,
         activeStory: snapshot.activeStory,

package/src/api/v3/runtime/geometry.ts

@@ -15,6 +15,26 @@ import type { RuntimeApiHandle } from "../_runtime-handle.ts";
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
 import { mockPayload } from "../_mocks.ts";
 import type { MockPayload } from "../_layer-metadata.ts";
+import type {
+  GeometryIndex,
+  GeometryIndexCoverage,
+} from "../../../runtime/geometry/index.ts";
+
+function createUnavailableGeometryCoverage(): GeometryIndexCoverage {
+  return {
+    status: "unavailable",
+    pageCount: 0,
+    regionCount: 0,
+    sliceCount: 0,
+    lineCount: 0,
+    anchorCount: 0,
+    hitTargetCount: 0,
+    semanticEntryCount: 0,
+    replacementEnvelopeCount: 0,
+    objectHandleCount: 0,
+    precision: { exact: 0, "within-tolerance": 0, heuristic: 0 },
+  };
+}
 
 export interface BlockRectEntry {
   readonly blockId: string;
@@ -57,6 +77,50 @@ export interface HitTestResult {
   readonly __mock?: true;
 }
 
+/* ================================================================== */
+/*  PE2 geometry index + coverage                                     */
+/* ================================================================== */
+
+export const getGeometryIndexMetadata: ApiV3FnMetadata = {
+  name: "runtime.geometry.getGeometryIndex",
+  status: "live-with-adapter",
+  sourceLayer: "geometry-projection",
+  liveEvidence: {
+    runnerTest: "test/api/v3/geometry-uses-geometry-handle.test.ts",
+    commit: "refactor-07-pe2-geometry-index-read-surface",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "geometry-read",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.geometry.getGeometryIndex. PE2 read surface over GeometryFacet.getGeometryIndex(): renderer-neutral pages, regions, slices, lines, anchors, hit targets, semantic entries, replacement envelopes, object handles, and coverage. Returns null when no geometry facet or render frame is warm. Promotes to live when L05 projects directly from L04 page slices instead of the render-frame adapter.",
+};
+
+export const getGeometryCoverageMetadata: ApiV3FnMetadata = {
+  name: "runtime.geometry.getGeometryCoverage",
+  status: "live-with-adapter",
+  sourceLayer: "geometry-projection",
+  liveEvidence: {
+    runnerTest: "test/api/v3/geometry-uses-geometry-handle.test.ts",
+    commit: "refactor-07-pe2-geometry-index-read-surface",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "geometry-read",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.geometry.getGeometryCoverage. PE2 lightweight status read over GeometryFacet.getGeometryCoverage(). Always returns a coverage object; unwired/pre-paint states report status:'unavailable' with zero counts so agents and evidence runners can distinguish no geometry from empty geometry.",
+};
+
 /* ================================================================== */
 /*  getCaret — Slice-4 caret geometry (Slice X3 of §4 of coord-05)    */
 /* ================================================================== */
@@ -224,6 +288,21 @@ export function createGeometryFamily(runtime: RuntimeApiHandle) {
   const geometry = runtime.geometry;
 
   return {
+    getGeometryIndex(): GeometryIndex | null {
+      // @endStateApi — live-with-adapter. Exposes the Layer-05 PE2
+      // geometry index through the v3 runtime seam. The current L05
+      // index is projected from the render frame; callers still get
+      // renderer-neutral value objects and no DOM/PM/runtime instances.
+      return geometry?.getGeometryIndex() ?? null;
+    },
+
+    getGeometryCoverage(): GeometryIndexCoverage {
+      // @endStateApi — live-with-adapter. Coverage is intentionally
+      // total: an unwired/pre-paint handle reports an unavailable zero
+      // summary instead of null so evidence code can branch on status.
+      return geometry?.getGeometryCoverage() ?? createUnavailableGeometryCoverage();
+    },
+
     getBlockRects(blockIds: readonly string[]): ReadonlyArray<BlockRectEntry & Partial<MockPayload>> {
       // @endStateApi — live-with-adapter. Routes directly through the
       // Layer-05 GeometryFacet's `getBlockRects(blockId)`, which walks

package/src/io/ooxml/parse-drawing.ts

@@ -2,7 +2,12 @@ import type { OpcRelationship } from "./part-manifest.ts";
 import { normalizePartPath, resolveRelationshipTarget } from "./part-manifest.ts";
 import type { InlineMediaPart } from "./parse-inline-media.ts";
 import type { ChartPartLookup } from "./parse-complex-content.ts";
-import type { AnchorGeometry, DrawingFrameNode, Mutable } from "../../model/canonical-document.ts";
+import type {
+  AnchorGeometry,
+  DrawingFrameNode,
+  Mutable,
+  PreserveOnlyObjectSizing,
+} from "../../model/canonical-document.ts";
 import { parseAnchorGeometry } from "./parse-anchor.ts";
 import { parsePicture } from "./parse-picture.ts";
 import { parseShapeContent, type TxbxBlockParser } from "./parse-shapes.ts";
@@ -144,6 +149,13 @@ function resolveFromBranch(
   if (uri === WPS_SHAPE_GRAPHIC_URI && isWordArtGraphicData(graphicData)) return null;
 
   const content = resolveContent(uri, graphicData, outerRawXml, opts);
+  attachPreserveOnlyObjectSizing(content, {
+    anchor: geometry,
+    container,
+    fallbackHint: fallbackHintForContent(content, geometry),
+    rawXml: outerRawXml,
+    sourcePartPath: opts.sourcePartPath,
+  });
   return { type: "drawing_frame", anchor: geometry, content };
 }
 
@@ -231,6 +243,92 @@ function resolveContent(
   return { type: "opaque", rawXml };
 }
 
+function attachPreserveOnlyObjectSizing(
+  content: DrawingFrameNode["content"],
+  context: {
+    anchor: AnchorGeometry;
+    container: XmlElementNode;
+    fallbackHint: PreserveOnlyObjectSizing["fallbackHint"] | null;
+    rawXml: string;
+    sourcePartPath: string | undefined;
+  },
+): void {
+  if (content.type === "picture" || context.fallbackHint === null) {
+    return;
+  }
+
+  (content as Mutable<typeof content>).preserveOnlyObject = {
+    sourceId: createPreserveOnlyObjectSourceId(
+      context.sourcePartPath,
+      context.anchor,
+      context.rawXml,
+    ),
+    display: context.anchor.display,
+    extentEmu: {
+      widthEmu: context.anchor.extent.widthEmu,
+      heightEmu: context.anchor.extent.heightEmu,
+    },
+    fallbackHint: context.fallbackHint,
+    relationshipIds: collectRelationshipIds(context.container),
+  };
+}
+
+function fallbackHintForContent(
+  content: DrawingFrameNode["content"],
+  anchor: AnchorGeometry,
+): PreserveOnlyObjectSizing["fallbackHint"] | null {
+  switch (content.type) {
+    case "picture":
+      return null;
+    case "chart_preview":
+      return "chart";
+    case "smartart_preview":
+      return "smartart";
+    case "shape":
+      return "shape";
+    case "opaque":
+      return anchor.display === "floating" ? "drawing-floating" : "drawing-inline";
+  }
+}
+
+function createPreserveOnlyObjectSourceId(
+  sourcePartPath: string | undefined,
+  anchor: AnchorGeometry,
+  rawXml: string,
+): string {
+  const part = sourcePartPath ?? "/word/document.xml";
+  const docPrId = anchor.docPr?.id;
+  if (docPrId) return `part:${part}#drawing-docPr:${docPrId}`;
+  return `part:${part}#drawing:${hashString(rawXml)}`;
+}
+
+function collectRelationshipIds(node: XmlElementNode): string[] {
+  const ids = new Set<string>();
+  const visit = (current: XmlElementNode): void => {
+    const id =
+      current.attributes["r:id"] ??
+      current.attributes["r:embed"] ??
+      current.attributes.embed ??
+      current.attributes["r:link"] ??
+      current.attributes.link;
+    if (id) ids.add(id);
+    for (const child of current.children) {
+      if (child.type === "element") visit(child);
+    }
+  };
+  visit(node);
+  return [...ids].sort();
+}
+
+function hashString(value: string): string {
+  let hash = 2166136261;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
 function extractChartRelId(graphicData: XmlElementNode | undefined): string | null {
   if (!graphicData) return null;
   const chart = findFirstDescendant(graphicData, "chart");

package/src/io/ooxml/parse-fields.ts

@@ -330,6 +330,11 @@ import type {
   TocStructure,
   Mutable,
 } from "../../model/canonical-document.ts";
+import {
+  MAIN_STORY_KEY,
+  createHeaderFooterStoryKey,
+  createNoteStoryKey,
+} from "../../model/canonical-layout-inputs.ts";
 import { parseFieldSwitches } from "./parse-field-switches.ts";
 
 const FIELD_FAMILY_PATTERN =
@@ -439,6 +444,7 @@ export function buildFieldRegistry(
         ...(classification.target ? { fieldTarget: classification.target } : {}),
         displayText,
         paragraphIndex,
+        storyKey: MAIN_STORY_KEY,
         refreshStatus: node.refreshStatus ?? (classification.supported ? "stale" : "preserve-only"),
         ...(classification.switches ? { switches: classification.switches } : {}),
       };
@@ -454,7 +460,7 @@ export function buildFieldRegistry(
     }
   });
   if (document.subParts) {
-    walkSubPartFields(document.subParts, (node, pIdx) => {
+    walkSubPartFields(document.subParts, (node, pIdx, storyKey) => {
       paragraphIndex = pIdx;
       if (node.type === "field") {
         const classification = node.fieldFamily
@@ -469,6 +475,7 @@ export function buildFieldRegistry(
           ...(classification.target ? { fieldTarget: classification.target } : {}),
           displayText,
           paragraphIndex,
+          storyKey,
           refreshStatus: node.refreshStatus ?? (classification.supported ? "stale" : "preserve-only"),
           ...(classification.switches ? { switches: classification.switches } : {}),
         };
@@ -1062,27 +1069,41 @@ function walkFieldDocument(
 
 function walkSubPartFields(
   subParts: Mutable<SubPartsCatalog>,
-  visit: (node: DocumentNode, paragraphIndex: number) => void,
+  visit: (node: DocumentNode, paragraphIndex: number, storyKey: string) => void,
 ): void {
   for (const header of subParts.headers) {
+    const storyKey = createHeaderFooterStoryKey({
+      kind: "header",
+      relationshipId: header.relationshipId,
+      variant: header.variant,
+      ...(header.sectionIndex !== undefined ? { sectionIndex: header.sectionIndex } : {}),
+    });
     for (const block of header.blocks) {
-      walkFieldDocument(block, visit);
+      walkFieldDocument(block, (node, paragraphIndex) => visit(node, paragraphIndex, storyKey));
     }
   }
   for (const footer of subParts.footers) {
+    const storyKey = createHeaderFooterStoryKey({
+      kind: "footer",
+      relationshipId: footer.relationshipId,
+      variant: footer.variant,
+      ...(footer.sectionIndex !== undefined ? { sectionIndex: footer.sectionIndex } : {}),
+    });
     for (const block of footer.blocks) {
-      walkFieldDocument(block, visit);
+      walkFieldDocument(block, (node, paragraphIndex) => visit(node, paragraphIndex, storyKey));
     }
   }
   if (subParts.footnoteCollection) {
     for (const note of Object.values(subParts.footnoteCollection.footnotes)) {
+      const storyKey = createNoteStoryKey("footnote", note.noteId);
       for (const block of note.blocks) {
-        walkFieldDocument(block, visit);
+        walkFieldDocument(block, (node, paragraphIndex) => visit(node, paragraphIndex, storyKey));
       }
     }
     for (const note of Object.values(subParts.footnoteCollection.endnotes)) {
+      const storyKey = createNoteStoryKey("endnote", note.noteId);
       for (const block of note.blocks) {
-        walkFieldDocument(block, visit);
+        walkFieldDocument(block, (node, paragraphIndex) => visit(node, paragraphIndex, storyKey));
       }
     }
   }

package/src/io/ooxml/parse-shapes.ts

@@ -15,6 +15,7 @@ import type {
   ShapeContent,
   TextBoxBodyProperties,
   Mutable,
+  PreserveOnlyObjectSizing,
 } from "../../model/canonical-document.ts";
 import { parseFill } from "./parse-fill.ts";
 import {
@@ -52,6 +53,7 @@ export interface ParsedWpsShape {
   geometry?: string;
   /** Original drawing XML for lossless round-trip export. */
   rawXml: string;
+  preserveOnlyObject?: PreserveOnlyObjectSizing;
 }
 
 export interface ParsedWordArt {
@@ -62,6 +64,7 @@ export interface ParsedWordArt {
   geometry?: string;
   /** Original drawing XML for lossless round-trip export. */
   rawXml: string;
+  preserveOnlyObject?: PreserveOnlyObjectSizing;
 }
 
 export interface ParsedVmlShape {
@@ -72,6 +75,7 @@ export interface ParsedVmlShape {
   text?: string;
   /** Original w:pict XML for lossless round-trip export. */
   rawXml: string;
+  preserveOnlyObject?: PreserveOnlyObjectSizing;
 }
 
 export type ParsedShape = ParsedWpsShape | ParsedWordArt | ParsedVmlShape;
@@ -113,6 +117,11 @@ export function parseShapeXml(
       text: text ?? "",
       ...(prst ? { geometry: prst } : {}),
       rawXml: drawingXml,
+      preserveOnlyObject: createDrawingPreserveOnlyObject(
+        drawingXml,
+        "wordart",
+        collectRelationshipIds(root),
+      ),
     };
   }
 
@@ -158,6 +167,11 @@ export function parseShapeXml(
     ...(txbxBlocks && txbxBlocks.length > 0 ? { txbxBlocks } : {}),
     ...(prst ? { geometry: prst } : {}),
     rawXml: drawingXml,
+    preserveOnlyObject: createDrawingPreserveOnlyObject(
+      drawingXml,
+      "shape",
+      collectRelationshipIds(root),
+    ),
   };
 }
 
@@ -200,6 +214,11 @@ export function parseVmlXml(pictXml: string): ParsedVmlShape | null {
     ...(shapeType ? { shapeType } : {}),
     ...(text ? { text } : {}),
     rawXml: pictXml,
+    preserveOnlyObject: createVmlPreserveOnlyObject(
+      pictXml,
+      vmlNode,
+      collectRelationshipIds(root),
+    ),
   };
 }
 
@@ -361,3 +380,114 @@ function readIntAttr(node: XmlElementNode, attr: string): number | undefined {
   const parsed = parseInt(raw, 10);
   return Number.isFinite(parsed) ? parsed : undefined;
 }
+
+function createDrawingPreserveOnlyObject(
+  rawXml: string,
+  fallbackHint: PreserveOnlyObjectSizing["fallbackHint"],
+  relationshipIds: string[],
+): PreserveOnlyObjectSizing {
+  const extentEmu = readDrawingExtentEmu(rawXml);
+  return {
+    sourceId: `drawing:${hashString(rawXml)}`,
+    display: rawXml.includes("<wp:anchor") ? "floating" : "inline",
+    ...(extentEmu ? { extentEmu } : {}),
+    fallbackHint,
+    ...(relationshipIds.length > 0 ? { relationshipIds } : {}),
+  };
+}
+
+function createVmlPreserveOnlyObject(
+  rawXml: string,
+  node: XmlElementNode,
+  relationshipIds: string[],
+): PreserveOnlyObjectSizing {
+  const extentEmu = readVmlExtentEmu(node.attributes.style);
+  return {
+    sourceId: `vml:${node.attributes.id ?? hashString(rawXml)}`,
+    display: "unknown",
+    ...(extentEmu ? { extentEmu } : {}),
+    fallbackHint: "vml-shape",
+    ...(relationshipIds.length > 0 ? { relationshipIds } : {}),
+  };
+}
+
+function readDrawingExtentEmu(
+  rawXml: string,
+): { widthEmu: number; heightEmu: number } | undefined {
+  const extentMatch = /<wp:extent\b[^>]*\bcx=["']([0-9]+)["'][^>]*\bcy=["']([0-9]+)["'][^>]*\/?>/u.exec(rawXml);
+  if (extentMatch) {
+    return {
+      widthEmu: Number.parseInt(extentMatch[1] ?? "0", 10),
+      heightEmu: Number.parseInt(extentMatch[2] ?? "0", 10),
+    };
+  }
+  const xfrmMatch = /<a:ext\b[^>]*\bcx=["']([0-9]+)["'][^>]*\bcy=["']([0-9]+)["'][^>]*\/?>/u.exec(rawXml);
+  if (!xfrmMatch) return undefined;
+  return {
+    widthEmu: Number.parseInt(xfrmMatch[1] ?? "0", 10),
+    heightEmu: Number.parseInt(xfrmMatch[2] ?? "0", 10),
+  };
+}
+
+function readVmlExtentEmu(
+  style: string | undefined,
+): { widthEmu: number; heightEmu: number } | undefined {
+  if (!style) return undefined;
+  const widthTwips = readCssLengthTwips(style, "width");
+  const heightTwips = readCssLengthTwips(style, "height");
+  if (widthTwips === undefined || heightTwips === undefined) return undefined;
+  return {
+    widthEmu: Math.round(widthTwips * 635),
+    heightEmu: Math.round(heightTwips * 635),
+  };
+}
+
+function readCssLengthTwips(style: string, property: "width" | "height"): number | undefined {
+  const match = new RegExp(`(?:^|;)\\s*${property}\\s*:\\s*([0-9.]+)\\s*(pt|in|cm|mm|px)?`, "iu")
+    .exec(style);
+  if (!match) return undefined;
+  const value = Number.parseFloat(match[1] ?? "");
+  if (!Number.isFinite(value)) return undefined;
+  const unit = (match[2] ?? "pt").toLowerCase();
+  switch (unit) {
+    case "pt":
+      return Math.round(value * 20);
+    case "in":
+      return Math.round(value * 1440);
+    case "cm":
+      return Math.round(value * 567);
+    case "mm":
+      return Math.round(value * 56.7);
+    case "px":
+      return Math.round(value * 15);
+    default:
+      return undefined;
+  }
+}
+
+function collectRelationshipIds(node: XmlElementNode): string[] {
+  const ids = new Set<string>();
+  const visit = (current: XmlElementNode): void => {
+    const id =
+      current.attributes["r:id"] ??
+      current.attributes["r:embed"] ??
+      current.attributes.embed ??
+      current.attributes["r:link"] ??
+      current.attributes.link;
+    if (id) ids.add(id);
+    for (const child of current.children) {
+      if (child.type === "element") visit(child);
+    }
+  };
+  visit(node);
+  return [...ids].sort();
+}
+
+function hashString(value: string): string {
+  let hash = 2166136261;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}