@beyondwork/docx-react-component 1.0.84 → 1.0.86

package/package.json

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

package/src/api/internal/build-ref-projections.ts

@@ -52,6 +52,9 @@ export function buildRefProjections(
     rejectAll: () => getRef().rejectAllChanges(),
     acceptGroup: (groupId) => getRef().acceptSuggestionGroup(groupId),
     rejectGroup: (groupId) => getRef().rejectSuggestionGroup(groupId),
+    getCommentThread: (changeId) => getRef().getCommentThreadForChange(changeId),
+    ensureCommentThread: (changeId) => getRef().ensureCommentThreadForChange(changeId),
+    addReply: (changeId, body) => getRef().addReplyToChange(changeId, body),
     scrollTo: (revisionId) => getRef().scrollToRevision(revisionId),
     get: () => getRef().getTrackedChanges(),
     getSuggestions: () => getRef().getSuggestionsSnapshot(),

package/src/api/public-types.ts

@@ -592,6 +592,8 @@ export interface CommentSidebarThreadSnapshot {
   createdBy: string;
   warningCount: number;
   anchorLabel: string;
+  /** Present when this thread is the discussion attached to a tracked change. */
+  linkedRevisionId?: string;
   detachedReason?: "incomplete-markers" | "multi-paragraph" | "opaque-region" | "revision-overlap";
   actionabilityNote?: string;
   isActive: boolean;
@@ -630,6 +632,10 @@ export interface TrackedChangeEntrySnapshot {
   warningCount: number;
   canAccept: boolean;
   canReject: boolean;
+  /** Comment threads whose metadata links them to this revision. */
+  commentThreadIds?: string[];
+  /** Number of reply entries across linked comment threads. */
+  replyCount?: number;
   preserveOnlyReason?: string;
   excerpt?: string;
   detail?: string;
@@ -672,6 +678,10 @@ export interface SuggestionEntrySnapshot {
   preserveOnlyReason?: string;
   excerpt?: string;
   detail?: string;
+  /** Comment threads linked to any revision in this suggestion unit. */
+  commentThreadIds?: string[];
+  /** Number of reply entries across linked comment threads. */
+  replyCount?: number;
   /**
    * R3 — scope-card-overlay P2. When present, links this entry to a
    * `SuggestionGroup` via `SuggestionsSnapshot.groups[].groupId`.
@@ -1311,6 +1321,12 @@ export type SurfaceInlineSegment =
       instruction: string;
       refreshStatus: FieldRefreshStatus;
       label: string;
+      /**
+       * Current display text for fields whose visible value is computed by
+       * layout context (PAGE / NUMPAGES / SECTIONPAGES). Consumers fall back
+       * to `label` when absent.
+       */
+      displayText?: string;
     }
   | {
       /**
@@ -4431,6 +4447,9 @@ export interface WordReviewEditorChangesFacet {
   rejectAll(): void;
   acceptGroup(groupId: string): void;
   rejectGroup(groupId: string): void;
+  getCommentThread(changeId: string): CommentSidebarThreadSnapshot | null;
+  ensureCommentThread(changeId: string): AddCommentResult | null;
+  addReply(changeId: string, body: string): AddCommentReplyResult | null;
   scrollTo(revisionId: string): void;
   get(): TrackedChangesSnapshot;
   getSuggestions(): SuggestionsSnapshot;
@@ -4578,6 +4597,25 @@ export interface WordReviewEditorRef {
     commentId: string,
     body: string,
   ): AddCommentReplyResult | null;
+  /**
+   * Return the open/resolved comment thread linked to a tracked change, if
+   * one exists. This is the read side for "reply to tracked change" UX.
+   */
+  getCommentThreadForChange(changeId: string): CommentSidebarThreadSnapshot | null;
+  /**
+   * Create or return the discussion thread attached to a tracked change.
+   * Newly-created threads are anchored to the revision range and opened in
+   * the comments rail by mounted UI callers.
+   */
+  ensureCommentThreadForChange(changeId: string): AddCommentResult | null;
+  /**
+   * Append a reply to a tracked change's linked discussion thread, creating
+   * that thread first when needed.
+   */
+  addReplyToChange(
+    changeId: string,
+    body: string,
+  ): AddCommentReplyResult | null;
   editCommentBody(commentId: string, body: string): void;
   deleteComment(commentId: string): void;
   /**

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

@@ -53,12 +53,18 @@ export type RuntimeApiHandle = Pick<
   | "getCanonicalDocument"
   // Content search + selection (runtime.content + ai.bundle families)
   | "findAllText"
+  | "replaceText"
+  // Formatting mutations (runtime.formatting.apply)
+  | "applyFormattingOperation"
   // Review (runtime.review family)
   | "getReviewWorkSnapshot"
   | "getSuggestionsSnapshot"
   | "acceptChange"
   | "rejectChange"
   | "resolveComment"
+  | "getCommentThreadForChange"
+  | "ensureCommentThreadForChange"
+  | "addReplyToChange"
   // Workflow (runtime.workflow + ai.inspect families)
   | "queryScopes"
   | "getWorkflowMarkupSnapshot"
@@ -147,11 +153,16 @@ export const RUNTIME_API_HANDLE_SHAPE_CHECK: Record<keyof RuntimeApiHandle, true
   getRenderSnapshot: true,
   getCanonicalDocument: true,
   findAllText: true,
+  replaceText: true,
+  applyFormattingOperation: true,
   getReviewWorkSnapshot: true,
   getSuggestionsSnapshot: true,
   acceptChange: true,
   rejectChange: true,
   resolveComment: true,
+  getCommentThreadForChange: true,
+  ensureCommentThreadForChange: true,
+  addReplyToChange: true,
   queryScopes: true,
   getWorkflowMarkupSnapshot: true,
   getInteractionGuardSnapshot: true,

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

@@ -12,7 +12,12 @@
 
 import type { RuntimeApiHandle } from "../_runtime-handle.ts";
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
-import type { CanonicalDocumentFragment } from "../../public-types.ts";
+import type {
+  CanonicalDocumentFragment,
+  EditorAnchorProjection,
+  SurfaceBlockSnapshot,
+  SurfaceInlineSegment,
+} from "../../public-types.ts";
 import { emitUxResponse } from "../_ux-response.ts";
 import { createScopeCompilerService } from "../../../runtime/scopes/index.ts";
 
@@ -179,6 +184,18 @@ export function createContentFamily(runtime: RuntimeApiHandle) {
       // Layer-08 compiler-service facade. Same pipeline as
       // ai.applyReplacementScope; the host/UI path omits actionId (not
       // an agent action) and tags origin:"ui" + actorId:"user".
+      const tableCellResult = replaceTableCellText(runtime, input);
+      if (tableCellResult) {
+        emitUxResponse(runtime, {
+          apiFn: replaceTextMetadata.name,
+          intent: replaceTextMetadata.uxIntent.expectedDelta ?? "",
+          mockOrLive: "live",
+          uiVisible: true,
+          expectedDelta: replaceTextMetadata.uxIntent.expectedDelta,
+        });
+        return tableCellResult;
+      }
+
       const result = compiler.applyReplacement({
         targetScopeId: input.scopeId,
         operation: "replace",
@@ -234,3 +251,133 @@ export function createContentFamily(runtime: RuntimeApiHandle) {
     },
   };
 }
+
+function replaceTableCellText(
+  runtime: RuntimeApiHandle,
+  input: ReplaceTextInput,
+): ReplaceTextResult | null {
+  const parsed = parseTableCellScopeId(input.scopeId);
+  if (!parsed) {
+    return null;
+  }
+
+  const snapshot = runtime.getRenderSnapshot();
+  if (!snapshot.isReady || snapshot.readOnly || snapshot.fatalError) {
+    return { applied: false, reason: "document-not-editable" };
+  }
+
+  const document = runtime.getCanonicalDocument();
+  const rootChild = document.content.children[parsed.blockIndex];
+  if (!rootChild || rootChild.type !== "table") {
+    return { applied: false, reason: "table-cell-scope-not-resolvable" };
+  }
+
+  const tableOrdinal = document.content.children
+    .slice(0, parsed.blockIndex)
+    .filter((block) => block.type === "table").length;
+  const tableBlock =
+    snapshot.surface?.blocks.find(
+      (block): block is Extract<SurfaceBlockSnapshot, { kind: "table" }> =>
+        block.kind === "table" && block.blockId === `table-${tableOrdinal}`,
+    ) ??
+    (snapshot.surface?.blocks[parsed.blockIndex]?.kind === "table"
+      ? snapshot.surface.blocks[parsed.blockIndex]
+      : null);
+  if (!tableBlock || tableBlock.kind !== "table") {
+    return { applied: false, reason: "table-cell-surface-not-realized" };
+  }
+
+  const cell = tableBlock.rows[parsed.rowIndex]?.cells[parsed.cellIndex];
+  if (!cell) {
+    return { applied: false, reason: "table-cell-scope-not-resolvable" };
+  }
+
+  const range = resolveTableCellTextRange(cell.content);
+  if (range.status === "empty") {
+    return { applied: false, reason: "table-cell-empty-text" };
+  }
+  if (range.status === "ambiguous") {
+    return { applied: false, reason: "table-cell-text-scope-ambiguous" };
+  }
+  const { from, to } = range;
+
+  const anchor: EditorAnchorProjection = {
+    kind: "range",
+    from,
+    to,
+    assoc: { start: -1, end: 1 },
+  };
+  const beforeRevisionToken = snapshot.revisionToken;
+  runtime.replaceText(input.replacement, anchor);
+  const afterRevisionToken = runtime.getRenderSnapshot().revisionToken;
+  if (afterRevisionToken === beforeRevisionToken) {
+    return { applied: false, reason: "replace-text-not-applied" };
+  }
+  return { applied: true };
+}
+
+function parseTableCellScopeId(
+  scopeId: string,
+): { blockIndex: number; rowIndex: number; cellIndex: number } | null {
+  const match = /^cell:(\d+):(\d+):(\d+)$/u.exec(scopeId);
+  if (!match) return null;
+  return {
+    blockIndex: Number(match[1]),
+    rowIndex: Number(match[2]),
+    cellIndex: Number(match[3]),
+  };
+}
+
+type TableCellTextRangeResult =
+  | { status: "ok"; from: number; to: number }
+  | { status: "empty" }
+  | { status: "ambiguous" };
+
+function resolveTableCellTextRange(
+  blocks: readonly SurfaceBlockSnapshot[],
+): TableCellTextRangeResult {
+  const paragraphRanges = collectTableCellParagraphTextRanges(blocks);
+  if (paragraphRanges.length === 0) {
+    return { status: "empty" };
+  }
+  if (paragraphRanges.length > 1) {
+    return { status: "ambiguous" };
+  }
+  const [range] = paragraphRanges;
+  return range && range.from < range.to
+    ? { status: "ok", from: range.from, to: range.to }
+    : { status: "empty" };
+}
+
+function collectTableCellParagraphTextRanges(
+  blocks: readonly SurfaceBlockSnapshot[],
+  output: Array<{ from: number; to: number }> = [],
+): Array<{ from: number; to: number }> {
+  for (const block of blocks) {
+    if (block.kind === "paragraph") {
+      const textSegments = block.segments.filter(
+        (segment): segment is Extract<SurfaceInlineSegment, { kind: "text" }> =>
+          segment.kind === "text" && segment.from < segment.to,
+      );
+      if (textSegments.length > 0) {
+        output.push({
+          from: Math.min(...textSegments.map((segment) => segment.from)),
+          to: Math.max(...textSegments.map((segment) => segment.to)),
+        });
+      }
+      continue;
+    }
+    if (block.kind === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          collectTableCellParagraphTextRanges(cell.content, output);
+        }
+      }
+      continue;
+    }
+    if (block.kind === "sdt_block") {
+      collectTableCellParagraphTextRanges(block.children, output);
+    }
+  }
+  return output;
+}

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

@@ -13,12 +13,14 @@
 
 import type { RuntimeApiHandle } from "../_runtime-handle.ts";
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import { emitUxResponse } from "../_ux-response.ts";
 import {
   resolveEffectiveFormatting,
   createFormattingContext,
   type EffectiveFormatting,
   type RunProvenance,
 } from "../../../runtime/formatting/index.ts";
+import type { FormattingOperation } from "../../../core/commands/formatting-commands.ts";
 import {
   findParagraphByBlockId,
   resolveDirectRunFormattingAtSegment,
@@ -132,8 +134,47 @@ export const resolveRunWithProvenanceMetadata: ApiV3FnMetadata = {
     "§Runtime API § runtime.formatting.resolveRunWithProvenance. Agent-facing provenance view — `source ∈ {direct, characterStyle, style, docDefaults}` plus `sourceId` for style tiers. Substrate for ai.explainFormatting (L09).",
 };
 
+export const applyMetadata: ApiV3FnMetadata = {
+  name: "runtime.formatting.apply",
+  status: "live",
+  sourceLayer: "runtime-core",
+  liveEvidence: {
+    runnerTest: "test/api/v3/runtime/formatting-adapter.test.ts",
+    commit: "refactor-03-tracked-changes-v1-formatting-apply-2026-04-23",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  broadcastsVia: "crdt",
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "inline-change",
+    expectedDelta: "formatting changes in the active selection",
+  },
+  agentMetadata: {
+    readOrMutate: "mutate",
+    boundedScope: "selection",
+    auditCategory: "formatting-write",
+  },
+  rwdReference:
+    "§Runtime API § runtime.formatting.apply. Live adapter over DocumentRuntime.applyFormattingOperation(); supports direct formatting/paragraph alignment/indentation and authors bounded property-change suggestions when the effective mode is suggesting. Style suggestions are intentionally not accepted by this operation shape.",
+};
+
 export function createFormattingFamily(runtime: RuntimeApiHandle) {
   return {
+    apply(operation: FormattingOperation): void {
+      // @endStateApi — live. Delegates to the runtime-owned mutation seam
+      // so direct edits, workflow blocking, and suggesting-mode property-
+      // change authorship all share one implementation.
+      runtime.applyFormattingOperation(operation);
+      emitUxResponse(runtime, {
+        apiFn: applyMetadata.name,
+        intent: applyMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: applyMetadata.uxIntent.expectedDelta,
+      });
+    },
+
     getEffective(
       nodeRef: FormattingNodeRef,
       opts?: FormattingGetEffectiveOpts,

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

@@ -8,6 +8,8 @@
 import type { RuntimeApiHandle } from "../_runtime-handle.ts";
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
 import type {
+  AddCommentReplyResult,
+  AddCommentResult,
   CommentSidebarThreadSnapshot,
   SuggestionsSnapshot,
   TrackedChangeEntrySnapshot,
@@ -120,6 +122,56 @@ export const resolveCommentMetadata: ApiV3FnMetadata = {
   rwdReference: "§Runtime API § runtime.review.resolveComment",
 };
 
+export const getCommentThreadForChangeMetadata: ApiV3FnMetadata = {
+  name: "runtime.review.getCommentThreadForChange",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/create-accepts-handle.test.ts",
+    commit: "refactor-03-redline-revision-thread-link",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "scope", auditCategory: "review-read" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.review.getCommentThreadForChange. Live adapter over runtime linked revision comment threads.",
+};
+
+export const ensureCommentThreadForChangeMetadata: ApiV3FnMetadata = {
+  name: "runtime.review.ensureCommentThreadForChange",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/create-accepts-handle.test.ts",
+    commit: "refactor-03-redline-revision-thread-link",
+  },
+  uxIntent: { uiVisible: true, expectsUxResponse: "inline-change", expectedDelta: "comment thread opens for tracked change" },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "scope", auditCategory: "comment-add" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  broadcastsVia: "crdt",
+  rwdReference:
+    "§Runtime API § runtime.review.ensureCommentThreadForChange. Creates or returns the comment thread attached to a tracked change.",
+};
+
+export const addReplyToChangeMetadata: ApiV3FnMetadata = {
+  name: "runtime.review.addReplyToChange",
+  status: "live",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/create-accepts-handle.test.ts",
+    commit: "refactor-03-redline-revision-thread-link",
+  },
+  uxIntent: { uiVisible: true, expectsUxResponse: "inline-change", expectedDelta: "reply appears on tracked-change thread" },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "scope", auditCategory: "comment-reply" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  broadcastsVia: "crdt",
+  rwdReference:
+    "§Runtime API § runtime.review.addReplyToChange. Appends a reply to the comment thread linked to a tracked change.",
+};
+
 export function createReviewFamily(runtime: RuntimeApiHandle) {
   return {
     getComments(): readonly CommentSidebarThreadSnapshot[] {
@@ -140,6 +192,52 @@ export function createReviewFamily(runtime: RuntimeApiHandle) {
       return runtime.getSuggestionsSnapshot();
     },
 
+    getCommentThreadForChange(changeId: string): CommentSidebarThreadSnapshot | null {
+      // @endStateApi — live. Reads the comment thread linked to a tracked
+      // change from the canonical comment projection.
+      return runtime.getCommentThreadForChange(changeId);
+    },
+
+    ensureCommentThreadForChange(changeId: string): AddCommentResult | null {
+      // @endStateApi — live. Ensures a canonical comment thread exists for
+      // a tracked change and emits an inline UX response when created/found.
+      const result = runtime.ensureCommentThreadForChange(changeId);
+      if (result) {
+        emitUxResponse(runtime, {
+          apiFn: ensureCommentThreadForChangeMetadata.name,
+          intent: ensureCommentThreadForChangeMetadata.uxIntent.expectedDelta ?? "",
+          mockOrLive: "live",
+          uiVisible: true,
+          expectedDelta: ensureCommentThreadForChangeMetadata.uxIntent.expectedDelta,
+          actualDelta: {
+            kind: "inline-change",
+            payload: { changeId, commentId: result.commentId },
+          },
+        });
+      }
+      return result;
+    },
+
+    addReplyToChange(changeId: string, body: string): AddCommentReplyResult | null {
+      // @endStateApi — live. Appends a canonical comment reply to the
+      // thread linked to a tracked change.
+      const result = runtime.addReplyToChange(changeId, body);
+      if (result) {
+        emitUxResponse(runtime, {
+          apiFn: addReplyToChangeMetadata.name,
+          intent: addReplyToChangeMetadata.uxIntent.expectedDelta ?? "",
+          mockOrLive: "live",
+          uiVisible: true,
+          expectedDelta: addReplyToChangeMetadata.uxIntent.expectedDelta,
+          actualDelta: {
+            kind: "inline-change",
+            payload: { changeId, commentId: result.commentId, entryId: result.entryId },
+          },
+        });
+      }
+      return result;
+    },
+
     acceptChange(changeId: string): void {
       // @endStateApi — live. Delegates.
       runtime.acceptChange(changeId);

package/src/core/commands/index.ts

@@ -58,7 +58,9 @@ import {
 } from "./text-commands.ts";
 import type {
   BlockNode,
+  InlineNode,
   MutableCanonicalDocument,
+  ParagraphNode,
   RevisionRecord as CanonicalRevisionRecord,
 } from "../../model/canonical-document.ts";
 import { remapCommentThreads } from "../../review/store/comment-remapping.ts";
@@ -2314,39 +2316,93 @@ function isSingleParagraphSuggestingRange(
   to: number,
 ): boolean {
   const ranges: Array<{ start: number; end: number }> = [];
-  let cursor = 0;
-  let previousWasParagraph = false;
+  collectSuggestingParagraphRanges(
+    document.content.children,
+    0,
+    ranges,
+    true,
+  );
+
+  return ranges.some((range) => from >= range.start && to <= range.end);
+}
+
+function collectSuggestingParagraphRanges(
+  blocks: readonly BlockNode[],
+  startCursor: number,
+  output: Array<{ start: number; end: number }>,
+  addRootParagraphBoundaries: boolean,
+): number {
+  let cursor = startCursor;
+
+  for (let index = 0; index < blocks.length; index += 1) {
+    const block = blocks[index];
+    if (!block) {
+      continue;
+    }
 
-  for (const block of document.content.children) {
     if (block.type === "paragraph") {
-      if (previousWasParagraph) {
-        cursor += 1;
-      }
       const start = cursor;
-      cursor += block.children.reduce<number>((size, child) => {
-        if (child.type === "text") {
-          return size + child.text.length;
-        }
-        if (child.type === "hyperlink") {
-          return size + child.children.reduce<number>((childSize, entry) => {
-            if (entry.type === "text") {
-              return childSize + entry.text.length;
-            }
-            return childSize + 1;
-          }, 0);
+      cursor += paragraphLogicalLength(block);
+      output.push({ start, end: cursor });
+    } else if (block.type === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          cursor = collectSuggestingParagraphRanges(
+            cell.children,
+            cursor,
+            output,
+            false,
+          );
         }
-        return size + 1;
-      }, 0);
-      ranges.push({ start, end: cursor });
-      previousWasParagraph = true;
-      continue;
+      }
+    } else if (block.type === "sdt") {
+      cursor = collectSuggestingParagraphRanges(
+        block.children,
+        cursor,
+        output,
+        false,
+      );
+    } else {
+      cursor += 1;
     }
 
-    cursor += 1;
-    previousWasParagraph = false;
+    if (
+      addRootParagraphBoundaries &&
+      index < blocks.length - 1 &&
+      blocks[index + 1]?.type === "paragraph"
+    ) {
+      cursor += 1;
+    }
   }
 
-  return ranges.some((range) => from >= range.start && to <= range.end);
+  return cursor;
+}
+
+function paragraphLogicalLength(paragraph: ParagraphNode): number {
+  return paragraph.children.reduce<number>(
+    (size, child) => size + inlineLogicalLength(child),
+    0,
+  );
+}
+
+function inlineLogicalLength(node: InlineNode): number {
+  switch (node.type) {
+    case "text":
+      return node.text.length;
+    case "hyperlink":
+    case "field":
+      return node.children.reduce<number>(
+        (size, child) => size + inlineLogicalLength(child as InlineNode),
+        0,
+      );
+    case "bookmark_start":
+    case "bookmark_end":
+    case "scope_marker_start":
+    case "scope_marker_end":
+      return 0;
+    default:
+      return 1;
+  }
 }
 
 function applySuggestingInsert(

package/src/core/state/editor-state.ts

@@ -839,6 +839,21 @@ export function normalizeCommentThreadRecord(value: unknown): CommentThreadRecor
             typeof record.metadata.rootParaId === "string"
               ? record.metadata.rootParaId
               : undefined,
+          linkedRevisionId:
+            typeof record.metadata.linkedRevisionId === "string"
+              ? record.metadata.linkedRevisionId
+              : undefined,
+          detachedReason:
+            record.metadata.detachedReason === "incomplete-markers" ||
+            record.metadata.detachedReason === "multi-paragraph" ||
+            record.metadata.detachedReason === "opaque-region" ||
+            record.metadata.detachedReason === "revision-overlap"
+              ? record.metadata.detachedReason
+              : undefined,
+          actionabilityNote:
+            typeof record.metadata.actionabilityNote === "string"
+              ? record.metadata.actionabilityNote
+              : undefined,
         }
       : undefined,
   };

package/src/io/ooxml/header-footer-reference.ts

@@ -0,0 +1,38 @@
+import type { HeaderFooterVariant } from "../../model/canonical-document.ts";
+
+interface HeaderFooterReferenceElement {
+  attributes: Record<string, string>;
+}
+
+export interface ParsedHeaderFooterReferenceAttributes {
+  variant: HeaderFooterVariant;
+  relationshipId: string;
+}
+
+export function readHeaderFooterReferenceAttributes(
+  element: HeaderFooterReferenceElement,
+): ParsedHeaderFooterReferenceAttributes | undefined {
+  const relationshipId =
+    element.attributes["r:id"] ??
+    element.attributes["r:Id"] ??
+    element.attributes.id ??
+    element.attributes.Id;
+  if (!relationshipId) {
+    return undefined;
+  }
+
+  return {
+    variant: toHeaderFooterVariant(element.attributes["w:type"] ?? element.attributes.type),
+    relationshipId,
+  };
+}
+
+export function toHeaderFooterVariant(raw: string | undefined): HeaderFooterVariant {
+  if (raw === "first") {
+    return "first";
+  }
+  if (raw === "even") {
+    return "even";
+  }
+  return "default";
+}