@scipen/ot-core

Platform-agnostic Operational Transformation client state machine for real-time collaborative editing.

Core responsibilities:

• Connection lifecycle (with exponential backoff + jitter reconnect)
• OT state machine: DISCONNECTED → CONNECTING → SYNCHRONIZED ⇄ WAITING_FOR_ACK
• Local op debouncing + compose (batch consecutive edits)
• Remote op transformation against pending local ops
• WebSocket ping/pong watchdog + ack timeout guard

Install

pnpm add @scipen/ot-core @scipen/ot-protocol

# + one adapter, e.g.:
pnpm add @scipen/ot-adapter-browser  # or -electron-main

Usage

import { OTCore } from '@scipen/ot-core';
import { createOTBrowserAdapters } from '@scipen/ot-adapter-browser';

const client = new OTCore(
  { baseUrl: '/ot', token: 'xxx', userId: 'u1' },
  createOTBrowserAdapters()
);

client.on('content:change', (content) => console.log(content));
client.connect();
client.joinFile('project-id', 'file-id');

State machine

DISCONNECTED → CONNECTING → SYNCHRONIZED ⇄ WAITING_FOR_ACK
                                ↑                   |
                                └───────────────────┘

• Local edits in SYNCHRONIZED → transition to WAITING_FOR_ACK
• Ack received → back to SYNCHRONIZED
• Remote op while WAITING_FOR_ACK → transform against pending op, buffer further local edits

Testing

pnpm test  # 45 tests: smoke (6) + state machine (39 — 四态转换 / pending op 重放 / remote op transform / watchdog)

Dependency graph

@scipen/ot-protocol
        ↓
  @scipen/ot-core  (this package)
        ↓
  ot-adapter-browser, ot-adapter-electron-main, ot-react

License

MIT © SciPen Team