@beyondwork/docx-react-component 1.0.19 → 1.0.21

package/src/model/canonical-document.ts

@@ -28,7 +28,7 @@ const CANONICAL_DOCUMENT_TOP_LEVEL_KEYS = [
   "diagnostics",
 ] as const;
 
-const CANONICAL_DOCUMENT_OPTIONAL_KEYS = ["subParts"] as const;
+const CANONICAL_DOCUMENT_OPTIONAL_KEYS = ["subParts", "fieldRegistry"] as const;
 
 const ID_PATTERNS = {
   styleId: /^[A-Za-z_][A-Za-z0-9._-]{0,127}$/,
@@ -62,6 +62,8 @@ export interface CanonicalDocument {
   preservation: PreservationStore;
   diagnostics: DiagnosticStore;
   subParts?: SubPartsCatalog;
+  /** Package-backed field registry for supported field families. */
+  fieldRegistry?: FieldRegistry;
 }
 
 export interface DocumentMetadata {
@@ -329,6 +331,7 @@ export interface ParagraphNode {
   };
   alignment?: "left" | "center" | "right" | "both" | "distribute";
   spacing?: ParagraphSpacing;
+  contextualSpacing?: boolean;
   indentation?: ParagraphIndentation;
   tabStops?: TabStop[];
   keepNext?: boolean;
@@ -477,11 +480,119 @@ export interface AltChunkNode {
   relationshipId: string;
 }
 
+/**
+ * Supported field families that receive first-class canonical treatment.
+ * These families have stable registry IDs, dependency metadata, and
+ * runtime-owned refresh behavior.
+ */
+export type SupportedFieldFamily = "REF" | "PAGEREF" | "NOTEREF" | "TOC";
+
+/**
+ * Unsupported field families that remain preserve-only.
+ * They survive round-trip but do not participate in runtime refresh.
+ */
+export type PreserveOnlyFieldFamily =
+  | "PAGE"
+  | "NUMPAGES"
+  | "DATE"
+  | "TIME"
+  | "AUTHOR"
+  | "FILENAME"
+  | "MERGEFIELD"
+  | "IF"
+  | "SEQ"
+  | "INDEX"
+  | "TC"
+  | "STYLEREF"
+  | "FORMULA"
+  | "UNKNOWN";
+
+export type FieldFamily = SupportedFieldFamily | PreserveOnlyFieldFamily;
+
+/** Runtime refresh status for a field instance. */
+export type FieldRefreshStatus =
+  | "current"
+  | "stale"
+  | "unresolvable"
+  | "preserve-only";
+
 export interface FieldNode {
   type: "field";
   fieldType: "simple" | "complex";
   instruction: string;
   children: InlineNode[];
+  /** Classified field family. Undefined for legacy snapshots. */
+  fieldFamily?: FieldFamily;
+  /** Target bookmark name for REF/PAGEREF/NOTEREF fields. */
+  fieldTarget?: string;
+  /** Runtime refresh status. Undefined for legacy or preserve-only fields. */
+  refreshStatus?: FieldRefreshStatus;
+}
+
+// ─── Field registry ─────────────────────────────────────────────────────────
+
+/**
+ * Package-backed field registry that catalogs every field instance in the
+ * document, grouped by supported vs preserve-only families.
+ *
+ * Supported field entries carry dependency metadata (bookmark targets) and
+ * participate in deterministic refresh.  Preserve-only entries survive
+ * round-trip but are not refreshable.
+ */
+export interface FieldRegistry {
+  /** Supported field instances that participate in refresh. */
+  supported: FieldRegistryEntry[];
+  /** Preserve-only field instances cataloged for round-trip safety. */
+  preserveOnly: FieldRegistryEntry[];
+  /** Generated TOC structure extracted from heading-driven TOC fields. */
+  tocStructure?: TocStructure;
+}
+
+export interface FieldRegistryEntry {
+  /** Stable document-order index of this field (0-based). */
+  fieldIndex: number;
+  /** Classified field family. */
+  fieldFamily: FieldFamily;
+  /** Whether the field is in the supported refresh slice. */
+  supported: boolean;
+  /** Field instruction text. */
+  instruction: string;
+  /** Target bookmark name for REF/PAGEREF/NOTEREF fields. */
+  fieldTarget?: string;
+  /** Current display text extracted from field content. */
+  displayText: string;
+  /** Paragraph index in document order where this field appears. */
+  paragraphIndex: number;
+  /** Runtime refresh status. */
+  refreshStatus: FieldRefreshStatus;
+}
+
+/**
+ * Generated table-of-contents structure extracted from TOC fields and
+ * heading-styled paragraphs in the document.
+ */
+export interface TocStructure {
+  /** The raw TOC field instruction (e.g. "TOC \\o \"1-3\" \\h"). */
+  instruction: string;
+  /** Heading level range the TOC covers. */
+  levelRange: { from: number; to: number };
+  /** Ordered TOC entries derived from heading paragraphs. */
+  entries: TocEntry[];
+  /** Whether the TOC content is current with the heading structure. */
+  status: "current" | "stale";
+}
+
+export interface TocEntry {
+  /** Heading text. */
+  text: string;
+  /** Heading outline level (1-9). */
+  level: number;
+  /** Paragraph index of the heading in document order. */
+  paragraphIndex: number;
+  /** Style ID of the heading paragraph, if available. */
+  styleId?: string;
+  /** Bookmark name anchoring this heading, if present. */
+  bookmarkName?: string;
 }
 
 export interface BookmarkStartNode {
@@ -612,6 +723,7 @@ export type TextMark =
   | { type: "doubleStrikethrough" }
   | { type: "vanish" }
   | { type: "lang"; val: string }
+  | { type: "highlight"; color: string; val: string }
   | { type: "backgroundColor"; color: string }
   | { type: "charSpacing"; val: number }
   | { type: "kerning"; val: number }
@@ -743,6 +855,7 @@ export interface OpaqueBlockNode {
   type: "opaque_block";
   fragmentId: string;
   warningId: string;
+  rawXml?: string;
 }
 
 export interface DocRange {
@@ -1272,6 +1385,9 @@ function validateDocumentNode(
     case "opaque_block":
       expectDomainString(record.fragmentId, "fragmentId", `${path}.fragmentId`, issues);
       expectDomainString(record.warningId, "warningId", `${path}.warningId`, issues);
+      if (record.rawXml !== undefined) {
+        expectString(record.rawXml, `${path}.rawXml`, issues);
+      }
       return;
     case "table":
       if (!Array.isArray(record.gridColumns)) {

package/src/model/snapshot.ts

@@ -110,6 +110,7 @@ export interface PersistedEditorSnapshot {
   canonicalDocument: CanonicalDocument;
   compatibility: CompatibilityReport;
   warningLog: EditorWarning[];
+  protectionSnapshot?: ProtectionSnapshotRecord;
   sourcePackage?: PersistedSourcePackage;
 }
 
@@ -127,7 +128,26 @@ const SNAPSHOT_REQUIRED_TOP_LEVEL_KEYS = [
   "warningLog",
 ] as const;
 
-const SNAPSHOT_OPTIONAL_TOP_LEVEL_KEYS = ["sourcePackage"] as const;
+const SNAPSHOT_OPTIONAL_TOP_LEVEL_KEYS = ["sourcePackage", "protectionSnapshot"] as const;
+
+export interface ProtectionRangeRecord {
+  rangeId: string;
+  start?: number;
+  end?: number;
+  editorGroup?: string;
+  editor?: string;
+  enforced: boolean;
+  enforcementReason: string;
+}
+
+export interface ProtectionSnapshotRecord {
+  hasDocumentProtection: boolean;
+  editType?: string;
+  enforcementActive: boolean;
+  ranges: ProtectionRangeRecord[];
+  enforcedRangeCount: number;
+  preservedRangeCount: number;
+}
 
 const PERSISTED_EDITOR_SNAPSHOT_VERSIONS = new Set<PersistedEditorSnapshotVersion>([
   LEGACY_PERSISTED_EDITOR_SNAPSHOT_VERSION,
@@ -260,6 +280,9 @@ export function validatePersistedEditorSnapshot(
   if (record.sourcePackage !== undefined) {
     validatePersistedSourcePackage(record.sourcePackage, "$.sourcePackage", issues);
   }
+  if (record.protectionSnapshot !== undefined) {
+    validateProtectionSnapshot(record.protectionSnapshot, "$.protectionSnapshot", issues);
+  }
 
   return issues;
 }
@@ -537,6 +560,7 @@ export function createPersistedEditorSnapshot(params: {
   canonicalDocument: CanonicalDocument;
   compatibility: CompatibilityReport;
   warningLog?: EditorWarning[];
+  protectionSnapshot?: ProtectionSnapshotRecord;
   sourcePackage?: PersistedSourcePackage;
 }): PersistedEditorSnapshot {
   assertCanonicalDocument(params.canonicalDocument);
@@ -554,10 +578,70 @@ export function createPersistedEditorSnapshot(params: {
     canonicalDocument: params.canonicalDocument,
     compatibility: params.compatibility,
     warningLog: params.warningLog ?? params.compatibility.warnings,
+    protectionSnapshot: params.protectionSnapshot,
     sourcePackage: params.sourcePackage,
   };
 }
 
+function validateProtectionSnapshot(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+  if (typeof record.hasDocumentProtection !== "boolean") {
+    issues.push({ path: `${path}.hasDocumentProtection`, message: "hasDocumentProtection must be a boolean." });
+  }
+  if (record.editType !== undefined) {
+    expectString(record.editType, `${path}.editType`, issues);
+  }
+  if (typeof record.enforcementActive !== "boolean") {
+    issues.push({ path: `${path}.enforcementActive`, message: "enforcementActive must be a boolean." });
+  }
+  if (!Array.isArray(record.ranges)) {
+    issues.push({ path: `${path}.ranges`, message: "ranges must be an array." });
+  } else {
+    record.ranges.forEach((range, index) => validateProtectionRange(range, `${path}.ranges[${index}]`, issues));
+  }
+  if (!Number.isInteger(record.enforcedRangeCount)) {
+    issues.push({ path: `${path}.enforcedRangeCount`, message: "enforcedRangeCount must be an integer." });
+  }
+  if (!Number.isInteger(record.preservedRangeCount)) {
+    issues.push({ path: `${path}.preservedRangeCount`, message: "preservedRangeCount must be an integer." });
+  }
+}
+
+function validateProtectionRange(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+  expectString(record.rangeId, `${path}.rangeId`, issues);
+  if (record.start !== undefined && !Number.isInteger(record.start)) {
+    issues.push({ path: `${path}.start`, message: "start must be an integer." });
+  }
+  if (record.end !== undefined && !Number.isInteger(record.end)) {
+    issues.push({ path: `${path}.end`, message: "end must be an integer." });
+  }
+  if (record.editorGroup !== undefined) {
+    expectString(record.editorGroup, `${path}.editorGroup`, issues);
+  }
+  if (record.editor !== undefined) {
+    expectString(record.editor, `${path}.editor`, issues);
+  }
+  if (typeof record.enforced !== "boolean") {
+    issues.push({ path: `${path}.enforced`, message: "enforced must be a boolean." });
+  }
+  expectString(record.enforcementReason, `${path}.enforcementReason`, issues);
+}
+
 export function projectAnchorToSnapshot(
   anchor: Record<string, unknown>,
 ): Record<string, unknown> {

package/src/review/store/revision-store.ts

@@ -44,6 +44,8 @@ export interface RevisionSidebarEntry {
   canAccept: boolean;
   canReject: boolean;
   preserveOnlyReason?: string;
+  linkedMoveRevisionId?: string;
+  moveDirection?: "from" | "to";
 }
 
 export interface RevisionSidebarProjection {
@@ -212,6 +214,8 @@ function toSidebarEntry(revision: RevisionRecord): RevisionSidebarEntry {
   const anchorSummary = summarizeRevisionAnchor(revision.anchor);
   const actionability = getRevisionActionability(revision);
 
+  const moveData = revision.metadata.moveData;
+
   return {
     revisionId: revision.revisionId,
     kind: revision.kind,
@@ -228,6 +232,8 @@ function toSidebarEntry(revision: RevisionRecord): RevisionSidebarEntry {
     canAccept: isRevisionActionable(revision),
     canReject: isRevisionActionable(revision),
     preserveOnlyReason: revision.metadata.preserveOnlyReason,
+    linkedMoveRevisionId: moveData?.linkedRevisionId,
+    moveDirection: moveData?.direction,
   };
 }
 

package/src/review/store/revision-types.ts

@@ -28,6 +28,7 @@ export interface PropertyChangeData {
 export interface MoveData {
   moveId: string;
   direction: "from" | "to";
+  linkedRevisionId?: string;
 }
 
 export interface RevisionMetadataEnvelope {

package/src/runtime/document-navigation.ts

@@ -45,6 +45,21 @@ import { findNoteReferencePosition } from "./view-state.ts";
 const MIN_BLOCK_HEIGHT_TWIPS = 240;
 const FOOTNOTE_REFERENCE_RESERVATION_TWIPS = 180;
 
+interface NavigationBaseSnapshot {
+  mainSurface: EditorSurfaceSnapshot;
+  sections: ResolvedDocumentSection[];
+  pages: DocumentPageSnapshot[];
+  headings: DocumentHeadingSnapshot[];
+}
+
+const navigationBaseCache = new WeakMap<
+  CanonicalDocumentEnvelope["content"],
+  NavigationBaseSnapshot & {
+    styles: CanonicalDocumentEnvelope["styles"];
+    subParts: CanonicalDocumentEnvelope["subParts"];
+  }
+>();
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -61,31 +76,55 @@ export function createDocumentNavigationSnapshot(
   selectionHead: number,
   activeStory: EditorStoryTarget,
 ): DocumentNavigationSnapshot {
+  const base = getNavigationBaseSnapshot(document);
+  const navigationContext = resolveActiveNavigationContext(
+    document,
+    base.pages,
+    base.sections,
+    base.mainSurface,
+    selectionHead,
+    activeStory,
+  );
+
+  return {
+    pageCount: base.pages.length,
+    pages: base.pages,
+    headings: base.headings,
+    activePageIndex: navigationContext.activePageIndex,
+    activeSectionIndex: navigationContext.activeSectionIndex,
+  };
+}
+
+function getNavigationBaseSnapshot(
+  document: CanonicalDocumentEnvelope,
+): NavigationBaseSnapshot {
+  const cached = navigationBaseCache.get(document.content);
+  if (
+    cached &&
+    cached.styles === document.styles &&
+    cached.subParts === document.subParts
+  ) {
+    return cached;
+  }
+
   const mainSurface = createEditorSurfaceSnapshot(
     document,
     createSelectionSnapshot(0, 0),
     MAIN_STORY_TARGET,
   );
-
   const sections = buildResolvedSections(document);
   const pages = buildPageStack(document, sections, mainSurface);
   const headings = buildHeadingOutline(document, mainSurface, sections, pages);
-  const navigationContext = resolveActiveNavigationContext(
-    document,
-    pages,
-    sections,
+  const next = {
     mainSurface,
-    selectionHead,
-    activeStory,
-  );
-
-  return {
-    pageCount: pages.length,
+    sections,
     pages,
     headings,
-    activePageIndex: navigationContext.activePageIndex,
-    activeSectionIndex: navigationContext.activeSectionIndex,
+    styles: document.styles,
+    subParts: document.subParts,
   };
+  navigationBaseCache.set(document.content, next);
+  return next;
 }
 
 /**