@beyondwork/docx-react-component 1.0.102 → 1.0.104

package/src/runtime/prerender/graph-canonicalize.ts

@@ -1,6 +1,7 @@
 import type {
   RuntimeBlockFragment,
   RuntimePageAnchor,
+  RuntimePageFrame,
   RuntimePageGraph,
   RuntimePageNode,
   RuntimePageRegion,
@@ -54,6 +55,9 @@ export function canonicalizeGraph(graph: RuntimePageGraph): RuntimePageGraph {
     ...page,
     pageId: rewriteId(page.pageId),
     regions: rewriteRegions(page.regions, rewriteId),
+    ...(page.frame === undefined
+      ? {}
+      : { frame: rewriteFrame(page.frame, rewriteId) }),
     lineBoxes: page.lineBoxes.map((line) => ({
       ...line,
       fragmentId: rewriteId(line.fragmentId),
@@ -86,6 +90,32 @@ export function canonicalizeGraph(graph: RuntimePageGraph): RuntimePageGraph {
   };
 }
 
+function rewriteFrame(
+  frame: RuntimePageFrame,
+  rewriteId: (id: string) => string,
+): RuntimePageFrame {
+  return {
+    ...frame,
+    pageId: rewriteId(frame.pageId),
+    regions: {
+      ...frame.regions,
+      body: rewriteRegion(frame.regions.body, rewriteId),
+      ...(frame.regions.header
+        ? { header: rewriteRegion(frame.regions.header, rewriteId) }
+        : {}),
+      ...(frame.regions.footer
+        ? { footer: rewriteRegion(frame.regions.footer, rewriteId) }
+        : {}),
+      ...(frame.regions.columns
+        ? { columns: frame.regions.columns.map((region) => rewriteRegion(region, rewriteId)) }
+        : {}),
+      ...(frame.regions.footnotes
+        ? { footnotes: frame.regions.footnotes.map((region) => rewriteRegion(region, rewriteId)) }
+        : {}),
+    },
+  };
+}
+
 function rewriteRegions(
   regions: RuntimePageRegions,
   rewriteId: (id: string) => string,

package/src/runtime/surface-projection.ts

@@ -6,6 +6,7 @@ import type {
   SurfaceDrawingAnchor,
   SurfaceInlineSegment,
   SurfacePictureEffects,
+  SurfacePreserveOnlyObjectSizing,
   SurfaceTableCellSnapshot,
   SurfaceTableRowSnapshot,
   SurfaceTextMark,
@@ -38,9 +39,11 @@ import type {
   TextMark,
   DrawingFrameNode,
   PictureContent,
+  PreserveOnlyObjectSizing,
   ShapeContent,
   VmlShapeNode,
   WordArtNode,
+  Mutable,
 } from "../model/canonical-document.ts";
 import {
   describeOpaqueFragment,
@@ -575,7 +578,7 @@ function createSurfaceBlock(
 
 function createTableBlock(
   tableIndex: number,
-  table: TableNode,
+  table: Mutable<TableNode>,
   document: CanonicalDocumentEnvelope,
   cursor: number,
   counters: {
@@ -769,7 +772,7 @@ function createTableBlock(
   };
 }
 
-function computeTableRowSpans(table: TableNode): Map<string, number> {
+function computeTableRowSpans(table: Mutable<TableNode>): Map<string, number> {
   const positionedRows = table.rows.map((row) => {
     let startColumn = 0;
 
@@ -933,7 +936,7 @@ function toSurfaceFrameProperties(
 }
 
 function resolveSurfaceParagraphFormatting(
-  formatting: CanonicalParagraphFormatting,
+  formatting: Mutable<CanonicalParagraphFormatting>,
   themeResolver: ThemeColorResolver | undefined,
 ): CanonicalParagraphFormatting {
   if (!formatting.shading) {
@@ -1065,7 +1068,7 @@ function resolveCellBorderStyles(
 
 function createSdtBlock(
   sdtIndex: number,
-  block: SdtNode,
+  block: Mutable<SdtNode>,
   document: CanonicalDocumentEnvelope,
   cursor: number,
   counters: {
@@ -1123,7 +1126,7 @@ function createSdtBlock(
 
 function createParagraphBlock(
   paragraphIndex: number,
-  paragraph: ParagraphNode,
+  paragraph: Mutable<ParagraphNode>,
   document: CanonicalDocumentEnvelope,
   start: number,
   formattingContext: FormattingContext,
@@ -1548,6 +1551,9 @@ function appendInlineSegments(
           ...(c.line ? { line: c.line } : {}),
           ...(c.isTextBox ? { isTextBox: true } : {}),
           ...(c.textBoxBody ? { textBoxBody: c.textBoxBody } : {}),
+          ...(c.preserveOnlyObject
+            ? { preserveOnlyObject: surfacePreserveOnlyObject(c.preserveOnlyObject) }
+            : {}),
           ...(txbxText ? { txbxText } : {}),
           ...(txbxTextSegment?.marks && txbxTextSegment.marks.length > 0
             ? { txbxMarks: txbxTextSegment.marks }
@@ -1567,6 +1573,7 @@ function appendInlineSegments(
           {
             previewMediaId: c.previewMediaId,
             parsedChartId,
+            anchor: surfaceAnchorFromGeometry(node.anchor),
           },
         );
       }
@@ -1577,7 +1584,10 @@ function appendInlineSegments(
           start,
           "SmartArt diagram",
           `DrawingFrame smartart_preview (${node.anchor.wrapMode}).`,
-          { previewMediaId: c.previewMediaId },
+          {
+            previewMediaId: c.previewMediaId,
+            anchor: surfaceAnchorFromGeometry(node.anchor),
+          },
         );
       }
       return appendComplexPreviewSegment(
@@ -1586,6 +1596,7 @@ function appendInlineSegments(
         start,
         "Drawing frame",
         `DrawingFrame ${c.type} (${node.anchor.wrapMode}).`,
+        { anchor: surfaceAnchorFromGeometry(node.anchor) },
       );
     }
     case "symbol":
@@ -1757,13 +1768,7 @@ function appendInlineSegments(
         const fieldLabel =
           node.fieldFamily === "TOC"
             ? "Table of Contents"
-            : node.fieldFamily === "PAGE"
-              ? "Current page number"
-              : node.fieldFamily === "NUMPAGES"
-                ? "Total pages"
-                : node.fieldFamily === "SECTIONPAGES"
-                  ? "Section pages"
-                  : `${node.fieldFamily ?? "Field"}: ${node.fieldTarget ?? node.instruction.trim()}`;
+            : `${node.fieldFamily ?? "Field"}: ${node.fieldTarget ?? node.instruction.trim()}`;
         paragraph.segments.push({
           segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
           kind: "field_ref",
@@ -1804,7 +1809,7 @@ function appendInlineSegments(
 }
 
 function registerParsedChartPreview(
-  node: ChartPreviewNode,
+  node: Mutable<ChartPreviewNode>,
   document: CanonicalDocumentEnvelope,
 ): string | undefined {
   if (!node.parsedData) return undefined;
@@ -1946,7 +1951,7 @@ function surfaceAnchorFromGeometry(
  * fast-path image rendering.
  */
 function surfacePictureEffectsFromContent(
-  content: PictureContent,
+  content: Mutable<PictureContent>,
   themeResolver?: ThemeColorResolver,
 ): SurfacePictureEffects | undefined {
   const outerShadow = resolveSurfacePictureShadow(content.outerShadow, themeResolver);
@@ -2114,12 +2119,19 @@ function extractTxbxFirstTextSegment(
 
 function appendComplexPreviewSegment(
   paragraph: ParagraphAccumulator,
-  node: { rawXml: string },
+  node: { rawXml: string; preserveOnlyObject?: PreserveOnlyObjectSizing },
   start: number,
   label: string,
   detail: string,
-  extras: { previewMediaId?: string; parsedChartId?: string } = {},
+  extras: {
+    previewMediaId?: string;
+    parsedChartId?: string;
+    anchor?: SurfaceDrawingAnchor;
+  } = {},
 ): { nextCursor: number; lockedFragmentIds: string[] } {
+  const preserveOnlyObject = node.preserveOnlyObject
+    ? surfacePreserveOnlyObject(node.preserveOnlyObject)
+    : undefined;
   paragraph.segments.push({
     segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
     kind: "opaque_inline",
@@ -2131,11 +2143,34 @@ function appendComplexPreviewSegment(
     detail,
     ...(extras.previewMediaId ? { previewMediaId: extras.previewMediaId } : {}),
     ...(extras.parsedChartId ? { parsedChartId: extras.parsedChartId } : {}),
+    ...(preserveOnlyObject ? { preserveOnlyObject } : {}),
+    ...(extras.anchor ? { anchor: extras.anchor } : {}),
     state: "locked-preserve-only",
   });
   return { nextCursor: start + 1, lockedFragmentIds: [] };
 }
 
+function surfacePreserveOnlyObject(
+  object: PreserveOnlyObjectSizing,
+): SurfacePreserveOnlyObjectSizing {
+  return {
+    ...(object.sourceId ? { sourceId: object.sourceId } : {}),
+    display: object.display,
+    ...(object.extentEmu
+      ? {
+          extentEmu: {
+            widthEmu: object.extentEmu.widthEmu,
+            heightEmu: object.extentEmu.heightEmu,
+          },
+        }
+      : {}),
+    fallbackHint: object.fallbackHint,
+    ...(object.relationshipIds && object.relationshipIds.length > 0
+      ? { relationshipIds: [...object.relationshipIds] }
+      : {}),
+  };
+}
+
 function appendTextBoxSegment(
   paragraph: ParagraphAccumulator,
   start: number,
@@ -2159,7 +2194,7 @@ function appendTextBoxSegment(
   return { nextCursor: start + 1, lockedFragmentIds: [] };
 }
 
-function shouldRenderSecondaryStoryVmlTextBox(node: VmlShapeNode): boolean {
+function shouldRenderSecondaryStoryVmlTextBox(node: Mutable<VmlShapeNode>): boolean {
   return Boolean(node.text) && (!node.shapeType || /_x0000_t202$/iu.test(node.shapeType));
 }
 
@@ -2174,7 +2209,7 @@ function isMicrosoftSensitivityLabelShape(
     /"Placement"\s*:\s*"Footer"/iu.test(node.rawXml);
 }
 
-function createChartDetail(node: ChartPreviewNode): string {
+function createChartDetail(node: Mutable<ChartPreviewNode>): string {
   const parts = ["Embedded chart."];
   if (node.previewMediaId) {
     parts.push(`Preview available via fallback image (${node.previewMediaId}).`);
@@ -2185,7 +2220,7 @@ function createChartDetail(node: ChartPreviewNode): string {
   return parts.join(" ");
 }
 
-function createSmartArtDetail(node: SmartArtPreviewNode): string {
+function createSmartArtDetail(node: Mutable<SmartArtPreviewNode>): string {
   const parts = ["SmartArt diagram."];
   if (node.previewMediaId) {
     parts.push(`Preview available via fallback image (${node.previewMediaId}).`);
@@ -2196,7 +2231,7 @@ function createSmartArtDetail(node: SmartArtPreviewNode): string {
   return parts.join(" ");
 }
 
-function createShapeDetail(node: ShapeNode): string {
+function createShapeDetail(node: Mutable<ShapeNode>): string {
   if (node.isTextBox) {
     const parts = ["Text box."];
     if (node.text) parts.push(`Content: "${node.text}".`);
@@ -2210,7 +2245,7 @@ function createShapeDetail(node: ShapeNode): string {
   return parts.join(" ");
 }
 
-function createWordArtDetail(node: WordArtNode): string {
+function createWordArtDetail(node: Mutable<WordArtNode>): string {
   const parts = ["WordArt decorative text."];
   if (node.text) parts.push(`Text: "${node.text}".`);
   if (node.geometry) parts.push(`Effect: ${node.geometry}.`);
@@ -2218,7 +2253,7 @@ function createWordArtDetail(node: WordArtNode): string {
   return parts.join(" ");
 }
 
-function createVmlDetail(node: VmlShapeNode): string {
+function createVmlDetail(node: Mutable<VmlShapeNode>): string {
   const parts = ["Legacy VML drawing."];
   if (node.shapeType) parts.push(`Type: ${node.shapeType}.`);
   if (node.text) parts.push(`Text content: "${node.text}".`);
@@ -2587,22 +2622,22 @@ function toSurfaceTabStop(
 }
 
 function buildDirectParagraphFormattingFromNode(
-  paragraph: ParagraphNode,
+  paragraph: Mutable<ParagraphNode>,
 ): CanonicalParagraphFormatting | undefined {
-  const direct: CanonicalParagraphFormatting = {};
-  if (paragraph.spacing) direct.spacing = paragraph.spacing;
-  if (paragraph.indentation) direct.indentation = paragraph.indentation;
-  if (paragraph.alignment) direct.alignment = paragraph.alignment;
-  if (paragraph.borders) direct.borders = paragraph.borders;
-  if (paragraph.shading) direct.shading = paragraph.shading;
-  if (paragraph.tabStops && paragraph.tabStops.length > 0) direct.tabStops = [...paragraph.tabStops];
-  if (paragraph.contextualSpacing !== undefined) direct.contextualSpacing = paragraph.contextualSpacing;
-  if (paragraph.keepNext !== undefined) direct.keepNext = paragraph.keepNext;
-  if (paragraph.keepLines !== undefined) direct.keepLines = paragraph.keepLines;
-  if (paragraph.widowControl !== undefined) direct.widowControl = paragraph.widowControl;
-  if (paragraph.pageBreakBefore !== undefined) direct.pageBreakBefore = paragraph.pageBreakBefore;
-  if (paragraph.outlineLevel !== undefined) direct.outlineLevel = paragraph.outlineLevel;
-  if (paragraph.bidi !== undefined) direct.bidi = paragraph.bidi;
+  const direct: Mutable<CanonicalParagraphFormatting> = {};
+  if (paragraph.spacing) (direct as Mutable<typeof direct>).spacing = paragraph.spacing;
+  if (paragraph.indentation) (direct as Mutable<typeof direct>).indentation = paragraph.indentation;
+  if (paragraph.alignment) (direct as Mutable<typeof direct>).alignment = paragraph.alignment;
+  if (paragraph.borders) (direct as Mutable<typeof direct>).borders = paragraph.borders;
+  if (paragraph.shading) (direct as Mutable<typeof direct>).shading = paragraph.shading;
+  if (paragraph.tabStops && paragraph.tabStops.length > 0) (direct as Mutable<typeof direct>).tabStops = [...paragraph.tabStops];
+  if (paragraph.contextualSpacing !== undefined) (direct as Mutable<typeof direct>).contextualSpacing = paragraph.contextualSpacing;
+  if (paragraph.keepNext !== undefined) (direct as Mutable<typeof direct>).keepNext = paragraph.keepNext;
+  if (paragraph.keepLines !== undefined) (direct as Mutable<typeof direct>).keepLines = paragraph.keepLines;
+  if (paragraph.widowControl !== undefined) (direct as Mutable<typeof direct>).widowControl = paragraph.widowControl;
+  if (paragraph.pageBreakBefore !== undefined) (direct as Mutable<typeof direct>).pageBreakBefore = paragraph.pageBreakBefore;
+  if (paragraph.outlineLevel !== undefined) (direct as Mutable<typeof direct>).outlineLevel = paragraph.outlineLevel;
+  if (paragraph.bidi !== undefined) (direct as Mutable<typeof direct>).bidi = paragraph.bidi;
   if (paragraph.suppressLineNumbers !== undefined) direct.suppressLineNumbers = paragraph.suppressLineNumbers;
   return Object.keys(direct).length > 0 ? direct : undefined;
 }
@@ -2947,7 +2982,7 @@ function createFloatingImageDetail(
   return parts.join(" ");
 }
 
-function hasMediaItem(media: MediaCatalog, mediaId: string): boolean {
+function hasMediaItem(media: Mutable<MediaCatalog>, mediaId: string): boolean {
   return mediaId in media.items;
 }
 

package/src/runtime/workflow/coordinator.ts

@@ -62,6 +62,7 @@ import type {
   WorkflowMetadataDefinition,
   WorkflowMetadataEntry,
   WorkflowMetadataSnapshot,
+  WorkflowEventOrigin,
   WorkflowOverlay,
   WorkflowScope,
   WorkflowScopeGuardPolicy,
@@ -100,10 +101,8 @@ import {
 } from "./visibility-policy.ts";
 import { type WorkflowMarkupModePolicy } from "./markup-mode-policy.ts";
 
-/** Shape of origin metadata attached to commands. The runtime has a
- * richer `CommandOrigin` type; we only pass it through, so we keep an
- * open shape here to avoid coupling. */
-type CoordinatorCommandOrigin = { readonly source: string; readonly at?: string };
+/** Shape of origin metadata attached to workflow commands/events. */
+type CoordinatorCommandOrigin = WorkflowEventOrigin;
 
 /** Document-mutation commands the coordinator emits through `deps.dispatch`. */
 type CoordinatorDispatchedCommand =
@@ -157,10 +156,17 @@ export interface WorkflowEmittableEvent {
   readonly type:
     | "workflow_overlay_changed"
     | "workflow_active_work_item_changed"
-    | "workflow_metadata_changed";
+    | "workflow_metadata_changed"
+    | "workflow_shared_state_changed"
+    | "workflow_visibility_policy_changed"
+    | "workflow_markup_mode_policy_changed";
   readonly documentId: string;
   readonly snapshot?: WorkflowScopeSnapshot | WorkflowMetadataSnapshot | null;
   readonly activeWorkItemId?: string | null;
+  readonly state?: SharedWorkflowState | null;
+  readonly kind?: OverlayKind;
+  readonly policy?: OverlayVisibilityPolicy | WorkflowMarkupModePolicy | null;
+  readonly origin?: CoordinatorCommandOrigin;
 }
 
 export interface PerfCounters {
@@ -276,7 +282,10 @@ export interface WorkflowCoordinator {
    * seam) so UI surfaces re-fire when policy changes mid-session. */
   subscribeMarkupModePolicy(listener: () => void): () => void;
   /* --- collab shared state --- */
-  setSharedWorkflowState(state: SharedWorkflowState | null): void;
+  setSharedWorkflowState(
+    state: SharedWorkflowState | null,
+    origin?: CoordinatorCommandOrigin,
+  ): void;
   /* --- snapshots (cached) --- */
   getInteractionGuardSnapshot(): InteractionGuardSnapshot;
   getWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null;
@@ -1133,12 +1142,21 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     return overlayStore.getMetadataSnapshot();
   }
 
-  function setSharedWorkflowState(state: SharedWorkflowState | null): void {
+  function setSharedWorkflowState(
+    state: SharedWorkflowState | null,
+    origin: CoordinatorCommandOrigin = { source: "api", at: clock() },
+  ): void {
     const prior = overlayStore.getSharedWorkflowState();
     if (state === prior) return;
     overlayStore.replaceSharedWorkflowState(state);
     cachedInteractionGuardSnapshot = undefined;
     cachedWorkflowScopeSnapshot = undefined;
+    deps.emitEvent({
+      type: "workflow_shared_state_changed",
+      documentId: deps.getState().documentId,
+      state,
+      origin,
+    });
   }
 
   function setScopeChromeVisibility(state: ScopeChromeVisibilityState): void {
@@ -1161,13 +1179,13 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
 
   function setVisibilityPolicy(policy: OverlayVisibilityPolicy): boolean {
     const changed = overlayStore.replaceVisibilityPolicy(policy.kind, policy);
-    if (changed) emitVisibilityPolicyChanged();
+    if (changed) emitVisibilityPolicyChanged(policy.kind, policy);
     return changed;
   }
 
   function clearVisibilityPolicy(kind: OverlayKind): boolean {
     const changed = overlayStore.replaceVisibilityPolicy(kind, null);
-    if (changed) emitVisibilityPolicyChanged();
+    if (changed) emitVisibilityPolicyChanged(kind, null);
     return changed;
   }
 
@@ -1175,7 +1193,10 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     policies: readonly OverlayVisibilityPolicy[],
   ): boolean {
     const changed = overlayStore.replaceVisibilityPolicies(policies);
-    if (changed) emitVisibilityPolicyChanged();
+    if (changed) emitVisibilityPolicyChanged(undefined, undefined, {
+      source: "runtime",
+      at: clock(),
+    });
     return changed;
   }
 
@@ -1195,6 +1216,12 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     const changed = overlayStore.replaceMarkupModePolicy(policy);
     if (changed) {
       overlayStore.notifyMarkupModePolicyChanged();
+      deps.emitEvent({
+        type: "workflow_markup_mode_policy_changed",
+        documentId: deps.getState().documentId,
+        policy,
+        origin: { source: "api", at: clock() },
+      });
       if (deps.telemetryBus.isEnabled("scope")) {
         deps.telemetryBus.emit({
           channel: "scope",
@@ -1211,11 +1238,22 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     return overlayStore.subscribeMarkupModePolicy(listener);
   }
 
-  function emitVisibilityPolicyChanged(): void {
+  function emitVisibilityPolicyChanged(
+    kind?: OverlayKind,
+    policy?: OverlayVisibilityPolicy | null,
+    origin: CoordinatorCommandOrigin = { source: "api", at: clock() },
+  ): void {
     // Notify direct subscribers first — L10 X3's ui.overlays.subscribeVisibility
     // chains onto this signal so UI surfaces re-fire when an authoring tool
     // mutates policy mid-session.
     overlayStore.notifyVisibilityPolicyChanged();
+    deps.emitEvent({
+      type: "workflow_visibility_policy_changed",
+      documentId: deps.getState().documentId,
+      ...(kind !== undefined ? { kind } : {}),
+      ...(policy !== undefined ? { policy } : {}),
+      origin,
+    });
     if (!deps.telemetryBus.isEnabled("scope")) return;
     deps.telemetryBus.emit({
       channel: "scope",
@@ -1301,12 +1339,14 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
           type: "workflow_overlay_changed",
           documentId,
           snapshot,
+          origin: command.origin,
         });
         if (command.overlay.activeWorkItemId !== undefined) {
           deps.emitEvent({
             type: "workflow_active_work_item_changed",
             documentId,
             activeWorkItemId: command.overlay.activeWorkItemId ?? null,
+            origin: command.origin,
           });
         }
         return warningDelta;
@@ -1323,6 +1363,7 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
           type: "workflow_active_work_item_changed",
           documentId,
           activeWorkItemId: null,
+          origin: command.origin,
         });
         deps.emitEvent({
           type: "workflow_overlay_changed",
@@ -1334,6 +1375,7 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
             candidates: [],
             blockedReasons: [],
           },
+          origin: command.origin,
         });
         return warningDelta;
       }
@@ -1343,6 +1385,7 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
           type: "workflow_metadata_changed",
           documentId,
           snapshot: overlayStore.getMetadataSnapshot(),
+          origin: command.origin,
         });
         return null;
       }
@@ -1352,6 +1395,7 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
           type: "workflow_metadata_changed",
           documentId,
           snapshot: overlayStore.getMetadataSnapshot(),
+          origin: command.origin,
         });
         return null;
       }
@@ -1361,6 +1405,7 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
           type: "workflow_metadata_changed",
           documentId,
           snapshot: overlayStore.getMetadataSnapshot(),
+          origin: command.origin,
         });
         return null;
       }
@@ -1370,6 +1415,7 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
           type: "workflow_metadata_changed",
           documentId,
           snapshot: overlayStore.getMetadataSnapshot(),
+          origin: command.origin,
         });
         return null;
       }

package/src/session/import/normalize.ts

@@ -22,6 +22,7 @@ import type {
   CanonicalDocument,
   FootnoteCollection,
   OpaqueFragmentRecord,
+  Mutable,
 } from "../../model/canonical-document.ts";
 
 /** Warning shape carried on `CanonicalDocument.diagnostics.warnings`. */
@@ -130,7 +131,7 @@ export function normalizeFootnoteCollectionOpaqueBlocks(
   if (!collection) return;
   const notes = kind === "footnote" ? collection.footnotes : collection.endnotes;
   for (const definition of Object.values(notes)) {
-    definition.blocks = normalizeSubPartOpaqueBlocks(
+    (definition as Mutable<typeof definition>).blocks = normalizeSubPartOpaqueBlocks(
       definition.blocks,
       opaqueFragments,
       warnings,