@rtif-sdk/web 1.0.0

package/dist/editor.js

@@ -0,0 +1,710 @@
+/**
+ * Web editor entry point — composes all modules into a single `WebEditor`.
+ *
+ * The `createWebEditor()` factory sets up a contenteditable element, wires
+ * the input bridge, renderer, selection sync, composition handler, clipboard,
+ * cursor navigation, command bus, shortcut handler, content pipeline, and
+ * drag-and-drop handling. It returns a {@link WebEditor} handle for imperative
+ * control (focus, blur, destroy).
+ *
+ * @module
+ */
+import { resolve } from '@rtif-sdk/core';
+import { renderInitial, reconcile } from './renderer.js';
+import { buildBlockOffsetCache, domPointToRtifOffset, readDomSelection, setDomSelection, isSuppressed, resetSuppression, } from './selection-sync.js';
+import { InputBridge } from './input-bridge.js';
+import { CompositionHandler } from './composition.js';
+import { ClipboardHandler } from './clipboard.js';
+import { CursorNavHandler, isMac } from './cursor-nav.js';
+import { createCommandBus } from './command-bus.js';
+import { ShortcutHandler } from './shortcut-handler.js';
+import { scrollToCursor } from './scroll-to-cursor.js';
+import { createContentPipeline } from './content-pipeline.js';
+import { extractFromPaste, extractFromDrop } from './content-extraction.js';
+import { createPlainTextHandler } from './content-handlers.js';
+import { createRtifPasteHandler } from './content-handlers.js';
+import { createHtmlPasteHandler } from './content-handlers.js';
+import { createImageContentHandler } from './content-handler-image.js';
+import { createUrlContentHandler } from './content-handler-url.js';
+import { createFileDropHandler } from './content-handler-file.js';
+import { DropIndicator } from './drop-indicator.js';
+import { createMarkRendererRegistry, registerBuiltinRenderers, } from './mark-renderer.js';
+import { createBlockRendererRegistry, registerBuiltinBlockRenderers, } from './block-renderer.js';
+import { BlockDragHandler } from './block-drag-handler.js';
+import { createCursorRectAPI } from './cursor-rect.js';
+import { createTriggerManager } from './trigger-manager.js';
+import { findContiguousMarkRange, adjustOffsetAroundAtomicMarks, adjustOffsetAroundAtomicBlocks } from './plugins/mark-utils.js';
+import { installWebPlugins } from './plugin-kit.js';
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a web editor instance backed by the RTIF engine.
+ *
+ * Sets up `contenteditable`, attaches all event handlers, performs the initial
+ * render, and optionally auto-focuses. Returns a {@link WebEditor} handle.
+ *
+ * @param config - Editor configuration (root element, engine, options)
+ * @returns A WebEditor instance with imperative control methods
+ *
+ * @example
+ * ```ts
+ * import { createEngine } from '@rtif-sdk/engine';
+ * import { createWebEditor } from '@rtif-sdk/web';
+ *
+ * const engine = createEngine({
+ *   initialDoc: { version: 1, blocks: [{ id: 'b1', type: 'text', spans: [{ text: '' }] }] },
+ * });
+ *
+ * const editor = createWebEditor({
+ *   root: document.getElementById('editor')!,
+ *   engine,
+ *   accessibleLabel: 'Document editor',
+ * });
+ *
+ * editor.focus();
+ * ```
+ */
+export function createWebEditor(config) {
+    const { root, engine } = config;
+    const readOnly = config.readOnly ?? false;
+    const spellcheck = config.spellcheck ?? true;
+    const autoFocus = config.autoFocus ?? false;
+    let destroyed = false;
+    // -------------------------------------------------------------------
+    // Set up the contenteditable root
+    // -------------------------------------------------------------------
+    root.setAttribute('contenteditable', readOnly ? 'false' : 'true');
+    root.setAttribute('role', 'textbox');
+    root.setAttribute('aria-multiline', 'true');
+    root.setAttribute('aria-label', config.accessibleLabel);
+    root.setAttribute('data-rtif-root', '');
+    root.spellcheck = spellcheck;
+    // Accessibility: announce read-only state to screen readers
+    if (readOnly) {
+        root.setAttribute('aria-readonly', 'true');
+    }
+    // CSS containment for layout isolation (Phase 8)
+    root.style.contain = 'content';
+    // Preserve whitespace so trailing spaces, consecutive spaces, and tabs render
+    root.style.whiteSpace = 'pre-wrap';
+    if (config.placeholder) {
+        root.setAttribute('data-placeholder', config.placeholder);
+    }
+    // -------------------------------------------------------------------
+    // Mark renderer registry
+    // -------------------------------------------------------------------
+    const markRenderers = createMarkRendererRegistry();
+    registerBuiltinRenderers(markRenderers);
+    // -------------------------------------------------------------------
+    // Block renderer registry
+    // -------------------------------------------------------------------
+    const blockRenderers = createBlockRendererRegistry();
+    registerBuiltinBlockRenderers(blockRenderers);
+    // -------------------------------------------------------------------
+    // Web plugins (custom marks, blocks, attrs, replacers)
+    // -------------------------------------------------------------------
+    if (config.webPlugins) {
+        installWebPlugins(config.webPlugins, engine, markRenderers, blockRenderers);
+    }
+    // -------------------------------------------------------------------
+    // Initial render
+    // -------------------------------------------------------------------
+    renderInitial(root, engine.state.doc, markRenderers, blockRenderers);
+    // -------------------------------------------------------------------
+    // Command bus
+    // -------------------------------------------------------------------
+    const commandBus = createCommandBus(engine);
+    // -------------------------------------------------------------------
+    // Composition handler
+    // -------------------------------------------------------------------
+    const compositionHandler = new CompositionHandler({
+        getSelection: () => engine.state.selection,
+        getBlockIdAtOffset: (offset) => {
+            try {
+                const { blockIndex } = resolve(engine.state.doc, offset);
+                return engine.state.doc.blocks[blockIndex]?.id ?? null;
+            }
+            catch {
+                return null;
+            }
+        },
+    });
+    // -------------------------------------------------------------------
+    // Cursor rect API (for positioning floating UI)
+    // -------------------------------------------------------------------
+    const cursorRect = createCursorRectAPI(root, () => engine.state.doc);
+    // -------------------------------------------------------------------
+    // Trigger manager (for @mentions, #hashtags, /slash-commands)
+    // Must be created BEFORE shortcutHandler so trigger keys are
+    // intercepted first (both use capture-phase keydown).
+    // -------------------------------------------------------------------
+    const triggerManager = createTriggerManager({
+        root,
+        engine,
+        cursorRect,
+        isComposing: () => compositionHandler.isComposing(),
+    });
+    // -------------------------------------------------------------------
+    // Shortcut handler
+    // -------------------------------------------------------------------
+    const shortcutHandler = new ShortcutHandler(root, {
+        getShortcuts: () => engine.getShortcuts(),
+        commandBus,
+        isComposing: () => compositionHandler.isComposing(),
+    });
+    // -------------------------------------------------------------------
+    // Input bridge
+    // -------------------------------------------------------------------
+    // Shared closure for finding atomic mark ranges — used by InputBridge and
+    // selection change handler
+    const findAtomicMarkRangeFn = (offset) => {
+        const doc = engine.state.doc;
+        const marks = engine.getMarksAtOffset(offset);
+        for (const key of Object.keys(marks)) {
+            if (markRenderers.isAtomic(key)) {
+                return findContiguousMarkRange(doc, offset, key);
+            }
+        }
+        return null;
+    };
+    const inputBridge = new InputBridge(root, {
+        getSelection: () => engine.state.selection,
+        getDoc: () => engine.state.doc,
+        dispatch: (ops) => engine.dispatch(ops),
+        undo: () => engine.undo(),
+        redo: () => engine.redo(),
+        isComposing: () => compositionHandler.isComposing(),
+        isReadOnly: () => readOnly,
+        generateBlockId: () => generateId(),
+        getPendingMarks: () => engine.getPendingMarks(),
+        clearPendingMarks: () => engine.clearPendingMarks(),
+        findAtomicMarkRange: findAtomicMarkRangeFn,
+        isAtomicBlock: (type) => blockRenderers.isAtomic(type),
+    });
+    // -------------------------------------------------------------------
+    // Content pipeline
+    // -------------------------------------------------------------------
+    const contentPipeline = createContentPipeline();
+    // Register built-in handlers (priority: RTIF JSON -80, image -85, HTML -90,
+    // URL -95, plain text -100, file drop -105)
+    contentPipeline.register(createRtifPasteHandler(() => generateId()));
+    contentPipeline.register(createImageContentHandler());
+    contentPipeline.register(createHtmlPasteHandler());
+    contentPipeline.register(createUrlContentHandler());
+    contentPipeline.register(createPlainTextHandler(() => generateId()));
+    contentPipeline.register(createFileDropHandler());
+    // -------------------------------------------------------------------
+    // Clipboard handler (paste delegated to content pipeline)
+    // -------------------------------------------------------------------
+    const clipboardHandler = new ClipboardHandler(root, {
+        getSelection: () => engine.state.selection,
+        getDoc: () => engine.state.doc,
+        dispatch: (ops) => engine.dispatch(ops),
+        isReadOnly: () => readOnly,
+        isComposing: () => compositionHandler.isComposing(),
+        generateBlockId: () => generateId(),
+        skipPaste: true,
+    });
+    // -------------------------------------------------------------------
+    // Drop indicator
+    // -------------------------------------------------------------------
+    const dropIndicator = new DropIndicator(root);
+    // -------------------------------------------------------------------
+    // Block drag handler (reorder blocks via drag handles)
+    // -------------------------------------------------------------------
+    const blockDragHandler = new BlockDragHandler({
+        root,
+        getDoc: () => engine.state.doc,
+        dispatch: (ops) => engine.dispatch(ops),
+        isReadOnly: () => readOnly,
+    });
+    // -------------------------------------------------------------------
+    // Paste handler (via content pipeline)
+    // -------------------------------------------------------------------
+    const onPaste = (e) => {
+        e.preventDefault();
+        if (readOnly)
+            return;
+        if (compositionHandler.isComposing())
+            return;
+        const items = extractFromPaste(e);
+        if (items.length === 0)
+            return;
+        // Process async — fire and forget. Errors are swallowed by the pipeline.
+        void contentPipeline.process(items, {
+            engine,
+            commands: commandBus,
+            source: 'paste',
+            generateBlockId: () => generateId(),
+        });
+    };
+    // -------------------------------------------------------------------
+    // Drag and drop handlers
+    // -------------------------------------------------------------------
+    const onDragOver = (e) => {
+        if (readOnly)
+            return;
+        const dt = e.dataTransfer;
+        if (!dt)
+            return;
+        const hasFiles = dt.types.includes('Files');
+        const hasHandleable = dt.types.some((t) => contentPipeline.hasHandlerForType(t));
+        if (hasFiles || hasHandleable) {
+            e.preventDefault();
+            dt.dropEffect = 'copy';
+            if (hasFiles) {
+                dropIndicator.showForFile();
+            }
+            else {
+                // Find nearest block for between-blocks indicator
+                const blockEl = findNearestBlock(root, e.clientY);
+                if (blockEl) {
+                    const blockRect = blockEl.getBoundingClientRect();
+                    const midY = blockRect.top + blockRect.height / 2;
+                    const position = e.clientY < midY ? 'before' : 'after';
+                    dropIndicator.showBetweenBlocks(blockEl, position);
+                }
+            }
+        }
+    };
+    const onDragLeave = (e) => {
+        // Only hide if leaving the editor root (not entering a child)
+        if (e.relatedTarget &&
+            root.contains(e.relatedTarget)) {
+            return;
+        }
+        dropIndicator.hide();
+    };
+    const onDrop = (e) => {
+        e.preventDefault();
+        dropIndicator.hide();
+        if (readOnly)
+            return;
+        const items = extractFromDrop(e);
+        if (items.length === 0)
+            return;
+        // Compute drop offset from coordinates
+        const dropOffset = getOffsetFromDropPoint(root, engine.state.doc, e.clientX, e.clientY);
+        // Process async
+        void contentPipeline.process(items, {
+            engine,
+            commands: commandBus,
+            source: 'drop',
+            dropOffset: dropOffset ?? undefined,
+            generateBlockId: () => generateId(),
+        });
+    };
+    // -------------------------------------------------------------------
+    // Cursor navigation handler
+    // -------------------------------------------------------------------
+    const cursorNavHandler = new CursorNavHandler(root, {
+        getSelection: () => engine.state.selection,
+        getDoc: () => engine.state.doc,
+        dispatch: (ops) => engine.dispatch(ops),
+        undo: () => engine.undo(),
+        redo: () => engine.redo(),
+        isComposing: () => compositionHandler.isComposing(),
+        isReadOnly: () => readOnly,
+        setSelection: (sel) => {
+            // Programmatic selection change (Cmd+A, Cmd+Home/End):
+            // update engine state AND sync to DOM.
+            engine.setSelection(sel);
+            setDomSelection(root, engine.state.doc, sel);
+        },
+        isMac: () => isMac(),
+    });
+    // -------------------------------------------------------------------
+    // Selection change handler
+    // -------------------------------------------------------------------
+    let prevDoc = engine.state.doc;
+    /**
+     * Adjust a selection's anchor/focus if either falls inside an atomic mark.
+     * Infers direction from comparing new vs previous selection offsets.
+     * Returns the original selection reference if no adjustment needed.
+     */
+    function adjustSelectionAroundAtomicMarks(sel, prevSel, findAtomic) {
+        // Determine direction for anchor
+        const anchorDir = sel.anchor.offset > prevSel.anchor.offset ? 'forward'
+            : sel.anchor.offset < prevSel.anchor.offset ? 'backward'
+                : 'nearest';
+        // Determine direction for focus
+        const focusDir = sel.focus.offset > prevSel.focus.offset ? 'forward'
+            : sel.focus.offset < prevSel.focus.offset ? 'backward'
+                : 'nearest';
+        const adjustedAnchor = adjustOffsetAroundAtomicMarks(sel.anchor.offset, anchorDir, findAtomic);
+        const adjustedFocus = adjustOffsetAroundAtomicMarks(sel.focus.offset, focusDir, findAtomic);
+        if (adjustedAnchor === sel.anchor.offset && adjustedFocus === sel.focus.offset) {
+            return sel; // No adjustment needed — return same reference
+        }
+        return {
+            anchor: { offset: adjustedAnchor },
+            focus: { offset: adjustedFocus },
+        };
+    }
+    const selectionChangeHandler = () => {
+        if (destroyed)
+            return;
+        if (isSuppressed())
+            return;
+        if (compositionHandler.isComposing())
+            return;
+        const cache = buildBlockOffsetCache(engine.state.doc);
+        const sel = readDomSelection(root, cache);
+        if (sel === null)
+            return;
+        // Adjust offsets that land inside atomic marks
+        const adjustedSel = adjustSelectionAroundAtomicMarks(sel, engine.state.selection, findAtomicMarkRangeFn);
+        if (adjustedSel !== sel) {
+            // Selection was adjusted — update engine AND re-sync DOM
+            engine.setSelection(adjustedSel);
+            setDomSelection(root, engine.state.doc, adjustedSel);
+            return;
+        }
+        // Adjust offsets that land inside atomic blocks (HR, image, embed)
+        const isAtomicBlockFn = (type) => blockRenderers.isAtomic(type);
+        const prevSel = engine.state.selection;
+        const anchorDir = sel.anchor.offset > prevSel.anchor.offset ? 'forward'
+            : sel.anchor.offset < prevSel.anchor.offset ? 'backward'
+                : 'nearest';
+        const focusDir = sel.focus.offset > prevSel.focus.offset ? 'forward'
+            : sel.focus.offset < prevSel.focus.offset ? 'backward'
+                : 'nearest';
+        const adjAnchor = adjustOffsetAroundAtomicBlocks(engine.state.doc, sel.anchor.offset, anchorDir, isAtomicBlockFn);
+        const adjFocus = adjustOffsetAroundAtomicBlocks(engine.state.doc, sel.focus.offset, focusDir, isAtomicBlockFn);
+        if (adjAnchor !== sel.anchor.offset || adjFocus !== sel.focus.offset) {
+            const blockAdjustedSel = {
+                anchor: { offset: adjAnchor },
+                focus: { offset: adjFocus },
+            };
+            engine.setSelection(blockAdjustedSel);
+            setDomSelection(root, engine.state.doc, blockAdjustedSel);
+            return;
+        }
+        // Update engine selection without triggering a dispatch
+        // (engine.setSelection fires onSelectionChange which runs clearExclusiveMarksAtBoundary)
+        setEngineSelection(sel);
+    };
+    // -------------------------------------------------------------------
+    // Composition event handlers
+    // -------------------------------------------------------------------
+    const onCompositionStart = (e) => {
+        compositionHandler.onCompositionStart(e);
+    };
+    const onCompositionUpdate = (e) => {
+        compositionHandler.onCompositionUpdate(e);
+    };
+    const onCompositionEnd = (e) => {
+        const commit = compositionHandler.onCompositionEnd(e);
+        if (commit) {
+            if (commit.deleteRange) {
+                engine.dispatch([
+                    {
+                        type: 'delete_text',
+                        offset: commit.deleteRange.offset,
+                        count: commit.deleteRange.count,
+                    },
+                    {
+                        type: 'insert_text',
+                        offset: commit.deleteRange.offset,
+                        text: commit.text,
+                    },
+                ]);
+            }
+            else {
+                engine.dispatch({
+                    type: 'insert_text',
+                    offset: commit.offset,
+                    text: commit.text,
+                });
+            }
+        }
+    };
+    // -------------------------------------------------------------------
+    // Engine onChange — reconcile DOM and sync selection
+    // -------------------------------------------------------------------
+    const unsubscribeOnChange = engine.onChange((state) => {
+        if (destroyed)
+            return;
+        const composingBlockId = compositionHandler.getComposingBlockId();
+        reconcile(root, prevDoc, state.doc, composingBlockId, markRenderers, blockRenderers);
+        prevDoc = state.doc;
+        // Sync selection to DOM (unless composing)
+        if (!compositionHandler.isComposing()) {
+            setDomSelection(root, state.doc, state.selection);
+            scrollToCursor(root);
+        }
+        // Update placeholder visibility
+        updatePlaceholder(root, state.doc);
+    });
+    // -------------------------------------------------------------------
+    // Exclusive mark boundary helper
+    // -------------------------------------------------------------------
+    /**
+     * Clear pending marks for exclusive mark types when the cursor is at
+     * the end boundary of an exclusive mark span. This prevents typing
+     * from extending the mark (e.g., typing after a link).
+     */
+    function clearExclusiveMarksAtBoundary(sel) {
+        if (sel.anchor.offset !== sel.focus.offset)
+            return; // range selection, skip
+        const offset = sel.focus.offset;
+        const marks = engine.getMarksAtOffset(offset);
+        for (const key of Object.keys(marks)) {
+            if (markRenderers.isExclusive(key)) {
+                const range = findContiguousMarkRange(engine.state.doc, offset, key);
+                if (range && offset === range.offset + range.count) {
+                    engine.setPendingMark(key, null);
+                }
+            }
+        }
+    }
+    // -------------------------------------------------------------------
+    // Engine onSelectionChange — clear exclusive marks at boundaries
+    // -------------------------------------------------------------------
+    const unsubscribeOnSelectionChange = engine.onSelectionChange((state) => {
+        if (destroyed)
+            return;
+        clearExclusiveMarksAtBoundary(state.selection);
+    });
+    // -------------------------------------------------------------------
+    // Focus/blur handling
+    // -------------------------------------------------------------------
+    const onBlur = () => {
+        compositionHandler.reset();
+        resetSuppression();
+    };
+    // -------------------------------------------------------------------
+    // Set engine selection helper
+    // -------------------------------------------------------------------
+    /**
+     * Update the engine's selection state from a DOM-originated change.
+     *
+     * Called by the selectionchange handler when the user moves the cursor
+     * via click, arrow keys, or touch. Stores the selection in the engine
+     * so that subsequent operations use the correct cursor position.
+     *
+     * Does NOT re-set the DOM selection (it was already set by the user action).
+     */
+    function setEngineSelection(sel) {
+        engine.setSelection(sel);
+    }
+    // -------------------------------------------------------------------
+    // Escape key handler — clear pending marks to exit mark spans
+    // -------------------------------------------------------------------
+    const onEscapeKeyDown = (e) => {
+        if (e.key !== 'Escape' || e.defaultPrevented)
+            return;
+        const { selection } = engine.state;
+        if (selection.anchor.offset !== selection.focus.offset)
+            return; // range selection, skip
+        const offset = selection.focus.offset;
+        const marks = engine.getMarksAtOffset(offset);
+        const markKeys = Object.keys(marks);
+        if (markKeys.length === 0)
+            return; // no marks to exit
+        // Clear all current marks via pending marks
+        for (const key of markKeys) {
+            engine.setPendingMark(key, null);
+        }
+        e.preventDefault();
+    };
+    // -------------------------------------------------------------------
+    // Attach all event listeners
+    // -------------------------------------------------------------------
+    shortcutHandler.attach();
+    inputBridge.attach();
+    clipboardHandler.attach();
+    cursorNavHandler.attach();
+    blockDragHandler.attach();
+    root.addEventListener('compositionstart', onCompositionStart);
+    root.addEventListener('compositionupdate', onCompositionUpdate);
+    root.addEventListener('compositionend', onCompositionEnd);
+    root.addEventListener('blur', onBlur);
+    root.addEventListener('paste', onPaste);
+    root.addEventListener('dragover', onDragOver);
+    root.addEventListener('dragleave', onDragLeave);
+    root.addEventListener('drop', onDrop);
+    document.addEventListener('selectionchange', selectionChangeHandler);
+    // Escape handler registered AFTER TriggerManager and ShortcutHandler
+    // (all capture phase). TriggerManager/LinkPopover call e.preventDefault()
+    // when they handle Escape, so defaultPrevented check prevents conflicts.
+    root.addEventListener('keydown', onEscapeKeyDown, true);
+    // Initial placeholder update
+    updatePlaceholder(root, engine.state.doc);
+    // Auto-focus
+    if (autoFocus) {
+        root.focus();
+    }
+    // -------------------------------------------------------------------
+    // Return WebEditor handle
+    // -------------------------------------------------------------------
+    return {
+        engine,
+        commandBus,
+        content: contentPipeline,
+        markRenderers,
+        blockRenderers,
+        triggers: triggerManager,
+        cursorRect,
+        focus() {
+            if (destroyed)
+                return;
+            root.focus();
+            // Restore the engine's selection to the DOM. Browsers may clear or
+            // reset the contenteditable's selection when focus leaves and returns
+            // (e.g., after interacting with a popover). The engine is the source
+            // of truth, so always sync after focusing.
+            setDomSelection(root, engine.state.doc, engine.state.selection);
+        },
+        blur() {
+            if (destroyed)
+                return;
+            root.blur();
+        },
+        isFocused() {
+            if (destroyed)
+                return false;
+            return document.activeElement === root;
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            // Detach event handlers
+            shortcutHandler.detach();
+            inputBridge.detach();
+            clipboardHandler.detach();
+            cursorNavHandler.detach();
+            blockDragHandler.detach();
+            root.removeEventListener('compositionstart', onCompositionStart);
+            root.removeEventListener('compositionupdate', onCompositionUpdate);
+            root.removeEventListener('compositionend', onCompositionEnd);
+            root.removeEventListener('blur', onBlur);
+            root.removeEventListener('paste', onPaste);
+            root.removeEventListener('dragover', onDragOver);
+            root.removeEventListener('dragleave', onDragLeave);
+            root.removeEventListener('drop', onDrop);
+            root.removeEventListener('keydown', onEscapeKeyDown, true);
+            document.removeEventListener('selectionchange', selectionChangeHandler);
+            // Unsubscribe from engine changes
+            unsubscribeOnChange();
+            unsubscribeOnSelectionChange();
+            // Destroy command bus
+            commandBus.destroy();
+            // Destroy trigger manager
+            triggerManager.destroy();
+            // Destroy content pipeline
+            contentPipeline.destroy();
+            // Destroy drop indicator
+            dropIndicator.destroy();
+            // Reset composition handler
+            compositionHandler.reset();
+            resetSuppression();
+            // Remove contenteditable attributes
+            root.removeAttribute('contenteditable');
+            root.removeAttribute('role');
+            root.removeAttribute('aria-multiline');
+            root.removeAttribute('aria-label');
+            root.removeAttribute('aria-readonly');
+            root.removeAttribute('data-rtif-root');
+            root.removeAttribute('data-placeholder');
+            root.style.contain = '';
+            root.style.whiteSpace = '';
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Simple counter-based ID generator. Sufficient for single-session editing. */
+let idCounter = 0;
+/**
+ * Generate a unique block ID.
+ *
+ * Uses a simple counter for deterministic, unique IDs within a session.
+ * Production applications may want to use `crypto.randomUUID()` instead.
+ */
+function generateId() {
+    return `b_${++idCounter}`;
+}
+/**
+ * Update the placeholder visibility based on document content.
+ *
+ * Shows the placeholder when the document has a single block with empty text.
+ * Uses a `data-empty` attribute that CSS can target.
+ */
+function updatePlaceholder(root, doc) {
+    const isEmpty = doc.blocks.length === 1 &&
+        doc.blocks[0].spans.length === 1 &&
+        doc.blocks[0].spans[0].text === '';
+    if (isEmpty) {
+        root.setAttribute('data-empty', 'true');
+    }
+    else {
+        root.removeAttribute('data-empty');
+    }
+}
+/**
+ * Get an RTIF offset from drop coordinates using the browser's caret APIs.
+ *
+ * Uses `document.caretPositionFromPoint()` (standard) or
+ * `document.caretRangeFromPoint()` (WebKit/Blink fallback) to find the
+ * DOM position at the given screen coordinates, then converts to an
+ * absolute RTIF offset.
+ *
+ * @param root - The editor root element
+ * @param doc - The current RTIF document
+ * @param clientX - X coordinate (from DragEvent)
+ * @param clientY - Y coordinate (from DragEvent)
+ * @returns The absolute RTIF offset, or null if position cannot be determined
+ */
+function getOffsetFromDropPoint(root, doc, clientX, clientY) {
+    const cache = buildBlockOffsetCache(doc);
+    // Standard API (Firefox 126+, Chrome 128+)
+    if (typeof document.caretPositionFromPoint === 'function') {
+        const pos = document.caretPositionFromPoint(clientX, clientY);
+        if (pos) {
+            return domPointToRtifOffset(root, pos.offsetNode, pos.offset, cache);
+        }
+    }
+    // WebKit/Blink fallback
+    // caretRangeFromPoint is non-standard but widely supported
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- browser-specific API not in lib.dom.d.ts
+    const caretRangeFromPoint = document.caretRangeFromPoint;
+    if (typeof caretRangeFromPoint === 'function') {
+        const range = caretRangeFromPoint.call(document, clientX, clientY);
+        if (range) {
+            return domPointToRtifOffset(root, range.startContainer, range.startOffset, cache);
+        }
+    }
+    return null;
+}
+/**
+ * Find the nearest block element to a given Y coordinate.
+ *
+ * Used for positioning the drop indicator between blocks during drag-over.
+ *
+ * @param root - The editor root element
+ * @param clientY - The Y coordinate to find the nearest block to
+ * @returns The nearest block element, or null if no blocks found
+ */
+function findNearestBlock(root, clientY) {
+    const blocks = root.querySelectorAll('[data-rtif-block]');
+    if (blocks.length === 0)
+        return null;
+    let nearest = null;
+    let nearestDistance = Infinity;
+    for (let i = 0; i < blocks.length; i++) {
+        const block = blocks[i];
+        const rect = block.getBoundingClientRect();
+        const midY = rect.top + rect.height / 2;
+        const distance = Math.abs(clientY - midY);
+        if (distance < nearestDistance) {
+            nearestDistance = distance;
+            nearest = block;
+        }
+    }
+    return nearest;
+}
+//# sourceMappingURL=editor.js.map