@synclineapi/editor 2.0.0 → 3.0.0

package/README.md

@@ -75,6 +75,16 @@ Ships as both an **ES module** and **UMD bundle**, runs entirely inside a **Shad
   - [Indent Guides](#indent-guides)
   - [Active Line Highlight](#active-line-highlight)
   - [Read-Only Mode](#read-only-mode)
+- [Collaborative Editing](#collaborative-editing)
+  - [Quick Start — Same Page](#quick-start--same-page)
+  - [Cross-Tab Collaboration](#cross-tab-collaboration)
+  - [Using WebSocket for Realtime Collaboration](#using-websocket-for-realtime-collaboration)
+  - [CollabConfig Reference](#collabconfig-reference)
+  - [Transport Reference](#transport-reference)
+  - [Peer Awareness & Cursors](#peer-awareness--cursors)
+  - [Remote Cursor CSS Classes](#remote-cursor-css-classes)
+  - [Offline & Reconnect](#offline--reconnect)
+  - [Playground Collab Panel](#playground-collab-panel)
 - [Behavioral Options](#behavioral-options)
   - [Auto-Close Pairs](#auto-close-pairs)
   - [Line Comment Token](#line-comment-token)
@@ -115,11 +125,14 @@ Ships as both an **ES module** and **UMD bundle**, runs entirely inside a **Shad
 | **Unified autocomplete** | One `completions` array for keywords, snippets, custom symbols, and DSL items |
 | **VS Code-style docs panel** | Description panel beside the popup — shown for items with `description` |
 | **Dynamic provider** | `provideCompletions` callback for context-aware, fully runtime-controlled completions |
-| **Built-in snippets** | 17 snippets across TypeScript/JS, CSS, and HTML — Tab-expandable |
+| **Built-in snippets** | 17 snippets across TypeScript/JS, CSS, and HTML — Tab-expandable with full tab-stop session (`$1` → `$2` → …) |
 | **Emmet expansion** | `div.wrapper>ul>li*3` → Tab — with inline preview tooltip |
 | **Multi-cursor** | `Alt+Click` to add cursors; `Ctrl+D` to select next occurrence |
 | **Hover documentation** | Tooltip on pointer-rest over any identifier — built-in JS/TS/CSS docs + custom `provideHover` callback |
 | **Move line** | `Alt+Up` / `Alt+Down` to move the current line or selected block up/down |
+| **Duplicate line** | `Shift+Alt+Down` / `Shift+Alt+Up` to duplicate the current line or selected block — cursor follows the new copy |
+| **Go to Line** | `Ctrl+G` / `Cmd+G` prompt to jump to any line number — opt-in via `goToLine: true` |
+| **Placeholder** | Ghost hint text shown in the editor when the document is empty — set via `placeholder` option |
 | **Find & Replace** | Literal and regex search, case-sensitive mode, replace one / all |
 | **Code folding** | Collapse `{}` blocks via gutter toggle |
 | **Bracket matching** | Highlights matching `()[]{}` pairs at the cursor |
@@ -131,6 +144,7 @@ Ships as both an **ES module** and **UMD bundle**, runs entirely inside a **Shad
 | **Whitespace rendering** | Visible `·` / `→` for spaces and tabs (`none` / `boundary` / `all`) |
 | **Cursor styles** | `line`, `block`, or `underline`; configurable blink rate |
 | **Read-only mode** | All edits blocked; navigation, selection, and copy still work |
+| **Collaborative editing** | Real-time multi-user editing via CRDT (RGA/YATA); remote cursors + selections rendered inline; three built-in transports |
 
 ---
 
@@ -258,6 +272,8 @@ Default `autoClosePairs`:
 | `findReplace` | `boolean` | `true` | Enable find-and-replace (`Ctrl+H`). |
 | `wordSelection` | `boolean` | `true` | Double-click selects the word under the cursor. |
 | `hover` | `boolean` | `true` | Show a documentation tooltip when the pointer rests on a known identifier for ~500 ms. Covers built-in JS/TS symbols and any symbol in `completions` with a `description`, plus the `provideHover` callback. |
+| `goToLine` | `boolean` | `false` | Enable the Go to Line bar (`Ctrl+G` / `Cmd+G`). Pressing the shortcut opens a centered prompt; `Enter` jumps the cursor, `Escape` dismisses. Off by default. |
+| `placeholder` | `string` | `''` | Ghost text rendered at the cursor position when the document is completely empty. Hidden when the document has any content or when the string is empty. |
 
 ### Syntax & Autocomplete Customisation
 
@@ -913,7 +929,7 @@ editor.updateConfig({ hover: false });
 
 ## Snippets
 
-Snippets let you type a short trigger word and press `Tab` to expand a full multi-line block. The cursor lands at the first `$1` tab stop after expansion.
+Snippets let you type a short trigger word and press `Tab` to expand a full multi-line block. After expansion a **tab-stop session** begins: the cursor lands at `$1`, and each subsequent `Tab` advances to `$2`, `$3`, and so on. `Shift+Tab` moves backward. Upcoming tab stops are shown as dim ghost cursor markers so you always know where you'll land next. The session ends when you reach the last stop, press `Escape`, or click elsewhere.
 
 Snippets appear in the unified autocomplete popup with an **S** badge alongside keywords, functions, and Emmet abbreviations. When a snippet item is selected in the popup, its body template is previewed in the description panel on the right.
 
@@ -1003,10 +1019,13 @@ createEditor(container, { snippetExpansion: false });
 
 | Placeholder | Meaning |
 |---|---|
-| `$1` | First cursor stop — where the caret lands immediately after expansion |
-| `$2`, `$3`, … | Additional tab stops (rendered as visual hints; no cycling yet) |
+| `$1` | First tab stop — cursor lands here immediately after expansion |
+| `$2`, `$3`, … | Additional tab stops — press `Tab` to jump through them in order |
+| `$0` | Final cursor position (VS Code convention) — session ends here |
 | `\n` | Line break — continuation lines inherit the trigger line's indentation |
 
+Tab stops are rendered as **dim ghost cursor markers** at their positions in the document. As you type at the current stop the ghost markers shift to stay accurate. Pressing `Shift+Tab` moves back to the previous stop. The session exits when you reach `$0` (or the last stop), press `Escape`, click elsewhere, or press `Enter` / `Delete`.
+
 > **Priority:** Emmet is tried first on Tab. If both Emmet and a snippet match the same word, Emmet wins.
 
 ---
@@ -1296,6 +1315,253 @@ editor.updateConfig({ readOnly: true });   // lock again
 
 ---
 
+## Collaborative Editing
+
+Syncline Editor has **built-in real-time collaboration** powered by an RGA/YATA CRDT. All you need is a transport — every operation is causally ordered and converges identically on every peer with no server-side merge logic required.
+
+Collaboration is activated by adding a `collab` property to `EditorConfig`:
+
+```ts
+import { createEditor, LocalTransport } from 'syncline-editor';
+
+const transport = new LocalTransport('my-room');
+
+const editor = createEditor(container, {
+  value: '',
+  language: 'typescript',
+  collab: {
+    transport,
+    name: 'Alice',
+  },
+});
+```
+
+That's all. The editor auto-creates the internal `RGADocument`, wires bidirectional sync, and starts rendering remote peers' cursors and selections.
+
+---
+
+### Quick Start — Same Page
+
+`LocalTransport` uses a same-page event bus — perfect for demos and tests where multiple `createEditor` calls share one HTML document (e.g. an **A / B** split demo).
+
+```ts
+import { createEditor, LocalTransport } from 'syncline-editor';
+
+// Both editors share the same room ID — they sync instantly
+const transport = new LocalTransport('demo-room');
+
+const editorA = createEditor(containerA, {
+  collab: { transport, name: 'Alice' },
+});
+
+const editorB = createEditor(containerB, {
+  collab: { transport: new LocalTransport('demo-room'), name: 'Bob' },
+});
+```
+
+> Each `LocalTransport` instance gets its own `siteId` automatically. Two instances with the same room string form a peer pair.
+
+---
+
+### Cross-Tab Collaboration
+
+`BroadcastChannelTransport` uses the browser's built-in `BroadcastChannel` API — syncs across **multiple tabs on the same origin** with no server needed.
+
+```ts
+import { createEditor, BroadcastChannelTransport } from 'syncline-editor';
+
+const editor = createEditor(container, {
+  collab: {
+    transport: new BroadcastChannelTransport('my-room'),
+    name: 'Alice',
+  },
+});
+```
+
+Open the same page in two tabs — edits in one appear in the other within milliseconds.
+
+---
+
+### Using WebSocket for Realtime Collaboration
+
+For cross-device / cross-origin collaboration, use `WebSocketTransport` with any WebSocket server that broadcasts messages to room participants. The server never needs to understand CRDT operations — it simply relays raw messages.
+
+```ts
+import { createEditor, WebSocketTransport } from 'syncline-editor';
+
+const editor = createEditor(container, {
+  collab: {
+    transport: new WebSocketTransport('wss://your-server.example.com', 'my-room'),
+    name:      'Alice',
+    onStatus:  (s) => console.log('collab status:', s),
+  },
+});
+```
+
+You can point `WebSocketTransport` at **any** WebSocket endpoint — a custom Node.js server, a managed service, or a serverless WebSocket API. All CRDT merging happens client-side; the server only needs to broadcast incoming messages to every other participant in the same room.
+
+#### `WebSocketTransport` resilience
+
+- **Exponential backoff** reconnect (100 ms → 1.6 s cap) with automatic re-send of any operations queued while offline
+- **State-vector sync** on reconnect — only missing operations are exchanged, not the full document
+- **Send queue** — operations generated while disconnected are buffered and flushed once the socket reopens
+
+---
+
+### CollabConfig Reference
+
+```ts
+interface CollabConfig {
+  /** Transport layer — required. Determines how ops are exchanged. */
+  transport: CRDTTransport;
+
+  /**
+   * Display name shown in the cursor label of remote peers.
+   * Defaults to the site ID if omitted.
+   */
+  name?: string;
+
+  /**
+   * Called whenever the set of connected peers changes (join / leave / heartbeat).
+   * Receives the full current peer map: siteId → AwarenessState.
+   */
+  onPeersChange?: (peers: Map<string, AwarenessState>) => void;
+
+  /**
+   * Called when the transport connection status changes.
+   * Useful for showing a status indicator in your UI.
+   */
+  onStatus?: (status: 'connecting' | 'connected' | 'disconnected' | 'syncing') => void;
+}
+```
+
+Pass `collab: undefined` (or omit it) to disable collaboration.
+Disable at runtime by calling `editor.updateConfig({ collab: undefined })`.
+
+---
+
+### Transport Reference
+
+| Transport | Import | Description |
+|---|---|---|
+| `LocalTransport` | `syncline-editor` | In-page event bus. Ideal for split-screen demos and unit tests. |
+| `BroadcastChannelTransport` | `syncline-editor` | Cross-tab sync on the same origin. No server required. |
+| `WebSocketTransport` | `syncline-editor` | Realtime WebSocket. Works across devices and origins. |
+
+All three implement the same `CRDTTransport` interface, so you can provide your own transport (e.g. WebRTC data channels, SSE, etc.) if needed:
+
+```ts
+interface CRDTTransport {
+  readonly siteId: string;
+  connect(onMessage: (msg: ChannelMessage) => void): void;
+  send(msg: ChannelMessage): void;
+  disconnect(): void;
+}
+```
+
+---
+
+### Peer Awareness & Cursors
+
+Syncline broadcasts awareness state (cursor position, selection, display name) over the transport alongside document operations.
+
+- Each connected peer gets a **deterministic color** derived from its `siteId` hash
+- Peer presence is maintained via **3-second heartbeats**; peers that miss 3 beats (9 s) are garbage-collected
+- Remote cursors and selections update on every render cycle — they respond to scrolling, word wrap changes, and virtual-scroll position automatically
+
+#### Reacting to peer changes
+
+```ts
+const editor = createEditor(container, {
+  collab: {
+    transport,
+    name: 'Alice',
+    onPeersChange: (peers) => {
+      // peers: Map<siteId, AwarenessState>
+      renderPeerAvatars([...peers.values()]);
+    },
+  },
+});
+```
+
+#### `AwarenessState` shape
+
+```ts
+interface AwarenessState {
+  siteId:    string;
+  name?:     string;
+  color:     string;   // hex color derived from siteId
+  cursor?:   { row: number; col: number };
+  selection?: { anchor: { row: number; col: number }; focus: { row: number; col: number } };
+  updatedAt: number;   // timestamp of last heartbeat
+}
+```
+
+---
+
+### Remote Cursor CSS Classes
+
+Remote cursors and selections are rendered as inline `<span>` elements inside the Shadow DOM. You can override their appearance using Shadow DOM part selectors or by targeting the CSS custom properties from outside the shadow root if your host page injects styles into it.
+
+| Class | Element | Description |
+|---|---|---|
+| `.sl-rc` | `<span>` | Zero-width anchor for a remote cursor beam |
+| `.sl-rc::after` | pseudo | The 2 px vertical cursor beam |
+| `.sl-rc-label` | `<span>` | Name chip that floats above the beam |
+| `.sl-rs` | `<span>` | Highlighted text span for a remote selection |
+
+CSS custom properties set inline on each `.sl-rc` and `.sl-rs`:
+
+| Property | Description |
+|---|---|
+| `--rc-color` | Peer color (hex) — controls the beam and label background |
+| `--rs-color` | Peer color with `33` alpha suffix — semi-transparent selection fill |
+
+Example override (injected via `adoptedStyleSheets` or a `<style>` tag appended to the shadow root):
+
+```css
+/* Thicker cursor beam */
+.sl-rc::after { width: 3px; }
+
+/* Fully opaque name label */
+.sl-rc-label { opacity: 1; }
+
+/* Rounder selection highlight */
+.sl-rs { border-radius: 4px; }
+```
+
+---
+
+### Offline & Reconnect
+
+When a peer disconnects and reconnects:
+
+1. The transport fires a `connect` event with a **state vector** — a map of `siteId → clock` representing everything the reconnecting peer already has.
+2. The local `RGADocument` computes the **diff**: operations the peer is missing.
+3. Only the missing ops are retransmitted — not the full document history.
+
+This makes reconnect efficient even for long editing sessions.
+
+While disconnected, any local edits are stored in the **send queue** and flushed automatically once the socket reopens.
+
+---
+
+### Playground Collab Panel
+
+The interactive playground (`npm run dev`) includes a dedicated **Collaboration** panel in the left sidebar:
+
+- **Enable / disable** toggle — connect or disconnect with one click
+- **Display name** — the name shown in your cursor label on other peers' screens
+- **Transport selector** — `Local` / `BroadcastChannel` / `WebSocket`
+- **Room ID** — shared room name (all peers must use the same room)
+- **WebSocket URL** — shown only when the WebSocket transport is selected
+- **Status** — live `connecting` / `connected` / `disconnected` indicator
+- **Connected peers** — colored avatar chips with each peer's display name
+
+The playground CRDT demo section also shows a live **Alice ↔ Bob** split view — both editors on the same page using `LocalTransport` — so you can see remote cursors and selections in action immediately.
+
+---
+
 ## Behavioral Options
 
 ### Auto-Close Pairs
@@ -1385,6 +1651,8 @@ createEditor(container, {
   showGutter:          false,  // hide line numbers
   showMinimap:         false,  // hide minimap panel
   showStatusBar:       false,  // hide status bar
+  goToLine:            true,   // enable Ctrl+G / Cmd+G Go to Line
+  placeholder:         'Start typing…',  // shown when document is empty
 });
 ```
 
@@ -1402,6 +1670,7 @@ createEditor(container, {
 | `Ctrl / Cmd + V` | Paste | `readOnly` |
 | `Ctrl / Cmd + F` | Open find bar | `find` |
 | `Ctrl / Cmd + H` | Open find + replace | `findReplace` |
+| `Ctrl / Cmd + G` | Open Go to Line prompt | `goToLine` |
 | `Ctrl / Cmd + D` | Select next occurrence | `multiCursor` |
 | `Ctrl / Cmd + Shift + D` | Duplicate line | `readOnly` |
 | `Ctrl / Cmd + K` | Delete line | `readOnly` |
@@ -1409,12 +1678,16 @@ createEditor(container, {
 | `Alt / Option + Z` | Toggle word wrap | — |
 | `Alt / Option + ↑` | Move current line (or selected block) up | `readOnly` |
 | `Alt / Option + ↓` | Move current line (or selected block) down | `readOnly` |
-| `Tab` | Indent / expand Emmet / expand snippet | `emmet`, `snippetExpansion`, `tabSize` |
-| `Shift + Tab` | Outdent | `tabSize` |
+| `Shift + Alt / Option + ↓` | Duplicate current line (or selected block) down — cursor moves to new copy | `readOnly` |
+| `Shift + Alt / Option + ↑` | Duplicate current line (or selected block) up — cursor stays on new copy | `readOnly` |
+| `Tab` | Advance to next snippet tab stop · expand Emmet · expand snippet · indent | `snippetExpansion`, `emmet`, `tabSize` |
+| `Shift + Tab` | Go to previous snippet tab stop · outdent | `snippetExpansion`, `tabSize` |
+| `Alt / Option + →` (Mac) | Word skip right (groups by character class: word / punctuation) | `wordSeparators` |
+| `Alt / Option + ←` (Mac) | Word skip left (groups by character class: word / punctuation) | `wordSeparators` |
 | `Alt / Option + Click` | Add extra cursor | `multiCursor` |
 | `Double-click` | Select word | `wordSelection`, `wordSeparators` |
 | `Triple-click` | Select entire line | — |
-| `Escape` | Clear selection · close popup · close find · remove extra cursors | — |
+| `Escape` | Clear selection · exit snippet session · close popup · close find · remove extra cursors | — |
 | `↑ ↓ ← →` | Move cursor | — |
 | `Cmd + ← →` (Mac) | Start / end of line | — |
 | `Cmd + ↑ ↓` (Mac) | Start / end of document | — |
@@ -1664,6 +1937,12 @@ import type {
   // Themes
   ThemeDefinition,
   ThemeTokens,
+
+  // Collaboration
+  CollabConfig,
+  CRDTTransport,
+  AwarenessState,
+  ChannelMessage,
 } from 'syncline-editor';
 ```
 
@@ -1774,6 +2053,15 @@ syncline-editor/
 │   │   ├── document.ts           # Document model, undo/redo, selection helpers
 │   │   ├── tokeniser.ts          # Language-aware syntax tokeniser (zero deps)
 │   │   └── wrap-map.ts           # Soft-wrap virtual line map
+│   ├── crdt/
+│   │   ├── rga.ts                # RGA/YATA CRDT document — insert/delete with causal ordering
+│   │   ├── binding.ts            # Two-way bridge between SynclineEditor and RGADocument
+│   │   ├── awareness.ts          # Peer presence heartbeat + garbage collection
+│   │   ├── transport-local.ts    # LocalTransport — same-page event bus
+│   │   ├── transport-bc.ts       # BroadcastChannelTransport — cross-tab
+│   │   ├── transport-ws.ts       # WebSocketTransport — realtime WebSocket + reconnect queue
+│   │   ├── types.ts              # CRDT type definitions (CharId, CRDTOp, CollabConfig, …)
+│   │   └── index.ts              # CRDT barrel export
 │   ├── features/
 │   │   ├── autocomplete.ts       # Completion engine — ranking, filtering, snippet items
 │   │   ├── bracket-matcher.ts    # Bracket-pair finder
@@ -1850,6 +2138,7 @@ The playground at `playground/index.html` is a fully self-contained interactive
 - **Behavior** — auto-close pairs, line comment token, word separators, undo batch window
 - **Actions** — buttons for every `executeCommand` and `getValue` / `setValue`
 - **Event log** — live feed of all `onChange` / `onCursorChange` / `onSelectionChange` / `onFocus` / `onBlur` events
+- **Collaboration** — enable/disable collab, choose transport (Local / BroadcastChannel / WebSocket), set display name and room ID, see live peer avatars and connection status
 
 ---