PRIORITY 1 (REQUIRED): LOCATION
  → We MUST know WHERE the comment/change applies
  → Without location, we cannot place the annotation - ONLY valid skip

PRIORITY 2 (REQUIRED): CONTENT
  → The comment TEXT or changed TEXT must be preserved

PRIORITY 3 (BEST EFFORT): METADATA
  → Author → Use if available, else "imported-unknown"
  → Date → Use if available, else Date.now()

// Golden rule: if we have ANY location marker, preserve the comment
if (!startTokenRange && !endTokenRange) {
  // Only skip when we have NO markers at all
  if (process.env.NODE_ENV !== "production") {
    console.warn("[DOCX Import] Skipping comment with no location markers:", comment.id);
  }
  continue;
}

// Use whichever marker we have, fallback to the other for point comments
const effectiveStartTokenRange = startTokenRange ?? endTokenRange;
const effectiveEndTokenRange = endTokenRange ?? startTokenRange;

// COMMENTS: Always import if we have location
if (!startTokenRange || !endTokenRange) {
  // NO LOCATION = only valid skip
  console.warn("Skipping - no location:", comment.id);
  continue;
}
// Everything else? IMPORT with defaults
const userId = comment.authorName ?? "imported-unknown";
const date = comment.date ? Date.parse(comment.date) : Date.now();
// ... create discussion

// TRACKED CHANGES: Same principle
if (!changeRange) {
  console.warn("Skipping - no location:", change.id);
  continue;
}
const suggestion = {
  userId: change.author ?? "imported-unknown",
  createdAt: change.date ? Date.parse(change.date) : Date.now(),
  // ... rest
};

┌─────────────────────────────────────────────────────────┐
│  PRESERVATION > PRECISION                               │
│                                                         │
│  Better to import with imperfect metadata               │
│  than lose content for "cleaner" code.                  │
└─────────────────────────────────────────────────────────┘

                    IMPORT FLOW
┌──────────┐    ┌─────────────┐    ┌────────────────┐    ┌─────────────┐
│  .docx   │───►│ mammoth.js  │───►│ HTML + Tokens  │───►│Plate Editor │
│  file    │    │ body-reader │    │ [[DOCX_*:...]] │    │ Suggestions │
└──────────┘    │ doc-to-html │    └────────────────┘    │ Comments    │
                └─────────────┘                          └─────────────┘

                    EXPORT FLOW
┌─────────────┐    ┌────────────────┐    ┌───────────────┐    ┌──────────┐
│Plate Editor │───►│ Serialize to   │───►│ docx-export   │───►│  .docx   │
│ Suggestions │    │ Word-safe HTML │    │ kit           │    │  file    │
│ Comments    │    │ <ins>/<del>    │    └───────────────┘    └──────────┘
└─────────────┘    │ Word comments  │
                   └────────────────┘

// ✅ CORRECT - Token positioned inline with content
commentRangeStart: function (element, messages, options) {
  return findHtmlPath(element, htmlPaths.empty).wrap(function () {
    var token = DOCX_COMMENT_START_TOKEN_PREFIX + payload + DOCX_COMMENT_TOKEN_SUFFIX;
    return [Html.text(token)];
  });
},

// ❌ WRONG - Token may appear outside paragraph structure
commentRangeStart: function (element, messages, options) {
  var token = DOCX_COMMENT_START_TOKEN_PREFIX + payload + DOCX_COMMENT_TOKEN_SUFFIX;
  return [Html.text(token)];  // No wrap = wrong position
},

WITHOUT wrap():
  <p>Hello</p>[[DOCX_CMT_START:...]]<p>world</p>
  └─ Token outside paragraph
  └─ After deserialization: token in wrong node or lost
  └─ searchRange() fails → comment not imported

WITH wrap():
  <p>Hello[[DOCX_CMT_START:...]]world</p>
  └─ Token inline with text
  └─ After deserialization: token in same text node as content
  └─ searchRange() succeeds → comment imported correctly

{
  "id": "unique-id",
  "author": "Author Name",
  "date": "2024-01-15T10:30:00Z"
}

{
  "id": "0",
  "authorName": "John Doe",
  "authorInitials": "JD",
  "date": "2024-01-15T10:30:00Z",
  "text": "Comment content here"
}

{
  renderChanges: false,  // Can render tracked changes
  renderComments: false, // Can render comments
  breakPages: true,
  // ...
}

IMPORT:  .docx ──mammoth.js──► HTML+tokens ──Plate──► Editor
EXPORT:  Editor ──serialize──► HTML ──html-to-docx──► .docx
PREVIEW: .docx ──docxjs──► DOM (read-only)

if (!startTokenRange || !endTokenRange) {
  // MUST clean up orphan tokens
  if (startTokenRange) editor.tf.delete({ at: startTokenRange });
  if (endTokenRange) editor.tf.delete({ at: endTokenRange });
  continue; // But don't fail the whole import
}

// CORRECT - Use author name directly
const userId = authorName ?? "imported-unknown";

// WRONG - Don't do this
const user = await findUserByEmail(authorEmail);
const userId = user?.id; // ❌ Will fail for external authors

// Ranges can become stale after node-splitting operations
const startTokenRef = editor.api.rangeRef(startTokenRange);
const endTokenRef = editor.api.rangeRef(endTokenRange);

// After operations, get current ranges
const currentStart = startTokenRef.current;
const currentEnd = endTokenRef.current;

// Always unref when done
startTokenRef.unref();
endTokenRef.unref();

var comment = comments[reference.commentId];
if (!comment) {
  messages.push(results.warning("Comment not found: " + reference.commentId));
  comment = { commentId: reference.commentId, body: [], authorInitials: "" };
}

import { logger } from "@/lib/logger";

// For warnings (e.g., skipped items, fallbacks used)
// Uses logfire.warning() under the hood
logger.warning("[DOCX Import] Failed to parse token", {
  rawPayload,
  error: e,
});

// For errors (e.g., failed operations)
// Uses logfire.error() under the hood
logger.error("[DOCX Import] Failed to create comment", e, {
  commentId: comment.id,
  documentId,
});

// For info (e.g., successful operations)
// Uses logfire.info() under the hood
logger.info("[DOCX Import] Import completed", {
  commentsCreated,
  insertions,
  deletions,
});

{
  [KEYS.suggestion]: true,
  [getSuggestionKey(id)]: {
    id: string,
    type: "insert" | "remove",
    userId: string,
    createdAt: number
  }
}

{
  [KEYS.comment]: true,
  [getCommentKey(discussionId)]: true,
  [getTransientCommentKey()]: true // During creation
}

// Force cleanup of all remaining tokens
const tokenPatterns = [
  /\[\[DOCX_INS_START:.*?\]\]/g,
  /\[\[DOCX_INS_END:.*?\]\]/g,
  /\[\[DOCX_DEL_START:.*?\]\]/g,
  /\[\[DOCX_DEL_END:.*?\]\]/g,
  /\[\[DOCX_CMT_START:.*?\]\]/g,
  /\[\[DOCX_CMT_END:.*?\]\]/g,
];
// Search and delete each match