@synclineapi/editor 2.0.0 → 3.0.1

package/dist/types/index.d.ts

@@ -1,3 +1,69 @@
+export declare class AwarenessManager {
+    private _local;
+    private _peers;
+    private _transport;
+    private _unsub;
+    private _heartbeat;
+    private _gcTimer;
+    private _onChange;
+    constructor(transport: CRDTTransport, name: string);
+    /** Called by the binding when the local cursor moves */
+    updateCursor(row: number, col: number): void;
+    updateSelection(from: {
+        row: number;
+        col: number;
+    }, to: {
+        row: number;
+        col: number;
+    }): void;
+    clearSelection(): void;
+    get localState(): AwarenessState;
+    get peers(): Map<string, AwarenessState>;
+    onChange(cb: (peers: Map<string, AwarenessState>) => void): void;
+    /** Expose broadcast for external use (e.g. initial announcement) */
+    broadcast(): void;
+    private _broadcast;
+    destroy(): void;
+}
+
+export declare interface AwarenessState {
+    readonly siteId: string;
+    readonly name: string;
+    readonly color: string;
+    cursor: {
+        row: number;
+        col: number;
+    } | null;
+    selection: {
+        from: {
+            row: number;
+            col: number;
+        };
+        to: {
+            row: number;
+            col: number;
+        };
+    } | null;
+    readonly updatedAt: number;
+}
+
+export declare interface BindingOptions {
+    /** Display name shown to remote peers (default: 'Peer') */
+    name?: string;
+    /** Called whenever the set of remote peers changes */
+    onPeersChange?: (peers: Map<string, AwarenessState>) => void;
+}
+
+export declare class BroadcastChannelTransport implements CRDTTransport {
+    readonly siteId: string;
+    private readonly _channel;
+    private readonly _cbs;
+    constructor(channelName: string, siteId: string);
+    send(msg: ChannelMessage): void;
+    onMessage(cb: (msg: ChannelMessage) => void): () => void;
+    close(): void;
+}
+
 export declare const BUILT_IN_THEMES: ThemeDefinition[];
 
 /**
@@ -15,6 +81,56 @@ export declare interface CacheMetrics {
     size: number;
 }
 
+export declare type ChannelMessage = {
+    type: 'ops';
+    fromSite: string;
+    ops: CRDTOp[];
+    sv: Record<string, number>;
+} | {
+    type: 'awareness';
+    state: AwarenessState;
+} | {
+    type: 'sync-request';
+    fromSite: string;
+    sv: Record<string, number>;
+} | {
+    type: 'sync-reply';
+    fromSite: string;
+    ops: CRDTOp[];
+};
+
+/** Unique identifier for a character node in the CRDT sequence */
+export declare interface CharId {
+    readonly site: string;
+    readonly clock: number;
+}
+
+export declare function charIdEq(a: CharId, b: CharId): boolean;
+
+export declare function charIdToStr(id: CharId): string;
+
+/**
+ * Collaboration configuration passed to `EditorConfig.collab`.
+ * When set, the editor automatically creates a CRDT binding and renders
+ * remote peer cursors, selections, and presence indicators.
+ */
+export declare interface CollabConfig {
+    /** The transport layer to use (LocalTransport, BroadcastChannelTransport, or WebSocketTransport). */
+    transport: CRDTTransport;
+    /** Display name shown to remote peers. Default: `'Peer'`. */
+    name?: string;
+    /**
+     * Called whenever the set of connected peers changes.
+     * The map is keyed by siteId and contains each peer's latest awareness state.
+     */
+    onPeersChange?: (peers: Map<string, AwarenessState>) => void;
+    /**
+     * Called when the WebSocket connection status changes.
+     * Only relevant when using `WebSocketTransport`.
+     */
+    onStatus?: (status: 'connecting' | 'connected' | 'disconnected' | 'syncing') => void;
+}
+
 /**
  * Context passed to a `provideCompletions` callback.
  * Describes the current cursor position and document state at the moment
@@ -104,6 +220,74 @@ export declare interface CompletionItem {
  */
 export declare type CompletionKind = 'kw' | 'fn' | 'typ' | 'cls' | 'var' | 'snip' | 'emmet';
 
+export declare class CRDTBinding {
+    readonly doc: RGADocument;
+    readonly awareness: AwarenessManager;
+    private readonly _editor;
+    private readonly _transport;
+    private readonly _unsub;
+    private _lastText;
+    private _suppress;
+    constructor(editor: EditorLike, doc: RGADocument, transport: CRDTTransport, opts?: BindingOptions);
+    private _onEditorChange;
+    private _onMessage;
+    private _applyRemoteOps;
+    destroy(): void;
+}
+
+/** A node in the CRDT linked sequence */
+export declare interface CRDTChar {
+    readonly id: CharId;
+    readonly after: CharId;
+    readonly char: string;
+    deleted: boolean;
+}
+
+export declare type CRDTOp = InsertOp | DeleteOp;
+
+export declare interface CRDTTransport {
+    readonly siteId: string;
+    send(msg: ChannelMessage): void;
+    onMessage(cb: (msg: ChannelMessage) => void): () => void;
+    close(): void;
+}
+
+/**
+ * Convenience factory: create a fully wired collaborative editor session.
+ *
+ * @example
+ * ```ts
+ * const session = createCollabSession(editor, { room: 'my-doc', name: 'Alice' });
+ * // Later:
+ * session.destroy();
+ * ```
+ */
+export declare function createCollabSession(editor: {
+    getValue(): string;
+    setValue(v: string): void;
+    updateConfig(c: Record<string, unknown>): void;
+}, options?: {
+    /** Room / channel name shared by all collaborating peers */
+    room?: string;
+    /** Stable unique ID for this peer. Defaults to crypto.randomUUID(). */
+    siteId?: string;
+    /** Display name shown to remote peers */
+    name?: string;
+    /**
+     * Transport type:
+     *  - 'local' (default) — in-process event bus, for same-page demos
+     *  - 'broadcastchannel' — cross-tab on same origin
+     *  - A CRDTTransport constructor (e.g. WebSocketTransport)
+     */
+    transport?: 'local' | 'broadcastchannel' | (new (room: string, siteId: string) => CRDTTransport);
+    /** Called whenever the set of remote peers changes */
+    onPeersChange?: (peers: Map<string, AwarenessState>) => void;
+}): {
+    binding: CRDTBinding;
+    doc: RGADocument;
+    destroy(): void;
+};
+
 /** Convenience type alias for the `createEditor` function signature. */
 export declare type CreateEditor = typeof createEditor;
 
@@ -153,6 +337,29 @@ export declare interface CursorPosition {
     col: number;
 }
 
+export declare interface DeleteOp {
+    readonly type: 'delete';
+    readonly id: CharId;
+}
+
+export declare interface DiffEdit {
+    readonly type: 'insert' | 'delete';
+    readonly offset: number;
+    readonly chars: string;
+}
+
+/**
+ * Compute a minimal edit script from `oldText` to `newText`.
+ *
+ * Strategy: trim common prefix and suffix, then the middle is
+ * either a pure delete, a pure insert, or a replace (delete at
+ * position P + insert at position P). Offsets are in old-text
+ * coordinates for deletes and new-text coordinates for inserts.
+ *
+ * This is O(n) and correct for all practical editor operations.
+ */
+export declare function diffText(a: string, b: string): DiffEdit[];
+
 /**
  * Public API surface returned by `SynclineEditor.create()`.
  * All methods are safe to call at any time after construction.
@@ -689,6 +896,54 @@ export declare interface EditorConfig {
      * ```
      */
     provideHover?: (context: HoverContext) => HoverDoc | null | undefined;
+    /**
+     * Ghost text shown inside the editor when the document is completely empty.
+     * Only rendered when this string is non-empty.
+     * @default ''
+     */
+    placeholder?: string;
+    /**
+     * Enable the Go to Line bar (Ctrl+G / Cmd+G).
+     * When `false` the shortcut does nothing and the bar is never shown.
+     * @default false
+     */
+    goToLine?: boolean;
+    /**
+     * Enable real-time collaborative editing via CRDT.
+     *
+     * When set, the editor automatically:
+     * - Creates an RGA CRDT document and binds it to this editor instance.
+     * - Broadcasts local edits and cursor/selection state to remote peers.
+     * - Renders remote peer cursors (coloured beams + name labels) and
+     *   remote selections (semi-transparent coloured highlights) live.
+     * - Reconciles state on reconnect — works offline and re-syncs automatically.
+     *
+     * To enable collaboration just pass a transport:
+     * ```ts
+     * import { WebSocketTransport } from '@synclineapi/editor';
+     *
+     * const editor = SynclineEditor.create(container, {
+     *   collab: {
+     *     transport: new WebSocketTransport('wss://relay.example.com', 'my-room', crypto.randomUUID()),
+     *     name: 'Alice',
+     *     onPeersChange: (peers) => console.log('peers:', [...peers.values()].map(p => p.name)),
+     *   },
+     * });
+     * ```
+     *
+     * To change or remove collab at runtime call `updateConfig({ collab: ... })`.
+     * Pass `undefined` to tear down the existing binding.
+     *
+     * @default undefined
+     */
+    collab?: CollabConfig;
+}
+
+/** Minimal interface required from the editor */
+declare interface EditorLike {
+    getValue(): string;
+    setValue(v: string): void;
+    updateConfig(c: Record<string, unknown>): void;
 }
 
 /**
@@ -759,12 +1014,30 @@ declare interface HoverDoc {
     language?: string | string[];
 }
 
+export declare interface InsertOp {
+    readonly type: 'insert';
+    readonly id: CharId;
+    readonly after: CharId;
+    readonly char: string;
+}
+
 /**
  * Supported language identifiers for syntax highlighting and autocomplete.
  * Pass as the `language` option in `EditorConfig`.
  */
 export declare type Language = 'typescript' | 'javascript' | 'css' | 'json' | 'markdown' | 'text';
 
+export declare class LocalTransport implements CRDTTransport {
+    readonly siteId: string;
+    private readonly _room;
+    private readonly _cbs;
+    constructor(room: string, siteId: string);
+    private readonly _receive;
+    send(msg: ChannelMessage): void;
+    onMessage(cb: (msg: ChannelMessage) => void): () => void;
+    close(): void;
+}
+
 /**
  * Colour palette used when painting the minimap canvas.
  * Each value is a CSS colour string resolved from the active theme.
@@ -796,6 +1069,72 @@ export declare interface MinimapColors {
     [key: string]: string;
 }
 
+export declare class RGADocument {
+    /** All nodes, keyed by their canonical string ID */
+    private readonly _chars;
+    /** The full ordered sequence of IDs (visible + tombstones) */
+    private _seq;
+    /** Reverse index: idStr → index in _seq (invalidated on splice, rebuilt lazily) */
+    private _idxDirty;
+    private _idxMap;
+    readonly siteId: string;
+    private _clock;
+    readonly stateVector: StateVector;
+    /** Full operation log — used to answer sync-requests from peers */
+    private readonly _opLog;
+    constructor(siteId: string);
+    get clock(): number;
+    /** Return the visible document text */
+    getText(): string;
+    /** Number of visible characters */
+    get length(): number;
+    /**
+     * Insert `text` at visible offset `offset`.
+     * Returns the generated ops (apply them locally AND send to peers).
+     */
+    localInsert(offset: number, text: string): InsertOp[];
+    /**
+     * Delete `length` visible characters starting at `offset`.
+     * Returns the generated ops.
+     */
+    localDelete(offset: number, length: number): DeleteOp[];
+    /**
+     * Apply an op from a remote peer.
+     * Returns true if the op was new (applied), false if already seen.
+     */
+    apply(op: CRDTOp): boolean;
+    /** Return all ops not yet seen by `sv` */
+    getOpsSince(sv: StateVector): CRDTOp[];
+    getStateVector(): StateVector;
+    serialize(): {
+        siteId: string;
+        clock: number;
+        ops: CRDTOp[];
+    };
+    static deserialize(data: {
+        siteId: string;
+        clock: number;
+        ops: CRDTOp[];
+    }): RGADocument;
+    private _genId;
+    private _updateSV;
+    private _applyInsert;
+    private _applyDelete;
+    /**
+     * YATA comparison: returns >0 if `a` has priority (goes first / to the left).
+     * Higher clock wins; equal clock → lower siteId wins.
+     */
+    private _cmp;
+    private _rebuildIdx;
+    /** Return the ID of the n-th visible character (0-indexed). Returns ROOT_ID for n<0. */
+    private _visibleIdAt;
+    /** Return IDs of `len` visible characters starting at `offset` */
+    private _visibleIdsInRange;
+}
+
+/** Sentinel root node — logical start-of-document anchor */
+export declare const ROOT_ID: CharId;
+
 /**
  * A selection range defined by an anchor (where selection started)
  * and a focus (where the caret currently sits). Either end can be
@@ -813,6 +1152,15 @@ declare interface Selection_2 {
 }
 export { Selection_2 as Selection }
 
+export declare function siteColor(siteId: string): string;
+
+/** Maps siteId → highest clock value seen from that site */
+export declare type StateVector = Map<string, number>;
+
+export declare function svFromRecord(r: Record<string, number>): StateVector;
+
+export declare function svToRecord(sv: StateVector): Record<string, number>;
+
 export declare class SynclineEditor implements EditorAPI {
     private readonly _host;
     private readonly _shadow;
@@ -835,6 +1183,10 @@ export declare class SynclineEditor implements EditorAPI {
     private readonly _hoverTip;
     private readonly _themeOverlay;
     private readonly _themePanel;
+    private readonly _placeholderEl;
+    private readonly _goToLineBar;
+    private readonly _goToLineInput;
+    private readonly _goToLineHint;
     private _config;
     private _tab;
     private _wm;
@@ -867,6 +1219,10 @@ export declare class SynclineEditor implements EditorAPI {
     private _dynamicStyleEl;
     private _emmetExpanded;
     private _snippetExpanded;
+    /** Active snippet tab-stop session. Cleared on click, Escape, or structural edit. */
+    private _snippetSession;
+    private _collabBinding;
+    private _remotePeers;
     /** Pending debounce timer ID for autocomplete re-computation. */
     private _acDebounceTimer;
     /** Pending requestAnimationFrame ID for coalesced renders. */
@@ -893,8 +1249,15 @@ export declare class SynclineEditor implements EditorAPI {
     undo(): void;
     redo(): void;
     executeCommand(command: string): void;
+    private _initCollab;
+    private _destroyCollab;
+    /** Notify remote peers of the current local cursor / selection position. */
+    private _broadcastCursorToCollab;
     destroy(): void;
     private _buildFindBar;
+    private _buildGoToLineBar;
+    private _openGoToLine;
+    private _closeGoToLine;
     private _buildStatusBar;
     private _applyDynamicStyles;
     /**
@@ -974,6 +1337,7 @@ export declare class SynclineEditor implements EditorAPI {
     private _isWordChar;
     private _wordSkipRight;
     private _wordSkipLeft;
+    private _duplicateLines;
     private _moveLines;
     private _scheduleHover;
     private _doHover;
@@ -1180,4 +1544,53 @@ export declare interface TokenColors {
     decorator?: string;
 }
 
+export declare class WebSocketTransport implements CRDTTransport {
+    readonly siteId: string;
+    private _ws;
+    private readonly _baseUrl;
+    private readonly _cbs;
+    private _reconnectTimer;
+    private _pingTimer;
+    private _closed;
+    private _attempt;
+    private _queue;
+    private readonly _opts;
+    /**
+     * @param serverUrl  Base WebSocket URL **without** trailing slash.
+     *                   Room and siteId are appended automatically.
+     *                   Example: `"ws://localhost:8080"` → connects to
+     *                   `ws://localhost:8080/<room>?site=<siteId>`
+     * @param room       Document / collaboration room identifier.
+     * @param siteId     This peer's unique ID (UUID).
+     * @param opts       Optional behaviour hooks and tuning knobs.
+     */
+    constructor(serverUrl: string, room: string, siteId: string, opts?: WebSocketTransportOptions);
+    private _connect;
+    /** Exponential back-off: 250 ms × 2^attempt, capped at maxBackoffMs. */
+    private _scheduleReconnect;
+    private _startPing;
+    private _stopPing;
+    send(msg: ChannelMessage): void;
+    private _rawSend;
+    onMessage(cb: (msg: ChannelMessage) => void): () => void;
+    close(): void;
+    /** Current WebSocket ready-state as a human-readable string. */
+    get connectionState(): 'connecting' | 'open' | 'closing' | 'closed';
+    /** Number of messages currently buffered waiting for reconnection. */
+    get queuedMessageCount(): number;
+}
+
+declare interface WebSocketTransportOptions {
+    /** Called each time the connection is established (including re-connects). */
+    onConnect?: () => void;
+    /** Called when the connection drops.  `willReconnect` is false on explicit close(). */
+    onDisconnect?: (willReconnect: boolean) => void;
+    /** Called on unrecoverable or unexpected errors. */
+    onError?: (err: Event) => void;
+    /** Ping interval in ms.  Default 25 000.  Set to 0 to disable. */
+    pingIntervalMs?: number;
+    /** Maximum reconnection delay in ms.  Default 30 000. */
+    maxBackoffMs?: number;
+}
+
 export { }

package/package.json

@@ -3,7 +3,7 @@
     "publishConfig": {
         "access": "public"
     },
-    "version": "2.0.0",
+    "version": "3.0.1",
     "description": "A zero-dependency, pixel-perfect, fully customisable browser-based code editor",
     "type": "module",
     "main": "./dist/syncline-editor.umd.js",
@@ -22,6 +22,7 @@
     ],
     "scripts": {
         "dev": "vite --config vite.config.ts",
+        "dev:app": "vite --config vite.config.app.ts",
         "build": "tsc --noEmit && vite build --config vite.lib.config.ts",
         "build:app": "vite build --config vite.config.app.ts",
         "preview": "vite preview --config vite.config.ts",