@beyondwork/docx-react-component 1.0.29 → 1.0.30

package/src/runtime/surface-projection.ts

@@ -0,0 +1,1553 @@
+import type {
+  EditorStoryTarget,
+  EditorSurfaceSnapshot,
+  SecondaryStorySurface,
+  SurfaceBlockSnapshot,
+  SurfaceInlineSegment,
+  SurfaceTableCellSnapshot,
+  SurfaceTableRowSnapshot,
+  SurfaceTextMark,
+} from "../api/public-types";
+import type {
+  CanonicalDocumentEnvelope,
+  SelectionSnapshot,
+} from "../core/state/editor-state.ts";
+import type {
+  BlockNode,
+  ChartPreviewNode,
+  DocumentRootNode,
+  InlineNode,
+  MediaCatalog,
+  ParagraphNode,
+  SdtNode,
+  ShapeNode,
+  SmartArtPreviewNode,
+  TableCellBorders,
+  TableNode,
+  TextMark,
+  VmlShapeNode,
+  WordArtNode,
+} from "../model/canonical-document.ts";
+import {
+  describeOpaqueFragment,
+  describeStructuredWrapperBlock,
+  getOpaqueFragment,
+  isBlockedImportFeatureKey,
+} from "../preservation/store.ts";
+import { getStoryBlocks } from "./story-targeting.ts";
+import {
+  createNumberingPrefixResolver,
+  type NumberingPrefixResult,
+  type NumberingPrefixResolver,
+} from "./numbering-prefix.ts";
+import {
+  collectSectionContexts,
+  findHeaderFooterDocumentEntry,
+  resolveSectionVariants,
+} from "./story-context.ts";
+import { resolveTableStyleResolution } from "./table-style-resolver.ts";
+
+interface ParagraphAccumulator {
+  blockId: string;
+  kind: "paragraph";
+  from: number;
+  to: number;
+  styleId?: string;
+  numbering?: ParagraphNode["numbering"];
+  numberingPrefix?: string;
+  numberingSuffix?: "tab" | "space" | "nothing";
+  resolvedNumbering?: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>["resolvedNumbering"];
+  contextualSpacing?: boolean;
+  segments: SurfaceInlineSegment[];
+}
+
+export function createEditorSurfaceSnapshot(
+  document: CanonicalDocumentEnvelope,
+  _selection: SelectionSnapshot,
+  activeStory: EditorStoryTarget = { kind: "main" },
+): EditorSurfaceSnapshot {
+  const root = normalizeDocumentRoot({
+    type: "doc",
+    children: [...getStoryBlocks(document, activeStory)],
+  });
+  const blocks: SurfaceBlockSnapshot[] = [];
+  const lockedFragmentIds: string[] = [];
+  const numberingPrefixResolver = createNumberingPrefixResolver(document.numbering);
+  let cursor = 0;
+  const counters = {
+    paragraph: 0,
+    table: 0,
+    opaque: 0,
+    sdt: 0,
+    customXml: 0,
+    altChunk: 0,
+  };
+
+  for (let index = 0; index < root.children.length; index += 1) {
+    const surfaceBlock = createSurfaceBlock(
+      root.children[index],
+      document,
+      cursor,
+      counters,
+      numberingPrefixResolver,
+    );
+    blocks.push(surfaceBlock.block);
+    lockedFragmentIds.push(...surfaceBlock.lockedFragmentIds);
+    cursor = surfaceBlock.nextCursor;
+    if (index < root.children.length - 1 && root.children[index + 1]?.type === "paragraph") {
+      cursor += 1;
+    }
+  }
+
+  const secondaryStories = createSecondaryStorySurfaces(document);
+
+  return {
+    storySize: cursor,
+    plainText: createPlainText(blocks),
+    blocks,
+    lockedFragmentIds,
+    secondaryStories,
+  };
+}
+
+function createSurfaceBlock(
+  block: BlockNode,
+  document: CanonicalDocumentEnvelope,
+  cursor: number,
+  counters: {
+    paragraph: number;
+    table: number;
+    opaque: number;
+    sdt: number;
+    customXml: number;
+    altChunk: number;
+  },
+  numberingPrefixResolver: NumberingPrefixResolver,
+): { block: SurfaceBlockSnapshot; lockedFragmentIds: string[]; nextCursor: number } {
+  if (block.type === "opaque_block") {
+    const fragment = getOpaqueFragment(document.preservation as never, block.fragmentId);
+    const descriptor = fragment ? describeOpaqueFragment(fragment) : null;
+    const blockedReasonCode = descriptor && isBlockedImportFeatureKey(descriptor.featureKey)
+      ? "workflow_blocked_import"
+      : "workflow_preserve_only";
+    const blockId = `opaque-${counters.opaque}`;
+    counters.opaque += 1;
+    return {
+      block: {
+        blockId,
+        kind: "opaque_block",
+        from: cursor,
+        to: cursor + 1,
+        fragmentId: block.fragmentId,
+        warningId: block.warningId,
+        label: descriptor?.label ?? "Unsupported OOXML fragment",
+        detail:
+          descriptor?.detail ??
+          "Locked whole-unit to keep unsupported OOXML intact through export.",
+        ...(descriptor ? { featureKey: descriptor.featureKey, blockedReasonCode } : {}),
+        state: "locked-preserve-only",
+      },
+      lockedFragmentIds: [block.fragmentId],
+      nextCursor: cursor + 1,
+    };
+  }
+
+  if (block.type === "table") {
+    const tableIndex = counters.table;
+    counters.table += 1;
+    return createTableBlock(
+      tableIndex,
+      block,
+      document,
+      cursor,
+      counters,
+      numberingPrefixResolver,
+    );
+  }
+
+  if (block.type === "sdt") {
+    const descriptor = describeStructuredWrapperBlock(block);
+    if (descriptor) {
+      const blockId = `sdt-wrapper-${counters.sdt}`;
+      counters.sdt += 1;
+      return {
+        block: {
+          blockId,
+          kind: "opaque_block",
+          from: cursor,
+          to: cursor + 1,
+          fragmentId: blockId,
+          warningId: blockId,
+          label: descriptor.label,
+          detail: descriptor.detail,
+          featureKey: descriptor.featureKey,
+          blockedReasonCode: isBlockedImportFeatureKey(descriptor.featureKey)
+            ? "workflow_blocked_import"
+            : "workflow_preserve_only",
+          state: "locked-preserve-only",
+        },
+        lockedFragmentIds: [],
+        nextCursor: cursor + 1,
+      };
+    }
+
+    const sdtIndex = counters.sdt;
+    counters.sdt += 1;
+    return createSdtBlock(
+      sdtIndex,
+      block,
+      document,
+      cursor,
+      counters,
+      numberingPrefixResolver,
+    );
+  }
+
+  if (block.type === "custom_xml") {
+    const descriptor = describeStructuredWrapperBlock(block);
+    const blockId = `custom-xml-${counters.customXml}`;
+    counters.customXml += 1;
+    return {
+      block: {
+        blockId,
+        kind: "opaque_block",
+        from: cursor,
+        to: cursor + 1,
+        fragmentId: blockId,
+        warningId: blockId,
+        label: descriptor?.label ?? "Custom XML wrapper",
+        detail: descriptor?.detail ?? "Custom XML wrapper remains package-backed and read-only.",
+        ...(descriptor
+          ? {
+              featureKey: descriptor.featureKey,
+              blockedReasonCode: isBlockedImportFeatureKey(descriptor.featureKey)
+                ? "workflow_blocked_import"
+                : "workflow_preserve_only",
+            }
+          : {}),
+        state: "locked-preserve-only",
+      },
+      lockedFragmentIds: [],
+      nextCursor: cursor + 1,
+    };
+  }
+
+  if (block.type === "alt_chunk") {
+    const descriptor = describeStructuredWrapperBlock(block);
+    const blockId = `alt-chunk-${counters.altChunk}`;
+    counters.altChunk += 1;
+    return {
+      block: {
+        blockId,
+        kind: "opaque_block",
+        from: cursor,
+        to: cursor + 1,
+        fragmentId: blockId,
+        warningId: blockId,
+        label: descriptor?.label ?? "AltChunk import",
+        detail:
+          descriptor?.detail ??
+          `AltChunk import remains package-backed and blocked through relationship ${block.relationshipId}.`,
+        ...(descriptor
+          ? {
+              featureKey: descriptor.featureKey,
+              blockedReasonCode: isBlockedImportFeatureKey(descriptor.featureKey)
+                ? "workflow_blocked_import"
+                : "workflow_preserve_only",
+            }
+          : {}),
+        state: "locked-preserve-only",
+      },
+      lockedFragmentIds: [],
+      nextCursor: cursor + 1,
+    };
+  }
+
+  if (block.type === "section_break") {
+    const blockId = `section-break-${counters.opaque}`;
+    counters.opaque += 1;
+    return {
+      block: {
+        blockId,
+        kind: "opaque_block",
+        from: cursor,
+        to: cursor + 1,
+        fragmentId: blockId,
+        warningId: blockId,
+        label: "Section break",
+        detail: "Section properties preserved as a read-only boundary.",
+        state: "locked-preserve-only",
+      },
+      lockedFragmentIds: [],
+      nextCursor: cursor + 1,
+    };
+  }
+
+  const paragraphIndex = counters.paragraph;
+  counters.paragraph += 1;
+  return createParagraphBlock(
+    paragraphIndex,
+    block,
+    document,
+    cursor,
+    numberingPrefixResolver,
+  );
+}
+
+function createTableBlock(
+  tableIndex: number,
+  table: TableNode,
+  document: CanonicalDocumentEnvelope,
+  cursor: number,
+  counters: {
+    paragraph: number;
+    table: number;
+    opaque: number;
+    sdt: number;
+    customXml: number;
+    altChunk: number;
+  },
+  numberingPrefixResolver: NumberingPrefixResolver,
+): { block: SurfaceBlockSnapshot; lockedFragmentIds: string[]; nextCursor: number } {
+  const lockedFragmentIds: string[] = [];
+  let innerCursor = cursor;
+  const rows: SurfaceTableRowSnapshot[] = [];
+  const rowSpans = computeTableRowSpans(table);
+  const resolvedTable = resolveTableStyleResolution(table, document.styles.tables);
+
+  for (const [rowIndex, row] of table.rows.entries()) {
+    const cells: SurfaceTableCellSnapshot[] = [];
+    const resolvedRow = resolvedTable.rows[rowIndex];
+    for (const [cellIndex, cell] of row.cells.entries()) {
+      const cellContent: SurfaceBlockSnapshot[] = [];
+      for (const child of cell.children) {
+        const result = createSurfaceBlock(
+          child,
+          document,
+          innerCursor,
+          counters,
+          numberingPrefixResolver,
+        );
+        cellContent.push(result.block);
+        lockedFragmentIds.push(...result.lockedFragmentIds);
+        innerCursor = result.nextCursor;
+      }
+      const resolvedCell = resolvedRow?.cells[cellIndex];
+      const cellBorders = resolveCellBorderStyles(resolvedCell?.borders ?? cell.borders);
+      cells.push({
+        gridSpan: cell.gridSpan ?? 1,
+        verticalMerge: cell.verticalMerge ?? null,
+        colspan: cell.gridSpan ?? 1,
+        rowspan: rowSpans.get(`${rowIndex}:${cellIndex}`) ?? 1,
+        ...(resolvedCell?.shading?.fill ? { backgroundColor: `#${resolvedCell.shading.fill}` } : {}),
+        ...(resolvedCell?.verticalAlign ? { verticalAlign: resolvedCell.verticalAlign } : {}),
+        ...(cellBorders.borderTop ? { borderTop: cellBorders.borderTop } : {}),
+        ...(cellBorders.borderRight ? { borderRight: cellBorders.borderRight } : {}),
+        ...(cellBorders.borderBottom ? { borderBottom: cellBorders.borderBottom } : {}),
+        ...(cellBorders.borderLeft ? { borderLeft: cellBorders.borderLeft } : {}),
+        content: cellContent,
+      });
+    }
+    const headerLike =
+      row.isHeader === true ||
+      resolvedRow?.style.isHeader === true;
+    rows.push({
+      cells,
+      ...(row.gridBefore !== undefined ? { gridBefore: row.gridBefore } : {}),
+      ...(row.gridAfter !== undefined ? { gridAfter: row.gridAfter } : {}),
+      ...(resolvedRow?.style.height !== undefined ? { height: resolvedRow.style.height } : {}),
+      ...(resolvedRow?.style.heightRule ? { heightRule: resolvedRow.style.heightRule } : {}),
+      ...(headerLike ? { isHeader: true } : {}),
+    });
+  }
+
+  return {
+    block: {
+      blockId: `table-${tableIndex}`,
+      kind: "table",
+      from: cursor,
+      to: innerCursor,
+      styleId: table.styleId,
+      gridColumns: table.gridColumns,
+      ...(resolvedTable.table?.alignment ? { alignment: resolvedTable.table.alignment } : {}),
+      tblLook: resolvedTable.effectiveTblLook,
+      rows,
+    },
+    lockedFragmentIds,
+    nextCursor: innerCursor,
+  };
+}
+
+function computeTableRowSpans(table: TableNode): Map<string, number> {
+  const positionedRows = table.rows.map((row) => {
+    let startColumn = 0;
+
+    return row.cells.map((cell, cellIndex) => {
+      const width = cell.gridSpan ?? 1;
+      const positionedCell = {
+        cell,
+        cellIndex,
+        startColumn,
+        endColumn: startColumn + width - 1,
+      };
+      startColumn += width;
+      return positionedCell;
+    });
+  });
+
+  const rowSpans = new Map<string, number>();
+
+  for (const [rowIndex, row] of positionedRows.entries()) {
+    for (const positionedCell of row) {
+      if (positionedCell.cell.verticalMerge !== "restart") {
+        rowSpans.set(`${rowIndex}:${positionedCell.cellIndex}`, 1);
+        continue;
+      }
+
+      let rowspan = 1;
+      for (let nextRowIndex = rowIndex + 1; nextRowIndex < positionedRows.length; nextRowIndex += 1) {
+        const continuedCell = positionedRows[nextRowIndex]?.find(
+          (candidate) =>
+            candidate.cell.verticalMerge === "continue" &&
+            candidate.startColumn === positionedCell.startColumn &&
+            candidate.endColumn === positionedCell.endColumn,
+        );
+
+        if (!continuedCell) {
+          break;
+        }
+
+        rowspan += 1;
+      }
+
+      rowSpans.set(`${rowIndex}:${positionedCell.cellIndex}`, rowspan);
+    }
+  }
+
+  return rowSpans;
+}
+
+function resolveCellBorderStyles(
+  borders: TableCellBorders | undefined,
+): { borderTop?: string; borderRight?: string; borderBottom?: string; borderLeft?: string } {
+  if (!borders) return {};
+  const result: { borderTop?: string; borderRight?: string; borderBottom?: string; borderLeft?: string } = {};
+  const sides = [["top", "borderTop"], ["right", "borderRight"], ["bottom", "borderBottom"], ["left", "borderLeft"]] as const;
+  for (const [side, key] of sides) {
+    const spec = borders[side];
+    if (!spec || spec.value === "none" || spec.value === "nil") continue;
+    const width = spec.size ? `${Math.max(1, Math.round(spec.size / 8))}px` : "1px";
+    const style = spec.value === "double" ? "double" : spec.value === "dashed" || spec.value === "dashSmallGap" ? "dashed" : spec.value === "dotted" ? "dotted" : "solid";
+    const color = spec.color && spec.color !== "auto" ? `#${spec.color}` : "currentColor";
+    result[key] = `${width} ${style} ${color}`;
+  }
+  return result;
+}
+
+function createSdtBlock(
+  sdtIndex: number,
+  block: SdtNode,
+  document: CanonicalDocumentEnvelope,
+  cursor: number,
+  counters: {
+    paragraph: number;
+    table: number;
+    opaque: number;
+    sdt: number;
+    customXml: number;
+    altChunk: number;
+  },
+  numberingPrefixResolver: NumberingPrefixResolver,
+): { block: SurfaceBlockSnapshot; lockedFragmentIds: string[]; nextCursor: number } {
+  const children: SurfaceBlockSnapshot[] = [];
+  const lockedFragmentIds: string[] = [];
+  let innerCursor = cursor;
+
+  for (const child of block.children) {
+    const result = createSurfaceBlock(
+      child,
+      document,
+      innerCursor,
+      counters,
+      numberingPrefixResolver,
+    );
+    children.push(result.block);
+    lockedFragmentIds.push(...result.lockedFragmentIds);
+    innerCursor = result.nextCursor;
+  }
+
+  return {
+    block: {
+      blockId: `sdt-${sdtIndex}`,
+      kind: "sdt_block",
+      from: cursor,
+      to: innerCursor,
+      ...(block.properties.sdtType ? { sdtType: block.properties.sdtType } : {}),
+      ...(block.properties.alias ? { alias: block.properties.alias } : {}),
+      ...(block.properties.tag ? { tag: block.properties.tag } : {}),
+      ...(block.properties.lock ? { lock: block.properties.lock } : {}),
+      ...(block.properties.checkbox ? { checkboxChecked: block.properties.checkbox.checked } : {}),
+      ...(block.properties.datePicker?.fullDate ? { dateValue: block.properties.datePicker.fullDate } : {}),
+      ...(block.properties.dropdownList ? { dropdownItems: block.properties.dropdownList } : {}),
+      ...(block.properties.comboBox ? { comboBoxItems: block.properties.comboBox } : {}),
+      ...(block.properties.showingPlcHdr ? { showingPlcHdr: true } : {}),
+      children,
+    },
+    lockedFragmentIds,
+    nextCursor: innerCursor,
+  };
+}
+
+function createParagraphBlock(
+  paragraphIndex: number,
+  paragraph: ParagraphNode,
+  document: CanonicalDocumentEnvelope,
+  start: number,
+  numberingPrefixResolver: NumberingPrefixResolver,
+): {
+  block: SurfaceBlockSnapshot;
+  nextCursor: number;
+  lockedFragmentIds: string[];
+} {
+  const effectiveNumbering = resolveEffectiveParagraphNumbering(document, paragraph);
+  const resolvedNumbering = effectiveNumbering
+    ? numberingPrefixResolver.resolveDetailed(effectiveNumbering, paragraph)
+    : null;
+  const accumulator: ParagraphAccumulator = {
+    blockId: `paragraph-${paragraphIndex}`,
+    kind: "paragraph",
+    from: start,
+    to: start,
+    ...(paragraph.styleId ? { styleId: paragraph.styleId } : {}),
+    ...(effectiveNumbering ? { numbering: effectiveNumbering } : {}),
+    ...(resolvedNumbering
+      ? {
+          ...(resolvedNumbering.text !== null ? { numberingPrefix: resolvedNumbering.text } : {}),
+          ...(resolvedNumbering.text !== null && resolvedNumbering.suffix
+            ? { numberingSuffix: resolvedNumbering.suffix }
+            : {}),
+          resolvedNumbering: toSurfaceResolvedNumbering(resolvedNumbering),
+        }
+      : {}),
+    ...(paragraph.alignment ? { alignment: paragraph.alignment } : {}),
+    ...(paragraph.spacing ? { spacing: paragraph.spacing } : {}),
+    ...(paragraph.contextualSpacing !== undefined
+      ? { contextualSpacing: paragraph.contextualSpacing }
+      : {}),
+    ...(paragraph.indentation ? { indentation: paragraph.indentation } : {}),
+    ...(paragraph.borders ? { borders: paragraph.borders } : {}),
+    ...(paragraph.shading ? { shading: paragraph.shading } : {}),
+    ...(paragraph.tabStops && paragraph.tabStops.length > 0
+      ? { tabStops: paragraph.tabStops.map((tabStop) => toSurfaceTabStop(tabStop)) }
+      : {}),
+    ...(paragraph.keepNext ? { keepNext: true } : {}),
+    ...(paragraph.keepLines ? { keepLines: true } : {}),
+    ...(paragraph.pageBreakBefore ? { pageBreakBefore: true } : {}),
+    ...(paragraph.outlineLevel !== undefined ? { outlineLevel: paragraph.outlineLevel } : {}),
+    ...(paragraph.bidi ? { bidi: true } : {}),
+    ...(paragraph.suppressLineNumbers ? { suppressLineNumbers: true } : {}),
+    segments: [],
+  };
+  const lockedFragmentIds: string[] = [];
+  let cursor = start;
+  const children = Array.isArray(paragraph.children) ? paragraph.children : [];
+
+  for (const child of children) {
+    const result = appendInlineSegments(accumulator, child, document, cursor);
+    cursor = result.nextCursor;
+    lockedFragmentIds.push(...result.lockedFragmentIds);
+  }
+
+  accumulator.to = cursor;
+  return {
+    block: accumulator,
+    nextCursor: cursor,
+    lockedFragmentIds,
+  };
+}
+
+function resolveEffectiveParagraphNumbering(
+  document: CanonicalDocumentEnvelope,
+  paragraph: ParagraphNode,
+): ParagraphNode["numbering"] | undefined {
+  if (paragraph.numbering) {
+    return paragraph.numbering;
+  }
+  if (!paragraph.styleId) {
+    return undefined;
+  }
+
+  const paragraphStyles = document.styles?.paragraphs ?? {};
+  const styleChain = collectParagraphStyleChain(document, paragraph.styleId);
+  let styleNumbering:
+    | CanonicalDocumentEnvelope["styles"]["paragraphs"][string]["numbering"]
+    | undefined;
+  for (const styleId of styleChain) {
+    const style = paragraphStyles[styleId];
+    if (style?.numbering) {
+      styleNumbering = style.numbering;
+      break;
+    }
+  }
+  if (!styleNumbering) {
+    return undefined;
+  }
+  if (styleNumbering.level !== undefined) {
+    return {
+      numberingInstanceId: styleNumbering.numberingInstanceId,
+      level: styleNumbering.level,
+    };
+  }
+
+  const resolvedLevel = resolveStyleLinkedNumberingLevel(
+    document,
+    styleNumbering.numberingInstanceId,
+    styleChain,
+  );
+  return resolvedLevel !== undefined
+    ? {
+        numberingInstanceId: styleNumbering.numberingInstanceId,
+        level: resolvedLevel,
+      }
+    : undefined;
+}
+
+function collectParagraphStyleChain(
+  document: CanonicalDocumentEnvelope,
+  styleId: string,
+): string[] {
+  const paragraphStyles = document.styles?.paragraphs ?? {};
+  const chain: string[] = [];
+  const visited = new Set<string>();
+  let currentStyleId: string | undefined = styleId;
+
+  while (currentStyleId && !visited.has(currentStyleId)) {
+    visited.add(currentStyleId);
+    chain.push(currentStyleId);
+    currentStyleId = paragraphStyles[currentStyleId]?.basedOn;
+  }
+
+  return chain;
+}
+
+function resolveStyleLinkedNumberingLevel(
+  document: CanonicalDocumentEnvelope,
+  numberingInstanceId: string,
+  styleChain: readonly string[],
+): number | undefined {
+  const instance = document.numbering.instances[numberingInstanceId];
+  if (!instance) {
+    return undefined;
+  }
+
+  for (const styleId of styleChain) {
+    const overrideMatch = instance.overrides.find(
+      (override) => override.levelDefinition?.paragraphStyleId === styleId,
+    );
+    if (overrideMatch) {
+      return overrideMatch.level;
+    }
+  }
+
+  const abstractDefinition = document.numbering.abstractDefinitions[instance.abstractNumberingId];
+  if (!abstractDefinition) {
+    return undefined;
+  }
+
+  for (const styleId of styleChain) {
+    const levelMatch = abstractDefinition.levels.find(
+      (levelDefinition) => levelDefinition.paragraphStyleId === styleId,
+    );
+    if (levelMatch) {
+      return levelMatch.level;
+    }
+  }
+
+  return undefined;
+}
+
+function appendInlineSegments(
+  paragraph: ParagraphAccumulator,
+  node: InlineNode,
+  document: CanonicalDocumentEnvelope,
+  start: number,
+  hyperlinkHref?: string,
+): { nextCursor: number; lockedFragmentIds: string[] } {
+  switch (node.type) {
+    case "text":
+      paragraph.segments.push({
+        segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
+        kind: "text",
+        from: start,
+        to: start + Array.from(node.text).length,
+        text: node.text,
+        ...(node.marks ? (() => {
+          const result = cloneMarks(node.marks);
+          return {
+            ...(result.marks.length > 0 ? { marks: result.marks } : {}),
+            ...(result.markAttrs ? { markAttrs: result.markAttrs } : {}),
+          };
+        })() : {}),
+        ...(hyperlinkHref ? { hyperlinkHref } : {}),
+      });
+      return { nextCursor: start + Array.from(node.text).length, lockedFragmentIds: [] };
+    case "tab":
+      paragraph.segments.push({
+        segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
+        kind: "tab",
+        from: start,
+        to: start + 1,
+        ...(hyperlinkHref ? { hyperlinkHref } : {}),
+      });
+      return { nextCursor: start + 1, lockedFragmentIds: [] };
+    case "hard_break":
+      paragraph.segments.push({
+        segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
+        kind: "hard_break",
+        from: start,
+        to: start + 1,
+        ...(hyperlinkHref ? { hyperlinkHref } : {}),
+      });
+      return { nextCursor: start + 1, lockedFragmentIds: [] };
+    case "hyperlink": {
+      let cursor = start;
+      for (const child of node.children) {
+        const result = appendInlineSegments(paragraph, child, document, cursor, node.href);
+        cursor = result.nextCursor;
+      }
+      return { nextCursor: cursor, lockedFragmentIds: [] };
+    }
+    case "image":
+      paragraph.segments.push({
+        segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
+        kind: "image",
+        from: start,
+        to: start + 1,
+        mediaId: node.mediaId,
+        altText: node.altText,
+        state: hasMediaItem(document.media, node.mediaId) ? "editable" : "missing",
+        ...(node.display ? { display: node.display } : {}),
+        detail:
+          node.display === "floating"
+            ? createFloatingImageDetail(node.altText, node.floating)
+            : node.altText
+              ? `Alt text ${node.altText}.`
+              : "Inline image remains a whole-unit render surface.",
+      });
+      return { nextCursor: start + 1, lockedFragmentIds: [] };
+    case "opaque_inline": {
+      const fragment = getOpaqueFragment(document.preservation as never, node.fragmentId);
+      const descriptor = fragment ? describeOpaqueFragment(fragment) : null;
+      const preview = fragment ? describePreservedInlinePreview(fragment.payloadReference) : null;
+      const blockedReasonCode = descriptor && isBlockedImportFeatureKey(descriptor.featureKey)
+        ? "workflow_blocked_import"
+        : "workflow_preserve_only";
+      paragraph.segments.push({
+        segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
+        kind: "opaque_inline",
+        from: start,
+        to: start + 1,
+        fragmentId: node.fragmentId,
+        warningId: node.warningId,
+        label: preview?.label ?? descriptor?.label ?? "Unsupported inline OOXML",
+        detail:
+          preview?.detail ??
+          descriptor?.detail ??
+          "Locked whole-unit to keep unsupported inline OOXML intact through export.",
+        ...(descriptor ? { featureKey: descriptor.featureKey, blockedReasonCode } : {}),
+        ...(preview?.presentation ? { presentation: preview.presentation } : {}),
+        state: "locked-preserve-only",
+      });
+      return { nextCursor: start + 1, lockedFragmentIds: [node.fragmentId] };
+    }
+    case "chart_preview":
+      return appendComplexPreviewSegment(paragraph, node, start, "Embedded chart", createChartDetail(node));
+    case "smartart_preview":
+      return appendComplexPreviewSegment(paragraph, node, start, "SmartArt diagram", createSmartArtDetail(node));
+    case "shape":
+      return appendComplexPreviewSegment(paragraph, node, start,
+        node.isTextBox ? "Text box" : "Drawing shape", createShapeDetail(node));
+    case "wordart":
+      return appendComplexPreviewSegment(paragraph, node, start, "WordArt", createWordArtDetail(node));
+    case "vml_shape":
+      return appendComplexPreviewSegment(paragraph, node, start, "Legacy VML drawing", createVmlDetail(node));
+    case "symbol":
+      paragraph.segments.push({
+        segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
+        kind: "text",
+        from: start,
+        to: start + 1,
+        text: node.char ? String.fromCodePoint(parseInt(node.char, 16)) : "\uFFFD",
+      });
+      return { nextCursor: start + 1, lockedFragmentIds: [] };
+    case "column_break":
+      paragraph.segments.push({
+        segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
+        kind: "opaque_inline",
+        from: start,
+        to: start + 1,
+        fragmentId: "",
+        warningId: "",
+        label: "Column break",
+        detail: "Word column break marker preserved for export safety.",
+        presentation: "quiet-marker",
+        state: "locked-preserve-only",
+      });
+      return { nextCursor: start + 1, lockedFragmentIds: [] };
+    case "footnote_ref":
+      paragraph.segments.push({
+        segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
+        kind: "note_ref",
+        from: start,
+        to: start + 1,
+        noteKind: node.noteKind ?? "footnote",
+        noteId: node.noteId ?? "",
+        label: node.noteId ?? "*",
+      });
+      return { nextCursor: start + 1, lockedFragmentIds: [] };
+    case "field": {
+      const isSupportedField =
+        node.fieldFamily === "REF" ||
+        node.fieldFamily === "PAGEREF" ||
+        node.fieldFamily === "NOTEREF" ||
+        node.fieldFamily === "TOC";
+      if (node.children && node.children.length > 0) {
+        let cursor = start;
+        const lockedIds: string[] = [];
+        for (const child of node.children) {
+          const result = appendInlineSegments(paragraph, child, document, cursor);
+          cursor = result.nextCursor;
+          lockedIds.push(...result.lockedFragmentIds);
+        }
+        return { nextCursor: cursor, lockedFragmentIds: lockedIds };
+      }
+      if (isSupportedField) {
+        // Supported field with no resolved content — show as field chip
+        const fieldLabel =
+          node.fieldFamily === "TOC"
+            ? "Table of Contents"
+            : `${node.fieldFamily ?? "Field"}: ${node.fieldTarget ?? node.instruction.trim()}`;
+        paragraph.segments.push({
+          segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
+          kind: "field_ref",
+          from: start,
+          to: start + 1,
+          fieldFamily: node.fieldFamily!,
+          fieldTarget: node.fieldTarget,
+          instruction: node.instruction,
+          refreshStatus: node.refreshStatus ?? "stale",
+          label: fieldLabel,
+        } as SurfaceInlineSegment);
+        return { nextCursor: start + 1, lockedFragmentIds: [] };
+      }
+      paragraph.segments.push({
+        segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
+        kind: "opaque_inline",
+        from: start,
+        to: start + 1,
+        fragmentId: "",
+        warningId: "",
+        label: "Field",
+        detail: `Preserve-only field: ${node.instruction.trim()}`,
+        state: "locked-preserve-only",
+      });
+      return { nextCursor: start + 1, lockedFragmentIds: [] };
+    }
+    case "bookmark_start":
+    case "bookmark_end":
+      // Zero-width markers — no visual, no cursor advancement
+      return { nextCursor: start, lockedFragmentIds: [] };
+    default:
+      return { nextCursor: start + 1, lockedFragmentIds: [] };
+  }
+}
+
+function appendComplexPreviewSegment(
+  paragraph: ParagraphAccumulator,
+  node: { rawXml: string },
+  start: number,
+  label: string,
+  detail: string,
+): { nextCursor: number; lockedFragmentIds: string[] } {
+  paragraph.segments.push({
+    segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
+    kind: "opaque_inline",
+    from: start,
+    to: start + 1,
+    fragmentId: `complex:${label.replace(/\s/g, "-").toLowerCase()}:${start}`,
+    warningId: `warning:complex-preview:${start}`,
+    label,
+    detail,
+    state: "locked-preserve-only",
+  });
+  return { nextCursor: start + 1, lockedFragmentIds: [] };
+}
+
+function createChartDetail(node: ChartPreviewNode): string {
+  const parts = ["Embedded chart."];
+  if (node.previewMediaId) {
+    parts.push(`Preview available via fallback image (${node.previewMediaId}).`);
+  } else {
+    parts.push("No fallback preview image found; chart data preserved in package.");
+  }
+  parts.push("Edit in Word to modify chart data. Original DrawingML preserved for lossless export.");
+  return parts.join(" ");
+}
+
+function createSmartArtDetail(node: SmartArtPreviewNode): string {
+  const parts = ["SmartArt diagram."];
+  if (node.previewMediaId) {
+    parts.push(`Preview available via fallback image (${node.previewMediaId}).`);
+  } else {
+    parts.push("No fallback preview image found; diagram structure preserved in package.");
+  }
+  parts.push("Edit in Word to modify diagram layout and content. Original DrawingML preserved for lossless export.");
+  return parts.join(" ");
+}
+
+function createShapeDetail(node: ShapeNode): string {
+  if (node.isTextBox) {
+    const parts = ["Text box."];
+    if (node.text) parts.push(`Content: "${node.text}".`);
+    parts.push("Text content is visible; formatting and geometry preserved for export.");
+    return parts.join(" ");
+  }
+  const parts = ["Drawing shape."];
+  if (node.geometry) parts.push(`Geometry: ${node.geometry}.`);
+  if (node.text) parts.push(`Text content: "${node.text}".`);
+  parts.push("Visual geometry is preview-only. Original DrawingML preserved for export.");
+  return parts.join(" ");
+}
+
+function createWordArtDetail(node: WordArtNode): string {
+  const parts = ["WordArt decorative text."];
+  if (node.text) parts.push(`Text: "${node.text}".`);
+  if (node.geometry) parts.push(`Effect: ${node.geometry}.`);
+  parts.push("Text effect is preview-only. Edit in Word for full formatting. Original DrawingML preserved for export.");
+  return parts.join(" ");
+}
+
+function createVmlDetail(node: VmlShapeNode): string {
+  const parts = ["Legacy VML drawing."];
+  if (node.shapeType) parts.push(`Type: ${node.shapeType}.`);
+  if (node.text) parts.push(`Text content: "${node.text}".`);
+  parts.push("VML content is preview-only. Edit in Word for full control. Original VML XML preserved for export.");
+  return parts.join(" ");
+}
+
+function createPlainText(
+  blocks: SurfaceBlockSnapshot[],
+): string {
+  const text: string[] = [];
+  for (const block of blocks) {
+    if (block.kind === "opaque_block") {
+      if (block.fragmentId.startsWith("preview:")) {
+        continue;
+      }
+      text.push("\uFFFA");
+      continue;
+    }
+
+    if (block.kind === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          text.push(createPlainText(cell.content));
+        }
+      }
+      continue;
+    }
+
+    if (block.kind === "sdt_block") {
+      text.push(createPlainText(block.children));
+      continue;
+    }
+
+    for (const segment of block.segments) {
+      switch (segment.kind) {
+        case "text":
+          text.push(segment.text);
+          break;
+        case "tab":
+          text.push("\t");
+          break;
+        case "hard_break":
+          text.push("\n");
+          break;
+        case "image":
+          text.push("\uFFFC");
+          break;
+        case "opaque_inline":
+          text.push("\uFFF9");
+          break;
+      }
+    }
+  }
+
+  return text.join("");
+}
+
+function createSecondaryStorySurfaces(
+  document: CanonicalDocumentEnvelope,
+): SecondaryStorySurface[] {
+  const surfaces: SecondaryStorySurface[] = [];
+  const subParts = document.subParts;
+  if (!subParts) {
+    return surfaces;
+  }
+
+  const numberingPrefixResolver = createNumberingPrefixResolver(document.numbering);
+
+  for (const section of collectSectionContexts(document)) {
+    const headerVariants = resolveSectionVariants(
+      "header",
+      section.index,
+      section.properties?.headerReferences,
+      subParts.headers ?? [],
+    );
+    for (const headerVariant of headerVariants) {
+      const target: EditorStoryTarget = {
+        kind: "header",
+        relationshipId: headerVariant.relationshipId,
+        variant: headerVariant.variant,
+        sectionIndex: section.index,
+      };
+      const header = findHeaderFooterDocumentEntry(document, target);
+      if (!header) {
+        continue;
+      }
+      surfaces.push(
+        createStorySurface(
+          target,
+          `Header · ${headerVariant.variant}`,
+          header.blocks,
+          document,
+          numberingPrefixResolver,
+        ),
+      );
+    }
+
+    const footerVariants = resolveSectionVariants(
+      "footer",
+      section.index,
+      section.properties?.footerReferences,
+      subParts.footers ?? [],
+    );
+    for (const footerVariant of footerVariants) {
+      const target: EditorStoryTarget = {
+        kind: "footer",
+        relationshipId: footerVariant.relationshipId,
+        variant: footerVariant.variant,
+        sectionIndex: section.index,
+      };
+      const footer = findHeaderFooterDocumentEntry(document, target);
+      if (!footer) {
+        continue;
+      }
+      surfaces.push(
+        createStorySurface(
+          target,
+          `Footer · ${footerVariant.variant}`,
+          footer.blocks,
+          document,
+          numberingPrefixResolver,
+        ),
+      );
+    }
+  }
+
+  const footnotes = Object.values(subParts.footnoteCollection?.footnotes ?? {}).sort(compareNoteIds);
+  for (const note of footnotes) {
+    const target: EditorStoryTarget = { kind: "footnote", noteId: note.noteId };
+    surfaces.push(createStorySurface(target, `Footnote ${note.noteId}`, note.blocks, document, numberingPrefixResolver));
+  }
+
+  const endnotes = Object.values(subParts.footnoteCollection?.endnotes ?? {}).sort(compareNoteIds);
+  for (const note of endnotes) {
+    const target: EditorStoryTarget = { kind: "endnote", noteId: note.noteId };
+    surfaces.push(createStorySurface(target, `Endnote ${note.noteId}`, note.blocks, document, numberingPrefixResolver));
+  }
+
+  return surfaces;
+}
+
+function createStorySurface(
+  target: EditorStoryTarget,
+  label: string,
+  blocks: readonly BlockNode[],
+  document: CanonicalDocumentEnvelope,
+  numberingPrefixResolver: NumberingPrefixResolver,
+): SecondaryStorySurface {
+  const surfaceBlocks: SurfaceBlockSnapshot[] = [];
+  let cursor = 0;
+  const counters = {
+    paragraph: 0,
+    table: 0,
+    opaque: 0,
+    sdt: 0,
+    customXml: 0,
+    altChunk: 0,
+  };
+
+  for (let index = 0; index < blocks.length; index += 1) {
+    const surfaceBlock = createSurfaceBlock(
+      blocks[index],
+      document,
+      cursor,
+      counters,
+      numberingPrefixResolver,
+    );
+    surfaceBlocks.push(surfaceBlock.block);
+    cursor = surfaceBlock.nextCursor;
+    if (index < blocks.length - 1 && blocks[index + 1]?.type === "paragraph") {
+      cursor += 1;
+    }
+  }
+
+  return {
+    target,
+    label,
+    storySize: cursor,
+    blocks: surfaceBlocks,
+  };
+}
+
+function createSecondaryStoryPreviewBlocks(
+  document: CanonicalDocumentEnvelope,
+  cursor: number,
+): SurfaceBlockSnapshot[] {
+  const previews: SurfaceBlockSnapshot[] = [];
+  const subParts = document.subParts;
+  if (!subParts) {
+    return previews;
+  }
+
+  for (const header of subParts.headers ?? []) {
+    previews.push(
+      createSecondaryStoryPreviewBlock(
+        `Header · ${header.variant}`,
+        `header:${header.relationshipId}`,
+        cursor,
+        createSecondaryStoryPreviewDetail(header.partPath, header.blocks),
+      ),
+    );
+  }
+
+  for (const footer of subParts.footers ?? []) {
+    previews.push(
+      createSecondaryStoryPreviewBlock(
+        `Footer · ${footer.variant}`,
+        `footer:${footer.relationshipId}`,
+        cursor,
+        createSecondaryStoryPreviewDetail(footer.partPath, footer.blocks),
+      ),
+    );
+  }
+
+  const footnotes = Object.values(subParts.footnoteCollection?.footnotes ?? {}).sort(compareNoteIds);
+  for (const note of footnotes) {
+    previews.push(
+      createSecondaryStoryPreviewBlock(
+        `Footnote ${note.noteId}`,
+        `footnote:${note.noteId}`,
+        cursor,
+        createSecondaryStoryPreviewDetail(`/word/footnotes.xml#${note.noteId}`, note.blocks),
+      ),
+    );
+  }
+
+  const endnotes = Object.values(subParts.footnoteCollection?.endnotes ?? {}).sort(compareNoteIds);
+  for (const note of endnotes) {
+    previews.push(
+      createSecondaryStoryPreviewBlock(
+        `Endnote ${note.noteId}`,
+        `endnote:${note.noteId}`,
+        cursor,
+        createSecondaryStoryPreviewDetail(`/word/endnotes.xml#${note.noteId}`, note.blocks),
+      ),
+    );
+  }
+
+  return previews;
+}
+
+function createSecondaryStoryPreviewBlock(
+  label: string,
+  previewId: string,
+  cursor: number,
+  detail: string,
+): Extract<SurfaceBlockSnapshot, { kind: "opaque_block" }> {
+  return {
+    blockId: `secondary-story-${previewId.replace(/[^a-z0-9._:-]+/gi, "-")}`,
+    kind: "opaque_block",
+    from: cursor,
+    to: cursor,
+    fragmentId: `preview:${previewId}`,
+    warningId: `preview:${previewId}`,
+    label,
+    detail,
+    state: "locked-preserve-only",
+  };
+}
+
+function createSecondaryStoryPreviewDetail(
+  sourceLabel: string,
+  blocks: readonly BlockNode[],
+): string {
+  const previewLines = blocks
+    .map((block) => summarizePreviewBlock(block))
+    .filter((line) => line.trim().length > 0);
+  const previewText = previewLines.length > 0 ? previewLines.join("\n\n") : "Empty story.";
+  return `Read-only preview from ${sourceLabel}.\n${previewText}`;
+}
+
+function summarizePreviewBlock(block: BlockNode): string {
+  switch (block.type) {
+    case "paragraph": {
+      const text = block.children.map((child) => summarizePreviewInline(child)).join("");
+      return text.trim().length > 0 ? text : "¶";
+    }
+    case "table":
+      return "[Table preserved in secondary story]";
+    case "opaque_block":
+      return "[Locked block preserved for export]";
+    case "sdt":
+      return "[Content control preview]";
+    case "custom_xml":
+      return "[Custom XML preview]";
+    case "alt_chunk":
+      return "[AltChunk preview]";
+    case "section_break":
+      return "[Section boundary]";
+  }
+}
+
+function summarizePreviewInline(node: InlineNode): string {
+  switch (node.type) {
+    case "text":
+      return node.text;
+    case "tab":
+      return "\t";
+    case "hard_break":
+      return "\n";
+    case "hyperlink":
+      return node.children.map((child) => summarizePreviewInline(child)).join("");
+    case "footnote_ref":
+      return node.noteKind === "footnote" ? `[fn ${node.noteId}]` : `[en ${node.noteId}]`;
+    case "field": {
+      const instruction = node.instruction.trim();
+      return instruction.length > 0 ? `[Field: ${instruction}]` : "[Field]";
+    }
+    case "bookmark_start":
+      return node.name ? `[Bookmark: ${node.name}]` : "[Bookmark]";
+    case "bookmark_end":
+      return "";
+    case "image":
+      return node.altText ? `[Image: ${node.altText}]` : "[Image]";
+    case "opaque_inline":
+      return "[Locked inline content]";
+    case "symbol":
+      return node.char ? String.fromCodePoint(parseInt(node.char, 16)) : "\uFFFD";
+    case "column_break":
+      return "[Column break]";
+    case "chart_preview":
+      return "[Embedded chart]";
+    case "smartart_preview":
+      return "[SmartArt diagram]";
+    case "shape":
+      if (node.isTextBox && node.text) return `[Text box: ${node.text}]`;
+      return node.text ? `[Shape: ${node.text}]` : "[Drawing shape]";
+    case "wordart":
+      return node.text ? `[WordArt: ${node.text}]` : "[WordArt]";
+    case "vml_shape":
+      return node.text ? `[VML: ${node.text}]` : "[Legacy VML drawing]";
+  }
+}
+
+function compareNoteIds(
+  left: { noteId: string },
+  right: { noteId: string },
+): number {
+  return Number.parseInt(left.noteId, 10) - Number.parseInt(right.noteId, 10);
+}
+
+function toSurfaceTabStop(
+  tabStop: NonNullable<ParagraphNode["tabStops"]>[number],
+): { pos: number; val?: string; leader?: string } {
+  return {
+    pos: tabStop.position,
+    ...(tabStop.align ? { val: tabStop.align } : {}),
+    ...(tabStop.leader ? { leader: tabStop.leader } : {}),
+  };
+}
+
+function toSurfaceResolvedNumbering(
+  numbering: NumberingPrefixResult,
+): NonNullable<Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>["resolvedNumbering"]> {
+  return {
+    level: numbering.level,
+    format: numbering.format,
+    ...(numbering.text !== null ? { text: numbering.text } : {}),
+    startAt: numbering.startAt,
+    ...(numbering.paragraphStyleId ? { paragraphStyleId: numbering.paragraphStyleId } : {}),
+    ...(numbering.isLegalNumbering ? { isLegalNumbering: true } : {}),
+    ...(numbering.suffix ? { suffix: numbering.suffix } : {}),
+    geometry: {
+      ...(numbering.geometry.markerJustification
+        ? { markerJustification: numbering.geometry.markerJustification }
+        : {}),
+      ...(numbering.geometry.spacing ? { spacing: { ...numbering.geometry.spacing } } : {}),
+      ...(numbering.geometry.indentation
+        ? { indentation: { ...numbering.geometry.indentation } }
+        : {}),
+      ...(numbering.geometry.tabStops && numbering.geometry.tabStops.length > 0
+        ? { tabStops: numbering.geometry.tabStops.map((tabStop) => toSurfaceTabStop(tabStop)) }
+        : {}),
+      ...(numbering.geometry.markerLane
+        ? { markerLane: { ...numbering.geometry.markerLane } }
+        : {}),
+      ...(numbering.geometry.textColumn
+        ? { textColumn: { ...numbering.geometry.textColumn } }
+        : {}),
+    },
+  };
+}
+
+function describePreservedInlinePreview(
+  payloadReference: string,
+): {
+  label: string;
+  detail: string;
+  presentation?: "inline-chip" | "quiet-marker";
+} | null {
+  if (/\b(?:w:)?proofErr\b/u.test(payloadReference)) {
+    const proofType = /\bw:type="([^"]+)"/u.exec(payloadReference)?.[1];
+    return {
+      label: "Proofing marker",
+      detail:
+        proofType && proofType.trim().length > 0
+          ? `Word proofing marker (${proofType}) preserved for export safety.`
+          : "Word proofing marker preserved for export safety.",
+      presentation: "quiet-marker",
+    };
+  }
+
+  if (/\b(?:w:)?lastRenderedPageBreak\b/u.test(payloadReference)) {
+    return {
+      label: "Rendered page break",
+      detail: "Word rendered page-break marker preserved for export safety.",
+      presentation: "quiet-marker",
+    };
+  }
+
+  if (/\b(?:w:)?permStart\b/u.test(payloadReference)) {
+    const editorGroup = /\bw:edGrp="([^"]+)"/u.exec(payloadReference)?.[1];
+    return {
+      label: "Protected range start",
+      detail:
+        editorGroup && editorGroup.trim().length > 0
+          ? `Protected range start for ${editorGroup} preserved for export safety.`
+          : "Protected range start preserved for export safety.",
+      presentation: "quiet-marker",
+    };
+  }
+
+  if (/\b(?:w:)?permEnd\b/u.test(payloadReference)) {
+    return {
+      label: "Protected range end",
+      detail: "Protected range end preserved for export safety.",
+      presentation: "quiet-marker",
+    };
+  }
+
+  if (/\b(?:w:)?bookmarkStart\b/u.test(payloadReference)) {
+    const name = /\bw:name="([^"]+)"/u.exec(payloadReference)?.[1];
+    return {
+      label: name ? `Bookmark · ${name}` : "Bookmark",
+      detail: name
+        ? `Bookmark anchor \"${name}\" is preserved as a read-only inline token for export safety.`
+        : "Bookmark anchor is preserved as a read-only inline token for export safety.",
+    };
+  }
+
+  if (/\b(?:w:)?bookmarkEnd\b/u.test(payloadReference)) {
+    return {
+      label: "Bookmark end",
+      detail: "Bookmark end marker is preserved as a read-only inline token for export safety.",
+    };
+  }
+
+  if (/\b(?:w:)?fldSimple\b|\b(?:w:)?fldChar\b|\b(?:w:)?instrText\b/u.test(payloadReference)) {
+    const simpleInstruction = /\bw:instr="([^"]*)"/u.exec(payloadReference)?.[1];
+    const complexInstruction = [...payloadReference.matchAll(/<(?:\w+:)?instrText\b[^>]*>([\s\S]*?)<\/(?:\w+:)?instrText>/gu)]
+      .map((match) => decodeXmlEntities(match[1] ?? ""))
+      .join("")
+      .trim();
+    const instruction = (simpleInstruction ?? complexInstruction ?? "").trim();
+    const family = /^([A-Z]+)/i.exec(instruction)?.[1]?.toUpperCase();
+    const label =
+      family === "TOC"
+        ? "Table of Contents field"
+        : family
+          ? `${family} field`
+          : "Field";
+    return {
+      label,
+      detail:
+        instruction.length > 0
+          ? `Read-only field preserved for export safety. Instruction: ${instruction}.`
+          : "Read-only field preserved for export safety.",
+    };
+  }
+
+  return null;
+}
+
+function decodeXmlEntities(text: string): string {
+  return text
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, "\"")
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, "&");
+}
+
+function cloneMarks(marks: TextMark[]): {
+  marks: SurfaceTextMark[];
+  markAttrs?: {
+    backgroundColor?: string;
+    charSpacing?: number;
+    kerning?: number;
+    textFill?: string;
+    fontFamily?: string;
+    fontSize?: number;
+    textColor?: string;
+  };
+} {
+  const supported: SurfaceTextMark[] = [];
+  const attrs: {
+    backgroundColor?: string;
+    charSpacing?: number;
+    kerning?: number;
+    textFill?: string;
+    fontFamily?: string;
+    fontSize?: number;
+    textColor?: string;
+  } = {};
+  let shadingColor: string | undefined;
+  let highlightColor: string | undefined;
+  for (const mark of marks) {
+    switch (mark.type) {
+      case "bold":
+      case "italic":
+      case "underline":
+      case "strikethrough":
+      case "doubleStrikethrough":
+      case "vanish":
+      case "emboss":
+      case "imprint":
+      case "shadow":
+        supported.push(mark.type);
+        break;
+      case "position":
+        if (mark.val > 0) supported.push("superscript");
+        else if (mark.val < 0) supported.push("subscript");
+        break;
+      case "backgroundColor":
+        shadingColor = mark.color;
+        break;
+      case "highlight":
+        highlightColor = mark.color;
+        break;
+      case "charSpacing":
+        attrs.charSpacing = mark.val;
+        break;
+      case "kerning":
+        attrs.kerning = mark.val;
+        break;
+      case "textFill":
+        attrs.textFill = mark.xml;
+        break;
+      case "fontFamily":
+        attrs.fontFamily = mark.val;
+        break;
+      case "fontSize":
+        attrs.fontSize = mark.val;
+        break;
+      case "textColor":
+        attrs.textColor = mark.color;
+        break;
+      case "smallCaps":
+        supported.push("smallCaps");
+        break;
+      case "allCaps":
+        supported.push("allCaps");
+        break;
+      case "lang":
+        // no visual effect — skip
+        break;
+    }
+  }
+  if (highlightColor || shadingColor) {
+    attrs.backgroundColor = highlightColor ?? shadingColor;
+  }
+  const hasAttrs = Object.keys(attrs).length > 0;
+  return hasAttrs ? { marks: supported, markAttrs: attrs } : { marks: supported };
+}
+
+function normalizeDocumentRoot(content: unknown): DocumentRootNode {
+  if (content && typeof content === "object" &&
+    ((content as { type?: string }).type === "doc" || (content as { type?: string }).type === "document_root")) {
+    return content as DocumentRootNode;
+  }
+
+  if (Array.isArray(content)) {
+    return {
+      type: "doc",
+      children: content.filter(
+        (value): value is DocumentRootNode["children"][number] =>
+          Boolean(value) &&
+          typeof value === "object" &&
+          ((value as { type?: string }).type === "paragraph" ||
+            (value as { type?: string }).type === "table" ||
+            (value as { type?: string }).type === "sdt" ||
+            (value as { type?: string }).type === "custom_xml" ||
+            (value as { type?: string }).type === "alt_chunk" ||
+            (value as { type?: string }).type === "opaque_block"),
+      ),
+    };
+  }
+
+  return {
+    type: "doc",
+    children: [{ type: "paragraph", children: [] }],
+  };
+}
+
+function createFloatingImageDetail(
+  altText: string | undefined,
+  floating: {
+    horizontalPosition?: { relativeFrom?: string; align?: string; offset?: number };
+    verticalPosition?: { relativeFrom?: string; align?: string; offset?: number };
+    wrap?: string;
+  } | undefined,
+): string {
+  const parts = [altText ? `Alt text ${altText}.` : "Floating image rendered inline in the editor."];
+  if (floating?.wrap) {
+    parts.push(`Wrap ${floating.wrap}.`);
+  }
+  if (floating?.horizontalPosition?.align || floating?.horizontalPosition?.offset !== undefined) {
+    parts.push(
+      `Horizontal ${floating.horizontalPosition.align ?? floating.horizontalPosition.offset}.`,
+    );
+  }
+  if (floating?.verticalPosition?.align || floating?.verticalPosition?.offset !== undefined) {
+    parts.push(
+      `Vertical ${floating.verticalPosition.align ?? floating.verticalPosition.offset}.`,
+    );
+  }
+  return parts.join(" ");
+}
+
+function hasMediaItem(media: MediaCatalog, mediaId: string): boolean {
+  return mediaId in media.items;
+}