@beyondwork/docx-react-component 1.0.29 → 1.0.30

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

@@ -0,0 +1,892 @@
+import {
+  DEFAULT_BOUNDARY_ASSOC,
+  createDetachedAnchor,
+  createNodeAnchor,
+  createRangeAnchor,
+  type EditorAnchorProjection,
+} from "../selection/mapping.ts";
+import { isUuid } from "../../model/cds-1.0.0.ts";
+import {
+  assertPersistedEditorSnapshot as assertModelPersistedEditorSnapshot,
+  createPersistedEditorSnapshot as createModelPersistedEditorSnapshot,
+  validatePersistedEditorSnapshot as validateModelPersistedEditorSnapshot,
+  type ProtectionSnapshotRecord as ModelProtectionSnapshotRecord,
+  type PersistedEditorSnapshot as ModelPersistedEditorSnapshot,
+} from "../../model/snapshot.ts";
+import {
+  assertCanonicalDocument,
+  type CanonicalDocument,
+  type CommentEntry as ModelCommentEntry,
+  type CommentResolution as ModelCommentResolution,
+  type CommentThread as ModelCommentThread,
+  type RevisionMetadataRecord as ModelRevisionMetadataRecord,
+  type RevisionRecord as ModelRevisionRecord,
+} from "../../model/canonical-document.ts";
+
+export type RuntimePhase = "loading" | "ready" | "error";
+export type EditorWarningCode =
+  | "unsupported_ooxml_preserved"
+  | "unsupported_ooxml_locked"
+  | "import_normalized"
+  | "export_roundtrip_risk"
+  | "comment_anchor_detached"
+  | "revision_anchor_detached"
+  | "large_document_degraded"
+  | "font_substitution"
+  | "image_missing";
+
+export interface EditorWarning {
+  warningId: string;
+  code: EditorWarningCode;
+  severity: "info" | "warning";
+  message: string;
+  source:
+    | "import"
+    | "runtime"
+    | "review"
+    | "preservation"
+    | "validation"
+    | "export";
+  affectedAnchor?: EditorAnchorProjection;
+  featureEntryId?: string;
+  details?: Record<string, unknown>;
+}
+
+export interface EditorError {
+  errorId: string;
+  code:
+    | "import_failed"
+    | "export_failed"
+    | "package_corrupt"
+    | "validation_failed"
+    | "datastore_failed"
+    | "internal_invariant";
+  message: string;
+  isFatal: boolean;
+  source: "import" | "runtime" | "validation" | "datastore" | "host" | "export";
+  details?: Record<string, unknown>;
+}
+
+export type CompatibilityFeatureClass =
+  | "supported-roundtrip"
+  | "preserve-only"
+  | "unsupported-fatal";
+
+export interface CompatibilityFeatureEntry {
+  featureEntryId: string;
+  featureKey: string;
+  featureClass: CompatibilityFeatureClass;
+  message: string;
+  affectedAnchor?: EditorAnchorProjection;
+  details?: Record<string, unknown>;
+}
+
+export interface CompatibilityReport {
+  reportVersion: "compatibility-report/1";
+  generatedAt: string;
+  blockExport: boolean;
+  featureEntries: CompatibilityFeatureEntry[];
+  warnings: EditorWarning[];
+  errors: EditorError[];
+}
+
+export type CommentEntryRecord = ModelCommentEntry;
+export type CommentResolutionRecord = ModelCommentResolution;
+export type CommentThreadRecord = ModelCommentThread;
+export type RevisionMetadataRecord = ModelRevisionMetadataRecord;
+export type RevisionRecord = ModelRevisionRecord;
+export type ReviewStore = CanonicalDocument["review"];
+export type CanonicalDocumentEnvelope = CanonicalDocument;
+
+export interface SelectionSnapshot {
+  anchor: number;
+  head: number;
+  isCollapsed: boolean;
+  activeRange: EditorAnchorProjection;
+}
+
+export interface DocumentStats {
+  paragraphCount: number;
+  wordCount: number;
+  characterCount: number;
+  commentCount: number;
+  revisionCount: number;
+}
+
+export interface CommentSidebarSnapshot {
+  activeCommentId?: string;
+  openThreadCount: number;
+  resolvedThreadCount: number;
+  threads: CommentThreadRecord[];
+}
+
+export interface TrackedChangesSnapshot {
+  totalCount: number;
+  pendingCount: number;
+  acceptedCount: number;
+  rejectedCount: number;
+}
+
+export interface CompatibilityPanelSnapshot {
+  report: CompatibilityReport;
+  blockExport: boolean;
+  totalEntries: number;
+}
+
+export interface CommandStateSnapshot {
+  canUndo: boolean;
+  canRedo: boolean;
+  canAddComment: boolean;
+  canAcceptAllChanges: boolean;
+  canRejectAllChanges: boolean;
+}
+
+export interface RuntimeRenderSnapshot {
+  documentId: string;
+  sessionId: string;
+  sourceLabel?: string;
+  revisionToken: string;
+  isReady: boolean;
+  isDirty: boolean;
+  readOnly: boolean;
+  selection: SelectionSnapshot;
+  documentStats: DocumentStats;
+  comments: CommentSidebarSnapshot;
+  trackedChanges: TrackedChangesSnapshot;
+  compatibility: CompatibilityPanelSnapshot;
+  warnings: EditorWarning[];
+  fatalError?: EditorError;
+  commandState: CommandStateSnapshot;
+}
+
+export interface PersistedEditorSnapshot
+  extends Omit<
+    ModelPersistedEditorSnapshot,
+    "canonicalDocument" | "compatibility" | "warningLog"
+  > {
+  canonicalDocument: CanonicalDocumentEnvelope;
+  compatibility: CompatibilityReport;
+  warningLog: EditorWarning[];
+}
+
+export interface EditorRuntimeState {
+  hasFocus: boolean;
+  activeCommentId?: string;
+}
+
+export interface EditorState {
+  phase: RuntimePhase;
+  documentId: string;
+  sessionId: string;
+  sourceLabel?: string;
+  sourcePackage?: ModelPersistedEditorSnapshot["sourcePackage"];
+  revision: number;
+  revisionToken: string;
+  isDirty: boolean;
+  readOnly: boolean;
+  document: CanonicalDocumentEnvelope;
+  selection: SelectionSnapshot;
+  warnings: EditorWarning[];
+  compatibility: CompatibilityReport;
+  fatalError?: EditorError;
+  runtime: EditorRuntimeState;
+}
+
+export interface CreateEditorStateOptions {
+  documentId: string;
+  sessionId: string;
+  sourceLabel?: string;
+  readOnly?: boolean;
+  canonicalDocument?: CanonicalDocumentEnvelope;
+  persistedSnapshot?: PersistedEditorSnapshot;
+  compatibility?: CompatibilityReport;
+  warnings?: EditorWarning[];
+  fatalError?: EditorError;
+}
+
+export function createEmptyReviewStore(): ReviewStore {
+  return {
+    comments: {},
+    revisions: {},
+  };
+}
+
+export function createDefaultCanonicalDocument(
+  documentId: string,
+  timestamp: string,
+): CanonicalDocumentEnvelope {
+  return {
+    schemaVersion: "cds/1.0.0",
+    docId: createCanonicalDocumentId(documentId),
+    createdAt: timestamp,
+    updatedAt: timestamp,
+    metadata: {
+      customProperties: {},
+    },
+    styles: {
+      paragraphs: {},
+      characters: {},
+      tables: {},
+    },
+    numbering: {
+      abstractDefinitions: {},
+      instances: {},
+    },
+    media: {
+      items: {},
+    },
+    content: {
+      type: "doc",
+      children: [{ type: "paragraph", children: [] }],
+    },
+    review: createEmptyReviewStore(),
+    preservation: {
+      opaqueFragments: {},
+      packageParts: {},
+    },
+    diagnostics: {
+      warnings: [],
+      errors: [],
+    },
+  };
+}
+
+export function createSelectionSnapshot(anchor = 0, head = anchor): SelectionSnapshot {
+  return {
+    anchor,
+    head,
+    isCollapsed: anchor === head,
+    activeRange: createRangeAnchor(anchor, head, DEFAULT_BOUNDARY_ASSOC),
+  };
+}
+
+export function createEmptyCompatibilityReport(generatedAt: string): CompatibilityReport {
+  return {
+    reportVersion: "compatibility-report/1",
+    generatedAt,
+    blockExport: false,
+    featureEntries: [],
+    warnings: [],
+    errors: [],
+  };
+}
+
+export function createEditorState(options: CreateEditorStateOptions): EditorState {
+  const timestamp = new Date(0).toISOString();
+  const normalizedSnapshot = options.persistedSnapshot
+    ? normalizePersistedSnapshotForRuntime(options.persistedSnapshot, options.documentId, timestamp)
+    : undefined;
+  if (options.canonicalDocument) {
+    assertCanonicalDocument(options.canonicalDocument as unknown);
+  }
+
+  const normalizedDocument = normalizedSnapshot
+    ? structuredClone(normalizedSnapshot.canonicalDocument)
+    : options.canonicalDocument
+      ? structuredClone(options.canonicalDocument)
+      : createDefaultCanonicalDocument(options.documentId, timestamp);
+  const warnings = normalizedSnapshot
+    ? normalizeWarningLog(normalizedSnapshot.warningLog)
+    : options.warnings ?? [];
+  const compatibility =
+    normalizedSnapshot
+      ? normalizeCompatibilityReport(normalizedSnapshot.compatibility)
+      : options.compatibility ?? createEmptyCompatibilityReport(normalizedDocument.updatedAt);
+
+  return {
+    phase: options.fatalError ? "error" : "ready",
+    documentId: options.documentId,
+    sessionId: options.sessionId,
+    sourceLabel: options.sourceLabel,
+    sourcePackage: normalizedSnapshot?.sourcePackage,
+    revision: 0,
+    revisionToken: `${options.sessionId}:0`,
+    isDirty: false,
+    readOnly: options.readOnly ?? false,
+    document: normalizedDocument,
+    selection: createSelectionSnapshot(),
+    warnings,
+    compatibility,
+    fatalError: options.fatalError,
+    runtime: {
+      hasFocus: false,
+    },
+  };
+}
+
+function normalizePersistedSnapshotForRuntime(
+  snapshot: PersistedEditorSnapshot,
+  documentId: string,
+  timestamp: string,
+): PersistedEditorSnapshot {
+  const issues = validateModelPersistedEditorSnapshot(snapshot as unknown);
+  if (issues.length === 0) {
+    return snapshot;
+  }
+
+  if (!isRecord(snapshot) || !isRecord(snapshot.canonicalDocument)) {
+    assertModelPersistedEditorSnapshot(snapshot as unknown);
+  }
+
+  const normalizedDocument = normalizeCanonicalDocumentEnvelope(
+    snapshot.canonicalDocument,
+    documentId,
+    timestamp,
+  );
+  try {
+    assertCanonicalDocument(normalizedDocument as unknown);
+  } catch {
+    assertModelPersistedEditorSnapshot(snapshot as unknown);
+  }
+  const repairWarning = createSnapshotRepairWarning(issues.length);
+  const compatibility = coerceCompatibilityReport(
+    snapshot.compatibility,
+    normalizedDocument.updatedAt,
+    repairWarning,
+  );
+
+  return {
+    snapshotVersion:
+      snapshot.snapshotVersion === "persisted-editor-snapshot/1" ||
+      snapshot.snapshotVersion === "persisted-editor-snapshot/2"
+        ? snapshot.snapshotVersion
+        : "persisted-editor-snapshot/2",
+    schemaVersion: "cds/1.0.0",
+    documentId:
+      typeof snapshot.documentId === "string" && snapshot.documentId.length > 0
+        ? snapshot.documentId
+        : documentId,
+    docId: normalizedDocument.docId,
+    createdAt: normalizedDocument.createdAt,
+    updatedAt: normalizedDocument.updatedAt,
+    savedAt:
+      typeof snapshot.savedAt === "string" && snapshot.savedAt.length > 0
+        ? snapshot.savedAt
+        : normalizedDocument.updatedAt,
+    editorBuild:
+      typeof snapshot.editorBuild === "string" && snapshot.editorBuild.length > 0
+        ? snapshot.editorBuild
+        : "dev",
+    canonicalDocument: normalizedDocument,
+    compatibility,
+    warningLog: dedupeWarnings([
+      ...coerceWarnings(snapshot.warningLog),
+      repairWarning,
+    ]),
+    sourcePackage: snapshot.sourcePackage,
+  };
+}
+
+function normalizeCanonicalDocumentEnvelope(
+  value: unknown,
+  documentId: string,
+  timestamp: string,
+): CanonicalDocumentEnvelope {
+  const base = createDefaultCanonicalDocument(documentId, timestamp);
+  const record = isRecord(value) ? value : {};
+  const metadata = isRecord(record.metadata) ? record.metadata : {};
+
+  return {
+    ...base,
+    ...record,
+    schemaVersion: "cds/1.0.0",
+    docId: isUuid(record.docId) ? record.docId : createCanonicalDocumentId(documentId),
+    createdAt:
+      typeof record.createdAt === "string" && record.createdAt.length > 0
+        ? record.createdAt
+        : base.createdAt,
+    updatedAt:
+      typeof record.updatedAt === "string" && record.updatedAt.length > 0
+        ? record.updatedAt
+        : base.updatedAt,
+    metadata: {
+      ...base.metadata,
+      ...metadata,
+      customProperties: isRecord(metadata.customProperties)
+        ? (Object.fromEntries(
+            Object.entries(metadata.customProperties).filter(([, entry]) => typeof entry === "string"),
+          ) as Record<string, string>)
+        : {},
+    },
+    styles:
+      record.styles === undefined
+        ? base.styles
+        : (record.styles as CanonicalDocumentEnvelope["styles"]),
+    numbering:
+      record.numbering === undefined
+        ? base.numbering
+        : (record.numbering as CanonicalDocumentEnvelope["numbering"]),
+    media:
+      record.media === undefined
+        ? base.media
+        : (record.media as CanonicalDocumentEnvelope["media"]),
+    content: isRecord(record.content)
+      ? (record.content as unknown as CanonicalDocumentEnvelope["content"])
+      : base.content,
+    review:
+      record.review === undefined
+        ? base.review
+        : (record.review as CanonicalDocumentEnvelope["review"]),
+    preservation:
+      record.preservation === undefined
+        ? base.preservation
+        : (record.preservation as CanonicalDocumentEnvelope["preservation"]),
+    diagnostics:
+      record.diagnostics === undefined
+        ? base.diagnostics
+        : (record.diagnostics as CanonicalDocumentEnvelope["diagnostics"]),
+    ...(isRecord(record.subParts)
+      ? { subParts: record.subParts as unknown as CanonicalDocumentEnvelope["subParts"] }
+      : {}),
+  };
+}
+
+function coerceCompatibilityReport(
+  value: unknown,
+  generatedAt: string,
+  repairWarning: EditorWarning,
+): CompatibilityReport {
+  const record = isRecord(value) ? value : {};
+  const warnings = dedupeWarnings([
+    ...coerceWarnings(record.warnings),
+    repairWarning,
+  ]);
+
+  return {
+    reportVersion: "compatibility-report/1",
+    generatedAt:
+      typeof record.generatedAt === "string" && record.generatedAt.length > 0
+        ? record.generatedAt
+        : generatedAt,
+    blockExport: typeof record.blockExport === "boolean" ? record.blockExport : false,
+    featureEntries: Array.isArray(record.featureEntries)
+      ? record.featureEntries.flatMap((entry) => {
+          if (!isRecord(entry)) {
+            return [];
+          }
+          if (
+            typeof entry.featureEntryId !== "string" ||
+            typeof entry.featureKey !== "string" ||
+            typeof entry.featureClass !== "string" ||
+            typeof entry.message !== "string"
+          ) {
+            return [];
+          }
+          return [{
+            featureEntryId: entry.featureEntryId,
+            featureKey: entry.featureKey,
+            featureClass: entry.featureClass as CompatibilityFeatureEntry["featureClass"],
+            message: entry.message,
+            ...(entry.affectedAnchor && isRecord(entry.affectedAnchor)
+              ? { affectedAnchor: entry.affectedAnchor as unknown as EditorAnchorProjection }
+              : {}),
+            ...(isRecord(entry.details) ? { details: entry.details } : {}),
+          }];
+        })
+      : [],
+    warnings,
+    errors: Array.isArray(record.errors)
+      ? record.errors.flatMap((entry) => {
+          if (!isRecord(entry)) {
+            return [];
+          }
+          if (
+            typeof entry.errorId !== "string" ||
+            typeof entry.code !== "string" ||
+            typeof entry.message !== "string" ||
+            typeof entry.source !== "string" ||
+            typeof entry.isFatal !== "boolean"
+          ) {
+            return [];
+          }
+          return [{
+            errorId: entry.errorId,
+            code: entry.code as EditorError["code"],
+            message: entry.message,
+            source: entry.source as EditorError["source"],
+            isFatal: entry.isFatal,
+            ...(isRecord(entry.details) ? { details: entry.details } : {}),
+          }];
+        })
+      : [],
+  };
+}
+
+function coerceWarnings(value: unknown): EditorWarning[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value.flatMap((warning) => {
+    if (!isRecord(warning)) {
+      return [];
+    }
+    if (
+      typeof warning.warningId !== "string" ||
+      typeof warning.code !== "string" ||
+      typeof warning.severity !== "string" ||
+      typeof warning.message !== "string" ||
+      typeof warning.source !== "string"
+    ) {
+      return [];
+    }
+
+    return [{
+      warningId: warning.warningId,
+      code: warning.code as EditorWarning["code"],
+      severity: warning.severity as EditorWarning["severity"],
+      message: warning.message,
+      source: warning.source as EditorWarning["source"],
+      ...(warning.affectedAnchor && isRecord(warning.affectedAnchor)
+        ? { affectedAnchor: warning.affectedAnchor as unknown as EditorAnchorProjection }
+        : {}),
+      ...(typeof warning.featureEntryId === "string"
+        ? { featureEntryId: warning.featureEntryId }
+        : {}),
+      ...(isRecord(warning.details) ? { details: warning.details } : {}),
+    }];
+  });
+}
+
+function createSnapshotRepairWarning(issueCount: number): EditorWarning {
+  return {
+    warningId: `warning:snapshot-repair:${issueCount}`,
+    code: "import_normalized",
+    severity: "warning",
+    message: `Loaded a persisted snapshot after repairing ${issueCount} validation issue${issueCount === 1 ? "" : "s"}.`,
+    source: "validation",
+  };
+}
+
+function dedupeWarnings(warnings: EditorWarning[]): EditorWarning[] {
+  const seen = new Set<string>();
+  const result: EditorWarning[] = [];
+
+  for (const warning of warnings) {
+    if (!warning.warningId || seen.has(warning.warningId)) {
+      continue;
+    }
+    seen.add(warning.warningId);
+    result.push(warning);
+  }
+
+  return result;
+}
+
+export function deriveDocumentStats(state: Pick<EditorState, "document">): DocumentStats {
+  const serializedContent = extractText(state.document.content);
+
+  return {
+    paragraphCount: estimateParagraphCount(state.document.content),
+    wordCount: serializedContent.trim().length === 0 ? 0 : serializedContent.trim().split(/\s+/u).length,
+    characterCount: Array.from(serializedContent).length,
+    commentCount: Object.keys(state.document.review.comments).length,
+    revisionCount: Object.keys(state.document.review.revisions).length,
+  };
+}
+
+export function deriveRenderSnapshot(
+  state: EditorState,
+  history: { canUndo: boolean; canRedo: boolean },
+): RuntimeRenderSnapshot {
+  const comments = Object.values(state.document.review.comments).sort((left, right) =>
+    left.createdAt.localeCompare(right.createdAt),
+  );
+  const revisions = Object.values(state.document.review.revisions);
+
+  return {
+    documentId: state.documentId,
+    sessionId: state.sessionId,
+    sourceLabel: state.sourceLabel,
+    revisionToken: state.revisionToken,
+    isReady: state.phase === "ready",
+    isDirty: state.isDirty,
+    readOnly: state.readOnly,
+    selection: state.selection,
+    documentStats: deriveDocumentStats(state),
+    comments: {
+      activeCommentId: state.runtime.activeCommentId,
+      openThreadCount: comments.filter((comment) => comment.status === "open").length,
+      resolvedThreadCount: comments.filter((comment) => comment.status === "resolved").length,
+      threads: comments,
+    },
+    trackedChanges: {
+      totalCount: revisions.length,
+      pendingCount: revisions.filter((revision) => revision.status === "open").length,
+      acceptedCount: revisions.filter((revision) => revision.status === "accepted").length,
+      rejectedCount: revisions.filter((revision) => revision.status === "rejected").length,
+    },
+    compatibility: {
+      report: state.compatibility,
+      blockExport: state.compatibility.blockExport,
+      totalEntries: state.compatibility.featureEntries.length,
+    },
+    warnings: state.warnings,
+    fatalError: state.fatalError,
+    commandState: {
+      canUndo: history.canUndo,
+      canRedo: history.canRedo,
+      canAddComment: !state.readOnly,
+      canAcceptAllChanges: revisions.some((revision) => revision.status === "open"),
+      canRejectAllChanges: revisions.some((revision) => revision.status === "open"),
+    },
+  };
+}
+
+export function createPersistedEditorSnapshot(
+  state: EditorState,
+  options: {
+    editorBuild: string;
+    savedAt: string;
+    compatibility?: CompatibilityReport;
+    protectionSnapshot?: ModelProtectionSnapshotRecord;
+  },
+): PersistedEditorSnapshot {
+  const snapshot = createModelPersistedEditorSnapshot({
+    documentId: state.documentId,
+    savedAt: options.savedAt,
+    editorBuild: options.editorBuild,
+    canonicalDocument: state.document,
+    compatibility: (options.compatibility ?? state.compatibility) as never,
+    warningLog: state.warnings as never,
+    protectionSnapshot: options.protectionSnapshot,
+    sourcePackage: state.sourcePackage,
+  });
+  return snapshot as PersistedEditorSnapshot;
+}
+
+function estimateParagraphCount(content: unknown): number {
+  if (Array.isArray(content)) {
+    return content.length;
+  }
+
+  if (content && typeof content === "object" && Array.isArray((content as { blocks?: unknown[] }).blocks)) {
+    return ((content as { blocks: unknown[] }).blocks).length;
+  }
+
+  return extractText(content).length > 0 ? 1 : 0;
+}
+
+function normalizeWarningLog(warnings: EditorWarning[]): EditorWarning[] {
+  return warnings.map((warning) => ({
+    ...warning,
+    affectedAnchor: warning.affectedAnchor
+      ? normalizeAnchorProjection(warning.affectedAnchor)
+      : undefined,
+  }));
+}
+
+function normalizeCompatibilityReport(report: CompatibilityReport): CompatibilityReport {
+  return {
+    ...report,
+    featureEntries: report.featureEntries.map((entry) => ({
+      ...entry,
+      affectedAnchor: entry.affectedAnchor
+        ? normalizeAnchorProjection(entry.affectedAnchor)
+        : undefined,
+    })),
+    warnings: normalizeWarningLog(report.warnings),
+  };
+}
+
+function normalizeAnchorProjection(anchor: EditorAnchorProjection): EditorAnchorProjection {
+  switch (anchor.kind) {
+    case "range": {
+      const rangeAnchor = anchor as EditorAnchorProjection & {
+        range?: { from: number; to: number };
+        from?: number;
+        to?: number;
+        assoc: { start: -1 | 1; end: -1 | 1 };
+      };
+      return rangeAnchor.range
+        ? createRangeAnchor(rangeAnchor.range.from, rangeAnchor.range.to, rangeAnchor.assoc)
+        : createRangeAnchor(rangeAnchor.from ?? 0, rangeAnchor.to ?? 0, rangeAnchor.assoc);
+    }
+    case "node":
+      return createNodeAnchor(anchor.at, anchor.assoc);
+    case "detached":
+      return createDetachedAnchor(anchor.lastKnownRange, anchor.reason);
+  }
+}
+
+function extractText(value: unknown): string {
+  if (typeof value === "string") {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => extractText(item)).join(" ");
+  }
+
+  if (!value || typeof value !== "object") {
+    return "";
+  }
+
+  return Object.values(value as Record<string, unknown>)
+    .map((item) => extractText(item))
+    .filter(Boolean)
+    .join(" ");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+export function createCanonicalDocumentId(documentId: string): string {
+  const hashWord = (seed: string): string => {
+    let hash = 0x811c9dc5;
+    for (const char of seed) {
+      hash ^= char.charCodeAt(0);
+      hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+  };
+
+  const raw =
+    hashWord(`${documentId}:0`) +
+    hashWord(`${documentId}:1`) +
+    hashWord(`${documentId}:2`) +
+    hashWord(`${documentId}:3`);
+
+  return [
+    raw.slice(0, 8),
+    raw.slice(8, 12),
+    `4${raw.slice(13, 16)}`,
+    `8${raw.slice(17, 20)}`,
+    raw.slice(20, 32),
+  ].join("-");
+}
+
+export function normalizeCommentThreadRecord(value: unknown): CommentThreadRecord {
+  const record = isRecord(value) ? value : {};
+  const authorId =
+    typeof record.createdBy === "string" && record.createdBy.length > 0
+      ? record.createdBy
+      : typeof record.authorId === "string" && record.authorId.length > 0
+        ? record.authorId
+        : "unknown";
+  const createdAt =
+    typeof record.createdAt === "string" && record.createdAt.length > 0
+      ? record.createdAt
+      : new Date(0).toISOString();
+  const entries = Array.isArray(record.entries)
+    ? record.entries
+        .filter((entry): entry is Record<string, unknown> => isRecord(entry))
+        .map((entry, index) => ({
+          entryId:
+            typeof entry.entryId === "string" && entry.entryId.length > 0
+              ? entry.entryId
+              : `${String(record.commentId ?? "comment")}-entry-${index + 1}`,
+          authorId:
+            typeof entry.authorId === "string" && entry.authorId.length > 0
+              ? entry.authorId
+              : authorId,
+          body: typeof entry.body === "string" ? entry.body : "",
+          createdAt:
+            typeof entry.createdAt === "string" && entry.createdAt.length > 0
+              ? entry.createdAt
+              : createdAt,
+          metadata: isRecord(entry.metadata)
+            ? {
+                ooxmlCommentId:
+                  typeof entry.metadata.ooxmlCommentId === "string"
+                    ? entry.metadata.ooxmlCommentId
+                    : undefined,
+                paraId:
+                  typeof entry.metadata.paraId === "string"
+                    ? entry.metadata.paraId
+                    : undefined,
+                parentParaId:
+                  typeof entry.metadata.parentParaId === "string"
+                    ? entry.metadata.parentParaId
+                    : undefined,
+                durableId:
+                  typeof entry.metadata.durableId === "string"
+                    ? entry.metadata.durableId
+                    : undefined,
+                initials:
+                  typeof entry.metadata.initials === "string"
+                    ? entry.metadata.initials
+                    : undefined,
+              }
+            : undefined,
+        }))
+    : [
+        {
+          entryId: `${String(record.commentId ?? "comment")}-entry-1`,
+          authorId,
+          body: typeof record.body === "string" ? record.body : "",
+          createdAt,
+        },
+      ];
+  const resolution = isRecord(record.resolution)
+    ? {
+        resolvedAt:
+          typeof record.resolution.resolvedAt === "string"
+            ? record.resolution.resolvedAt
+            : typeof record.resolvedAt === "string"
+              ? record.resolvedAt
+              : createdAt,
+        resolvedBy:
+          typeof record.resolution.resolvedBy === "string" &&
+          record.resolution.resolvedBy.length > 0
+            ? record.resolution.resolvedBy
+            : authorId,
+      }
+    : typeof record.resolvedAt === "string"
+      ? {
+          resolvedAt: record.resolvedAt,
+          resolvedBy: authorId,
+        }
+      : undefined;
+  const normalizedStatus =
+    typeof record.status === "string"
+      ? record.status
+      : record.anchor && isRecord(record.anchor) && record.anchor.kind === "detached"
+        ? "detached"
+        : resolution || record.isResolved
+          ? "resolved"
+          : "open";
+
+  return {
+    commentId:
+      typeof record.commentId === "string" && record.commentId.length > 0
+        ? record.commentId
+        : "comment-generated",
+    anchor:
+      isRecord(record.anchor) && typeof record.anchor.kind === "string"
+        ? (record.anchor as unknown as EditorAnchorProjection)
+        : createDetachedAnchor({ from: 0, to: 0 }, "importAmbiguity"),
+    createdAt,
+    createdBy: authorId,
+    authorId,
+    body: entries.map((entry) => entry.body).join("\n"),
+    entries,
+    status:
+      normalizedStatus === "resolved" || normalizedStatus === "detached"
+        ? normalizedStatus
+        : "open",
+    resolution,
+    resolvedAt: resolution?.resolvedAt,
+    warningIds: Array.isArray(record.warningIds)
+      ? record.warningIds.filter((warningId): warningId is string => typeof warningId === "string")
+      : [],
+    isResolved: normalizedStatus === "resolved",
+    metadata: isRecord(record.metadata)
+      ? {
+          source:
+            record.metadata.source === "import" || record.metadata.source === "runtime"
+              ? record.metadata.source
+              : undefined,
+          rootOoxmlCommentId:
+            typeof record.metadata.rootOoxmlCommentId === "string"
+              ? record.metadata.rootOoxmlCommentId
+              : undefined,
+          rootParaId:
+            typeof record.metadata.rootParaId === "string"
+              ? record.metadata.rootParaId
+              : undefined,
+        }
+      : undefined,
+  };
+}