@beyondwork/docx-react-component 1.0.27 → 1.0.29

package/src/runtime/surface-projection.ts

@@ -1,1357 +0,0 @@
-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,
-  getOpaqueFragment,
-} from "../preservation/store.ts";
-import { getStoryBlocks } from "./story-targeting.ts";
-import {
-  createNumberingPrefixResolver,
-  type NumberingPrefixResolver,
-} from "./numbering-prefix.ts";
-import {
-  collectSectionContexts,
-  findHeaderFooterDocumentEntry,
-  resolveSectionVariants,
-} from "./story-context.ts";
-
-interface ParagraphAccumulator {
-  blockId: string;
-  kind: "paragraph";
-  from: number;
-  to: number;
-  styleId?: string;
-  numbering?: ParagraphNode["numbering"];
-  numberingPrefix?: string;
-  numberingSuffix?: "tab" | "space" | "nothing";
-  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 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.",
-        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 sdtIndex = counters.sdt;
-    counters.sdt += 1;
-    return createSdtBlock(
-      sdtIndex,
-      block,
-      document,
-      cursor,
-      counters,
-      numberingPrefixResolver,
-    );
-  }
-
-  if (block.type === "custom_xml") {
-    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: "Custom XML block",
-        detail:
-          block.uri || block.element
-            ? `Custom XML wrapper ${[block.element, block.uri].filter(Boolean).join(" ")} preserved as a read-only block.`
-            : "Custom XML wrapper preserved as a read-only block.",
-        state: "locked-preserve-only",
-      },
-      lockedFragmentIds: [],
-      nextCursor: cursor + 1,
-    };
-  }
-
-  if (block.type === "alt_chunk") {
-    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: "AltChunk import",
-        detail: `Alternate content import remains read-only through relationship ${block.relationshipId}.`,
-        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);
-
-  for (const [rowIndex, row] of table.rows.entries()) {
-    const cells: SurfaceTableCellSnapshot[] = [];
-    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 cellBorders = resolveCellBorderStyles(cell.borders);
-      cells.push({
-        gridSpan: cell.gridSpan ?? 1,
-        verticalMerge: cell.verticalMerge ?? null,
-        colspan: cell.gridSpan ?? 1,
-        rowspan: rowSpans.get(`${rowIndex}:${cellIndex}`) ?? 1,
-        ...(cell.shading?.fill ? { backgroundColor: `#${cell.shading.fill}` } : {}),
-        ...(cell.verticalAlign ? { verticalAlign: cell.verticalAlign } : {}),
-        ...(cellBorders.borderTop ? { borderTop: cellBorders.borderTop } : {}),
-        ...(cellBorders.borderRight ? { borderRight: cellBorders.borderRight } : {}),
-        ...(cellBorders.borderBottom ? { borderBottom: cellBorders.borderBottom } : {}),
-        ...(cellBorders.borderLeft ? { borderLeft: cellBorders.borderLeft } : {}),
-        content: cellContent,
-      });
-    }
-    rows.push({
-      cells,
-      ...(row.gridBefore !== undefined ? { gridBefore: row.gridBefore } : {}),
-      ...(row.gridAfter !== undefined ? { gridAfter: row.gridAfter } : {}),
-      ...(row.height !== undefined ? { height: row.height } : {}),
-      ...(row.heightRule ? { heightRule: row.heightRule } : {}),
-      ...(row.isHeader ? { isHeader: row.isHeader } : {}),
-    });
-  }
-
-  return {
-    block: {
-      blockId: `table-${tableIndex}`,
-      kind: "table",
-      from: cursor,
-      to: innerCursor,
-      styleId: table.styleId,
-      gridColumns: table.gridColumns,
-      ...(table.alignment ? { alignment: table.alignment } : {}),
-      ...(table.tblLook ? { tblLook: table.tblLook } : {}),
-      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 accumulator: ParagraphAccumulator = {
-    blockId: `paragraph-${paragraphIndex}`,
-    kind: "paragraph",
-    from: start,
-    to: start,
-    ...(paragraph.styleId ? { styleId: paragraph.styleId } : {}),
-    ...(paragraph.numbering ? { numbering: paragraph.numbering } : {}),
-    ...(paragraph.numbering
-      ? (() => {
-          const detailed = numberingPrefixResolver.resolveDetailed(paragraph.numbering);
-          return detailed
-            ? {
-                numberingPrefix: detailed.text,
-                ...(detailed.suffix ? { numberingSuffix: detailed.suffix } : {}),
-              }
-            : {};
-        })()
-      : {}),
-    ...(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 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;
-      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.",
-        ...(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: "Column break marker preserved for export.",
-        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 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;
-}