Upload 7 files

Dockerfile

@@ -0,0 +1,29 @@
+# ── Stage 1: Builder ─────────────────────────────────────────
+FROM python:3.11-slim AS builder
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
+
+# ── Stage 2: Runtime ─────────────────────────────────────────
+FROM python:3.11-slim
+
+# HF Spaces runs as user 1000
+RUN useradd -m -u 1000 appuser
+
+WORKDIR /app
+
+# Copy dependencies
+COPY --from=builder /install /usr/local
+
+# Copy source
+COPY --chown=appuser:appuser . .
+
+USER appuser
+
+# HF Spaces exposes port 7860
+EXPOSE 7860
+
+# Start with uvicorn, binding to 0.0.0.0:7860
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "1", "--ws", "websockets"]

document_store.py

@@ -0,0 +1,113 @@
+"""
+Document Store
+Manages in-memory document state with snapshot support.
+In production this would be backed by Redis + Postgres.
+"""
+
+import time
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+from ot_engine import Operation, apply_operation, ServerState, transform_against_log
+
+SNAPSHOT_EVERY_N_OPS = 50  # Take snapshot every 50 ops
+
+
+@dataclass
+class Snapshot:
+    version: int
+    content: str
+    timestamp: float = field(default_factory=time.time)
+
+
+@dataclass
+class Document:
+    doc_id: str
+    title: str = "Untitled Document"
+    content: str = ""
+    version: int = 0
+    op_log: List[Tuple[int, Operation]] = field(default_factory=list)
+    snapshots: List[Snapshot] = field(default_factory=list)
+    created_at: float = field(default_factory=time.time)
+    updated_at: float = field(default_factory=time.time)
+
+    def get_latest_snapshot(self) -> Optional[Snapshot]:
+        if self.snapshots:
+            return self.snapshots[-1]
+        return None
+
+    def maybe_take_snapshot(self):
+        if self.version > 0 and self.version % SNAPSHOT_EVERY_N_OPS == 0:
+            snap = Snapshot(version=self.version, content=self.content)
+            self.snapshots.append(snap)
+
+    def apply_op(self, op: Operation) -> Operation:
+        """
+        Apply an incoming operation with OT.
+        Returns the transformed operation that was actually applied.
+        """
+        # If client is behind, transform against missed ops
+        if op.base_version < self.version:
+            op = transform_against_log(
+                op,
+                self.op_log,
+                from_version=op.base_version,
+                to_version=self.version,
+            )
+
+        # Apply to content
+        self.content = apply_operation(self.content, op)
+        self.version += 1
+        op.base_version = self.version  # stamp with server version
+
+        # Store in log
+        self.op_log.append((self.version, op))
+
+        # Keep op_log bounded (last 1000 ops)
+        if len(self.op_log) > 1000:
+            self.op_log = self.op_log[-1000:]
+
+        self.updated_at = time.time()
+        self.maybe_take_snapshot()
+
+        return op
+
+    def get_state(self) -> dict:
+        return {
+            "doc_id": self.doc_id,
+            "title": self.title,
+            "content": self.content,
+            "version": self.version,
+        }
+
+
+class DocumentStore:
+    def __init__(self):
+        self._docs: Dict[str, Document] = {}
+
+    def get_or_create(self, doc_id: str) -> Document:
+        if doc_id not in self._docs:
+            self._docs[doc_id] = Document(doc_id=doc_id)
+        return self._docs[doc_id]
+
+    def get(self, doc_id: str) -> Optional[Document]:
+        return self._docs.get(doc_id)
+
+    def update_title(self, doc_id: str, title: str):
+        doc = self.get(doc_id)
+        if doc:
+            doc.title = title
+
+    def list_docs(self) -> List[dict]:
+        return [
+            {
+                "doc_id": d.doc_id,
+                "title": d.title,
+                "version": d.version,
+                "updated_at": d.updated_at,
+            }
+            for d in self._docs.values()
+        ]
+
+
+# Global singleton
+store = DocumentStore()

index.html

@@ -0,0 +1,1118 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>CollabDocs</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link href="https://fonts.googleapis.com/css2?family=DM+Serif+Display:ital@0;1&family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;1,9..40,300&display=swap" rel="stylesheet">
+<style>
+  :root {
+    --bg: #F7F5F0;
+    --surface: #FFFFFF;
+    --surface2: #F0EDE8;
+    --border: #E2DDD6;
+    --border-strong: #C8C0B4;
+    --text: #1A1816;
+    --text-muted: #7A7168;
+    --text-light: #A89F94;
+    --accent: #2D6A4F;
+    --accent-light: #52B788;
+    --accent-dim: #D8F3DC;
+    --danger: #C0392B;
+    --shadow: 0 1px 3px rgba(0,0,0,0.08), 0 4px 16px rgba(0,0,0,0.04);
+    --shadow-lg: 0 4px 24px rgba(0,0,0,0.12);
+    --radius: 8px;
+    --font-serif: 'DM Serif Display', Georgia, serif;
+    --font-sans: 'DM Sans', system-ui, sans-serif;
+  }
+
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+
+  body {
+    font-family: var(--font-sans);
+    background: var(--bg);
+    color: var(--text);
+    min-height: 100vh;
+    display: flex;
+    flex-direction: column;
+  }
+
+  /* ── Toolbar ── */
+  #toolbar {
+    background: var(--surface);
+    border-bottom: 1px solid var(--border);
+    padding: 0 20px;
+    height: 56px;
+    display: flex;
+    align-items: center;
+    gap: 16px;
+    position: sticky;
+    top: 0;
+    z-index: 100;
+    box-shadow: var(--shadow);
+  }
+
+  .logo {
+    font-family: var(--font-serif);
+    font-size: 20px;
+    color: var(--accent);
+    white-space: nowrap;
+    letter-spacing: -0.3px;
+  }
+
+  .logo span { color: var(--text-muted); font-size: 14px; margin-left: 4px; }
+
+  #doc-title {
+    flex: 1;
+    min-width: 0;
+    background: none;
+    border: none;
+    outline: none;
+    font-family: var(--font-sans);
+    font-size: 16px;
+    font-weight: 500;
+    color: var(--text);
+    padding: 6px 10px;
+    border-radius: var(--radius);
+    transition: background 0.2s;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+
+  #doc-title:hover, #doc-title:focus {
+    background: var(--surface2);
+  }
+
+  .toolbar-right {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    flex-shrink: 0;
+  }
+
+  /* Status badge */
+  #status-badge {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    font-size: 12px;
+    color: var(--text-muted);
+    padding: 4px 10px;
+    border-radius: 20px;
+    background: var(--surface2);
+    border: 1px solid var(--border);
+    transition: all 0.3s;
+    white-space: nowrap;
+  }
+
+  #status-badge.connected { color: var(--accent); background: var(--accent-dim); border-color: #95D5B2; }
+  #status-badge.disconnected { color: var(--danger); background: #FADBD8; border-color: #F1948A; }
+
+  #status-dot {
+    width: 7px; height: 7px;
+    border-radius: 50%;
+    background: currentColor;
+    animation: pulse 2s infinite;
+  }
+
+  @keyframes pulse {
+    0%, 100% { opacity: 1; }
+    50% { opacity: 0.4; }
+  }
+
+  /* Share button */
+  #share-btn {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    padding: 7px 14px;
+    background: var(--accent);
+    color: white;
+    border: none;
+    border-radius: var(--radius);
+    font-family: var(--font-sans);
+    font-size: 13px;
+    font-weight: 500;
+    cursor: pointer;
+    transition: all 0.2s;
+    white-space: nowrap;
+  }
+
+  #share-btn:hover { background: #245A42; transform: translateY(-1px); box-shadow: var(--shadow); }
+  #share-btn:active { transform: translateY(0); }
+
+  /* User avatars */
+  #user-avatars {
+    display: flex;
+    align-items: center;
+  }
+
+  .avatar {
+    width: 30px; height: 30px;
+    border-radius: 50%;
+    display: flex; align-items: center; justify-content: center;
+    font-size: 12px;
+    font-weight: 600;
+    color: white;
+    border: 2px solid white;
+    margin-left: -8px;
+    cursor: default;
+    position: relative;
+    transition: transform 0.2s;
+    box-shadow: 0 1px 4px rgba(0,0,0,0.2);
+  }
+
+  .avatar:first-child { margin-left: 0; }
+  .avatar:hover { transform: translateY(-2px); z-index: 10; }
+
+  .avatar-tooltip {
+    position: absolute;
+    bottom: calc(100% + 6px);
+    left: 50%;
+    transform: translateX(-50%);
+    background: var(--text);
+    color: white;
+    font-size: 11px;
+    padding: 3px 8px;
+    border-radius: 4px;
+    white-space: nowrap;
+    opacity: 0;
+    pointer-events: none;
+    transition: opacity 0.2s;
+  }
+
+  .avatar:hover .avatar-tooltip { opacity: 1; }
+
+  /* ── Main layout ── */
+  #main {
+    flex: 1;
+    display: flex;
+    justify-content: center;
+    padding: 32px 20px 60px;
+  }
+
+  #editor-wrap {
+    width: 100%;
+    max-width: 860px;
+    display: flex;
+    flex-direction: column;
+    gap: 0;
+  }
+
+  /* Page shadow effect */
+  #page {
+    background: var(--surface);
+    border-radius: 4px;
+    box-shadow: var(--shadow-lg), 0 0 0 1px var(--border);
+    position: relative;
+    min-height: 80vh;
+  }
+
+  /* Remote cursor layer */
+  #cursor-layer {
+    position: absolute;
+    top: 0; left: 0; right: 0; bottom: 0;
+    pointer-events: none;
+    overflow: hidden;
+    z-index: 5;
+    border-radius: 4px;
+  }
+
+  .remote-cursor {
+    position: absolute;
+    width: 2px;
+    pointer-events: none;
+    transition: left 0.1s, top 0.1s;
+  }
+
+  .remote-cursor-line {
+    width: 2px;
+    height: 20px;
+    border-radius: 1px;
+    animation: cursor-blink 1s infinite;
+  }
+
+  @keyframes cursor-blink {
+    0%, 100% { opacity: 1; }
+    50% { opacity: 0.2; }
+  }
+
+  .remote-cursor-label {
+    position: absolute;
+    top: -20px;
+    left: 0;
+    font-size: 10px;
+    font-weight: 600;
+    color: white;
+    padding: 1px 5px;
+    border-radius: 3px 3px 3px 0;
+    white-space: nowrap;
+    font-family: var(--font-sans);
+    box-shadow: 0 1px 4px rgba(0,0,0,0.2);
+  }
+
+  /* The actual editor */
+  #editor {
+    width: 100%;
+    min-height: 80vh;
+    padding: 60px 80px;
+    font-family: 'Georgia', serif;
+    font-size: 16px;
+    line-height: 1.8;
+    color: var(--text);
+    border: none;
+    outline: none;
+    resize: none;
+    background: transparent;
+    position: relative;
+    z-index: 10;
+    white-space: pre-wrap;
+    word-wrap: break-word;
+    caret-color: var(--accent);
+  }
+
+  #editor::selection {
+    background: rgba(45, 106, 79, 0.2);
+  }
+
+  /* ── Notifications ── */
+  #notifs {
+    position: fixed;
+    bottom: 20px;
+    right: 20px;
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+    z-index: 1000;
+    pointer-events: none;
+  }
+
+  .notif {
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    padding: 10px 14px;
+    font-size: 13px;
+    box-shadow: var(--shadow-lg);
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    animation: notif-in 0.3s ease;
+    max-width: 280px;
+  }
+
+  @keyframes notif-in {
+    from { transform: translateX(20px); opacity: 0; }
+    to { transform: translateX(0); opacity: 1; }
+  }
+
+  .notif-dot {
+    width: 8px; height: 8px;
+    border-radius: 50%;
+    flex-shrink: 0;
+  }
+
+  /* ── Share modal ── */
+  #share-modal {
+    display: none;
+    position: fixed;
+    inset: 0;
+    background: rgba(0,0,0,0.4);
+    z-index: 500;
+    align-items: center;
+    justify-content: center;
+    backdrop-filter: blur(2px);
+  }
+
+  #share-modal.open { display: flex; }
+
+  .modal-box {
+    background: var(--surface);
+    border-radius: 12px;
+    padding: 28px;
+    width: 460px;
+    max-width: 90vw;
+    box-shadow: var(--shadow-lg);
+    animation: modal-in 0.25s ease;
+  }
+
+  @keyframes modal-in {
+    from { transform: scale(0.95); opacity: 0; }
+    to { transform: scale(1); opacity: 1; }
+  }
+
+  .modal-title {
+    font-family: var(--font-serif);
+    font-size: 22px;
+    margin-bottom: 8px;
+  }
+
+  .modal-desc {
+    font-size: 14px;
+    color: var(--text-muted);
+    margin-bottom: 20px;
+    line-height: 1.6;
+  }
+
+  .link-row {
+    display: flex;
+    gap: 8px;
+    margin-bottom: 16px;
+  }
+
+  .link-input {
+    flex: 1;
+    padding: 10px 12px;
+    border: 1px solid var(--border-strong);
+    border-radius: var(--radius);
+    font-size: 13px;
+    font-family: monospace;
+    background: var(--surface2);
+    color: var(--text);
+    outline: none;
+  }
+
+  .copy-btn {
+    padding: 10px 16px;
+    background: var(--accent);
+    color: white;
+    border: none;
+    border-radius: var(--radius);
+    font-size: 13px;
+    font-weight: 500;
+    cursor: pointer;
+    transition: all 0.2s;
+    white-space: nowrap;
+  }
+
+  .copy-btn:hover { background: #245A42; }
+  .copy-btn.copied { background: #52B788; }
+
+  .modal-close {
+    width: 100%;
+    padding: 10px;
+    background: var(--surface2);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    font-size: 14px;
+    cursor: pointer;
+    transition: background 0.2s;
+    font-family: var(--font-sans);
+    color: var(--text-muted);
+  }
+
+  .modal-close:hover { background: var(--border); }
+
+  /* ── Collab activity bar ── */
+  #activity-bar {
+    position: fixed;
+    left: 20px;
+    bottom: 20px;
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    padding: 8px 12px;
+    font-size: 12px;
+    color: var(--text-muted);
+    box-shadow: var(--shadow);
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    max-width: 200px;
+    transition: opacity 0.3s;
+  }
+
+  #activity-bar.hidden { opacity: 0; pointer-events: none; }
+
+  #typing-indicator {
+    display: flex;
+    align-items: center;
+    gap: 3px;
+  }
+
+  .typing-dot {
+    width: 4px; height: 4px;
+    border-radius: 50%;
+    background: var(--accent-light);
+    animation: typing 1.2s infinite;
+  }
+
+  .typing-dot:nth-child(2) { animation-delay: 0.2s; }
+  .typing-dot:nth-child(3) { animation-delay: 0.4s; }
+
+  @keyframes typing {
+    0%, 100% { transform: translateY(0); opacity: 0.6; }
+    50% { transform: translateY(-4px); opacity: 1; }
+  }
+
+  /* ── Responsive ── */
+  @media (max-width: 640px) {
+    #editor { padding: 30px 20px; }
+    .logo span { display: none; }
+    #doc-title { font-size: 14px; }
+  }
+
+  /* ── New doc button ── */
+  #new-doc-btn {
+    display: flex;
+    align-items: center;
+    gap: 5px;
+    padding: 6px 12px;
+    background: var(--surface2);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    font-size: 13px;
+    cursor: pointer;
+    color: var(--text-muted);
+    transition: all 0.2s;
+    font-family: var(--font-sans);
+    white-space: nowrap;
+  }
+
+  #new-doc-btn:hover { background: var(--border); color: var(--text); }
+
+  /* Version display */
+  #version-display {
+    font-size: 11px;
+    color: var(--text-light);
+    padding: 4px 8px;
+    border-radius: 4px;
+    background: var(--surface2);
+    white-space: nowrap;
+  }
+</style>
+</head>
+<body>
+
+<!-- Toolbar -->
+<div id="toolbar">
+  <div class="logo">CollabDocs <span>beta</span></div>
+
+  <input id="doc-title" type="text" value="Untitled Document" spellcheck="false" maxlength="200">
+
+  <div class="toolbar-right">
+    <div id="version-display">v0</div>
+
+    <div id="user-avatars"></div>
+
+    <div id="status-badge" class="disconnected">
+      <div id="status-dot"></div>
+      <span id="status-text">Connecting…</span>
+    </div>
+
+    <button id="new-doc-btn">+ New</button>
+    <button id="share-btn">⬆ Share</button>
+  </div>
+</div>
+
+<!-- Main -->
+<div id="main">
+  <div id="editor-wrap">
+    <div id="page">
+      <div id="cursor-layer"></div>
+      <textarea id="editor" spellcheck="true" autocomplete="off" autocorrect="on"
+        placeholder="Start typing to collaborate…"></textarea>
+    </div>
+  </div>
+</div>
+
+<!-- Notifications -->
+<div id="notifs"></div>
+
+<!-- Activity bar -->
+<div id="activity-bar" class="hidden">
+  <div id="typing-indicator">
+    <div class="typing-dot"></div>
+    <div class="typing-dot"></div>
+    <div class="typing-dot"></div>
+  </div>
+  <span id="activity-text"></span>
+</div>
+
+<!-- Share modal -->
+<div id="share-modal">
+  <div class="modal-box">
+    <div class="modal-title">Share Document</div>
+    <div class="modal-desc">Anyone with this link can view and edit this document in real time.</div>
+    <div class="link-row">
+      <input class="link-input" id="share-link-input" readonly>
+      <button class="copy-btn" id="copy-link-btn">Copy</button>
+    </div>
+    <button class="modal-close" id="modal-close-btn">Done</button>
+  </div>
+</div>
+
+<script>
+// ═══════════════════════════════════════════════════════════
+//  CollabDocs Client
+//  Implements client-side OT, cursor sync, WebSocket protocol
+// ═══════════════════════════════════════════════════════════
+
+(function() {
+  'use strict';
+
+  // ── State ──────────────────────────────────────────────
+  let ws = null;
+  let myUserId = null;
+  let myName = null;
+  let myColor = null;
+  let docId = null;
+  let serverVersion = 0;
+  let pendingOps = [];        // ops sent but not acked
+  let localVersion = 0;       // what we think server version is
+  let isApplyingRemote = false;
+
+  // Remote cursors: userId -> { pos, name, color, elem }
+  const remoteCursors = {};
+
+  // Activity tracking
+  let activityTimeout = null;
+  let typingUsers = {};
+
+  // ── DOM ────────────────────────────────────────────────
+  const editor = document.getElementById('editor');
+  const toolbar = document.getElementById('toolbar');
+  const statusBadge = document.getElementById('status-badge');
+  const statusText = document.getElementById('status-text');
+  const statusDot = document.getElementById('status-dot');
+  const userAvatars = document.getElementById('user-avatars');
+  const shareBtn = document.getElementById('share-btn');
+  const shareModal = document.getElementById('share-modal');
+  const shareLinkInput = document.getElementById('share-link-input');
+  const copyLinkBtn = document.getElementById('copy-link-btn');
+  const modalCloseBtn = document.getElementById('modal-close-btn');
+  const newDocBtn = document.getElementById('new-doc-btn');
+  const docTitle = document.getElementById('doc-title');
+  const versionDisplay = document.getElementById('version-display');
+  const notifs = document.getElementById('notifs');
+  const activityBar = document.getElementById('activity-bar');
+  const activityText = document.getElementById('activity-text');
+
+  // ── URL / Doc routing ──────────────────────────────────
+  function getDocId() {
+    const params = new URLSearchParams(window.location.search);
+    return params.get('doc') || 'welcome';
+  }
+
+  function getUserId() {
+    let id = sessionStorage.getItem('collabdocs_uid');
+    if (!id) {
+      id = 'u_' + Math.random().toString(36).substr(2, 9);
+      sessionStorage.setItem('collabdocs_uid', id);
+    }
+    return id;
+  }
+
+  function getShareUrl() {
+    const base = window.location.origin + window.location.pathname;
+    return `${base}?doc=${docId}`;
+  }
+
+  // ── OT: Client-side operation building ────────────────
+  // We detect what changed between old and new text
+  // by comparing textarea content before and after input events.
+
+  let prevContent = '';
+  let prevSelStart = 0;
+  let prevSelEnd = 0;
+
+  function buildOpsFromDiff(oldText, newText, selStart) {
+    // Simple LCS-based diff for single edits (textarea gives us input events)
+    // For real prod: use a proper diff library. This handles typical typing/paste/delete.
+    const ops = [];
+
+    // Find common prefix
+    let prefixLen = 0;
+    while (prefixLen < oldText.length && prefixLen < newText.length
+           && oldText[prefixLen] === newText[prefixLen]) {
+      prefixLen++;
+    }
+
+    // Find common suffix
+    let oldSuffix = oldText.length - 1;
+    let newSuffix = newText.length - 1;
+    while (oldSuffix >= prefixLen && newSuffix >= prefixLen
+           && oldText[oldSuffix] === newText[newSuffix]) {
+      oldSuffix--;
+      newSuffix--;
+    }
+
+    const deletedLen = oldSuffix - prefixLen + 1;
+    const insertedText = newText.slice(prefixLen, newSuffix + 1);
+
+    if (deletedLen > 0) {
+      ops.push({
+        op_type: 'delete',
+        position: prefixLen,
+        length: deletedLen,
+        value: '',
+      });
+    }
+
+    if (insertedText.length > 0) {
+      ops.push({
+        op_type: 'insert',
+        position: prefixLen,
+        value: insertedText,
+        length: insertedText.length,
+      });
+    }
+
+    return ops;
+  }
+
+  // ── WebSocket connection ───────────────────────────────
+  function connect() {
+    docId = getDocId();
+    myUserId = getUserId();
+
+    const protocol = location.protocol === 'https:' ? 'wss' : 'ws';
+    const wsUrl = `${protocol}://${location.host}/ws/${docId}?user_id=${myUserId}`;
+
+    ws = new WebSocket(wsUrl);
+
+    ws.onopen = () => {
+      setStatus('connected', 'Connected');
+      scheduleHeartbeat();
+    };
+
+    ws.onclose = () => {
+      setStatus('disconnected', 'Disconnected — reconnecting…');
+      clearInterval(heartbeatInterval);
+      setTimeout(connect, 2000);
+    };
+
+    ws.onerror = (e) => {
+      console.error('WS error', e);
+    };
+
+    ws.onmessage = (event) => {
+      try {
+        const msg = JSON.parse(event.data);
+        handleMessage(msg);
+      } catch (e) {
+        console.error('Parse error', e);
+      }
+    };
+  }
+
+  // ── Message handling ───────────────────────────────────
+  function handleMessage(msg) {
+    switch (msg.type) {
+      case 'init':
+        handleInit(msg);
+        break;
+      case 'operation':
+        handleRemoteOperation(msg);
+        break;
+      case 'ack':
+        handleAck(msg);
+        break;
+      case 'cursor':
+        handleRemoteCursor(msg);
+        break;
+      case 'user_joined':
+        handleUserJoined(msg);
+        break;
+      case 'user_left':
+        handleUserLeft(msg);
+        break;
+      case 'title_change':
+        docTitle.value = msg.title;
+        document.title = `${msg.title} — CollabDocs`;
+        break;
+    }
+  }
+
+  function handleInit(msg) {
+    myUserId = msg.user_id;
+    myName = msg.name;
+    myColor = msg.color;
+
+    const state = msg.doc_state;
+    serverVersion = state.version;
+    localVersion = state.version;
+
+    // Set content without triggering our own handlers
+    isApplyingRemote = true;
+    editor.value = state.content;
+    prevContent = state.content;
+    isApplyingRemote = false;
+
+    docTitle.value = state.title || 'Untitled Document';
+    document.title = `${docTitle.value} — CollabDocs`;
+    updateVersionDisplay();
+
+    renderUsers(msg.users || []);
+  }
+
+  function handleRemoteOperation(msg) {
+    if (msg.user_id === myUserId) return; // Already applied locally
+
+    serverVersion = msg.server_version;
+    localVersion = msg.server_version;
+    updateVersionDisplay();
+
+    // Save cursor
+    const cursorPos = editor.selectionStart;
+    const cursorEnd = editor.selectionEnd;
+
+    // Apply to editor
+    isApplyingRemote = true;
+    const oldContent = editor.value;
+    const newContent = applyOpToString(oldContent, msg);
+    editor.value = newContent;
+    prevContent = newContent;
+
+    // Adjust cursor for remote op
+    const newCursor = transformCursorPos(cursorPos, msg);
+    const newCursorEnd = transformCursorPos(cursorEnd, msg);
+    editor.setSelectionRange(newCursor, newCursorEnd);
+    isApplyingRemote = false;
+
+    // Show typing activity
+    showTypingActivity(msg.user_id, remoteCursors[msg.user_id]?.name || 'Someone');
+  }
+
+  function handleAck(msg) {
+    serverVersion = msg.server_version;
+    localVersion = msg.server_version;
+    updateVersionDisplay();
+
+    // Remove from pending
+    pendingOps = pendingOps.filter(op => op.op_id !== msg.op_id);
+  }
+
+  function handleRemoteCursor(msg) {
+    if (msg.user_id === myUserId) return;
+
+    remoteCursors[msg.user_id] = {
+      pos: msg.cursor_pos,
+      name: msg.name,
+      color: msg.color,
+    };
+
+    updateRemoteCursorUI(msg.user_id, msg.cursor_pos, msg.name, msg.color);
+  }
+
+  function handleUserJoined(msg) {
+    if (msg.user_id !== myUserId) {
+      showNotif(`${msg.name} joined`, msg.color);
+    }
+    renderUsers(msg.users || []);
+  }
+
+  function handleUserLeft(msg) {
+    showNotif(`${msg.name} left`, '#999');
+    removeRemoteCursor(msg.user_id);
+    delete remoteCursors[msg.user_id];
+    renderUsers(msg.users || []);
+  }
+
+  // ── Apply remote op to string ──────────────────────────
+  function applyOpToString(content, op) {
+    if (op.op_type === 'insert') {
+      const pos = Math.max(0, Math.min(op.position, content.length));
+      return content.slice(0, pos) + op.value + content.slice(pos);
+    } else if (op.op_type === 'delete') {
+      const pos = Math.max(0, Math.min(op.position, content.length));
+      const end = Math.max(0, Math.min(pos + op.length, content.length));
+      return content.slice(0, pos) + content.slice(end);
+    }
+    return content;
+  }
+
+  function transformCursorPos(cursorPos, op) {
+    if (op.op_type === 'insert') {
+      const insLen = op.value.length;
+      if (op.position <= cursorPos) return cursorPos + insLen;
+    } else if (op.op_type === 'delete') {
+      const delEnd = op.position + op.length;
+      if (delEnd <= cursorPos) return cursorPos - op.length;
+      if (op.position <= cursorPos && cursorPos < delEnd) return op.position;
+    }
+    return cursorPos;
+  }
+
+  // ── Send operation ─────────────────────────────────────
+  function sendOp(opType, position, value, length) {
+    const opId = Math.random().toString(36).substr(2, 9);
+    const msg = {
+      type: 'operation',
+      op_id: opId,
+      op_type: opType,
+      position: position,
+      value: value || '',
+      length: length || (value ? value.length : 1),
+      base_version: localVersion,
+    };
+
+    pendingOps.push(msg);
+    sendIfOpen(msg);
+  }
+
+  // ── Editor event handlers ──────────────────────────────
+  editor.addEventListener('input', (e) => {
+    if (isApplyingRemote) return;
+
+    const newContent = editor.value;
+    const ops = buildOpsFromDiff(prevContent, newContent, editor.selectionStart);
+
+    for (const op of ops) {
+      sendOp(op.op_type, op.position, op.value, op.length);
+    }
+
+    prevContent = newContent;
+    sendCursorPosition();
+  });
+
+  editor.addEventListener('keyup', sendCursorPosition);
+  editor.addEventListener('click', sendCursorPosition);
+  editor.addEventListener('mouseup', sendCursorPosition);
+  editor.addEventListener('touchend', sendCursorPosition);
+  editor.addEventListener('select', sendCursorPosition);
+
+  let cursorDebounce = null;
+  function sendCursorPosition() {
+    clearTimeout(cursorDebounce);
+    cursorDebounce = setTimeout(() => {
+      sendIfOpen({
+        type: 'cursor',
+        cursor_pos: editor.selectionStart,
+        selection_start: editor.selectionStart,
+        selection_end: editor.selectionEnd,
+      });
+    }, 30);
+  }
+
+  // ── Title sync ─────────────────────────────────────────
+  let titleDebounce = null;
+  docTitle.addEventListener('input', () => {
+    clearTimeout(titleDebounce);
+    titleDebounce = setTimeout(() => {
+      document.title = `${docTitle.value} — CollabDocs`;
+      sendIfOpen({ type: 'title_change', title: docTitle.value });
+    }, 300);
+  });
+
+  // ── Remote cursor rendering ────────────────────────────
+  // We approximate cursor pixel position from char index.
+  // This is a simplified approach — in prod you'd use Range API.
+  const cursorElems = {};
+
+  function updateRemoteCursorUI(userId, charPos, name, color) {
+    // We'll use a char-offset based approach
+    // Get pixel coords by measuring text before cursor
+    const coords = getCharCoords(charPos);
+    if (!coords) return;
+
+    let elem = cursorElems[userId];
+    if (!elem) {
+      elem = document.createElement('div');
+      elem.className = 'remote-cursor';
+      elem.innerHTML = `
+        <div class="remote-cursor-label" style="background:${color}">${escHtml(name)}</div>
+        <div class="remote-cursor-line" style="background:${color}"></div>
+      `;
+      document.getElementById('cursor-layer').appendChild(elem);
+      cursorElems[userId] = elem;
+    }
+
+    elem.style.left = `${coords.x}px`;
+    elem.style.top = `${coords.y}px`;
+    elem.querySelector('.remote-cursor-label').style.background = color;
+    elem.querySelector('.remote-cursor-line').style.background = color;
+    elem.querySelector('.remote-cursor-label').textContent = name;
+  }
+
+  function removeRemoteCursor(userId) {
+    const elem = cursorElems[userId];
+    if (elem) {
+      elem.remove();
+      delete cursorElems[userId];
+    }
+  }
+
+  function getCharCoords(charIndex) {
+    // Measure by creating a hidden mirror of textarea content
+    const editorRect = editor.getBoundingClientRect();
+    const pageRect = document.getElementById('page').getBoundingClientRect();
+
+    const mirror = document.createElement('div');
+    const styles = window.getComputedStyle(editor);
+    
+    Object.assign(mirror.style, {
+      position: 'absolute',
+      top: '-9999px',
+      left: '-9999px',
+      width: `${editor.clientWidth}px`,
+      fontFamily: styles.fontFamily,
+      fontSize: styles.fontSize,
+      lineHeight: styles.lineHeight,
+      padding: styles.padding,
+      whiteSpace: 'pre-wrap',
+      wordWrap: 'break-word',
+      overflowWrap: 'break-word',
+      visibility: 'hidden',
+    });
+
+    const text = editor.value.slice(0, charIndex);
+    const before = document.createTextNode(text);
+    const span = document.createElement('span');
+    span.textContent = '|';
+    mirror.appendChild(before);
+    mirror.appendChild(span);
+    document.body.appendChild(mirror);
+
+    const spanRect = span.getBoundingClientRect();
+    const mirrorRect = mirror.getBoundingClientRect();
+    const x = spanRect.left - mirrorRect.left + (editorRect.left - pageRect.left);
+    const y = spanRect.top - mirrorRect.top + (editorRect.top - pageRect.top);
+
+    document.body.removeChild(mirror);
+    return { x, y };
+  }
+
+  // ── User avatars ───────────────────────────────────────
+  function renderUsers(users) {
+    userAvatars.innerHTML = '';
+    const maxShow = 5;
+    const shown = users.slice(0, maxShow);
+
+    shown.forEach(u => {
+      const div = document.createElement('div');
+      div.className = 'avatar';
+      div.style.background = u.color;
+      div.textContent = (u.name || '?')[0].toUpperCase();
+      if (u.user_id === myUserId) {
+        div.style.border = '2px solid ' + u.color;
+        div.style.boxShadow = `0 0 0 2px white, 0 0 0 3px ${u.color}`;
+      }
+      const tooltip = document.createElement('div');
+      tooltip.className = 'avatar-tooltip';
+      tooltip.style.background = u.color;
+      tooltip.textContent = u.user_id === myUserId ? `${u.name} (you)` : u.name;
+      div.appendChild(tooltip);
+      userAvatars.appendChild(div);
+    });
+
+    if (users.length > maxShow) {
+      const more = document.createElement('div');
+      more.className = 'avatar';
+      more.style.background = '#888';
+      more.textContent = `+${users.length - maxShow}`;
+      userAvatars.appendChild(more);
+    }
+  }
+
+  // ── Activity/typing indicator ──────────────────────────
+  const typingTimeouts = {};
+
+  function showTypingActivity(userId, name) {
+    typingUsers[userId] = name;
+    clearTimeout(typingTimeouts[userId]);
+    typingTimeouts[userId] = setTimeout(() => {
+      delete typingUsers[userId];
+      updateActivityBar();
+    }, 2000);
+    updateActivityBar();
+  }
+
+  function updateActivityBar() {
+    const names = Object.values(typingUsers).filter(n => true);
+    if (names.length === 0) {
+      activityBar.classList.add('hidden');
+      return;
+    }
+    activityBar.classList.remove('hidden');
+    const label = names.length === 1
+      ? `${names[0]} is typing`
+      : `${names.slice(0,-1).join(', ')} and ${names[names.length-1]} are typing`;
+    activityText.textContent = label;
+  }
+
+  // ── Notifications ──────────────────────────────────────
+  function showNotif(text, color) {
+    const div = document.createElement('div');
+    div.className = 'notif';
+    div.innerHTML = `<div class="notif-dot" style="background:${color}"></div><span>${escHtml(text)}</span>`;
+    notifs.appendChild(div);
+    setTimeout(() => div.remove(), 3500);
+  }
+
+  // ── Status ─────────────────────────────────────────────
+  function setStatus(state, text) {
+    statusBadge.className = `${state}`;
+    statusText.textContent = text;
+  }
+
+  function updateVersionDisplay() {
+    versionDisplay.textContent = `v${serverVersion}`;
+  }
+
+  // ── Heartbeat ───────────��──────────────────────────────
+  let heartbeatInterval;
+  function scheduleHeartbeat() {
+    clearInterval(heartbeatInterval);
+    heartbeatInterval = setInterval(() => {
+      sendIfOpen({ type: 'ping' });
+    }, 10000);
+  }
+
+  function sendIfOpen(msg) {
+    if (ws && ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify(msg));
+    }
+  }
+
+  // ── Share modal ────────────────────────────────────────
+  shareBtn.addEventListener('click', () => {
+    shareLinkInput.value = getShareUrl();
+    shareModal.classList.add('open');
+    shareLinkInput.select();
+  });
+
+  modalCloseBtn.addEventListener('click', () => {
+    shareModal.classList.remove('open');
+  });
+
+  shareModal.addEventListener('click', (e) => {
+    if (e.target === shareModal) shareModal.classList.remove('open');
+  });
+
+  copyLinkBtn.addEventListener('click', () => {
+    navigator.clipboard.writeText(shareLinkInput.value).then(() => {
+      copyLinkBtn.textContent = '✓ Copied!';
+      copyLinkBtn.classList.add('copied');
+      setTimeout(() => {
+        copyLinkBtn.textContent = 'Copy';
+        copyLinkBtn.classList.remove('copied');
+      }, 2000);
+    });
+  });
+
+  // ── New doc ────────────────────────────────────────────
+  newDocBtn.addEventListener('click', async () => {
+    const res = await fetch('/api/docs', { method: 'POST' });
+    const data = await res.json();
+    window.location.href = data.url;
+  });
+
+  // ── Escape util ────────────────────────────────────────
+  function escHtml(str) {
+    return String(str)
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;');
+  }
+
+  // ── Init ───────────────────────────────────────────────
+  connect();
+
+})();
+</script>
+</body>
+</html>

main.py

@@ -0,0 +1,282 @@
+"""
+Google Docs Clone - FastAPI Backend
+Real-time collaborative document editing with Operational Transformation.
+
+Architecture:
+- WebSocket gateway for real-time bidirectional comms
+- OT Engine for conflict resolution
+- Presence manager for cursor/user tracking
+- Document store for persistence (in-memory, swap for Redis+PG in prod)
+"""
+
+import asyncio
+import json
+import logging
+import uuid
+from contextlib import asynccontextmanager
+from typing import Any, Dict
+
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, HTMLResponse
+from fastapi.staticfiles import StaticFiles
+
+from document_store import store
+from ot_engine import Operation
+from presence import presence_manager
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+# ─── Broadcast helpers ────────────────────────────────────────────────────────
+
+async def broadcast_to_doc(doc_id: str, message: dict, exclude_user: str = None):
+    """Fan out a message to all connected clients for a document."""
+    connections = presence_manager.get_connections(doc_id)
+    dead = []
+    for user_id, ws in connections.items():
+        if user_id == exclude_user:
+            continue
+        try:
+            await ws.send_json(message)
+        except Exception:
+            dead.append(user_id)
+    for uid in dead:
+        presence_manager.leave(doc_id, uid)
+
+
+async def send_to_user(doc_id: str, user_id: str, message: dict):
+    """Send a message to a specific user."""
+    user = presence_manager.get_user(doc_id, user_id)
+    if user and user.websocket:
+        try:
+            await user.websocket.send_json(message)
+        except Exception:
+            pass
+
+
+# ─── Message handlers ─────────────────────────────────────────────────────────
+
+async def handle_operation(doc_id: str, user_id: str, data: dict):
+    """
+    Process an incoming OT operation from a client.
+    Transform → Apply → Broadcast.
+    """
+    doc = store.get_or_create(doc_id)
+
+    op = Operation(
+        op_type=data["op_type"],
+        position=data["position"],
+        value=data.get("value", ""),
+        length=data.get("length", len(data.get("value", "")) or 1),
+        base_version=data["base_version"],
+        user_id=user_id,
+        op_id=data.get("op_id", str(uuid.uuid4())),
+    )
+
+    # Apply with OT (thread-safety note: use asyncio.Lock in prod)
+    transformed_op = doc.apply_op(op)
+
+    # Ack to sender
+    await send_to_user(doc_id, user_id, {
+        "type": "ack",
+        "op_id": op.op_id,
+        "server_version": doc.version,
+    })
+
+    # Broadcast transformed op to all others
+    broadcast_msg = {
+        "type": "operation",
+        "op_type": transformed_op.op_type,
+        "position": transformed_op.position,
+        "value": transformed_op.value,
+        "length": transformed_op.length,
+        "server_version": doc.version,
+        "user_id": user_id,
+        "op_id": transformed_op.op_id,
+    }
+    await broadcast_to_doc(doc_id, broadcast_msg, exclude_user=user_id)
+
+
+async def handle_cursor(doc_id: str, user_id: str, data: dict):
+    """Update and broadcast cursor position."""
+    presence_manager.update_cursor(
+        doc_id,
+        user_id,
+        cursor_pos=data.get("cursor_pos", 0),
+        sel_start=data.get("selection_start", -1),
+        sel_end=data.get("selection_end", -1),
+    )
+
+    user = presence_manager.get_user(doc_id, user_id)
+    if not user:
+        return
+
+    await broadcast_to_doc(doc_id, {
+        "type": "cursor",
+        "user_id": user_id,
+        "name": user.name,
+        "color": user.color,
+        "cursor_pos": data.get("cursor_pos", 0),
+        "selection_start": data.get("selection_start", -1),
+        "selection_end": data.get("selection_end", -1),
+    }, exclude_user=user_id)
+
+
+async def handle_title_change(doc_id: str, user_id: str, data: dict):
+    """Sync document title change."""
+    title = data.get("title", "Untitled Document")[:200]
+    store.update_title(doc_id, title)
+    await broadcast_to_doc(doc_id, {
+        "type": "title_change",
+        "title": title,
+        "user_id": user_id,
+    }, exclude_user=user_id)
+
+
+async def handle_ping(doc_id: str, user_id: str):
+    user = presence_manager.get_user(doc_id, user_id)
+    if user:
+        user.ping()
+
+
+# ─── WebSocket endpoint ───────────────────────────────────────────────────────
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Create a default welcome document
+    doc = store.get_or_create("welcome")
+    if not doc.content:
+        doc.title = "Welcome Document"
+        welcome_text = (
+            "Welcome to CollabDocs!\n\n"
+            "This is a real-time collaborative document editor.\n"
+            "Share the URL with anyone — they can edit simultaneously.\n\n"
+            "✦ Changes appear instantly for all users\n"
+            "✦ Each user gets a unique color cursor\n"
+            "✦ Conflicts are resolved via Operational Transformation (OT)\n\n"
+            "Start typing to collaborate..."
+        )
+        from ot_engine import Operation, apply_operation
+        doc.content = welcome_text
+        doc.version = 1
+    yield
+
+
+app = FastAPI(title="CollabDocs", lifespan=lifespan)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.websocket("/ws/{doc_id}")
+async def websocket_endpoint(websocket: WebSocket, doc_id: str):
+    await websocket.accept()
+
+    # Generate or get user_id from query params
+    user_id = websocket.query_params.get("user_id") or str(uuid.uuid4())
+
+    # Register presence
+    user = presence_manager.join(doc_id, user_id, websocket)
+    doc = store.get_or_create(doc_id)
+
+    logger.info(f"User {user.name} ({user_id}) joined doc {doc_id}")
+
+    # Send initial state to connecting user
+    await websocket.send_json({
+        "type": "init",
+        "user_id": user_id,
+        "name": user.name,
+        "color": user.color,
+        "doc_state": doc.get_state(),
+        "users": presence_manager.get_users(doc_id),
+    })
+
+    # Announce join to others
+    await broadcast_to_doc(doc_id, {
+        "type": "user_joined",
+        "user_id": user_id,
+        "name": user.name,
+        "color": user.color,
+        "users": presence_manager.get_users(doc_id),
+    }, exclude_user=user_id)
+
+    try:
+        while True:
+            raw = await websocket.receive_text()
+            try:
+                data = json.loads(raw)
+            except json.JSONDecodeError:
+                continue
+
+            msg_type = data.get("type")
+
+            if msg_type == "operation":
+                await handle_operation(doc_id, user_id, data)
+
+            elif msg_type == "cursor":
+                await handle_cursor(doc_id, user_id, data)
+
+            elif msg_type == "title_change":
+                await handle_title_change(doc_id, user_id, data)
+
+            elif msg_type == "ping":
+                await handle_ping(doc_id, user_id)
+
+    except WebSocketDisconnect:
+        logger.info(f"User {user.name} ({user_id}) left doc {doc_id}")
+        presence_manager.leave(doc_id, user_id)
+
+        await broadcast_to_doc(doc_id, {
+            "type": "user_left",
+            "user_id": user_id,
+            "name": user.name,
+            "users": presence_manager.get_users(doc_id),
+        })
+
+    except Exception as e:
+        logger.error(f"WebSocket error for {user_id}: {e}")
+        presence_manager.leave(doc_id, user_id)
+
+
+# ─── REST endpoints ───────────────────────────────────────────────────────────
+
+@app.get("/api/docs")
+async def list_documents():
+    return store.list_docs()
+
+
+@app.get("/api/docs/{doc_id}")
+async def get_document(doc_id: str):
+    doc = store.get(doc_id)
+    if not doc:
+        raise HTTPException(status_code=404, detail="Document not found")
+    return doc.get_state()
+
+
+@app.post("/api/docs")
+async def create_document():
+    doc_id = str(uuid.uuid4())[:8]
+    doc = store.get_or_create(doc_id)
+    return {"doc_id": doc_id, "url": f"/?doc={doc_id}"}
+
+
+@app.get("/health")
+async def health():
+    return {"status": "ok", "docs": len(store._docs)}
+
+
+# ─── Serve frontend ───────────────────────────────────────────────────────────
+
+@app.get("/")
+async def serve_index():
+    return FileResponse("static/index.html")
+
+
+@app.mount("/static", StaticFiles(directory="static"), name="static")

ot_engine.py

@@ -0,0 +1,181 @@
+"""
+Operational Transformation Engine
+Implements insert-insert, insert-delete, delete-insert, delete-delete,
+delete-range-insert, and insert-inside-delete-range transformations.
+Based on the architecture from the Google Docs system design.
+"""
+
+from dataclasses import dataclass, field
+from typing import Literal, Optional
+import copy
+
+
+@dataclass
+class Operation:
+    op_type: Literal["insert", "delete"]
+    position: int
+    value: str = ""          # For insert
+    length: int = 1          # For delete (range support)
+    base_version: int = 0
+    user_id: str = ""
+    op_id: str = ""
+
+
+@dataclass
+class ServerState:
+    version: int = 0
+    content: str = ""
+    # Operation log: list of (version, Operation)
+    op_log: list = field(default_factory=list)
+
+
+def transform_insert_insert(incoming: Operation, applied: Operation) -> Operation:
+    """
+    Two concurrent inserts. If applied insert position <= incoming position,
+    shift incoming position right by length of applied insert.
+    Tie-break by user_id to ensure consistency.
+    """
+    result = copy.copy(incoming)
+    app_len = len(applied.value)
+
+    if applied.position < incoming.position:
+        result.position += app_len
+    elif applied.position == incoming.position:
+        # Tie-break: lexicographically larger user_id goes later
+        if applied.user_id <= incoming.user_id:
+            result.position += app_len
+    return result
+
+
+def transform_delete_insert(incoming: Operation, applied: Operation) -> Operation:
+    """
+    incoming = delete, applied = insert (already on server).
+    Insert before delete pos: shift delete right.
+    Insert inside/after: no change.
+    """
+    result = copy.copy(incoming)
+    app_len = len(applied.value)
+
+    if applied.position <= incoming.position:
+        result.position += app_len
+    elif applied.position < incoming.position + incoming.length:
+        # Insert is inside the delete range — expand delete range
+        result.length += app_len
+    return result
+
+
+def transform_insert_delete(incoming: Operation, applied: Operation) -> Operation:
+    """
+    incoming = insert, applied = delete (already on server).
+    Delete before insert pos: shift insert left by deleted length.
+    Delete range overlaps insert pos: push insert to start of deleted range.
+    """
+    result = copy.copy(incoming)
+
+    del_end = applied.position + applied.length
+
+    if del_end <= incoming.position:
+        # Delete entirely before insert — shift left
+        result.position -= applied.length
+    elif applied.position <= incoming.position < del_end:
+        # Insert falls inside deleted region — push to start
+        result.position = applied.position
+    # If delete is entirely after insert pos, no change
+    return result
+
+
+def transform_delete_delete(incoming: Operation, applied: Operation) -> Operation:
+    """
+    Two concurrent deletes.
+    """
+    result = copy.copy(incoming)
+
+    app_end = applied.position + applied.length
+    inc_end = incoming.position + incoming.length
+
+    if app_end <= incoming.position:
+        # Applied delete entirely before incoming delete — shift left
+        result.position -= applied.length
+
+    elif applied.position >= inc_end:
+        # Applied delete entirely after incoming delete — no change
+        pass
+
+    else:
+        # Overlapping deletes — trim incoming to remove already-deleted chars
+        overlap_start = max(applied.position, incoming.position)
+        overlap_end = min(app_end, inc_end)
+        overlap = overlap_end - overlap_start
+
+        # Shift position if applied starts before incoming
+        if applied.position < incoming.position:
+            result.position = applied.position
+        
+        result.length = max(0, result.length - overlap)
+
+    return result
+
+
+def transform_operation(incoming: Operation, applied: Operation) -> Operation:
+    """
+    Transform incoming operation against an already-applied operation.
+    """
+    if incoming.op_type == "insert" and applied.op_type == "insert":
+        return transform_insert_insert(incoming, applied)
+    elif incoming.op_type == "delete" and applied.op_type == "insert":
+        return transform_delete_insert(incoming, applied)
+    elif incoming.op_type == "insert" and applied.op_type == "delete":
+        return transform_insert_delete(incoming, applied)
+    elif incoming.op_type == "delete" and applied.op_type == "delete":
+        return transform_delete_delete(incoming, applied)
+    return incoming
+
+
+def transform_against_log(
+    incoming: Operation,
+    op_log: list,
+    from_version: int,
+    to_version: int,
+) -> Operation:
+    """
+    Transform incoming against all operations from from_version to to_version.
+    op_log is list of (version, Operation) tuples.
+    """
+    result = copy.copy(incoming)
+    for ver, applied_op in op_log:
+        if from_version < ver <= to_version:
+            result = transform_operation(result, applied_op)
+    return result
+
+
+def apply_operation(content: str, op: Operation) -> str:
+    """
+    Apply a single operation to the document content string.
+    Returns new content string.
+    """
+    if op.op_type == "insert":
+        pos = max(0, min(op.position, len(content)))
+        return content[:pos] + op.value + content[pos:]
+    elif op.op_type == "delete":
+        pos = max(0, min(op.position, len(content)))
+        end = max(0, min(pos + op.length, len(content)))
+        return content[:pos] + content[end:]
+    return content
+
+
+def transform_cursor(cursor_pos: int, op: Operation) -> int:
+    """
+    Adjust a cursor position based on an operation.
+    Same logic as OT but for cursor position.
+    """
+    if op.op_type == "insert":
+        ins_len = len(op.value)
+        if op.position <= cursor_pos:
+            return cursor_pos + ins_len
+    elif op.op_type == "delete":
+        del_end = op.position + op.length
+        if del_end <= cursor_pos:
+            return cursor_pos - op.length
+        elif op.position <= cursor_pos < del_end:
+            return op.position
+    return cursor_pos

presence.py

@@ -0,0 +1,133 @@
+"""
+Presence Manager
+Tracks active users per document: cursor positions, selections, colors.
+"""
+
+import time
+import random
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Set
+from fastapi import WebSocket
+
+# Distinct user colors
+USER_COLORS = [
+    "#FF6B6B", "#4ECDC4", "#45B7D1", "#96CEB4", "#FFEAA7",
+    "#DDA0DD", "#98D8C8", "#F7DC6F", "#BB8FCE", "#85C1E9",
+    "#F8C471", "#82E0AA", "#F1948A", "#AED6F1", "#A9DFBF",
+]
+
+USER_NAMES = [
+    "Alice", "Bob", "Carol", "Dave", "Eve",
+    "Frank", "Grace", "Hank", "Iris", "Jack",
+    "Kate", "Leo", "Mia", "Nick", "Olivia",
+]
+
+
+@dataclass
+class UserPresence:
+    user_id: str
+    name: str
+    color: str
+    cursor_pos: int = 0
+    selection_start: int = -1
+    selection_end: int = -1
+    last_seen: float = field(default_factory=time.time)
+    websocket: Optional[object] = None
+
+    def to_dict(self) -> dict:
+        return {
+            "user_id": self.user_id,
+            "name": self.name,
+            "color": self.color,
+            "cursor_pos": self.cursor_pos,
+            "selection_start": self.selection_start,
+            "selection_end": self.selection_end,
+        }
+
+    def ping(self):
+        self.last_seen = time.time()
+
+
+class PresenceManager:
+    def __init__(self):
+        # doc_id -> {user_id -> UserPresence}
+        self._doc_users: Dict[str, Dict[str, UserPresence]] = {}
+        # doc_id -> {user_id -> WebSocket}
+        self._connections: Dict[str, Dict[str, WebSocket]] = {}
+        self._used_colors: Dict[str, Set[str]] = {}
+
+    def _get_color(self, doc_id: str) -> str:
+        used = self._used_colors.get(doc_id, set())
+        available = [c for c in USER_COLORS if c not in used]
+        if not available:
+            available = USER_COLORS
+        color = random.choice(available)
+        self._used_colors.setdefault(doc_id, set()).add(color)
+        return color
+
+    def join(self, doc_id: str, user_id: str, ws: WebSocket) -> UserPresence:
+        if doc_id not in self._doc_users:
+            self._doc_users[doc_id] = {}
+            self._connections[doc_id] = {}
+
+        if user_id not in self._doc_users[doc_id]:
+            color = self._get_color(doc_id)
+            name = random.choice(USER_NAMES)
+            presence = UserPresence(
+                user_id=user_id,
+                name=name,
+                color=color,
+                websocket=ws,
+            )
+            self._doc_users[doc_id][user_id] = presence
+        else:
+            self._doc_users[doc_id][user_id].websocket = ws
+            self._doc_users[doc_id][user_id].ping()
+
+        self._connections[doc_id][user_id] = ws
+        return self._doc_users[doc_id][user_id]
+
+    def leave(self, doc_id: str, user_id: str):
+        if doc_id in self._doc_users:
+            self._doc_users[doc_id].pop(user_id, None)
+            self._connections[doc_id].pop(user_id, None)
+            color = None
+            if color and doc_id in self._used_colors:
+                self._used_colors[doc_id].discard(color)
+
+    def update_cursor(
+        self,
+        doc_id: str,
+        user_id: str,
+        cursor_pos: int,
+        sel_start: int = -1,
+        sel_end: int = -1,
+    ):
+        users = self._doc_users.get(doc_id, {})
+        if user_id in users:
+            p = users[user_id]
+            p.cursor_pos = cursor_pos
+            p.selection_start = sel_start
+            p.selection_end = sel_end
+            p.ping()
+
+    def get_users(self, doc_id: str) -> List[dict]:
+        users = self._doc_users.get(doc_id, {})
+        # Prune stale users (> 30s no ping)
+        now = time.time()
+        active = {
+            uid: u for uid, u in users.items()
+            if now - u.last_seen < 30
+        }
+        self._doc_users[doc_id] = active
+        return [u.to_dict() for u in active.values()]
+
+    def get_connections(self, doc_id: str) -> Dict[str, WebSocket]:
+        return self._connections.get(doc_id, {})
+
+    def get_user(self, doc_id: str, user_id: str) -> Optional[UserPresence]:
+        return self._doc_users.get(doc_id, {}).get(user_id)
+
+
+# Global singleton
+presence_manager = PresenceManager()

requirements.txt

@@ -0,0 +1,4 @@
+fastapi==0.115.0
+uvicorn[standard]==0.30.6
+websockets==13.1
+python-multipart==0.0.12