Design a Collaborative Document Editor (Google Docs)

/docs                    → Document list
/docs/:id                → Document editor (main experience)
/docs/:id/history        → Version history view
/docs/:id/history/:vId   → Specific version with diff

┌─────────────────────────────────────────────────────────┐
│ DocumentEditor (root)                                    │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │ EditorChrome (toolbar + sidebar frame)           │   │
│  │  ┌───────────────────────────────────────────┐  │   │
│  │  │ FormattingToolbar                         │  │   │
│  │  │  [B] [I] [U] [S] [Code] [Link] [Color]  │  │   │
│  │  │  [H1] [H2] [H3] [•] [1.] [☐] [<>]      │  │   │
│  │  └───────────────────────────────────────────┘  │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  ┌──────────────────────────┐ ┌──────────────────────┐ │
│  │ EditorCanvas              │ │ CommentSidebar       │ │
│  │  ┌────────────────────┐  │ │  ┌────────────────┐ │ │
│  │  │ BlockRenderer[]    │  │ │  │ CommentThread  │ │ │
│  │  │  - ParagraphBlock │  │ │  │ CommentThread  │ │ │
│  │  │  - HeadingBlock    │  │ │  │ CommentThread  │ │ │
│  │  │  - ListBlock       │  │ │  └────────────────┘ │ │
│  │  │  - CodeBlock       │  │ └──────────────────────┘ │
│  │  │  - ImageBlock      │  │                          │
│  │  │  - TableBlock      │  │ ┌──────────────────────┐ │
│  │  │  - EmbedBlock      │  │ │ VersionHistoryPanel  │ │
│  │  └────────────────────┘  │ │  ┌────────────────┐ │ │
│  │  ┌────────────────────┐  │ │  │ VersionList    │ │ │
│  │  │ SlashCommandMenu   │  │ │  │ DiffViewer     │ │ │
│  │  └────────────────────┘  │ │  └────────────────┘ │ │
│  │  ┌────────────────────┐  │ └──────────────────────┘ │
│  │  │ SelectionToolbar   │  │                          │
│  │  └────────────────────┘  │                          │
│  └──────────────────────────┘                          │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │ StatusBar                                        │   │
│  │  [Saving...] [3 collaborators] [Word count]     │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

┌────────────────────────────────────────────┐
│ Layer 1: Document Model (EditorState)       │
│ - Block tree with content and marks         │
│ - Selection state                           │
│ - Immutable — changes via transactions      │
├────────────────────────────────────────────┤
│ Layer 2: Collaboration State                │
│ - Remote cursors and selections             │
│ - Pending/unconfirmed local operations      │
│ - Awareness (who is viewing what)           │
├────────────────────────────────────────────┤
│ Layer 3: UI State (Zustand)                 │
│ - Sidebar open/closed                       │
│ - Active comment thread                     │
│ - Version history panel state               │
│ - Slash command menu position               │
├────────────────────────────────────────────┤
│ Layer 4: Derived/Computed State             │
│ - Toolbar formatting indicators             │
│ - Table of contents                         │
│ - Word/character count                      │
│ - Comment position anchors                  │
└────────────────────────────────────────────┘

/** Union of all block types in the document */
type BlockType =
  | "paragraph"
  | "heading"
  | "bulletList"
  | "numberedList"
  | "todoList"
  | "toggleList"
  | "codeBlock"
  | "blockquote"
  | "callout"
  | "image"
  | "video"
  | "embed"
  | "table"
  | "divider"
  | "mathBlock";

/** Inline formatting marks */
type MarkType =
  | "bold"
  | "italic"
  | "underline"
  | "strikethrough"
  | "code"
  | "link"
  | "highlight"
  | "textColor"
  | "comment" // marks text that has an associated comment
  | "suggestion"; // marks text involved in a suggestion

/** A single mark instance with optional attributes */
interface Mark {
  type: MarkType;
  attrs?: Record<string, unknown>;
  // link: { href: string; title?: string }
  // highlight: { color: string }
  // comment: { commentId: string }
  // suggestion: { suggestionId: string; type: 'insert' | 'delete' }
}

/** Inline content — a run of text with formatting */
interface TextNode {
  type: "text";
  text: string;
  marks: Mark[];
}

/** An inline image or mention within text */
interface InlineNode {
  type: "mention" | "emoji" | "inlineImage";
  attrs: Record<string, unknown>;
}

type InlineContent = TextNode | InlineNode;

/** A block in the document tree */
interface Block {
  id: string; // stable unique ID (nanoid)
  type: BlockType;
  attrs: BlockAttrs; // type-specific attributes
  content: InlineContent[]; // inline text content (for text blocks)
  children: Block[]; // nested blocks (lists, toggles, table cells)
  meta: {
    createdAt: number;
    createdBy: string;
    updatedAt: number;
  };
}

/** Type-specific block attributes */
interface HeadingAttrs {
  level: 1 | 2 | 3;
}

interface CodeBlockAttrs {
  language: string;
  lineNumbers: boolean;
}

interface ImageAttrs {
  src: string;
  alt: string;
  width: number;
  height: number;
  caption?: string;
}

interface TableAttrs {
  columnWidths: number[]; // percentage widths
}

interface EmbedAttrs {
  url: string;
  provider: string; // 'figma' | 'loom' | 'youtube' | ...
  width: number;
  height: number;
}

interface CalloutAttrs {
  emoji: string;
  color: "blue" | "green" | "yellow" | "red" | "purple";
}

type BlockAttrs =
  | HeadingAttrs
  | CodeBlockAttrs
  | ImageAttrs
  | TableAttrs
  | EmbedAttrs
  | CalloutAttrs
  | Record<string, unknown>;

/** The root document */
interface Document {
  id: string;
  title: string;
  blocks: Block[]; // top-level blocks
  version: number; // monotonically increasing
  createdAt: string;
  updatedAt: string;
  createdBy: string;
  collaborators: Collaborator[];
}

interface Comment {
  id: string;
  documentId: string;
  /** Anchor: the block ID and character range this comment refers to */
  anchor: {
    blockId: string;
    from: number; // character offset in block
    to: number;
  };
  content: string; // markdown-supported comment text
  author: User;
  createdAt: string;
  resolvedAt?: string;
  resolvedBy?: User;
  replies: CommentReply[];
}

interface CommentReply {
  id: string;
  content: string;
  author: User;
  createdAt: string;
}

interface Suggestion {
  id: string;
  documentId: string;
  type: "insert" | "delete" | "replace" | "formatChange";
  /** The range being modified */
  anchor: {
    blockId: string;
    from: number;
    to: number;
  };
  /** The proposed new content (for insert/replace) */
  proposedContent?: InlineContent[];
  /** The proposed formatting change */
  proposedMarks?: Mark[];
  author: User;
  createdAt: string;
  status: "pending" | "accepted" | "rejected";
}

interface DocumentVersion {
  id: string;
  documentId: string;
  versionNumber: number;
  /** Named versions are user-created; auto versions are system-created */
  type: "named" | "auto";
  title?: string; // user-provided name for named versions
  snapshot: Block[]; // full document state at this version (or delta reference)
  createdAt: string;
  createdBy: string;
  /** Summary of changes from previous version */
  changeSummary: {
    blocksAdded: number;
    blocksDeleted: number;
    blocksModified: number;
    wordsAdded: number;
    wordsDeleted: number;
  };
}

interface VersionDiff {
  /** Per-block diffs */
  blockDiffs: BlockDiff[];
}

interface BlockDiff {
  blockId: string;
  type: "added" | "removed" | "modified" | "moved";
  /** For modified blocks: inline text diff */
  textChanges?: Array<{
    type: "insert" | "delete" | "retain";
    content: string;
  }>;
}

type PermissionLevel = "viewer" | "commenter" | "editor" | "owner";

interface ShareSettings {
  documentId: string;
  /** Public link sharing */
  linkSharing: {
    enabled: boolean;
    permission: PermissionLevel;
    expiresAt?: string;
  };
  /** Individual user permissions */
  userPermissions: Array<{
    userId: string;
    email: string;
    permission: PermissionLevel;
    addedAt: string;
    addedBy: string;
  }>;
  /** Workspace-level default */
  workspaceDefault: PermissionLevel | "none";
}

// GET /api/documents/:id
interface GetDocumentResponse {
  document: Document;
  permissions: PermissionLevel;
  collaborators: ActiveCollaborator[];
}

// POST /api/documents
interface CreateDocumentRequest {
  title: string;
  templateId?: string; // clone from template
  workspaceId: string;
}

// PATCH /api/documents/:id
interface UpdateDocumentRequest {
  title?: string;
  icon?: string;
  coverImage?: string;
}

// POST /api/documents/:id/operations
// Batched block mutations (typically sent via WebSocket, REST as fallback)
interface OperationBatch {
  documentId: string;
  baseVersion: number; // optimistic concurrency
  operations: Operation[];
}

type Operation =
  | { type: "insertBlock"; parentId: string; index: number; block: Block }
  | { type: "deleteBlock"; blockId: string }
  | {
      type: "moveBlock";
      blockId: string;
      newParentId: string;
      newIndex: number;
    }
  | { type: "updateBlockAttrs"; blockId: string; attrs: Partial<BlockAttrs> }
  | {
      type: "insertText";
      blockId: string;
      offset: number;
      text: string;
      marks: Mark[];
    }
  | { type: "deleteText"; blockId: string; from: number; to: number }
  | { type: "addMark"; blockId: string; from: number; to: number; mark: Mark }
  | {
      type: "removeMark";
      blockId: string;
      from: number;
      to: number;
      markType: MarkType;
    };

interface OperationBatchResponse {
  accepted: boolean;
  serverVersion: number;
  /** If rejected, client must rebase on these missed operations */
  missedOperations?: Operation[];
}

// GET /api/documents/:id/comments
interface GetCommentsResponse {
  comments: Comment[];
  total: number;
}

// POST /api/documents/:id/comments
interface CreateCommentRequest {
  anchor: { blockId: string; from: number; to: number };
  content: string;
}

// POST /api/documents/:id/comments/:commentId/replies
interface CreateReplyRequest {
  content: string;
}

// PATCH /api/documents/:id/comments/:commentId/resolve
interface ResolveCommentRequest {
  resolved: boolean;
}

// GET /api/documents/:id/versions?type=named|auto&limit=20&cursor=...
interface GetVersionsResponse {
  versions: DocumentVersion[];
  nextCursor?: string;
}

// POST /api/documents/:id/versions
interface CreateNamedVersionRequest {
  title: string;
}

// GET /api/documents/:id/versions/:versionId/diff?compareWith=:otherId
interface GetVersionDiffResponse {
  diff: VersionDiff;
  fromVersion: Pick<DocumentVersion, "id" | "versionNumber" | "createdAt">;
  toVersion: Pick<DocumentVersion, "id" | "versionNumber" | "createdAt">;
}

// POST /api/documents/:id/versions/:versionId/restore
interface RestoreVersionResponse {
  newVersion: number;
  document: Document;
}

// GET /api/documents/:id/sharing
interface GetSharingResponse {
  settings: ShareSettings;
}

// PATCH /api/documents/:id/sharing/link
interface UpdateLinkSharingRequest {
  enabled: boolean;
  permission: PermissionLevel;
  expiresAt?: string;
}

// POST /api/documents/:id/sharing/users
interface AddUserPermissionRequest {
  email: string;
  permission: PermissionLevel;
}

// DELETE /api/documents/:id/sharing/users/:userId
// 204 No Content

/** Client → Server messages */
type ClientMessage =
  | { type: "join"; documentId: string; token: string }
  | { type: "operations"; batch: OperationBatch }
  | { type: "cursor"; position: CursorPosition }
  | { type: "awareness"; state: AwarenessState };

/** Server → Client messages */
type ServerMessage =
  | { type: "joined"; documentState: Document; version: number; peers: Peer[] }
  | {
      type: "operations";
      peerId: string;
      operations: Operation[];
      version: number;
    }
  | { type: "cursor"; peerId: string; position: CursorPosition }
  | { type: "peerJoined"; peer: Peer }
  | { type: "peerLeft"; peerId: string }
  | { type: "ack"; version: number }
  | { type: "reject"; reason: string; serverVersion: number };

interface CursorPosition {
  blockId: string;
  offset: number;
  /** If selection, also include anchor */
  anchorBlockId?: string;
  anchorOffset?: number;
}

interface AwarenessState {
  user: { name: string; color: string; avatar?: string };
  activeBlockId?: string;
}

/**
 * Multi-layer caching for document content:
 *
 * L1: In-memory EditorState (current session)
 * L2: IndexedDB (offline persistence + fast reload)
 * L3: Service Worker cache (document metadata, images)
 * L4: CDN (static assets, embed thumbnails)
 */

interface DocumentCache {
  /** Current document state — always in memory during editing */
  editorState: EditorState;

  /** Persisted to IndexedDB for offline and fast reload */
  persistedState: {
    document: Document;
    lastSyncedVersion: number;
    pendingOperations: Operation[]; // not yet acknowledged by server
    lastSavedAt: number;
  };
}

class AutosaveManager {
  private saveTimer: ReturnType<typeof setTimeout> | null = null;
  private readonly SAVE_INTERVAL = 5000; // 5 seconds
  private readonly IDLE_SAVE_DELAY = 1000; // save 1s after last keystroke

  /**
   * Strategy:
   * 1. After every transaction, reset the idle timer
   * 2. If idle timer fires (1s of no changes), save immediately
   * 3. If user keeps typing, force-save every 5s regardless
   * 4. On visibility change (tab blur), save immediately
   * 5. On beforeunload, synchronous save to IndexedDB
   */
  onTransaction(tr: Transaction): void {
    if (!tr.docChanged) return;

    // Reset idle timer
    this.resetIdleTimer();

    // Ensure max interval save
    if (!this.saveTimer) {
      this.saveTimer = setTimeout(() => this.save(), this.SAVE_INTERVAL);
    }
  }

  private resetIdleTimer(): void {
    clearTimeout(this.idleTimer);
    this.idleTimer = setTimeout(() => this.save(), this.IDLE_SAVE_DELAY);
  }

  private async save(): Promise<void> {
    this.saveTimer = null;
    const ops = this.getPendingOperations();
    // 1. Persist to IndexedDB (always succeeds, offline-safe)
    await this.persistToIndexedDB(ops);
    // 2. Attempt server sync (may fail if offline)
    try {
      await this.syncToServer(ops);
    } catch {
      // Operations remain in IndexedDB pending queue
      // Will retry on reconnect
    }
  }
}

interface OfflineStorage {
  /** Full document snapshot for offline viewing/editing */
  getDocument(id: string): Promise<Document | null>;
  putDocument(doc: Document): Promise<void>;

  /** Operation queue for changes made while offline */
  getPendingOps(docId: string): Promise<Operation[]>;
  appendOps(docId: string, ops: Operation[]): Promise<void>;
  clearOps(docId: string, upToVersion: number): Promise<void>;

  /** Image blobs cached for offline */
  getImage(url: string): Promise<Blob | null>;
  putImage(url: string, blob: Blob): Promise<void>;
}

// Implementation uses IndexedDB with structured stores:
// - documents: { id, data, version, updatedAt }
// - operations: { docId, ops[], createdAt }
// - images: { url, blob, cachedAt }

class ImageUploadManager {
  async insertImage(file: File, blockId: string): Promise<void> {
    // 1. Create local blob URL for instant display
    const localUrl = URL.createObjectURL(file);
    this.editor.updateBlockAttrs(blockId, { src: localUrl, uploading: true });

    // 2. Upload in background
    const permanentUrl = await this.uploadToStorage(file);

    // 3. Replace blob URL with permanent URL
    this.editor.updateBlockAttrs(blockId, {
      src: permanentUrl,
      uploading: false,
    });

    // 4. Cache the permanent URL in Service Worker
    await this.cacheImage(permanentUrl, file);

    // 5. Revoke blob URL
    URL.revokeObjectURL(localUrl);
  }
}

/**
 * Version history uses cursor-based pagination with a local cache:
 * - First page (latest 20 versions) cached in memory
 * - Older versions fetched on demand and cached in session storage
 * - Full version snapshots are NOT preloaded — fetched only when user views diff
 */
const versionHistoryCache = new Map<string, DocumentVersion[]>();

async function loadVersionHistory(
  docId: string,
  cursor?: string,
): Promise<{ versions: DocumentVersion[]; nextCursor?: string }> {
  const cacheKey = `${docId}:${cursor ?? "initial"}`;
  if (versionHistoryCache.has(cacheKey)) {
    return { versions: versionHistoryCache.get(cacheKey)!, nextCursor: cursor };
  }

  const response = await api.getVersions(docId, { cursor, limit: 20 });
  versionHistoryCache.set(cacheKey, response.versions);
  return response;
}

interface VirtualizedEditor {
  /** Only blocks within viewport + buffer are rendered */
  visibleRange: { startIndex: number; endIndex: number };
  /** Buffer above and below viewport (in blocks) */
  overscan: number; // typically 10-20 blocks
  /** Estimated height for unrendered blocks */
  estimatedBlockHeight: number; // 40px default
  /** Measured heights for rendered blocks (cached) */
  measuredHeights: Map<string, number>;
}

/**
 * Virtualization strategy:
 * 1. Render blocks within viewport + 20-block overscan
 * 2. Use spacer divs above/below for scroll height
 * 3. Measure block heights after render, cache them
 * 4. On scroll, recalculate visible range
 * 5. Keep DOM node count under 500 at all times
 *
 * Exception: Active editing block and its neighbors are ALWAYS
 * rendered regardless of viewport position (prevents janky typing)
 */

┌─────────────────────────────────┐
│ Spacer (estimated height)        │ ← Blocks 0-45 (not rendered)
├─────────────────────────────────┤
│ Block 46                         │ ┐
│ Block 47                         │ │ Overscan (above)
│ ...                              │ │
│ Block 55                         │ ┘
├─────────────────────────────────┤
│ Block 56                         │ ┐
│ Block 57                         │ │
│ ...                              │ │ Viewport (visible)
│ Block 85                         │ │
│ Block 86                         │ ┘
├─────────────────────────────────┤
│ Block 87                         │ ┐
│ ...                              │ │ Overscan (below)
│ Block 96                         │ ┘
├─────────────────────────────────┤
│ Spacer (estimated height)        │ ← Blocks 97-2500 (not rendered)
└─────────────────────────────────┘

/**
 * Efficient toolbar state derivation:
 * 1. On selection change, gather marks at cursor position (single point)
 *    or intersection of marks across selection range
 * 2. Use the editor's storedMarks (ProseMirror concept) for empty selections
 * 3. Cache the result — only recompute when selection actually changes
 * 4. Toolbar subscribes to this derived state, NOT to the full document
 */

function deriveToolbarState(state: EditorState): ToolbarState {
  const { from, to, empty } = state.selection;

  if (empty) {
    // At cursor: use stored marks or marks at position
    const marks = state.storedMarks ?? state.doc.resolve(from).marks();
    return marksToToolbarState(marks);
  }

  // Range selection: find intersection of marks across all positions
  const activeMarks = new Set<MarkType>(ALL_MARK_TYPES);
  state.doc.nodesBetween(from, to, (node) => {
    if (node.isText) {
      const nodeMarks = new Set(node.marks.map((m) => m.type.name));
      for (const mark of activeMarks) {
        if (!nodeMarks.has(mark)) activeMarks.delete(mark);
      }
    }
  });

  return { activeMarks, blockType: getBlockTypeAtSelection(state) };
}

interface RemoteCursor {
  peerId: string;
  user: { name: string; color: string };
  position: { blockId: string; offset: number };
  selection?: { anchorBlockId: string; anchorOffset: number };
}

/**
 * Remote cursors are rendered as:
 * 1. A colored caret (2px wide div, positioned absolutely)
 * 2. A name label above the caret (appears on hover or activity)
 * 3. A colored highlight for selections
 *
 * Implementation: ProseMirror DecorationSet
 * - Decorations are computed from collaboration state
 * - They overlay the document without modifying it
 * - Positioned using the editor's coordsAtPos() method
 */

function createRemoteCursorDecoration(cursor: RemoteCursor): Decoration {
  const widget = document.createElement("span");
  widget.className = "remote-cursor";
  widget.style.borderLeft = `2px solid ${cursor.user.color}`;
  widget.setAttribute("data-name", cursor.user.name);
  return Decoration.widget(cursorPos, widget, { side: 1 });
}

/**
 * Images in the document use intersection observer for lazy loading:
 * 1. Below-the-fold images render as placeholder (blur-up thumbnail)
 * 2. When block enters viewport + 500px buffer, full image loads
 * 3. Images use srcset for responsive sizing
 * 4. Failed loads show a retry button, not a broken image icon
 */

function ImageBlock({ attrs }: { attrs: ImageAttrs }) {
  const [loaded, setLoaded] = useState(false);
  const ref = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const observer = new IntersectionObserver(
      ([entry]) => {
        if (entry.isIntersecting) {
          setLoaded(true);
          observer.disconnect();
        }
      },
      { rootMargin: '500px' },
    );
    if (ref.current) observer.observe(ref.current);
    return () => observer.disconnect();
  }, []);

  return (
    <div ref={ref} style={{ aspectRatio: `${attrs.width}/${attrs.height}` }}>
      {loaded ? (
        <img src={attrs.src} alt={attrs.alt} loading="lazy" />
      ) : (
        <div className="bg-muted animate-pulse" />
      )}
    </div>
  );
}

/**
 * Paste sanitization pipeline:
 * 1. Intercept paste event
 * 2. If HTML content, parse through DOMParser
 * 3. Walk the DOM tree, keeping ONLY allowlisted elements and attributes
 * 4. Convert sanitized HTML to editor blocks
 * 5. Insert blocks through the normal transaction pipeline
 */

const ALLOWED_ELEMENTS = new Set([
  "p",
  "h1",
  "h2",
  "h3",
  "h4",
  "h5",
  "h6",
  "ul",
  "ol",
  "li",
  "blockquote",
  "pre",
  "code",
  "strong",
  "em",
  "u",
  "s",
  "a",
  "br",
  "table",
  "thead",
  "tbody",
  "tr",
  "th",
  "td",
  "img",
]);

const ALLOWED_ATTRIBUTES: Record<string, Set<string>> = {
  a: new Set(["href", "title"]),
  img: new Set(["src", "alt", "width", "height"]),
  td: new Set(["colspan", "rowspan"]),
  th: new Set(["colspan", "rowspan"]),
};

function sanitizePastedHtml(html: string): string {
  const doc = new DOMParser().parseFromString(html, "text/html");
  const walker = document.createTreeWalker(doc.body, NodeFilter.SHOW_ELEMENT);

  const nodesToRemove: Node[] = [];
  let node: Node | null = walker.currentNode;

  while (node) {
    if (node.nodeType === Node.ELEMENT_NODE) {
      const el = node as Element;
      const tag = el.tagName.toLowerCase();

      if (!ALLOWED_ELEMENTS.has(tag)) {
        nodesToRemove.push(el);
      } else {
        // Strip all attributes not in allowlist
        const allowed = ALLOWED_ATTRIBUTES[tag] ?? new Set();
        for (const attr of Array.from(el.attributes)) {
          if (!allowed.has(attr.name)) {
            el.removeAttribute(attr.name);
          }
        }
        // Validate href — only http/https/mailto
        if (tag === "a") {
          const href = el.getAttribute("href") ?? "";
          if (!/^(https?:|mailto:)/i.test(href)) {
            el.removeAttribute("href");
          }
        }
        // Validate img src — only https
        if (tag === "img") {
          const src = el.getAttribute("src") ?? "";
          if (!/^https:/i.test(src)) {
            el.removeAttribute("src");
          }
        }
      }
    }
    node = walker.nextNode();
  }

  // Remove disallowed nodes (replace with their text content)
  for (const n of nodesToRemove) {
    const text = document.createTextNode(n.textContent ?? "");
    n.parentNode?.replaceChild(text, n);
  }

  return doc.body.innerHTML;
}

/**
 * Capability URLs for document sharing:
 * - Token: 22-character base62 (128 bits of entropy)
 * - URL: /docs/share/{token}
 * - Token is NOT the document ID — it maps to a permission record
 * - Tokens can be revoked without changing the document URL
 * - Rate limit: 10 share link accesses per IP per minute
 * - Honeypot: invalid tokens log the attempt for abuse detection
 */

function generateShareToken(): string {
  const bytes = crypto.getRandomValues(new Uint8Array(16));
  return base62Encode(bytes); // 22 characters
}

Content-Security-Policy:
  default-src 'self';
  script-src 'self' 'wasm-unsafe-eval';
  style-src 'self' 'unsafe-inline';
  img-src 'self' https://images.docs.example.com blob: data:;
  connect-src 'self' wss://collab.docs.example.com;
  frame-src https://embed.docs.example.com;
  object-src 'none';
  base-uri 'self';

/**
 * Embed isolation strategy:
 * 1. All third-party embeds load through our proxy: embed.docs.example.com
 * 2. Embed iframes have sandbox="allow-scripts allow-same-origin"
 * 3. No allow-top-navigation — embeds cannot redirect the parent
 * 4. Communication with embeds via postMessage with origin validation
 * 5. Embed URLs are validated against an allowlist of providers
 */

const EMBED_PROVIDERS: Record<string, { urlPattern: RegExp; sandbox: string }> =
  {
    figma: {
      urlPattern: /^https:\/\/(www\.)?figma\.com\/(file|proto|design)\//,
      sandbox: "allow-scripts allow-same-origin allow-popups",
    },
    youtube: {
      urlPattern: /^https:\/\/(www\.)?youtube\.com\/embed\//,
      sandbox: "allow-scripts allow-same-origin",
    },
    loom: {
      urlPattern: /^https:\/\/(www\.)?loom\.com\/embed\//,
      sandbox: "allow-scripts allow-same-origin",
    },
  };

/**
 * Operation compression strategies:
 *
 * 1. Character-level batching:
 *    Typing "hello" generates 5 insertText operations.
 *    Compress to 1 operation: insertText("hello") before sending.
 *    Batch window: 50ms or until next non-text operation.
 *
 * 2. Inverse cancellation:
 *    Type "a" then delete it → net zero, drop both operations.
 *
 * 3. Mark coalescing:
 *    Select range, apply bold, then italic → send single combined operation.
 *
 * 4. Move compression:
 *    Drag-and-drop generates delete + insert → compress to single move.
 */

function compressOperations(ops: Operation[]): Operation[] {
  const compressed: Operation[] = [];

  for (let i = 0; i < ops.length; i++) {
    const current = ops[i];
    const last = compressed[compressed.length - 1];

    if (
      current.type === "insertText" &&
      last?.type === "insertText" &&
      last.blockId === current.blockId &&
      last.offset + last.text.length === current.offset &&
      marksEqual(last.marks, current.marks)
    ) {
      // Merge consecutive inserts in the same block
      last.text += current.text;
    } else if (
      current.type === "deleteText" &&
      last?.type === "insertText" &&
      last.blockId === current.blockId &&
      current.from === last.offset &&
      current.to === last.offset + last.text.length
    ) {
      // Insert followed by delete of same content = no-op
      compressed.pop();
    } else {
      compressed.push({ ...current });
    }
  }

  return compressed;
}

┌─────────────────────────────────────────────────────────┐
│                   Autosave Pipeline                       │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  User types → Transaction → [Operation Buffer]          │
│                                    │                    │
│                          ┌─────────┴─────────┐         │
│                          ▼                   ▼          │
│                    IndexedDB             Server Sync     │
│                    (ALWAYS)              (best-effort)   │
│                          │                   │          │
│                          │            ┌──────┴──────┐   │
│                          │            │ Online?     │   │
│                          │            ├─────────────┤   │
│                          │            │ Yes → POST  │   │
│                          │            │ No → Queue  │   │
│                          │            └─────────────┘   │
│                          │                              │
│                          ▼                              │
│              Local state is ALWAYS                       │
│              consistent and recoverable                  │
│                                                         │
└─────────────────────────────────────────────────────────┘

/**
 * Offline editing flow:
 *
 * 1. User goes offline (detected via navigator.onLine + WebSocket disconnect)
 * 2. Editor continues working normally — all operations go to IndexedDB
 * 3. Status bar shows "Offline — changes saved locally"
 * 4. On reconnect:
 *    a. Fetch server's current version
 *    b. If server version > our last synced version, fetch missed operations
 *    c. Rebase our pending operations on top of missed operations
 *    d. Send rebased operations to server
 *    e. If rebase fails (structural conflict), show merge UI
 */

async function reconnectSync(docId: string): Promise<void> {
  const local = await offlineStorage.getPendingOps(docId);
  const lastSynced = await offlineStorage.getLastSyncedVersion(docId);

  // Fetch what we missed
  const serverState = await api.getDocumentSince(docId, lastSynced);

  if (serverState.version === lastSynced) {
    // No server changes — just send our operations
    await api.sendOperations(docId, local);
  } else {
    // Rebase our operations on top of server changes
    const rebased = rebaseOperations(local, serverState.missedOperations);
    if (rebased.conflicts.length === 0) {
      await api.sendOperations(docId, rebased.operations);
    } else {
      // Show conflict resolution UI for structural conflicts
      showMergeDialog(rebased.conflicts);
    }
  }
}

<!-- The editor's root element -->
<div
  role="textbox"
  aria-multiline="true"
  aria-label="Document editor"
  aria-describedby="editor-status"
  contenteditable="true"
>
  <!-- Block content rendered here -->
</div>

<!-- Live region for status updates -->
<div id="editor-status" aria-live="polite" aria-atomic="true">
  <!-- "Saving..." / "All changes saved" / "3 collaborators editing" -->
</div>

/**
 * Heading navigation features:
 * 1. Document outline panel (role="navigation", aria-label="Document outline")
 * 2. Cmd+Shift+H opens a heading jump menu (similar to VS Code's Cmd+Shift+O)
 * 3. All headings use proper <h1>-<h3> elements (not styled divs)
 * 4. aria-level attribute matches the heading level
 */

function HeadingBlock({ level, content }: { level: 1 | 2 | 3; content: InlineContent[] }) {
  const Tag = `h${level}` as const;
  return (
    <Tag aria-level={level} data-block-type="heading">
      <InlineRenderer content={content} />
    </Tag>
  );
}

/**
 * Table keyboard navigation:
 * - Tab: move to next cell (left-to-right, top-to-bottom)
 * - Shift+Tab: move to previous cell
 * - Arrow keys: move between cells when cursor is at cell boundary
 * - Enter: new line within cell (not next row)
 * - Escape: exit table, move cursor after table block
 *
 * ARIA:
 * - table: role="grid" (allows arrow key navigation)
 * - cells: role="gridcell" with aria-colindex and aria-rowindex
 * - header cells: role="columnheader" or "rowheader"
 */

<!-- Comment sidebar -->
<aside aria-label="Comments" role="complementary">
  <h2 id="comments-heading">Comments</h2>
  <div role="feed" aria-labelledby="comments-heading">
    <!-- Each thread -->
    <article aria-label="Comment by Alice on paragraph 3" role="article">
      <p>This should use a different approach...</p>
      <!-- Replies -->
      <div role="feed" aria-label="Replies">
        <article aria-label="Reply by Bob">
          <p>Agreed, let me update this.</p>
        </article>
      </div>
      <button aria-label="Reply to this comment">Reply</button>
      <button aria-label="Resolve this comment">Resolve</button>
    </article>
  </div>
</aside>

/**
 * When suggestions mode is active:
 * 1. Announce mode change: "Suggestions mode active. Your changes will be proposed, not applied directly."
 * 2. Each suggestion is marked with aria-description:
 *    - Inserted text: "Suggested addition by [name]"
 *    - Deleted text: "Suggested deletion by [name]"
 * 3. Accept/reject buttons have descriptive labels:
 *    - "Accept suggestion: insert 'component' after 'the'"
 *    - "Reject suggestion: delete 'old'"
 * 4. Navigation: Cmd+] to jump to next suggestion, Cmd+[ for previous
 */

function SuggestionDecoration({ suggestion }: { suggestion: Suggestion }) {
  const description =
    suggestion.type === 'insert'
      ? `Suggested addition by ${suggestion.author.name}`
      : `Suggested deletion by ${suggestion.author.name}`;

  return (
    <span
      className={cn(
        suggestion.type === 'insert' && 'bg-green-100 text-green-900',
        suggestion.type === 'delete' && 'bg-red-100 text-red-900 line-through',
      )}
      aria-description={description}
    >
      {/* suggestion content */}
    </span>
  );
}

/**
 * Custom performance marks for editor operations:
 */
class EditorPerformanceMonitor {
  /** Measure keystroke-to-render latency */
  measureKeystrokeLatency(): void {
    // Mark at keydown
    document.addEventListener(
      "keydown",
      () => {
        performance.mark("keystroke-start");
      },
      { once: true },
    );

    // Mark after DOM update (via MutationObserver or requestAnimationFrame)
    requestAnimationFrame(() => {
      requestAnimationFrame(() => {
        performance.mark("keystroke-rendered");
        const measure = performance.measure(
          "keystroke-latency",
          "keystroke-start",
          "keystroke-rendered",
        );
        this.report("keystroke_latency_ms", measure.duration);
      });
    });
  }

  /** Track document load phases */
  measureDocumentLoad(docId: string): void {
    performance.mark("doc-fetch-start");
    // ... after fetch
    performance.mark("doc-fetch-end");
    // ... after parse
    performance.mark("doc-parse-end");
    // ... after first render
    performance.mark("doc-render-end");

    this.report(
      "doc_fetch_ms",
      performance.measure("", "doc-fetch-start", "doc-fetch-end").duration,
    );
    this.report(
      "doc_parse_ms",
      performance.measure("", "doc-fetch-end", "doc-parse-end").duration,
    );
    this.report(
      "doc_render_ms",
      performance.measure("", "doc-parse-end", "doc-render-end").duration,
    );
  }

  /** Monitor collaboration health */
  measureCollabSync(sentAt: number, ackedAt: number): void {
    const latency = ackedAt - sentAt;
    this.report("collab_sync_latency_ms", latency);
    if (latency > 500) {
      this.reportWarning("collab_high_latency", { latency, docId: this.docId });
    }
  }

  private report(metric: string, value: number): void {
    // Send to analytics service (batched, non-blocking)
    navigator.sendBeacon(
      "/api/metrics",
      JSON.stringify({ metric, value, ts: Date.now() }),
    );
  }
}

/**
 * Editor-specific error boundaries:
 * 1. Block-level: If a single block throws, replace with error placeholder, don't crash editor
 * 2. Plugin-level: If a plugin (comments, suggestions) crashes, disable it gracefully
 * 3. Collaboration-level: If WebSocket dies, switch to polling mode
 * 4. Fatal: If EditorState becomes corrupt, restore from last IndexedDB snapshot
 */

function BlockErrorBoundary({ blockId, children }: { blockId: string; children: React.ReactNode }) {
  return (
    <ErrorBoundary
      fallback={
        <div className="p-4 border border-destructive rounded bg-destructive/10">
          <p className="text-sm text-destructive">
            This block encountered an error.{' '}
            <button onClick={() => reloadBlock(blockId)}>Retry</button>
          </p>
        </div>
      }
      onError={(error) => {
        reportError('block_render_error', { blockId, error: error.message });
      }}
    >
      {children}
    </ErrorBoundary>
  );
}